@wular/pnext 0.0.24 → 0.1.0

package/src/runtime/modules.ts

@@ -3,7 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { existsSync, readFileSync, type Dirent } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { copyFile, mkdir, readdir, symlink, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readdir, readlink, rm, symlink, writeFile } from 'node:fs/promises'
 import type { OnResolveResult, Plugin } from 'esbuild'
 import { build } from '../utils/esbuild'
 import { drainPreplanBuilds, vendorTraceEnabled, vendorTraceRow } from '../runtime/vendor'
@@ -12,7 +12,7 @@ import {
   clientReferenceModuleSource,
   hasUseClientDirective,
 } from '../client/reference-stub'
-import { noteCompiledClientReference } from '../client/reference'
+import { noteCompiledClientReference, ssrClientReference } from '../client/reference'
 import { getClientActionBundler } from '../dev/client-actions'
 import { deferredDynamicImportSpecifiers, devDynamicSplitEnabled } from '../resolve/dynamic'
 import { noteModuleGeneration, noteModuleImported } from './module-generations'
@@ -54,7 +54,11 @@ import {
   resolveExternalLoadTarget,
   resolvePackageSpecifier,
 } from '../resolve/imports'
-import { importSpecifiers, rewriteSpecifierLiterals } from '../resolve/scan-facts'
+import {
+  importSpecifiers,
+  moduleSpecifierEdges,
+  rewriteSpecifierLiterals,
+} from '../resolve/scan-facts'
 import {
   cacheRoot,
   devArtifactUsable,
@@ -102,6 +106,44 @@ let buildActive = 0
 const buildQueue: (() => void)[] = []
 const moduleBuilds = new Map<string, Promise<string>>()
 const routeBundleBuilds = new Map<string, Promise<string>>()
+// A cache hit from THIS process is safe after its entry drain, but a production
+// build also has a warm child filling the same content-addressed directory.
+// That other process can atomically publish an importer before its slower
+// dependency. Cache each artifact's parsed static edges, but re-check those
+// members on every acceptance: a later phase may remove a dependency that was
+// present during an earlier check. This avoids repeated reads/parses without
+// turning one observation into a permanent claim that the closure still exists.
+const completeArtifactClosures = new Map<string, readonly string[]>()
+let moduleGraphFailure: Error | undefined
+
+/** Reset build-only graph state before starting another build in this process. */
+export function resetModuleGraphFailure(): void {
+  moduleGraphFailure = undefined
+  completeArtifactClosures.clear()
+}
+
+/**
+ * Fail a build even when its renderer converted a module-resolution exception
+ * into a 500 response. Rendering may recover from user-code errors, but a
+ * missing content-addressed artifact means the build output itself is broken.
+ */
+export function throwIfModuleGraphFailed(): void {
+  if (moduleGraphFailure !== undefined) throw moduleGraphFailure
+}
+
+function noteModuleGraphFailure(error: unknown): void {
+  moduleGraphFailure ??= error instanceof Error ? error : new Error(String(error))
+}
+
+function isCompiledModuleResolutionError(error: unknown, href: string): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  if (!message.includes('Cannot find module')) return false
+  return (
+    href.includes('/cache/server/') ||
+    /[/\\]cache[/\\]server[/\\]/.test(message) ||
+    message.includes('/cache/server/')
+  )
+}
 
 // PNEXT_TRACE=server: attribute every per-module compile to its profile,
 // so cross-profile duplicate work is countable rather than inferred. Counts are
@@ -186,6 +228,9 @@ const routeModuleLoaders = new Map<string, Promise<DevRouteModuleLoaders>>()
 // request. Compiled hrefs are content-addressed, so a save that fixes the module yields a new href
 // and the entry is never consulted again.
 const moduleEvalErrors = new Map<string, unknown>()
