@wular/pnext 0.0.1

package/src/dev/module-generations.ts

@@ -0,0 +1,38 @@
+// Stale ESM registry generations - the accounting behind dev's recycle trigger. Compiled server
+// artifacts are content-graph-named, so every save that changes a module gives it a NEW href and
+// the server imports that; Bun's registry has no eviction API, so the previous href stays linked
+// for the process lifetime.
+//
+// Counting them needs no registry walk: an artifact goes stale exactly when its (profile, source)
+// pair is renamed to a different artifact, and it only costs memory if it was ever imported. Both
+// facts are known at the two call sites below, so the count is an O(1) side effect of compiling.
+import { fileURLToPath } from 'node:url';
+
+/** Current artifact per `${profile}:${file}`. */
+const liveNames = new Map<string, string>();
+/** Artifacts that actually entered the ES module registry. */
+const imported = new Set<string>();
+let stale = 0;
+
+/** Record that `outFile` is now the artifact for `key` (`${profile}:${file}`). */
+export function noteModuleGeneration(key: string, outFile: string) {
+  const previous = liveNames.get(key);
+  if (previous !== outFile) {
+    liveNames.set(key, outFile);
+    // Only a generation the registry actually holds costs memory; one that was
+    // compiled and superseded before any import cost disk alone.
+    if (previous !== undefined && imported.delete(previous)) stale += 1;
+  }
+}
+
+/** Record that `href` was imported, so superseding it will count as stale. */
+export function noteModuleImported(href: string) {
+  // Named as a path on the compile side, imported as an href: normalise through
+  // the same URL codec both sides use, or every entry would look never-imported.
+  imported.add(href.startsWith('file:') ? fileURLToPath(href) : href);
+}
+
+/** Live and superseded registry generations of compiled server modules. */
+export function moduleGenerationStats() {
+  return { live: imported.size, stale };
+}

package/src/dev/module-transform.ts