+const warmRetryHrefs = new Map<string, Promise<string>>()
+const warmImports = new Map<string, Promise<void>>()
+let warmRetryGeneration = 0
 
 /**
  * Import a compiled module, re-throwing its first evaluation error on later imports.
@@ -200,20 +245,81 @@ export async function importModuleOnce<T>(href: string): Promise<T> {
   try {
     return (await import(href)) as T
   } catch (error) {
+    if (isCompiledModuleResolutionError(error, href)) noteModuleGraphFailure(error)
     moduleEvalErrors.set(href, error)
     throw error
   }
 }
 
+interface ImportDevModuleOptions {
+  /** A speculative import whose evaluation failure must not become render state. */
+  warm?: boolean
+}
+
+async function nextWarmRetryHref(href: string) {
+  const url = new URL(href)
+  const generation = ++warmRetryGeneration
+  if (url.protocol !== 'file:') {
+    url.searchParams.set('pnext-warm-retry', String(generation))
+    return url.href
+  }
+  // Bun keys failed file imports by their underlying path even when the URL query changes. Copy the
+  // immutable content-addressed artifact beside itself: the distinct path retries its top-level
+  // evaluation, while the shared directory keeps all relative imports resolving identically.
+  const source = fileURLToPath(url)
+  const extension = path.extname(source)
+  const stem = extension ? source.slice(0, -extension.length) : source
+  const retry = `${stem}.pnext-warm-retry-${generation}${extension}`
+  await copyFile(source, retry)
+  return pathToFileHref(retry)
+}
+
 /** `importModuleOnce` plus dev's registry-generation accounting. */
-export async function importDevModule<T>(href: string): Promise<T> {
-  if (moduleEvalErrors.has(href)) throw moduleEvalErrors.get(href)
-  // Pre-planned vendor builds are enqueued without an awaiter; nothing
-  // evaluates until they all settle (no-op when the pipeline is empty).
-  await drainPreplanBuilds()
-  const module = await importModuleOnce<T>(href)
-  noteModuleImported(href)
-  return module
+export async function importDevModule<T>(
+  href: string,
+  options: ImportDevModuleOptions = {},
+): Promise<T> {
+  const warming = warmImports.get(href)
+  if (warming) {
+    await warming
+    return importDevModule<T>(href)
+  }
+
+  let finishWarm: (() => void) | undefined
+  let warmSettled: Promise<void> | undefined
+  if (options.warm) {
+    warmSettled = new Promise(resolve => {
+      finishWarm = resolve
+    })
+    warmImports.set(href, warmSettled)
+  }
+
+  let importHref = href
+  let attemptedEvaluation = false
+  try {
+    importHref = (await warmRetryHrefs.get(href)) ?? href
+    if (moduleEvalErrors.has(importHref)) throw moduleEvalErrors.get(importHref)
+    // Pre-planned vendor builds are enqueued without an awaiter; nothing
+    // evaluates until they all settle (no-op when the pipeline is empty).
+    await drainPreplanBuilds()
+    attemptedEvaluation = true
+    const module = await importModuleOnce<T>(importHref)
+    noteModuleImported(href)
+    return module
+  } catch (error) {
+    if (options.warm && attemptedEvaluation) {
+      // Bun retains a failed ESM evaluation in its registry. Drop our first-error record and give
+      // the real render a fresh module identity, so speculative work can never poison the request.
+      const retryHref = nextWarmRetryHref(href)
+      warmRetryHrefs.set(href, retryHref)
+      if (moduleEvalErrors.get(importHref) === error) moduleEvalErrors.delete(importHref)
+      await retryHref
+    }
+    throw error
+  } finally {
+    finishWarm?.()
+    if (warmSettled && warmImports.get(href) === warmSettled) warmImports.delete(href)
+  }
 }
 const extensionlessDynamicImportExtensions = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts'])
 const externalLoadNamespaces = {
@@ -466,6 +572,7 @@ export async function devServerModuleHref(
       bundleExternalPackages: reactCompatEnabled(config),
     })
     await drainModuleBuilds(visited)
+    assertCompiledArtifactClosure(compiled)
     return pathToFileHref(compiled)
   } finally {
     release()
@@ -491,6 +598,7 @@ export async function devClientModuleHref(
       clientLayerOptions(config, conditionTarget),
     )
     await drainModuleBuilds(visited)
+    assertCompiledArtifactClosure(compiled)
     return pathToFileHref(compiled)
   } finally {
     release()
@@ -617,46 +725,12 @@ function startRouteVendorStage(config: ResolvedConfig, route: RouteManifestEntry
   if (process.env.PNEXT_DISABLE_VENDOR_STAGE) return
   if (!reactCompatEnabled(config)) return
   const conditionTarget = serverBundleTargetForRuntime(route.segmentConfig?.runtime)
-  const options: DevModuleOptions = {
-    aliases: coreAliases(config, 'server'),
-    profile: 'compat',
-    conditionTarget,
-    externalLoadTarget: externalLoadTargetForConditionTarget(conditionTarget),
-    stubClientImports: true,
-    rewriteExternalServerImports: true,
-    bundleExternalPackages: true,
-  }
-  // Only the SERVER vendor layer is seeded here: the client-reference walk already fans the
-  // client-SSR demand out, so seeding that layer too only competes for the JS thread.
-  //
-  // Layered seeding: a separate walk pruned at 'use client' boundaries, so client-only packages get
-  // no server-target builds. On-demand fallback covers anything needed sooner.
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const layered = process.env.PNEXT_VENDOR_SEED_LAYERED !== '0'
   const seedT0 = performance.now()
   void (async () => {
-    const graph = devModuleGraph(config)
-    const demand = new Set<string>()
-    const dropped = new Set<string>()
-    // The layer of a source is part of the record the naming walk just scanned,
-    // so the seed reads it instead of re-reading the whole route graph.
-    const prune = (file: string) =>
-      (devHeadTrimEnabled() ? graph.isClientSource(file) : fileHasUseClientDirective(file)).catch(
-        () => false,
-      )
-    for (const file of files) {
-      const full = await graph.packageDemand(file)
-      const serverReachable = layered ? new Set(await graph.packageDemand(file, prune)) : undefined
-      for (const specifier of full) {
-        if (!shouldBundleExternalPackage(specifier, config, file, options)) continue
-        if (serverReachable && !serverReachable.has(specifier)) dropped.add(specifier)
-        else demand.add(specifier)
-      }
-    }
-    for (const specifier of demand) dropped.delete(specifier)
+    const { demand, dropped, layered } = await devVendorSeedSplit(config, route, files)
     if (traceEnabled('server')) {
       console.log(
-        `dev-import vendor seed walk ${route.route} in ${formatDuration(performance.now() - seedT0)} (kept ${demand.size}, dropped ${dropped.size})`,
+        `dev-import vendor seed walk ${route.route} in ${formatDuration(performance.now() - seedT0)} (kept ${demand.length}, dropped ${dropped.length})`,
       )
     }
     if (vendorTraceEnabled()) {
@@ -685,6 +759,64 @@ function startRouteVendorStage(config: ResolvedConfig, route: RouteManifestEntry
   })().catch(() => undefined)
 }
 
+/**
+ * The seed's split of a route's package demand: what the SERVER layer will ask for, and what only a
+ * client subtree reaches (which the client-SSR pass demands at its own target, so a server build of
+ * it is work nothing consumes).
+ *
+ * Only the SERVER vendor layer is seeded: the client-reference pass fans the client-SSR demand out
+ * itself, so seeding that layer too only competes for the JS thread.
+ *
+ * @internal Exported as a test seam - the split is otherwise only visible as timing.
+ */
+export async function devVendorSeedSplit(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  files: string[],
+) {
+  const conditionTarget = serverBundleTargetForRuntime(route.segmentConfig?.runtime)
+  const options: DevModuleOptions = {
+    aliases: coreAliases(config, 'server'),
+    profile: 'compat',
+    conditionTarget,
+    externalLoadTarget: externalLoadTargetForConditionTarget(conditionTarget),
+    stubClientImports: true,
+    rewriteExternalServerImports: true,
+    bundleExternalPackages: true,
+  }
+  // Layered seeding: a separate walk pruned at 'use client' boundaries, so client-only packages get
+  // no server-target builds. On-demand fallback covers anything needed sooner.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const layered = process.env.PNEXT_VENDOR_SEED_LAYERED !== '0'
+  const graph = devModuleGraph(config)
+  const demand = new Set<string>()
+  const dropped = new Set<string>()
+  // The layer of a source is part of the record the naming walk just scanned,
+  // so the seed reads it instead of re-reading the whole route graph.
+  const clientSource = (file: string) =>
+    (devHeadTrimEnabled() ? graph.isClientSource(file) : fileHasUseClientDirective(file)).catch(
+      () => false,
+    )
+  // A file the route bundle names as a SERVER entry is never a boundary: `writeDevRouteBundle` loads
+  // every layout (and a server page) through the server namespace whatever its directive, so pruning
+  // one would drop exactly the packages the bundle then demands - serially, mid-request, in front of
+  // the response.
+  const serverEntries = new Set(files.map(file => path.resolve(file)))
+  if (route.client) serverEntries.delete(path.resolve(route.file))
+  const prune = (file: string) => (serverEntries.has(file) ? false : clientSource(file))
+  for (const file of files) {
+    const full = await graph.packageDemand(file)
+    const serverReachable = layered ? new Set(await graph.packageDemand(file, prune)) : undefined
+    for (const specifier of full) {
+      if (!shouldBundleExternalPackage(specifier, config, file, options)) continue
+      if (serverReachable && !serverReachable.has(specifier)) dropped.add(specifier)
+      else demand.add(specifier)
+    }
+  }
+  for (const specifier of demand) dropped.delete(specifier)
+  return { demand: [...demand], dropped: [...dropped], layered }
+}
+
 export async function devRouteModuleLoaders(
   config: ResolvedConfig,
   route: RouteManifestEntry,
@@ -744,9 +876,17 @@ async function createDevRouteModuleLoaders(
       }),
     )
   }
+  const batched = new Set(devClientReferenceGroups(config, route).batched)
   const clientModuleLoader = async (file: string) => {
     const module = bundle.clientModules[file]
     if (module) return module
+    // The batched client-reference pass owns this file: join its one compile
+    // instead of starting a per-module walk over the same graph.
+    if (batched.has(path.resolve(file))) {
+      const modules = await devClientReferenceModules(config, route).catch(() => undefined)
+      const batchedModule = modules?.[path.resolve(file)]
+      if (batchedModule) return batchedModule
+    }
     return importDevModule<Record<string, unknown>>(
       await devClientModuleHref(
         config,
@@ -759,6 +899,193 @@ async function createDevRouteModuleLoaders(
   return { moduleLoader, clientModuleLoader }
 }
 
+/**
+ * The route's SSR-able client references, split by who compiles them. `batched` is one esbuild pass
+ * over the whole set (the client-SSR layer's own bundle, below); `perModule` is what the pass cannot
+ * own and the per-file walk still names:
+ *
+ * - a reference inside node_modules SSRs through its package's client vendor bundle
+ *   (`packageClientModuleHref`), so bundling a second copy here would split the package's singletons;
+ * - a pages-router source SSRs under a different condition target than the bundle's client layer.
+ */
+export function devClientReferenceGroups(config: ResolvedConfig, route: RouteManifestEntry) {
+  const batched: string[] = []
+  const perModule: string[] = []
+  const seen = new Set<string>()
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const bundling = reactCompatEnabled(config) && process.env.PNEXT_DEV_CLIENT_REF_BUNDLE !== '0'
+  const target = serverBundleTargetForRuntime(route.segmentConfig?.runtime)
+  for (const reference of route.clientReferences) {
+    if (!ssrClientReference(reference) || seen.has(reference.file)) continue
+    seen.add(reference.file)
+    const file = path.resolve(reference.file)
+    const batchable =
+      bundling &&
+      existsSync(file) &&
+      !isCssFile(file) &&
+      !nodeModulesPackageDir(file) &&
+      clientLayerConditionTarget(config, file, target) === 'client'
+    // The pass names its entries by resolved path (that is the key a module out
+    // of it carries); everything else keeps the reference's own name, which is
+    // what the per-file walk has always been handed.
+    if (batchable) batched.push(file)
+    else perModule.push(reference.file)
+  }
+  return { batched, perModule }
+}
+
+// Keyed on the bundle's own content-addressed path, so a save that renames it
+// never hands back the previous graph's modules.
+const clientReferenceModules = new Map<string, Promise<Record<string, Record<string, unknown>>>>()
+const clientReferenceBundleBuilds = new Map<string, Promise<string>>()
+// Bundle names memoized per reference set; a save may rename any of them, so
+// `clearDevRouteBundleKeys` drops these with the route bundle's own names.
+const clientReferenceBundleKeys = new Map<string, Promise<string>>()
+
+/**
+ * Every batchable client reference of the route, compiled in ONE esbuild pass and evaluated once.
+ * The per-module walk it replaces re-entered the compile pipeline for each reference and each of its
+ * imports, which is the dev first page's long pole; the pass names the same client-SSR layer
+ * (`clientSsrAliases`, client conditions, packages through their vendor bundles), so a module out of
+ * it is the same artifact the walk would have produced - and the render joins this promise through
+ * `clientModuleLoader` rather than compiling its own.
+ */
+export async function devClientReferenceModules(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  options: { evaluate?: boolean } = {},
+) {
+  const { batched } = devClientReferenceGroups(config, route)
+  if (batched.length === 0) return undefined
+  const release = devModuleGraph(config).hold()
+  const outFile = await devClientReferenceBundlePath(config, route, batched).catch(error => {
+    release()
+    throw error
+  })
+  if (options.evaluate === false) {
+    await writeDevClientReferenceBundle(config, route, batched, outFile).finally(release)
+    return undefined
+  }
+  const existing = clientReferenceModules.get(outFile)
+  if (existing) {
+    release()
+    return existing
+  }
+  const next = loadDevClientReferenceModules(config, route, batched, outFile)
+    .catch(error => {
+      clientReferenceModules.delete(outFile)
+      throw error
+    })
+    .finally(release)
+  clientReferenceModules.set(outFile, next)
+  return next
+}
+
+async function loadDevClientReferenceModules(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  files: string[],
+  outFile: string,
+) {
+  const bundleFile = await writeDevClientReferenceBundle(config, route, files, outFile)
+  const bundle = await profileDevImport(`import client references ${route.route}`, () =>
+    // Warm import: a reference that throws while evaluating speculatively must not leave Bun's
+    // registry holding the failure for the render that asks for it next.
+    importDevModule<DevRouteBundle>(pathToFileHref(bundleFile), { warm: true }),
+  )
+  return bundle.clientModules
+}
+
+/**
+ * Named by the whole source graph of every reference in it, exactly like the route bundle. Memoized
+ * on the reference set so concurrent demands (boot warm, request preload, the render itself) await
+ * ONE name and therefore meet each other in the load memo below instead of each starting a pass.
+ */
+function devClientReferenceBundlePath(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  files: string[],
+) {
+  const memoKey = `${route.id}\0${files.join('\0')}`
+  const memoized = clientReferenceBundleKeys.get(memoKey)
+  if (memoized) return memoized
+  const next = computeDevClientReferenceBundlePath(config, route, files).catch(error => {
+    clientReferenceBundleKeys.delete(memoKey)
+    throw error
+  })
+  clientReferenceBundleKeys.set(memoKey, next)
+  return next
+}
+
+async function computeDevClientReferenceBundlePath(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  files: string[],
+) {
+  const graph = devModuleGraph(config)
+  const hashes = await Promise.all(files.map(file => graph.graphHash(file)))
+  const hash = createHash('sha256').update(hashes.join('\0')).digest('hex').slice(0, 16)
+  const bundle = path.join(
+    cacheRoot(config.outPath),
+    'client-refs',
+    `${route.id}.${hash}.client-refs.mjs`,
+  )
+  noteModuleGeneration(`client-refs:${route.route}`, bundle)
+  return bundle
+}
+
+async function writeDevClientReferenceBundle(
+  config: ResolvedConfig,
+  route: RouteManifestEntry,
+  files: string[],
+  outFile: string,
+) {
+  if (devArtifactUsable(outFile)) return outFile
+
+  const existing = clientReferenceBundleBuilds.get(outFile)
+  if (existing) return existing
+
+  const next = profileDevImport(`build client references ${route.route}`, async () => {
+    await mkdir(path.dirname(outFile), { recursive: true })
+    const result = await withBuildSlot(() =>
+      build({
+        stdin: {
+          contents: routeBundleEntrySource([], files),
+          loader: 'ts',
+          resolveDir: config.root,
+          sourcefile: `${route.id}.client-references.ts`,
+        },
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'neutral',
+        target: 'es2022',
+        loader: { '.js': 'jsx', '.mjs': 'jsx' },
+        jsx: 'automatic',
+        jsxImportSource: 'preact',
+        packages: 'external',
+        logLevel: 'silent',
+        ...serverDefineOptions(),
+        plugins: [
+          serverAssetPlugin(config),
+          devRouteBundlePlugin(config, route),
+          ...getBundlerExtensions().serverEsbuildPlugins(config),
+        ],
+      }),
+    )
+    const output = result.outputFiles[0]
+    if (!output) throw new Error(`Failed to build dev client references for ${route.route}`)
+    await writeCompiledFile(outFile, output.text)
+    return outFile
+  }).catch(error => {
+    clientReferenceBundleBuilds.delete(outFile)
+    throw error
+  })
+
+  clientReferenceBundleBuilds.set(outFile, next)
+  return next
+}
+
 interface DevRouteBundle {
   modules: Record<string, Record<string, unknown>>
   clientModules: Record<string, Record<string, unknown>>
@@ -907,12 +1234,17 @@ function devRouteBundlePlugin(config: ResolvedConfig, route: RouteManifestEntry)
       registerExternalLoadHandlers(build, config, serverOptions, externalLoadNamespaces.server)
       registerExternalLoadHandlers(build, config, clientOptions, externalLoadNamespaces.client)
 
+      // `resolveDir` is what an unclaimed specifier resolves against: the asset and loader-rule
+      // plugins fall back to esbuild's own resolution, and a module in a plugin namespace has no
+      // directory of its own - without this a `./x.module.css` next to its importer is looked for at
+      // the process cwd, exactly as if the per-module path had compiled it from the wrong folder.
       build.onLoad({ filter: /.*/, namespace: 'pnext-route-server' }, async args => ({
         contents: rewriteServerSource(await readText(args.path), args.path, {
           nextFonts: nextCompatEnabled(config),
           root: config.root,
         }),
         loader: esbuildLoader(args.path),
+        resolveDir: path.dirname(args.path),
       }))
       build.onLoad({ filter: /.*/, namespace: 'pnext-route-client' }, async args => {
         // A client-side import of a 'use server' module becomes the RPC stub.
@@ -921,6 +1253,7 @@ function devRouteBundlePlugin(config: ResolvedConfig, route: RouteManifestEntry)
           return {
             contents: await clientActions.stubSource(args.path),
             loader: 'js',
+            resolveDir: path.dirname(args.path),
           }
         }
         return {
@@ -929,6 +1262,7 @@ function devRouteBundlePlugin(config: ResolvedConfig, route: RouteManifestEntry)
             root: config.root,
           }),
           loader: esbuildLoader(args.path),
+          resolveDir: path.dirname(args.path),
         }
       })
       build.onLoad({ filter: /.*/, namespace: 'pnext-client-reference' }, async args => ({
@@ -937,6 +1271,7 @@ function devRouteBundlePlugin(config: ResolvedConfig, route: RouteManifestEntry)
           await clientReferenceExportNames(config, args.path),
         ),
         loader: 'js',
+        resolveDir: path.dirname(args.path),
       }))
     },
   }