@@ -0,0 +1,188 @@
+// Batched transform pass for server modules: plain ESM sources are transformed with oxc and get their
+// import specifiers rewritten by us, instead of paying a per-module esbuild bundle whose only real job -
+// with `packages:'external'` and every specifier resolved by our own plugin - is specifier rewriting.
+//
+// esbuild's bundler is still load-bearing for a handful of shapes (below); `transformBailReason` sniffs
+// those out per file and the caller falls back to the esbuild build for them. Same pipeline in dev and prod.
+import { transformSync, type TransformOptions } from 'oxc-transform';
+import { isCommonJsModuleSource } from '../resolve/imports';
+
+/** Why a source cannot take the transform path — one per esbuild-only shape. */
+export type TransformBailReason =
+  | 'commonjs' // require()/module.exports: CJS→ESM conversion + the require-alias map
+  | 'glob-import' // non-literal `import()`: esbuild's `__glob` expansion
+  | 'enum' // oxc's enum lowering omits `E || {}`, breaking declaration merging
+  | 'helpers' // the transform needed @oxc-project/runtime helper imports
+  | 'parse-error'
+  | 'specifier'; // a specifier the bundler resolves by inlining (assets with a
+// loader rule, `#subpath` facades, require-aliases)
+
+// `import(` whose argument is not a string literal — esbuild turns those into a
+// `__glob({...})` map of the matching directory, which needs the bundler.
+const NON_LITERAL_DYNAMIC_IMPORT = /\bimport\s*\(\s*(?!['"])[^)]/;
+const REQUIRE_CALL = /\brequire\s*\(/;
+const COMMONJS_EXPORTS = /\bmodule\.exports\b|\bexports\s*\.\s*[A-Za-z_$]/;
+const ENUM_DECLARATION = /(?:^|[^.\w$])enum\s+[A-Za-z_$]/;
+
+export function transformBailReason(source: string, file: string): TransformBailReason | undefined {
+  if (REQUIRE_CALL.test(source) || COMMONJS_EXPORTS.test(source) || isCommonJsModuleSource(source, file)) {
+    return 'commonjs';
+  }
+  if (NON_LITERAL_DYNAMIC_IMPORT.test(source)) return 'glob-import';
+  if (ENUM_DECLARATION.test(source)) return 'enum';
+  return undefined;
+}
+
+/**
+ * TS/JSX → ESM for one server module. `define` mirrors the esbuild build's own
+ * `define` so constant folding stays identical across the two paths.
+ */
+export function transformServerModule(
+  source: string,
+  file: string,
+  define: Record<string, string> | undefined,
+): { code: string } | { bail: TransformBailReason } {
+  const options: TransformOptions = {
+    lang: langForFile(file),
+    jsx: { runtime: 'automatic', importSource: 'preact' },
+    // No `target`: these modules are loaded by Bun, so syntax lowering buys nothing and oxc's
+    // lowering plugins are expensive on the transform line.
+    sourcemap: false,
+    ...(define ? { define } : {}),
+  };
+  const result = transformSync(file, source, options);
+  if (result.errors.length > 0) return { bail: 'parse-error' };
+  // Runtime helpers would import `@oxc-project/runtime`, which the app does not
+  // have; esbuild inlines its equivalents, so hand those sources back to it.
+  if (Object.keys(result.helpersUsed).length > 0) return { bail: 'helpers' };
+  return { code: dropUnreferencedImports(result.code) };
+}
+
+// `.ts` forbids JSX (`<T>x` is a type assertion); `.js`/`.jsx` app modules may
+// contain JSX, matching the esbuild build's `loader: { '.js': 'jsx' }`.
+function langForFile(file: string): 'ts' | 'tsx' | 'jsx' {
+  if (/\.[mc]?ts$/.test(file)) return 'ts';
+  if (file.endsWith('.tsx')) return 'tsx';
+  return 'jsx';
+}
+
+// --------------------------------------------------------------------------
+// emitted-module specifier scan
+// --------------------------------------------------------------------------
+
+export type SpecifierKind = 'import-statement' | 'dynamic-import';
+
+export interface FoundSpecifier {
+  start: number;
+  end: number;
+  value: string;
+  kind: SpecifierKind;
+}
+
+const SPECIFIER_RE =
+  /(?:^|[\n;{}])\s*(?:import|export)\b[^;'"]*?\bfrom\s*("[^"]*"|'[^']*')|(?:^|[\n;{}])\s*import\s*("[^"]*"|'[^']*')|\bimport\s*\(\s*("[^"]*"|'[^']*')\s*\)/g;
+
+/** Every module specifier in emitted ESM, with the span of its string literal. */
+export function outputSpecifiers(code: string): FoundSpecifier[] {
+  const found: FoundSpecifier[] = [];
+  SPECIFIER_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = SPECIFIER_RE.exec(code))) {
+    for (let group = 1; group <= 3; group += 1) {
+      const literal = match[group];
+      if (literal === undefined) continue;
+      const start = match.index + match[0].lastIndexOf(literal);
+      found.push({
+        start,
+        end: start + literal.length,
+        value: literal.slice(1, -1),
+        kind: group === 3 ? 'dynamic-import' : 'import-statement',
+      });
+    }
+  }
+  return found;
+}
+
+/** Apply `{start, end, value}` replacements to `code` (spans must not overlap). */
+export function spliceSource(code: string, edits: { start: number; end: number; value: string }[]) {
+  let next = code;
+  for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    next = `${next.slice(0, edit.start)}${edit.value}${next.slice(edit.end)}`;
+  }
+  return next;
+}
+
+// --------------------------------------------------------------------------
+// drop-unreferenced-imports post-pass
+// --------------------------------------------------------------------------
+
+const IMPORT_STATEMENT_RE =
+  /(?:^|\n)[ \t]*import\s+([A-Za-z_$][\w$]*\s*,\s*)?(?:\*\s*as\s+([A-Za-z_$][\w$]*)|\{([^}]*)\}|([A-Za-z_$][\w$]*))\s+from\s*(?:"[^"]*"|'[^']*')\s*;?/g;
+
+/**
+ * oxc keeps an import whose only uses were type positions it could not see through; the emitted module then
+ * imports a name the compiled target does not export and fails to load. esbuild's TS pipeline drops those,
+ * so drop any import statement whose every binding is unreferenced in the rest of the module - textual and
+ * therefore conservative: a name mentioned anywhere else, even in a string, keeps its import.
+ * Side-effect-only `import 'x'` never matches this pattern and is always kept.
+ */
+export function dropUnreferencedImports(code: string) {
+  const statements: { start: number; end: number; names: string[] }[] = [];
+  IMPORT_STATEMENT_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = IMPORT_STATEMENT_RE.exec(code))) {
+    const [text, defaultWithNamed, namespace, named, defaultOnly] = match;
+    const names: string[] = [];
+    if (defaultWithNamed) names.push(defaultWithNamed.replace(/\s*,\s*$/, '').trim());
+    if (namespace) names.push(namespace);
+    if (defaultOnly) names.push(defaultOnly);
+    if (named !== undefined) {
+      for (const part of named.split(',')) {
+        const local = part.split(/\bas\b/).pop()?.trim();
+        // An unparsed clause (comments, odd spacing) yields no local name: keep.
+        if (!local) continue;
+        if (!/^[A-Za-z_$][\w$]*$/.test(local)) return code;
+        names.push(local);
+      }
+    }
+    if (names.length === 0) continue;
+    const leading = text.startsWith('\n') ? 1 : 0;
+    statements.push({ start: match.index + leading, end: match.index + text.length, names });
+  }
+  if (statements.length === 0) return code;
+
+  // Reference test runs against the module with every import statement cut out,
+  // so one import's bindings never count as a use of another's.
+  const gaps: string[] = [];
+  let cursor = 0;
+  for (const statement of statements) {
+    gaps.push(code.slice(cursor, statement.start));
+    cursor = statement.end;
+  }
+  gaps.push(code.slice(cursor));
+  const used = referencedNames(gaps.join('\n'));
+  const unused = statements.filter(statement => statement.names.every(name => !used.has(name)));
+  if (unused.length === 0) return code;
+  return spliceSource(
+    code,
+    unused.map(({ start, end }) => ({ start, end, value: '' })),
+  );
+}
+
+const IDENTIFIER_RE = /[A-Za-z_$][\w$]*/g;
+
+/**
+ * Every identifier token that is not a member-access property name. A single
+ * leading `.` is member access (`obj.name`, `obj?.name`); a doubled one is the
+ * spread/rest operator (`...name`), which IS a reference.
+ */
+function referencedNames(body: string) {
+  const names = new Set<string>();
+  IDENTIFIER_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = IDENTIFIER_RE.exec(body))) {
+    if (body[match.index - 1] === '.' && body[match.index - 2] !== '.') continue;
+    names.add(match[0]);
+  }
+  return names;
+}