@@ -1095,6 +1430,108 @@ async function writeCompiledFile(file: string, contents: string) {
   }
 }
 
+/**
+ * Whether every file URL reachable from a compiled artifact is already on
+ * disk. Individual files publish atomically, but the graph is a set of files:
+ * the build's warm child can expose an importer to the parent before it has
+ * exposed that importer's slower sibling. A mere existsSync(importer) is
+ * therefore not a complete-cache invariant across processes.
+ */
+function missingCompiledArtifact(entry: string): string | undefined {
+  const root = compiledArtifactProfileRoot(entry)
+  if (!root) return existsSync(entry) ? undefined : entry
+
+  const visiting = new Set<string>()
+  const visit = (file: string): string | undefined => {
+    if (visiting.has(file)) return undefined
+    if (!existsSync(file)) return file
+    // Raw framework/package file URLs are ordinary immutable dependencies, not
+    // members of the materialized graph whose publication order we own.
+    if (!isInside(root, file) || !compiledScriptFilePattern.test(file)) return undefined
+
+    visiting.add(file)
+    const cachedTargets = completeArtifactClosures.get(file)
+    if (cachedTargets) {
+      for (const target of cachedTargets) {
+        const missing = visit(target)
+        if (missing) return missing
+      }
+      visiting.delete(file)
+      return undefined
+    }
+
+    let source: string
+    try {
+      source = readFileSync(file, 'utf8')
+    } catch {
+      return file
+    }
+    const targets: string[] = []
+    for (const { specifier, kind } of moduleSpecifierEdges(source, file)) {
+      // A dynamic import is an on-demand publication boundary: its target may
+      // belong to a later client-chunk phase even when both artifacts share a
+      // profile directory. Static imports must be complete before evaluation.
+      if (kind === 'dynamic') continue
+      const { sourcePath } = splitHash(specifier)
+      if (!sourcePath.startsWith('file://')) continue
+      let target: string
+      try {
+        target = fileURLToPath(sourcePath)
+      } catch {
+        return sourcePath
+      }
+      if (!isInside(root, target)) {
+        if (existsSync(target)) continue
+        const emittedRoot = compiledArtifactProfileRoot(target)
+        // A different profile is produced by a separate build phase. Only a
+        // dead reference to this same profile can be a relocated cache member.
+        if (!emittedRoot || path.basename(emittedRoot) !== path.basename(root)) continue
+        target = path.resolve(root, path.relative(emittedRoot, target))
+      }
+      const missing = visit(target)
+      if (missing) return missing
+      targets.push(target)
+    }
+    completeArtifactClosures.set(file, targets)
+    visiting.delete(file)
+    return undefined
+  }
+
+  return visit(entry)
+}
+
+/** Accept a complete hit, or join the exact missing member already being published locally. */
+function compiledArtifactReadyOrCompleting(entry: string, visited: Set<string>): boolean {
+  if (!devArtifactUsable(entry)) return false
+  const missing = missingCompiledArtifact(entry)
+  if (!missing) return true
+  const completing = moduleBuilds.get(missing)
+  if (!completing) return false
+  ownedBuilds(visited).add(completing)
+  return true
+}
+
+function assertCompiledArtifactClosure(entry: string): void {
+  const missing = missingCompiledArtifact(entry)
+  if (!missing) return
+  const error = new Error(`incomplete server module graph ${entry}: ${missing}`)
+  noteModuleGraphFailure(error)
+  throw error
+}
+
+function compiledArtifactProfileRoot(file: string): string | undefined {
+  const marker = `${path.sep}cache${path.sep}server${path.sep}`
+  const index = file.lastIndexOf(marker)
+  if (index < 0) return undefined
+  const profileStart = index + marker.length
+  const profileEnd = file.indexOf(path.sep, profileStart)
+  if (profileEnd < 0) return undefined
+  const profile = file.slice(profileStart, profileEnd)
+  return profile === 'modules' || profile.startsWith('modules-')
+    ? file.slice(0, profileEnd)
+    : undefined
+}
+
 /** Where `file` compiles to under `profile`, named by its current source graph. */
 async function devModulePathFor(config: ResolvedConfig, file: string, profile: string) {
   return devServerPath(config, file, profile, await devModuleGraph(config).graphHash(file))
@@ -1116,11 +1553,11 @@ async function writeDevModule(
   noteModuleGeneration(visitedKey, outFile)
   if (visited.has(visitedKey)) return outFile
 
-  // The name carries the hash of this module's whole source graph, so an existing artifact is by
-  // construction current. An unusable one (the cache folder was wiped from outside) falls through to
-  // recompile, which overwrites it in place - never delete first, since Bun caches a failed resolution for
-  // the life of the process.
-  if (devArtifactUsable(outFile)) return outFile
+  // The name carries the hash of this module's whole source graph, so an existing artifact is current.
+  // It is reusable only when its emitted closure is present too: another process may have published the
+  // importer first. An unusable artifact falls through to recompile and is overwritten in place - never
+  // delete first, since Bun caches a failed resolution for the life of the process.
+  if (compiledArtifactReadyOrCompleting(outFile, visited)) return outFile
 
   // Already being built: its artifact path is all this caller needs, and the entry's drain is what
   // waits for the bytes. Awaiting it here is what used to deadlock two walks meeting a cycle. The
@@ -1170,6 +1607,7 @@ async function writeDevModuleUncached(
     return outFile
   }
 
+  let source: string | undefined
   // A client-profile compile of a 'use server' module emits the RPC stub, so
   // the browser bundle POSTs to the endpoint instead of shipping server code.
   if (options.profile === 'client' && nextCompatEnabled(config)) {
@@ -1180,10 +1618,16 @@ async function writeDevModuleUncached(
         await writeCompiledFile(outFile, await clientActions.stubSource(file))
         return outFile
       }
+      const loaded = await clientActions.loadClientSource(file, config.root)
+      source = loaded.source
+      if (loaded.stubSource !== undefined) {
+        await writeCompiledFile(outFile, loaded.stubSource)
+        return outFile
+      }
     }
   }
 
-  let source = await readText(file)
+  source ??= await readText(file)
   if (/\.mdx?$/.test(file) && nextCompatEnabled(config)) {
     // Markdown modules must be compiled to JS before import analysis and the
     // stdin-based bundle pass (which bypasses file-resolved onLoad plugins).
@@ -1263,10 +1707,31 @@ async function writeDevModuleUncached(
       .map(({ target }) => writeDevModule(config, target, visited, effectiveOptions)),
   ])
 
-  await writeCompiledFile(outFile, await compiled)
+  const compiledSource = await compiled
+  if (skipModuleWriteForTest(file)) return outFile
+  await delayWarmModuleWriteForTest(file)
+  await writeCompiledFile(outFile, compiledSource)
   return outFile
 }
 