package/src/dev/node-module-bundle-cache.ts

@@ -0,0 +1,63 @@
+// Persisted node_modules bundles - the restart half of runtime/server.ts' `transformNodeModuleSource`.
+// The node_modules load plugin esbuild-bundles each ESM package file it matches and remembers the
+// result in memory only, so every restart re-runs those builds on the request path while the route
+// bundle it is evaluating waits.
+//
+// The entry's own stat names the record, but the build inlines the package's relative graph too, so
+// the record carries EVERY esbuild input and is reused only while all of them still stat the same.
+// Anything else - a missing input, an unparseable record, a vanished file - is a miss, never a
+// stale hit: the bundle it names is imported directly, and Bun caches a bad import for the life of
+// the process.
+import { mkdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileAtomic } from '../utils/fs';
+
+/** `[file, mtimeMs, size]` for one esbuild input of the bundle. */
+type InputEntry = [string, number, number];
+
+interface BundleRecord {
+  inputs: InputEntry[];
+  code: string;
+}
+
+/** The recorded bundle when every input it was built from is unchanged. */
+export async function readNodeModuleBundle(recordFile: string): Promise<string | undefined> {
+  const contents = await readFile(recordFile, 'utf8').catch(() => undefined);
+  if (contents === undefined) return undefined;
+  let record: BundleRecord | undefined;
+  try {
+    record = JSON.parse(contents) as BundleRecord;
+  } catch {
+    return undefined;
+  }
+  if (typeof record?.code !== 'string' || !Array.isArray(record.inputs)) return undefined;
+  if (record.inputs.length === 0) return undefined;
+  const held = await Promise.all(
+    record.inputs.map(async ([input, mtimeMs, size]) => {
+      const stats = await stat(input).catch(() => undefined);
+      return stats?.mtimeMs === mtimeMs && stats.size === size;
+    }),
+  );
+  return held.every(Boolean) ? record.code : undefined;
+}
+
+export async function writeNodeModuleBundle(
+  recordFile: string,
+  inputs: string[],
+  code: string,
+): Promise<void> {
+  const stated = await Promise.all(
+    inputs.map(async (input): Promise<InputEntry | undefined> => {
+      const stats = await stat(input).catch(() => undefined);
+      return stats ? [input, stats.mtimeMs, stats.size] : undefined;
+    }),
+  );
+  // An input that vanished between the build and here would make the record
+  // unvalidatable forever; leaving it unwritten costs the next boot one bundle.
+  if (stated.length === 0 || stated.some(entry => entry === undefined)) return;
+  await mkdir(path.dirname(recordFile), { recursive: true }).catch(() => undefined);
+  await writeFileAtomic(
+    recordFile,
+    JSON.stringify({ inputs: stated as InputEntry[], code } satisfies BundleRecord),
+  ).catch(() => undefined);
+}

package/src/dev/restart-cache.ts

@@ -0,0 +1,10 @@
+/**
+ * `PNEXT_DEV_RESTART_CACHE=0` turns off everything that makes a dev restart reuse work from the previous
+ * process: the persisted client cache keys, the persisted next/font resolutions, and the boot-time proxy
+ * and client-reference warmups. Nothing else changes, so a restart can be measured with and without the
+ * whole group on one tree - the same bisect role `PNEXT_DISABLE_VENDOR_STAGE` plays for the vendor stage.
+ */
+export function restartCacheEnabled() {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  return process.env.PNEXT_DEV_RESTART_CACHE !== '0';
+}

package/src/dev/route-bundle-key-cache.ts

@@ -0,0 +1,154 @@
+// Persisted route-bundle names - the restart half of dev/imports.ts' devRouteBundlePath. A route's
+// bundle already lives at a content-addressed path, so a restart never has to rebuild it; deriving
+// that path did, by walking the whole source graph of the route and its layouts breadth-first, with
+// a stat round trip per level, on the first page of every restart. The sources cannot have moved
+// while nothing was watching them *unless* the file did, so this persists the walk's answer and
+// re-validates it with one flat stat per source.
+//
+// The same three-step ladder dev/client-key-cache.ts and dev/route-facts-cache.ts use:
+//   stat matches      -> reuse (the common case, and the only O(1) one)
+//   stat moved        -> read + hash; equal content still reuses the path
+//   content differs   -> discard, walk again, record the new answer
+// A missing source is a miss too, which is what keeps a deleted file from naming an artifact whose
+// edges are gone.
+//
+// One file PER ROUTE, not one index, for the reason route-facts-cache records: the source lists are
+// large across the whole table and the first page only ever asks about the route it is serving.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import type { ResolvedConfig } from '../config';
+import {
+  DEV_SOURCE_MISSING,
+  devTextSourceHash,
+  isBinaryDevSource,
+  type DevGraphSource,
+} from './module-cache';
+import { restartCacheEnabled } from './restart-cache';
+
+interface RecordFile {
+  version: number;
+  /** Hash of everything in the name that is not a walked source (see recordKey). */
+  key: string;
+  /** The named bundle path itself — the whole point of the record. */
+  bundle: string;
+  files: DevGraphSource[];
+}
+
+/** Bumped whenever a record's shape changes; an older record is simply ignored. */
+const RECORD_VERSION = 1;
+
+const hash = (value: string) => Bun.hash(value).toString(36);
+
+/** Records written this process (by record file), so a repeat naming does not re-serialize. */
+const written = new Map<string, string>();
+
+function enabled() {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  return restartCacheEnabled() && process.env.PNEXT_DEV_BUNDLE_KEY_CACHE !== '0';
+}
+
+function recordFile(config: ResolvedConfig, routeId: string) {
+  return path.join(config.outPath, 'cache', 'route-bundles', `${hash(routeId)}.json`);
+}
+
+/**
+ * The entry files and the graph's own key (compat, aliases, the pnext build
+ * itself) decide the name as much as the sources do, so either one moving makes
+ * the record read as a miss instead of half-validating it.
+ */
+function recordKey(graphKey: string, files: string[]) {
+  return hash(`${RECORD_VERSION}\n${graphKey}\n${files.join('\0')}`);
+}
+
+/** The persisted bundle path when every source it was named for is unchanged. */
+export async function cachedRouteBundlePath(
+  config: ResolvedConfig,
+  routeId: string,
+  graphKey: string,
+  files: string[],
+): Promise<string | undefined> {
+  if (!enabled()) return undefined;
+  const key = recordKey(graphKey, files);
+  let record: RecordFile | undefined;
+  try {
+    record = JSON.parse(readFileSync(recordFile(config, routeId), 'utf8')) as RecordFile;
+  } catch {
+    return undefined;
+  }
+  if (record?.version !== RECORD_VERSION || record.key !== key) return undefined;
+  if (typeof record.bundle !== 'string' || !Array.isArray(record.files)) return undefined;
+  const revalidated = await revalidate(record.files);
+  if (!revalidated) return undefined;
+  // Only the stats moved (a touch, a checkout): keep the name, record the new
+  // stats so the next boot takes the O(1) path again.
+  if (revalidated !== record.files) {
+    written.delete(recordFile(config, routeId));
+    write(config, routeId, key, record.bundle, revalidated);
+  }
+  return record.bundle;
+}
+
+export function saveRouteBundlePath(
+  config: ResolvedConfig,
+  routeId: string,
+  graphKey: string,
+  files: string[],
+  bundle: string,
+  sources: DevGraphSource[],
+): void {
+  if (!enabled()) return;
+  // A source the walk could not read describes a tree that no longer exists;
+  // the next boot walking again is the safe answer.
+  if (sources.some(([, , , srcHash]) => srcHash === DEV_SOURCE_MISSING)) return;
+  write(config, routeId, recordKey(graphKey, files), bundle, sources);
+}
+
+function write(
+  config: ResolvedConfig,
+  routeId: string,
+  key: string,
+  bundle: string,
+  files: DevGraphSource[],
+) {
+  const file = recordFile(config, routeId);
+  if (written.get(file) === bundle) return;
+  written.set(file, bundle);
+  const contents = JSON.stringify({
+    version: RECORD_VERSION,
+    key,
+    bundle,
+    files,
+  } satisfies RecordFile);
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, contents);
+  } catch {
+    // Best effort: a missing record only costs the next boot a walk.
+  }
+}
+
+/**
+ * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
+ * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
+ * walk has to run again.
+ */
+async function revalidate(files: DevGraphSource[]): Promise<DevGraphSource[] | undefined> {
+  let moved = false;
+  const checked = await Promise.all(
+    files.map(async (entry): Promise<DevGraphSource | undefined> => {
+      const [file, mtimeMs, size, srcHash] = entry;
+      const stats = await stat(file).catch(() => undefined);
+      if (!stats) return undefined;
+      if (stats.mtimeMs === mtimeMs && stats.size === size) return entry;
+      // A binary source is hashed from its stat, so a moved stat IS a new hash.
+      if (isBinaryDevSource(file)) return undefined;
+      const source = await readFile(file, 'utf8').catch(() => undefined);
+      if (source === undefined || devTextSourceHash(source) !== srcHash) return undefined;
+      moved = true;
+      return [file, stats.mtimeMs, stats.size, srcHash];
+    }),
+  );
+  if (checked.some(entry => entry === undefined)) return undefined;
+  return moved ? (checked as DevGraphSource[]) : files;
+}