+/** Test-only seam for proving an irreparable incomplete graph fails the build. */
+function skipModuleWriteForTest(file: string) {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const suffix = process.env.PNEXT_TEST_SKIP_MODULE_WRITE
+  return Boolean(suffix && file.endsWith(suffix))
+}
+
+/** Test-only seam for forcing the build/warm-child partial-graph publication window. */
+async function delayWarmModuleWriteForTest(file: string) {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const setting = process.env.PNEXT_TEST_DELAY_WARM_MODULE_WRITE
+  if (!setting || !process.argv.some(argument => argument.endsWith('vercel-warm.ts'))) return
+  const separator = setting.lastIndexOf(':')
+  if (separator < 1 || !file.endsWith(setting.slice(0, separator))) return
+  const delay = Number(setting.slice(separator + 1))
+  if (Number.isFinite(delay) && delay > 0) await Bun.sleep(delay)
+}
+
 const shakeEntrySpecifier = 'pnext-shake-entry'
 const shakeEntryNamespace = 'pnext-shake-entry'
 
@@ -1361,7 +1826,7 @@ async function writeShakenDynamicModule(
 ): Promise<string> {
   const profile = devModuleProfile(options)
   const outFile = await shakenModulePath(config, targetFile, profile, shakeExportsKey(usedExports))
-  if (devArtifactUsable(outFile)) return outFile
+  if (compiledArtifactReadyOrCompleting(outFile, visited)) return outFile
 
   const key = `shake\0${outFile}`
   if (moduleBuilds.has(key)) return outFile
@@ -2543,6 +3008,7 @@ const routeBundleKeys = new Map<string, Promise<string>>()
 /** A save may rename any route bundle: drop every memoized name. */
 export function clearDevRouteBundleKeys() {
   routeBundleKeys.clear()
+  clientReferenceBundleKeys.clear()
 }
 
 // The route bundle inlines the route file and its layouts, so its name carries
@@ -2698,11 +3164,7 @@ async function linkDirectoryAssetContext(
         await writeText(target, await stagedManifestSource(source))
         return
       }
-      try {
-        await symlink(source, target, 'file')
-      } catch {
-        if (!existsSync(target)) await copyFile(source, target)
-      }
+      await linkOrCopyAsset(source, target)
     }),
   )
 }