package/src/dev/route-facts-cache.ts

@@ -0,0 +1,223 @@
+// Persisted route facts - the restart half of routing/routes.ts' deferred scan. A route's facts
+// (mode, segment config, client references, css imports, the source list) are derived by reading
+// and sniffing every source the route's graph reaches, and that lands on the first page of every
+// restart - the otel root interceptor alone forces it to decide one span attribute. The sources
+// cannot have moved while nothing was watching them *unless* the file did, so this persists the
+// walk's result next to the compiled cache and re-validates it with one stat per source.
+//
+// The same three-step ladder dev/client-key-cache.ts uses:
+//   stat matches      -> reuse (the common case, and the only O(1) one)
+//   stat moved        -> read + hash; equal content still reuses the facts
+//   content differs   -> discard, walk again, record the new facts
+//
+// One file PER ROUTE, not one index: the whole table is large and the first page only ever asks
+// about the route it is serving, so as a single index its JSON.parse landed, in full, on that
+// request and gave most of the walk back.
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import type { ResolvedConfig } from '../config';
+import { setRouteFactsStore, type RouteFacts, type RouteFactsStore } from '../routing/routes';
+import { restartCacheEnabled } from './restart-cache';
+
+/** `[file, mtimeMs, size, contentHash]` — the same record shape the key cache uses. */
+type SourceEntry = [string, number, number, string];
+
+interface RecordFile {
+  version: number;
+  /** Everything the facts depend on that is not a walked source (see cacheKey). */
+  key: string;
+  files: SourceEntry[];
+  facts: RouteFacts;
+}
+
+/** Bumped whenever a record's shape changes; an older record is simply ignored. */
+const RECORD_VERSION = 1;
+
+const hash = (value: string) => Bun.hash(value).toString(36);
+
+/**
+ * The facts of a route whose own sources did not move can still change when the
+ * thing that *interprets* them does: the resolved config (compat on/off, route
+ * extensions, aliases) or pnext itself. Both go in the record's key, so either
+ * one moving makes every record read as a miss instead of half-validating it.
+ */
+function cacheKey(config: ResolvedConfig): string | undefined {
+  try {
+    const shape = JSON.stringify(config, (_key, value: unknown) =>
+      typeof value === 'function' ? '[fn]' : value,
+    );
+    return hash(`${RECORD_VERSION}\n${pnextBuildStamp()}\n${shape}`);
+  } catch {
+    // A config that will not serialize (cycles, exotic values) simply opts out.
+    return undefined;
+  }
+}
+
+/**
+ * mtime+size of the route scanner this process is running. The facts are the framework's own reading of
+ * the app's sources, so a pnext that changed since the record was written must re-derive them rather than
+ * inherit the old answers - which is what keeps this safe while pnext itself is being edited.
+ */
+function pnextBuildStamp() {
+  try {
+    const self = Bun.fileURLToPath(import.meta.url);
+    const scanner = path.join(path.dirname(path.dirname(self)), 'routing', 'routes.ts');
+    const info = statSync(scanner, { throwIfNoEntry: false });
+    return info ? `${info.mtimeMs}:${info.size}` : self;
+  } catch {
+    return 'unknown';
+  }
+}
+
+interface FactsCache {
+  dir: string;
+  key: string;
+  /** Records written this process, so a repeat save does not re-serialize. */
+  written: Set<string>;
+}
+
+export function installRouteFactsCache(config: ResolvedConfig) {
+  if (!restartCacheEnabled()) return;
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_DEV_FACTS_CACHE === '0') return;
+  const key = cacheKey(config);
+  if (!key) return;
+  const cache: FactsCache = {
+    dir: path.join(config.outPath, 'cache', 'route-facts'),
+    key,
+    written: new Set(),
+  };
+  setRouteFactsStore(createStore(cache));
+}
+
+function recordFile(cache: FactsCache, routeId: string) {
+  return path.join(cache.dir, `${hash(routeId)}.json`);
+}
+
+function createStore(cache: FactsCache): RouteFactsStore {
+  return {
+    load(routeId) {
+      const record = readRecord(cache, routeId);
+      if (!record) {
+        stats.misses += 1;
+        return undefined;
+      }
+      const revalidated = revalidate(record.files);
+      if (!revalidated) {
+        stats.misses += 1;
+        return undefined;
+      }
+      stats.hits += 1;
+      // Only the stats moved (a touch, a checkout): keep the facts, record the
+      // new stats so the next boot takes the O(1) path again.
+      if (revalidated !== record.files) {
+        cache.written.delete(routeId);
+        write(cache, routeId, revalidated, record.facts);
+      }
+      return record.facts;
+    },
+    save(routeId, facts) {
+      const files = factsSources(facts);
+      if (!files) return;
+      write(cache, routeId, files, facts);
+    },
+  };
+}
+
+function readRecord(cache: FactsCache, routeId: string): RecordFile | undefined {
+  let parsed: RecordFile | undefined;
+  try {
+    parsed = JSON.parse(readFileSync(recordFile(cache, routeId), 'utf8')) as RecordFile;
+  } catch {
+    return undefined;
+  }
+  if (parsed?.version !== RECORD_VERSION || parsed.key !== cache.key) return undefined;
+  if (!parsed.facts || !Array.isArray(parsed.files)) return undefined;
+  return parsed;
+}
+
+/**
+ * Records are written from a synchronous getter, so the write is synchronous too - a debounce would
+ * have to survive an exit that the walk's caller never awaits. Each is a single small file, written
+ * once per process per route.
+ */
+function write(cache: FactsCache, routeId: string, files: SourceEntry[], facts: RouteFacts) {
+  if (cache.written.has(routeId)) return;
+  cache.written.add(routeId);
+  const contents = JSON.stringify({
+    version: RECORD_VERSION,
+    key: cache.key,
+    files,
+    facts,
+  } satisfies RecordFile);
+  try {
+    mkdirSync(cache.dir, { recursive: true });
+    writeFileSync(recordFile(cache, routeId), contents);
+  } catch {
+    // Best effort: a missing record only costs the next boot a walk.
+  }
+}
+
+/**
+ * Stat and hash every source the walk read. A file that cannot be read at all means the record would
+ * describe a tree that no longer exists, so nothing is written - the next boot walks, which is the safe
+ * answer.
+ */
+function factsSources(facts: RouteFacts): SourceEntry[] | undefined {
+  const entries: SourceEntry[] = [];
+  for (const file of facts.sourceFiles) {
+    const entry = sourceEntry(file);
+    if (!entry) return undefined;
+    entries.push(entry);
+  }
+  return entries;
+}
+
+function sourceEntry(file: string): SourceEntry | undefined {
+  try {
+    const source = readFileSync(file, 'utf8');
+    // Stat AFTER the read: a file that changes between the two records the
+    // older stat, so the next boot re-hashes rather than trusting a stale one.
+    const info = statSync(file, { throwIfNoEntry: false });
+    if (!info) return undefined;
+    return [file, info.mtimeMs, info.size, hash(source)];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
+ * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
+ * walk has to run again.
+ */
+function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
+  let moved = false;
+  const checked: SourceEntry[] = [];
+  for (const entry of files) {
+    const [file, mtimeMs, size, contentHash] = entry;
+    const info = statSync(file, { throwIfNoEntry: false });
+    if (!info) return undefined;
+    if (info.mtimeMs === mtimeMs && info.size === size) {
+      checked.push(entry);
+      continue;
+    }
+    let source: string;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      return undefined;
+    }
+    if (hash(source) !== contentHash) return undefined;
+    moved = true;
+    checked.push([file, info.mtimeMs, info.size, contentHash]);
+  }
+  return moved ? checked : files;
+}
+
+/** Bisect seam: `PNEXT_DEV_FACTS_STATS=1` prints the hit/miss split at exit. */
+const stats = { hits: 0, misses: 0 };
+// eslint-disable-next-line turbo/no-undeclared-env-vars
+if (process.env.PNEXT_DEV_FACTS_STATS === '1') {
+  process.on('exit', () => console.log(`route-facts hits=${stats.hits} misses=${stats.misses}`));
+}