@@ -2720,6 +3182,29 @@ async function stagedManifestSource(file: string) {
 // into subdirectories, but never link code files — those compile through the
 // module graph into their own staged output and must not be shadowed by a raw
 // symlink.
+/** Stage an asset, repairing a dangling link left by cache relocation. */
+async function linkOrCopyAsset(source: string, target: string) {
+  const resolvedSource = path.resolve(source)
+  // Concurrent walkers keep a repaired link and remove only the stale target.
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    try {
+      await symlink(source, target, 'file')
+      return
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') break
+    }
+    try {
+      const linked = await readlink(target)
+      if (path.resolve(path.dirname(target), linked) === resolvedSource) return
+      await rm(target, { force: true })
+    } catch {
+      // It disappeared between EEXIST and inspection; retry the link.
+      if (existsSync(target)) return
+    }
+  }
+  if (!existsSync(target)) await copyFile(source, target)
+}
+
 async function mirrorAssetDirectory(sourceDir: string, targetDir: string) {
   let entries: Dirent<string>[]
   try {
@@ -2739,11 +3224,7 @@ async function mirrorAssetDirectory(sourceDir: string, targetDir: string) {
       if (isCodeFile(entry.name)) return
       if (existsSync(target)) return
       await mkdir(path.dirname(target), { recursive: true })
-      try {
-        await symlink(source, target, 'file')
-      } catch {
-        if (!existsSync(target)) await copyFile(source, target)
-      }
+      await linkOrCopyAsset(source, target)
     }),
   )
 }