@thomas.f/prnext 0.1.20-alpha → 0.1.21-alpha

package/build/app.mjs

@@ -7,7 +7,7 @@ import { createHash } from 'node:crypto';
 import { createRequire, builtinModules } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import * as t from '@babel/types';
-import {analyzeSource} from './source-analysis.mjs';
+import {analyzeSourceSummary} from './source-analysis.mjs';
 import { rewriteServerChunkOutputFiles } from './transform.mjs';
 import { transformDynamicImports } from './dynamic.mjs';
 import { createServerActions } from './actions.mjs';
@@ -47,13 +47,13 @@ export async function validateReactVersions(resolveFromProject) {
 
 function clientDirective(source, filename) {
   if (!source.includes('use client')) return false;
-  return analyzeSource(source,filename).directives.includes('use client');
+  return analyzeSourceSummary(source,filename).directives.includes('use client');
 }
 
 function frameworkDirective(source, filename) {
   if (clientDirective(source, filename)) return true;
   if (!source.includes('use server')) return false;
-  return analyzeSource(source,filename).hasServerDirective;
+  return analyzeSourceSummary(source,filename).hasServerDirective;
 }
 
 /** Enumerate runtime ESM exports without evaluating client code in the server build. */
@@ -61,7 +61,7 @@ export async function exportedNames(file, esbuild, seen = new Set()) {
   if (seen.has(file)) return new Set();
   seen.add(file);
   const source = await compilerSource(file);
-  const analysis=analyzeSource(source,file),names=new Set(analysis.runtimeExports);
+  const analysis=analyzeSourceSummary(source,file),names=new Set(analysis.runtimeExports);
   for (const specifier of analysis.exportStars) {
       const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(file), kind: 'import-statement', pluginData: { prnextExportScan: true } });
       if (resolved.errors.length || !resolved.path || resolved.external) throw new Error(`Cannot enumerate client boundary exports from ${specifier} in ${file}. Use explicit named re-exports.`);

package/build/build-timings.mjs

@@ -0,0 +1,38 @@
+import {AsyncLocalStorage} from 'node:async_hooks';
+
+const storage = new AsyncLocalStorage();
+const names = new Set(['configuration', 'discovery', 'runtime-inputs', 'pages-server', 'pages-browser', 'pages-output', 'middleware', 'metadata', 'app', 'instrumentation', 'types', 'runtime-bundle', 'prerender', 'native-ppr', 'retention', 'precompression', 'analysis', 'standalone', 'compiler-node', 'compiler-browser', 'compiler-edge']);
+
+/** Wall times include awaited native/compiler work; nested phases are not additive. */
+export async function withBuildTimings(run, clock = () => performance.now()) {
+  const state = {clock, started: clock(), phases: new Map()};
+  return storage.run(state, async () => {
+    try { return {result: await run(), timings: report(state)}; }
+    catch (error) {
+      // Diagnostics must never replace the original application/build failure.
+      try { if (error && typeof error === 'object') Object.defineProperty(error, 'buildTimings', {value: report(state), configurable: true}); } catch {}
+      throw error;
+    }
+  });
+}
+
+export async function measureBuildPhase(name, run) {
+  if (!names.has(name)) throw new TypeError('Unknown build timing phase');
+  const state = storage.getStore();
+  if (!state) return run();
+  const started = state.clock();
+  let failed = false;
+  try { return await run(); }
+  catch (error) { failed = true; throw error; }
+  finally {
+    const row = state.phases.get(name) || {calls: 0, failedCalls: 0, milliseconds: 0};
+    row.calls++; row.failedCalls += Number(failed); row.milliseconds += Math.max(0, state.clock() - started);
+    state.phases.set(name, row);
+  }
+}
+
+function report(state) {
+  return {version: 1, scope: 'build-wall-time-excluding-module-startup', nestedPhasesAreAdditive: false,
+    totalMilliseconds: Math.max(0, state.clock() - state.started),
+    phases: Object.fromEntries([...state.phases].map(([name, value]) => [name, {...value}]))};
+}

package/build/bundle-runtime.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {version as esbuildVersion} from 'esbuild';
 import {privateCacheDirectory,readCacheRecord,writeCacheRecord} from './persistent-cache.mjs';
+import {mapConcurrent} from './concurrent.mjs';
 
 // Paths used by the native worker, generated application modules, prerender,
 // standalone tracing, compatibility modules and the runtime lifecycle contract.
@@ -39,16 +40,15 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory,imageResp
   for (const name of selectedEntries) {
     if (!originals.some(entry => entry.name === `${name}.mjs`)) throw new Error(`Missing runtime entry ${name}.mjs`);
   }
-  const sources=new Map();
   // Production compiles the installed sources directly. Only generated stage
   // overrides (currently the bundled env loader) replace an installed module.
   // Hash and compile the same captured bytes; do not trust mtimes or skip app
   // graph callbacks. This avoids copying hundreds of modules into every stage.
-  for(const entry of originals){
+  const sources=new Map(await mapConcurrent(originals,async entry=>{
     let file=path.join(input,entry.name);
     if(sourceDirectory){const override=path.join(runtime,entry.name);const info=await lstat(override).catch(e=>{if(e.code!=='ENOENT')throw e;});if(info){if(!info.isFile()||info.isSymbolicLink())throw Error('Runtime overrides must be ordinary files');file=override;}}
-    sources.set(path.join(input,entry.name),await readFile(file));
-  }
+    return [path.join(input,entry.name),await readFile(file)];
+  },8));
   let directory,key,cached;
   if(projectRoot){
     directory=await privateCacheDirectory(projectRoot,'runtime-bundle-v2');
@@ -99,11 +99,11 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory,imageResp
   if(directory&&!validCache)await writeCacheRecord(directory,key,{files:[...emitted].map(([name,bytes])=>[name,Buffer.from(bytes).toString()])});
   // This is an unpublished, disposable stage. On any write failure buildProject
   // discards the stage and preserves the previous published build unchanged.
-  for (const [name, contents] of emitted) await writeFile(path.join(runtime, name), contents);
-  for (const entry of await readdir(runtime,{withFileTypes:true})) {
-    if(!entry.name.endsWith('.mjs')||!entry.isFile())continue;
+  await mapConcurrent(emitted,async([name,contents])=>writeFile(path.join(runtime,name),contents),8);
+  await mapConcurrent(await readdir(runtime,{withFileTypes:true}),async entry=>{
+    if(!entry.name.endsWith('.mjs')||!entry.isFile())return;
     if (!emitted.has(entry.name)) await unlink(path.join(runtime, entry.name));
-  }
+  },8);
   // JSON, CJS, license files and the OG assets directory are never traversed or
   // removed. The caller writes the normal runtime contract after prerender.
   return { entryCount: selectedEntries.length, moduleCount: emitted.size,cached:!!validCache,

package/build/compiler.mjs

@@ -19,6 +19,7 @@ import {recordDevDependencies,developmentDependencies,developmentStylePlans,deve
 import {normalizeReactCompilerConfig,reactCompilerVersion} from './react-compiler.mjs';
 import {withReactCompilerReporting,configureReactCompilerReporting,withReactCompilerGraph,recordReactCompilerGraph} from './react-compiler-report.mjs';
 import {withCompilationGraphCacheReporting,cachedGraphBuild} from './compilation-cache.mjs';
+import {measureBuildPhase} from './build-timings.mjs';
 export {reactCompilerReport} from './react-compiler-report.mjs';
 export {compilationGraphCacheReport} from './compilation-cache.mjs';
 
@@ -150,7 +151,7 @@ export async function build(options, { role = 'main' } = {}) {
   const state=compilation.getStore();
   const target=options.define?.['process.env.NEXT_RUNTIME']==='"edge"'?'edge':options.platform==='browser'?'browser':'node';
   return withReactCompilerGraph(target,async()=>{
-    const result=await compileGraph(options,role);
+    const result=await measureBuildPhase('compiler-'+target,()=>compileGraph(options,role));
     recordReactCompilerGraph(result);
     recordBuildAnalysis(state,options,result);
     recordDevDependencies(state,options,result);

package/build/flight-summary.mjs

@@ -0,0 +1,64 @@
+const phases = ['rsc', 'ssr'];
+const outcomes = ['completed', 'failed', 'cancelled', 'timedOut'];
+const bytes = value => Number.isSafeInteger(value) && value >= 0 && value <= 32 * 1024 * 1024;
+const duration = value => Number.isFinite(value) && value >= 0 && value <= 86400000;
+const quantile = (values, q) => values.length ? [...values].sort((a,b)=>a-b)[Math.ceil(values.length*q)-1] : null;
+
+// A route pattern is supplied by the framework, never inferred from a URL.
+// Copy only this schema from disk; old/corrupted/foreign diagnostic events cannot
+// contribute arbitrary properties, unbounded groups or non-finite metrics.
+export function flightSamples(events) {
+  return events.filter(event => event?.type === 'flight' && phases.includes(event.phase) && outcomes.includes(event.outcome) &&
+    typeof event.route === 'string' && event.route.length <= 256 && !/[\0\r\n]/.test(event.route) &&
+    Number.isSafeInteger(event.time) && event.time >= 0 && event.time <= 18446744073709 &&
+    bytes(event.flightBytes) && bytes(event.flightChunks) && bytes(event.responseBytes) && bytes(event.peakQueuedBytes) && duration(event.durationMs))
+    .slice(-10000).map(event => ({type:'flight',route:event.route,phase:event.phase,outcome:event.outcome,time:event.time,
+      method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(event.method)?event.method:'_OTHER',
+      durationMs:event.durationMs,flightBytes:event.flightBytes,flightChunks:event.flightChunks,responseBytes:event.responseBytes,peakQueuedBytes:event.peakQueuedBytes,
+      ...Object.fromEntries(['firstChunkMs','modelReadyMs','shellReadyMs'].filter(key=>duration(event[key])).map(key=>[key,event[key]])),
+      ...(['direct','normalized'].includes(event.ppr)?{ppr:event.ppr}:{})}));
+}
+
+export function summarizeFlight(events) {
+  const groups = new Map(), sample = flightSamples(events);
+  for (const event of sample) {
+    const key = JSON.stringify([event.route,event.phase]);
+    if (!groups.has(key)) {
+      if (groups.size >= 256) continue;
+      groups.set(key,{route:event.route,phase:event.phase,events:[]});
+    }
+    groups.get(key).events.push(event);
+  }
+  const routes = [...groups.values()].map(({events,...group})=>{
+    const completed=events.filter(event=>event.outcome==='completed');
+    const p95=key=>quantile(completed.map(event=>event[key]).filter(value=>Number.isFinite(value)),.95);
+    return {...group,samples:events.length,...Object.fromEntries(outcomes.map(outcome=>[outcome,events.filter(event=>event.outcome===outcome).length])),
+      flightP50Bytes:quantile(completed.map(event=>event.flightBytes),.5),flightP95Bytes:p95('flightBytes'),
+      responseP95Bytes:p95('responseBytes'),durationP95Ms:p95('durationMs'),firstChunkP95Ms:p95('firstChunkMs'),
+      modelReadyP95Ms:p95('modelReadyMs'),shellReadyP95Ms:p95('shellReadyMs'),
+      peakQueuedBytes:events.reduce((max,event)=>Math.max(max,event.peakQueuedBytes),0),
+      directPprSamples:events.filter(event=>event.ppr==='direct').length,normalizedPprSamples:events.filter(event=>event.ppr==='normalized').length};
+  }).sort((a,b)=>(b.flightP95Bytes??-1)-(a.flightP95Bytes??-1)||a.route.localeCompare(b.route)||a.phase.localeCompare(b.phase));
+  return {flight:routes,flightSample:sample};
+}
+
+export function flightMetrics(events) {
+  const bounds=[1024,4096,16384,65536,131072,262144,1048576,4194304,16777216],groups=new Map();
+  for (const event of flightSamples(events).filter(value=>value.outcome==='completed')) {
+    const key=JSON.stringify([event.route,event.phase]);
+    if(!groups.has(key)){
+      if(groups.size>=256)continue;
+      groups.set(key,{route:event.route,phase:event.phase,start:event.time,end:event.time,values:[]});
+    }
+    const group=groups.get(key);group.values.push(event.flightBytes);group.start=Math.min(group.start,event.time);group.end=Math.max(group.end,event.time);
+  }
+  const dataPoints=[...groups.values()].map(group=>{
+    const buckets=Array(bounds.length+1).fill(0);
+    for(const value of group.values){const index=bounds.findIndex(bound=>value<=bound);buckets[index<0?bounds.length:index]++;}
+    return {attributes:[{key:'http.route',value:{stringValue:group.route}},{key:'prnext.render.phase',value:{stringValue:group.phase}}],
+      startTimeUnixNano:String(BigInt(group.start)*1000000n),timeUnixNano:String(BigInt(group.end)*1000000n),
+      count:String(group.values.length),sum:group.values.reduce((a,b)=>a+b,0),min:Math.min(...group.values),max:Math.max(...group.values),
+      explicitBounds:bounds,bucketCounts:buckets.map(String)};
+  });
+  return {name:'prnext.flight.response.size',description:'Bounded diagnostic sample of uncompressed Flight bytes read to completion. RSC and SSR are separate observations of the same payload; never add their counts. Cancelled/failed samples are excluded.',unit:'By',histogram:{aggregationTemporality:1,dataPoints}};
+}

package/build/index.mjs

@@ -5,6 +5,8 @@ import { rename } from '../runtime/fs.mjs';
 import { writeRuntimeContract } from './runtime-contract.mjs';
 import { writeBuildOutput } from './output-contract.mjs';
 import { bundleRuntime } from './bundle-runtime.mjs';
+import {withBuildTimings, measureBuildPhase} from './build-timings.mjs';
+import {mapConcurrent} from './concurrent.mjs';
 import {withPersistentTransforms} from './transform-cache.mjs';
 import {withCompilationStorage,configureCompilationStorage} from './compilation-storage.mjs';
 import {reclaimBuildStages,trackBuildStage} from './build-retention.mjs';
@@ -26,7 +28,7 @@ import { randomUUID, randomBytes, createHash } from 'node:crypto';
 import { prepareBuildDirectory, OUTPUT_POINTER } from '../runtime/build-directory.mjs';
 import { moduleResolutionPlugin } from './module-resolution.mjs';
 import { scanProject } from './scan.mjs';
-import { stripServerCode, assertSupportedSource, rewriteServerChunks } from './transform.mjs';
+import { stripServerCode, assertSupportedSource, rewriteServerChunkOutputFiles } from './transform.mjs';
 import { transformDynamicImports } from './dynamic.mjs';
 import { createCssModules } from './css-modules.mjs';
 import { createFonts } from './fonts.mjs';
@@ -189,8 +191,8 @@ export function build(projectRoot, options = {}) {
     try { return await withBuildLock(projectRoot, async root => {
       await reclaimBuildStages(root);
       const started=performance.now();
-      const result=await withCompilationStorage(root,()=>withPersistentTransforms(root,{dev:!!options.dev},()=>withCompilation(() => buildProject(root, { ...options, envMode }))));
-      return {...result,durationMs:Math.round(performance.now()-started)};
+      const measured=await withBuildTimings(()=>withCompilationStorage(root,()=>withPersistentTransforms(root,{dev:!!options.dev},()=>withCompilation(() => buildProject(root, { ...options, envMode })))));
+      return {...measured.result,durationMs:Math.round(performance.now()-started),buildTimings:measured.timings};
     }); }
     finally { restore(); }
   });
@@ -206,7 +208,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       devInputs,devSession,devActionSecret,incremental});
     if (deferred) return deferred;
   }
-  const config = await loadProjectConfig(projectRoot, { dev, envMode, devInputs });
+  const config = await measureBuildPhase('configuration',()=>loadProjectConfig(projectRoot, { dev, envMode, devInputs }));
   configureCompilationStorage(config.compilationCache);
   const tsconfig = config.typescript ? await projectTsconfig(projectRoot, config) : undefined;
   const environment = defineEnvironment(config);
@@ -216,12 +218,12 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
   const scanOptions={basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n};
   let project,deferredRoutes=[];
   if(dev && Array.isArray(devRoutes)) {
-    const discovery=await scanProject(projectRoot,{...scanOptions,devAppFiles:new Set()});
-    project=await scanProject(projectRoot,{...scanOptions,devAppFiles:routeFiles(discovery,devRoutes)});
+    const discovery=await measureBuildPhase('discovery',()=>scanProject(projectRoot,{...scanOptions,devAppFiles:new Set()}));
+    project=await measureBuildPhase('discovery',()=>scanProject(projectRoot,{...scanOptions,devAppFiles:routeFiles(discovery,devRoutes)}));
     await writeTypedRoutes(projectRoot,discovery,config);
     deferredRoutes=discovery.routes.filter(route=>!devRoutes.includes(route.pattern)&&!route.internal&&!route.errorStatus);
     project.routes=project.routes.filter(route=>devRoutes.includes(route.pattern)||route.internal||route.errorStatus);
-  } else project=await scanProject(projectRoot,scanOptions);
+  } else project=await measureBuildPhase('discovery',()=>scanProject(projectRoot,scanOptions));
   if(dev&&config.experimental.lazyDynamicImports){
     if(project.routes.some(route=>route.router!=='app'&&!route.internal))throw Error('experimental.lazyDynamicImports currently requires an App Router-only application.');
     if(config.webpack||Object.keys(config.turbopack?.rules||{}).length)throw Error('experimental.lazyDynamicImports currently requires the native compiler without webpack hooks or custom loaders.');
@@ -258,7 +260,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
   const cssModules = createCssModules({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase, sassOptions: config.sassOptions, cssEngine:config.cssEngine,dev,config });
   configureCompiler({config,root:project.root,stage,buildId,dev,incremental,devInputs,tsconfig,assetBase:publicPaths.assetBase});
   try {
-    await copyRuntimeFiles(stage,{development:dev});
+    await measureBuildPhase('runtime-inputs',()=>copyRuntimeFiles(stage,{development:dev}));
     // Runtime copies must work even when dotenv is nested beneath the PRNext
     // package instead of hoisted beside the application's dependencies.
     await bundle({ entryPoints: [path.join(packageRoot, 'runtime/env.mjs')], outfile: path.join(stage, 'runtime/env.mjs'), bundle: true, platform: 'node', format: 'esm', target: 'node22', logLevel: 'silent', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" } });
@@ -291,14 +293,16 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     const common = { absWorkingDir: project.root, bundle: true, logLevel: 'silent', jsx: 'automatic', loader: assetLoaders, assetNames: '[name]-[hash]', publicPath: publicPaths.assetBase, metafile: true, define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...environment } };
     if (Object.keys(serverEntries).length) {
-      const server = await bundle({ ...common, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, locations, reactCompiler }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] });
+      const server = await measureBuildPhase('pages-server',()=>bundle({ ...common, write: false, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, locations, reactCompiler }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] }));
       fonts.record(server.metafile);
       const serverChunks = new Set(Object.keys(server.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
-      for (const [output, metadata] of Object.entries(server.metafile.outputs)) {
-        if (!output.endsWith('.mjs') || !metadata.imports.some(item => !item.external)) continue;
-        const file = path.resolve(project.root, output);
-        await rewriteServerChunks(file, serverChunks, publicPaths.assetBase);
-      }
+      const importers = new Set(Object.entries(server.metafile.outputs).filter(([output, metadata])=>output.endsWith('.mjs')&&metadata.imports.some(item=>!item.external)).map(([output])=>path.resolve(project.root,output)));
+      // All buffers are transformed before their first write. Settle every owned
+      // writer before stage cleanup on failure, including external sourcemaps.
+      await measureBuildPhase('pages-output',async()=>{
+        const outputs = rewriteServerChunkOutputFiles(server.outputFiles,serverChunks,publicPaths.assetBase,importers);
+        await mapConcurrent(outputs,async file=>{await mkdir(path.dirname(file.path),{recursive:true});await writeFile(file.path,file.contents);},8);
+      });
       // Image/font imports must resolve to the same public URLs on both render paths.
       await mkdir(path.join(stage, 'assets'), { recursive: true });
       for (const [output, metadata] of Object.entries(server.metafile.outputs)) {
@@ -306,7 +310,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       }
     }
     if (Object.keys(clientEntries).length) {
-      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, refresh, locations, reactCompiler, nativeCompiler: config.reactCompiler?.backend === 'oxc' }), cssModules.plugin(true)] });
+      const browser = await measureBuildPhase('pages-browser',()=>bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, refresh, locations, reactCompiler, nativeCompiler: config.reactCompiler?.backend === 'oxc' }), cssModules.plugin(true)] }));
       fonts.record(browser.metafile);
       const byEntry = new Map(Object.entries(clientEntries).map(([id, file]) => [path.resolve(file), id]));
       for (const [output, metadata] of Object.entries(browser.metafile.outputs)) {
@@ -320,10 +324,10 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
         if (metadata.cssBundle) route.css.push(publicPaths.assetBase + '/' + path.basename(metadata.cssBundle));
       }
     }
-    await compileMiddleware({ project, stage, manifest, dev, moduleResolution: config.turbopack, defineEnvironment: environment });
+    await measureBuildPhase('middleware',()=>compileMiddleware({ project, stage, manifest, dev, moduleResolution: config.turbopack, defineEnvironment: environment }));
     if (manifest.middleware) manifest.middleware.bodySizeLimit = config.experimental.proxyClientMaxBodySize;
-    await prepareMetadataRoutes(project, stage);
-    await compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, moduleResolution: config.turbopack, cssModules, fonts, images, dev, devActionSecret:dev?devActionSecret:undefined, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages, lazyDynamicImports:dev&&config.experimental.lazyDynamicImports,devLazyRequest,devLazyActivated, parallelBuilds: !dev && config.experimental.parallelBuilds && await cssModules.parallelSafe() ? config.experimental.parallelBuilds : false });
+    await measureBuildPhase('metadata',()=>prepareMetadataRoutes(project, stage));
+    await measureBuildPhase('app',async()=>compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, moduleResolution: config.turbopack, cssModules, fonts, images, dev, devActionSecret:dev?devActionSecret:undefined, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages, lazyDynamicImports:dev&&config.experimental.lazyDynamicImports,devLazyRequest,devLazyActivated, parallelBuilds: !dev && config.experimental.parallelBuilds && await cssModules.parallelSafe() ? config.experimental.parallelBuilds : false }));
     if(manifest.devLazy){
       const css=Object.values(manifest.devLazy.outputs).flatMap(module=>module.css);
       for(const route of manifest.routes)if(route.router==='app'&&route.kind==='page'){
@@ -339,14 +343,14 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       const selected=manifest.routes.find(route=>!route.internal&&route.pattern===pattern);
       if(!selected||selected.cacheConfig?.runtime==='edge'||selected.handlerConfig?.runtime==='edge')throw new Error(`workerPreload route ${pattern} must be an existing Node route.`);
     }
-    await compileInstrumentation({root:project.root,stage,manifest,config,dev,environment});
+    await measureBuildPhase('instrumentation',()=>compileInstrumentation({root:project.root,stage,manifest,config,dev,environment}));
     if(deferredRoutes.length){
       for(const route of deferredRoutes){
         const module=`server/dev-deferred-${route.id}.mjs`;await writeFile(path.join(stage,module),'export {};\n');
         manifest.routes.push({id:route.id,pattern:route.pattern,kind:route.kind,router:route.router,module,devDeferred:true,css:[],cacheConfig:{maxDuration:120}});
       }
     }
-    await checkTypeScript(project.root, config, { dev, tsconfig });
+    await measureBuildPhase('types',()=>checkTypeScript(project.root, config, { dev, tsconfig }));
     fonts.attach(manifest);
     expandLocales(manifest);
     const imageResponse = await imageResponseRequirement(stage, {dev, manifest});
@@ -354,13 +358,13 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     else await rm(path.join(stage, 'compat/og.cjs'), {force: true});
     // All runtime preparation must finish before its shared modules are built;
     // no staged renderer has been imported before this production-only point.
-    if (!dev) await bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime'),imageResponse:imageResponse.included});
+    if (!dev) await measureBuildPhase('runtime-bundle',()=>bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime'),imageResponse:imageResponse.included}));
     // Node caches CJS React by filename, not NODE_ENV. Once development metadata
     // imports load it, subsequent production renders need a clean process too.
     if(dev) developmentModulesLoaded = true;
-    if(!dev) Object.assign(manifest,await (incremental || developmentModulesLoaded ? isolatedPrerender : prerenderProduction)(project.root,stage,manifest,{prerender:config.prerender}));
-    else {await prerender(stage, manifest, dev);await prerenderApp(stage, manifest, dev);}
-    if (!dev) await prepareNativePprShells(stage, manifest);
+    if(!dev) Object.assign(manifest,await measureBuildPhase('prerender',()=>(incremental || developmentModulesLoaded ? isolatedPrerender : prerenderProduction)(project.root,stage,manifest,{prerender:config.prerender})));
+    else await measureBuildPhase('prerender',async()=>{await prerender(stage, manifest, dev);await prerenderApp(stage, manifest, dev);});
+    if (!dev) await measureBuildPhase('native-ppr',()=>prepareNativePprShells(stage, manifest));
     const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal && !route.devDeferred);
     const publicPage = route => ({ ...(route.locale ? {locale:route.locale,originalPattern:route.originalPattern} : {}), id: route.id, pattern: route.pattern, client: route.client, css: route.css, ...(route.fonts ? { fonts: route.fonts } : {}), ssg: !!route.ssg, ssp: !!route.ssp, gip: !!route.gip, appGip: !!route.appGip });
     if (pages.length || manifest.pagesErrors) {
@@ -402,7 +406,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     // A report belongs to this successful staging generation, never to the
     // runtime manifest or public assets. Publishing the stage is atomic below.
-    if(!dev)await retainDeploymentAssets({stage,destination,manifest,policy:config.deploymentRetention});
+    if(!dev)await measureBuildPhase('retention',()=>retainDeploymentAssets({stage,destination,manifest,policy:config.deploymentRetention}));
     const compilationCache=compilationGraphCacheReport();
     if(!dev)await writeFile(path.join(stage,'compilation-cache-report.json'),JSON.stringify(compilationCache,null,2)+'\n');
     const compilerReport=await writeReactCompilerReport(stage,reactCompilerReport());
@@ -411,9 +415,9 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await writeBuildOutput(stage, manifest);
     // Offline compression is a deployment optimization. Recompressing source
     // maps and every entry after a save stalls Fast Refresh for no local benefit.
-    if (!dev && config.compress) await precompressBuild(stage, manifest, {cacheDirectory:path.join(project.root,'.prnext-cache/precompress-v1')});
-    if(!dev)await writeBuildAnalysis({root:project.root,stage,destination,manifest,records:buildAnalysisRecords(),routeInputs:buildAnalysisRoutes(),precompressed:config.compress});
-    if (config.output === 'standalone' && !dev) await (await import('./standalone-runner.mjs')).prepareStandalone({ projectRoot: project.root, stage, manifest, config });
+    if (!dev && config.compress) await measureBuildPhase('precompression',()=>precompressBuild(stage, manifest, {cacheDirectory:path.join(project.root,'.prnext-cache/precompress-v1')}));
+    if(!dev)await measureBuildPhase('analysis',()=>writeBuildAnalysis({root:project.root,stage,destination,manifest,records:buildAnalysisRecords(),routeInputs:buildAnalysisRoutes(),precompressed:config.compress}));
+    if (config.output === 'standalone' && !dev) await measureBuildPhase('standalone',async()=>(await import('./standalone-runner.mjs')).prepareStandalone({ projectRoot: project.root, stage, manifest, config }));
     const exporting = config.output === 'export' && !dev ? await import('./static-export.mjs') : null;
     const exportSource = exporting && await exporting.prepareStaticExport({ project, stage, manifest, config });
     let hadDestination = false;

package/build/inspect.mjs

@@ -70,6 +70,8 @@ export async function inspectProject(directory) {
     notes: ['Enable measurements with prn start --inspect (or prn dev --inspect), visit routes, then run prn inspect again.',
       'HTTP and fetch durations end when response headers are ready. Samples are bounded and can span server sessions; they are not full-response benchmarks.',
       'Request-stage samples additionally separate admission, worker first byte, response headers and complete body consumption, with completion/cancellation/deadline outcomes. Stages overlap; do not add their durations. Body completion means the HTTP layer consumed the application body, not remote delivery.',
+      'Flight sizes are uncompressed application bytes observed while reading the stream. RSC and SSR observe the same payload separately: do not add their sizes or counts. Size quantiles include completed samples only; failed/cancelled samples may be partial.',
+      'Flight model-ready, shell-ready and duration timings include application work, queueing and asynchronous waits; they are not isolated serialization CPU. Browser execution, hydration, compressed transfer and remote delivery are not measured.',
       'Fetch destinations omit queries and credentials. Runtime cache tags/paths are hashed; matching identifiers link reads to invalidations. No diagnostic HTTP endpoint is exposed.'] };
 }
 export function printInspection(report) {
@@ -77,6 +79,7 @@ export function printInspection(report) {
   console.log(`Recorded sample: ${report.summary.requests} HTTP requests; p50 ${report.summary.p50Ms ?? 'n/a'} ms; p95 ${report.summary.p95Ms ?? 'n/a'} ms (response headers); ${report.summary.errors} server errors.`);
   if(report.summary.wakeP95Ms !== null) console.log(`Worker startup p95: ${report.summary.wakeP95Ms} ms.`);
   if(report.summary.workerRssBytes !== null) console.log(`Latest recorded worker RSS: ${(report.summary.workerRssBytes/1048576).toFixed(1)} MiB. Native server memory is not included.`);
+  for(const sample of report.flight||[])console.log(`FLIGHT ${sample.route} (${sample.phase}): ${sample.completed} completed sample(s), p95 ${sample.flightP95Bytes===null?'n/a':(sample.flightP95Bytes/1000).toFixed(1)+' kB'}; ${sample.failed} failed, ${sample.cancelled} cancelled, ${sample.timedOut} timed out; model ready p95 ${sample.modelReadyP95Ms??'n/a'} ms, shell ready p95 ${sample.shellReadyP95Ms??'n/a'} ms (includes waiting).`);
   for(const stage of report.requestStages||[]) console.log(`STAGE ${stage.stage}: ${stage.samples} sample(s), p95 ${stage.p95Ms ?? 'n/a'} ms; ${stage.completed} completed, ${stage.failed} failed, ${stage.cancelled} cancelled, ${stage.timedOut} timed out.`);
   for(const budget of report.budgets||[])console.log(`BUDGET ${budget.budget}: ${budget.used ?? 'n/a'}/${budget.limit ?? 'n/a'} ${budget.unit}, ${budget.waiting ?? 'n/a'} waiting; ${budget.rejected ?? 'n/a'} rejected, ${budget.timedOut ?? 'n/a'} timed out, ${budget.cancelledWaits ?? 'n/a'} cancelled waits.`);
   for(const finding of report.findings)console.log(`${finding.level.toUpperCase()}: ${finding.message} ${finding.action}`);

package/build/inspection-summary.mjs

@@ -1,3 +1,4 @@
+import {summarizeFlight,flightMetrics} from './flight-summary.mjs';
 const quantile = (values, q) => values.length ? Math.round([...values].sort((a,b)=>a-b)[Math.ceil(values.length*q)-1]*100)/100 : null;
 const durations = events => events.map(e=>e.durationMs).filter(v=>Number.isFinite(v)&&v>=0);
 const stages=['admission','renderStart','bodyAdmission','bodyRead','workerQueue','workerFirstByte','workerHeaders','httpHeaders','responseBody','requestTotal'];
@@ -21,6 +22,7 @@ function currentBudgets(snapshot) {
   });
 }
 export function summarizeDiagnostics(events, snapshots = []) {
+  const flightReport=summarizeFlight(events);
   const http=events.filter(e=>e.type==='http'), times=durations(http);
   const wake=durations(events.filter(e=>e.type==='wake'&&e.phase==='node-ready'));
   const processes=new Map();
@@ -34,13 +36,16 @@ export function summarizeDiagnostics(events, snapshots = []) {
     queuedJobs:current?last.workers?.queuedJobs??null:null,activeJobs:current?last.workers?.activeJobs??null:null, runtimeSampleAt:last?.unixMs??null,
     completedResponseP95Ms:quantile(durations(stageSample.filter(e=>e.stage==='requestTotal'&&e.outcome==='completed')),.95),cancelledResponses:totals?.cancelled??null,timedOutResponses:totals?.timedOut??null};
   const findings=[];
+  for(const route of flightReport.flight)if(route.completed>=3&&route.flightP95Bytes>=131072)findings.push({level:'info',code:'LARGE_FLIGHT',
+    message:`${route.route} (${route.phase}) has a sampled Flight p95 of ${(route.flightP95Bytes/1000).toFixed(1)} kB.`,
+    action:'Inspect the rendered model and repeated presentation markup. Compare explicit public-prop client boundaries with their browser JavaScript and hydration costs; private server code must stay on the server.'});
   if(!http.length)findings.push({level:'info',code:'NO_SAMPLE',message:'No HTTP sample recorded.',action:'Start with --inspect, visit the site and run inspect again.'});
   if(summary.queuedJobs>0)findings.push({level:'warning',code:'WORKER_QUEUE',message:`${summary.queuedJobs} jobs are waiting for a worker.`,action:'Check slow routes and available CPU/RAM before increasing concurrency.'});
   if(summary.p95Ms>=1000)findings.push({level:'warning',code:'SLOW_HEADERS',message:'The slowest 5% of recorded responses take at least one second to prepare headers.',action:'Inspect route and fetch timings below; this includes queueing and startup.'});
   if(summary.errors)findings.push({level:'warning',code:'SERVER_ERRORS',message:`${summary.errors} recorded requests returned a server error.`,action:'Check application logs for the same sample period.'});
   if(summary.wakeP95Ms>=1000)findings.push({level:'info',code:'SLOW_WAKE',message:'Recorded worker startup p95 exceeds one second.',action:'Review startup imports or use keep-warm if the extra memory is acceptable.'});
   if(summary.timedOutResponses>0)findings.push({level:'warning',code:'RESPONSE_DEADLINES',message:`${summary.timedOutResponses} recorded HTTP responses reached their request deadline.`,action:'Compare admission, worker and body timings before increasing the configured timeout.'});
-  return {summary,findings,requestStages,budgets:current?currentBudgets(last):null,stageSample,metricSample:http.filter(e=>Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&validTime(e.time)).map(e=>({route:typeof e.route==='string'?e.route.slice(0,256):'<unmatched>',method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(e.method)?e.method:'_OTHER',durationMs:e.durationMs,time:e.time}))};
+  return {summary,findings,requestStages,...flightReport,budgets:current?currentBudgets(last):null,stageSample,metricSample:http.filter(e=>Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&validTime(e.time)).map(e=>({route:typeof e.route==='string'?e.route.slice(0,256):'<unmatched>',method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(e.method)?e.method:'_OTHER',durationMs:e.durationMs,time:e.time}))};
 }
 
 /** OTLP/JSON Metrics export of a bounded local sample, never a complete traffic counter. */
@@ -66,5 +71,5 @@ export function inspectionMetrics(report) {
     group.count++;group.sum+=value;group.min=Math.min(group.min,value);group.max=Math.max(group.max,value);group.start=Math.min(group.start,event.time);group.end=Math.max(group.end,event.time);group.buckets[index<0?bounds.length:index]++;
   }
   const stagePoints=[...stageGroups.values()].map(g=>({attributes:[{key:'prnext.request.stage',value:{stringValue:g.stage}},{key:'prnext.request.outcome',value:{stringValue:g.outcome}}],startTimeUnixNano:String(BigInt(g.start)*1000000n),timeUnixNano:String(BigInt(g.end)*1000000n),count:String(g.count),sum:g.sum,min:g.min,max:g.max,explicitBounds:bounds,bucketCounts:g.buckets.map(String)}));
-  return {resourceMetrics:[{resource:{attributes:[{key:'service.name',value:{stringValue:'prnext'}},{key:'prnext.inspect.sampled',value:{boolValue:true}}]},scopeMetrics:[{scope:{name:'prnext.inspect',version:'1'},metrics:[{name:'prnext.http.response.headers.duration',description:'Bounded diagnostic sample of time until response headers; excludes response body streaming.',unit:'s',histogram:{aggregationTemporality:1,dataPoints}},{name:'prnext.request.stage.duration',description:'Bounded diagnostic sample of request stages and terminal outcomes; stages overlap and must not be added together.',unit:'s',histogram:{aggregationTemporality:1,dataPoints:stagePoints}}]}]}]};
+  return {resourceMetrics:[{resource:{attributes:[{key:'service.name',value:{stringValue:'prnext'}},{key:'prnext.inspect.sampled',value:{boolValue:true}}]},scopeMetrics:[{scope:{name:'prnext.inspect',version:'1'},metrics:[{name:'prnext.http.response.headers.duration',description:'Bounded diagnostic sample of time until response headers; excludes response body streaming.',unit:'s',histogram:{aggregationTemporality:1,dataPoints}},{name:'prnext.request.stage.duration',description:'Bounded diagnostic sample of request stages and terminal outcomes; stages overlap and must not be added together.',unit:'s',histogram:{aggregationTemporality:1,dataPoints:stagePoints}},flightMetrics(report.flightSample||[])]}]}]};
 }

package/build/native-discovery.mjs

@@ -1,7 +1,7 @@
 import { readdir, readFile, realpath } from 'node:fs/promises';
 import { builtinModules, createRequire } from 'node:module';
 import path from 'node:path';
-import { analyzeSource } from './source-analysis.mjs';
+import { analyzeSourceSummary } from './source-analysis.mjs';
 
 const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
 
@@ -15,6 +15,7 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   const sourceImports = new Map(), entryNative = new Map(), declaredNative = new Map();
   const resolvers = new Map();
   let sourceBytes = 0;
+  let declaredVisits=0,declaredProofHits=0;
   const isApplication = directory => {
     const relative = path.relative(directory, projectRoot);
     return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
@@ -27,7 +28,7 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
       const size = Buffer.byteLength(source);
       if (size > 8 * 1024 ** 2 || (sourceBytes += size) > 64 * 1024 ** 2) throw new Error('Native npm import analysis exceeds its 8 MiB file / 64 MiB source budget. Separate the native loader into a server-only package.');
       // The compiler accepts JSX in JavaScript npm entries, including .js.
-      const { imports, computedRequire } = analyzeSource(source, /\.[cm]?js$/.test(file) ? file + '.jsx' : file);
+      const { imports, computedRequire } = analyzeSourceSummary(source,file);
       // Keep edges, not the AST, so the shared parser can bound its retained cache.
       return { imports, computedRequire };
     })());
@@ -111,20 +112,30 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
     return dependencyRoots.get(key);
   }
 
-  async function nativeReachable(owner, visited = new Set()) {
+  const nativePresent=new Set(),nativeAbsent=new Set();
+  async function nativeReachable(owner, visited) {
+    if(nativePresent.has(owner.directory)){declaredProofHits++;return true;}
+    if(nativeAbsent.has(owner.directory)){declaredProofHits++;return false;}
     if (visited.has(owner.directory)) return false;
     visited.add(owner.directory);
-    if ((await filesFor(owner.directory)).native) return true;
+    declaredVisits++;
+    if ((await filesFor(owner.directory)).native) {nativePresent.add(owner.directory);return true;}
     const names = new Set([...Object.keys(owner.metadata.dependencies || {}), ...Object.keys(owner.metadata.optionalDependencies || {})]);
     for (const name of names) {
       const dependency = await resolveDependency(owner.directory, name);
-      if (dependency && await nativeReachable(dependency, visited)) return true;
+      if (dependency && await nativeReachable(dependency, visited)) {nativePresent.add(owner.directory);return true;}
     }
     return false;
   }
 
   function declaredNativeFor(owner) {
-    if (!declaredNative.has(owner.directory)) declaredNative.set(owner.directory, nativeReachable(owner));
+    if (!declaredNative.has(owner.directory)) declaredNative.set(owner.directory, (async()=>{
+      const visited=new Set(),result=await nativeReachable(owner,visited);
+      // A recursive false inside a cycle proves nothing by itself. Only a
+      // completely native-free root closure can certify all its visited nodes.
+      if(!result)for(const directory of visited)nativeAbsent.add(directory);
+      return result;
+    })());
     return declaredNative.get(owner.directory);
   }
 
@@ -172,6 +183,7 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   }
 
   return {
+    stats(){return {declaredVisits,declaredProofHits,nativePresent:nativePresent.size,nativeAbsent:nativeAbsent.size};},
     setResolver(mode, resolve) { resolvers.set(mode, resolve); },
     canExternalizeDirectory,
     async externalOwner(file, mode) {

package/build/npm-packages.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { builtinModules, createRequire } from 'node:module';
-import {analyzeSource} from './source-analysis.mjs';
+import {analyzeSourceSummary} from './source-analysis.mjs';
 import { createNativeDiscovery } from './native-discovery.mjs';
 import {frameworkImportPattern} from './framework-imports.mjs';
 
@@ -25,7 +25,7 @@ export function npmPackagesPlugin({ pages = false, projectRoot, transpilePackage
       sourceBytes += Buffer.byteLength(source);
       if (sourceBytes > 64 * 1024 * 1024) throw new Error('npm compilation analysis exceeded 64 MiB of source. Separate large runtime dependencies using serverExternalPackages.');
       if (Buffer.byteLength(source) > 8 * 1024 * 1024) throw new Error(`npm source ${file} exceeds the 8 MiB analysis limit. Configure serverExternalPackages for packages that do not use Next APIs.`);
-      const {imports,computedRequire,frameworkBoundary}=analyzeSource(source,file);
+      const {imports,computedRequire,frameworkBoundary}=analyzeSourceSummary(source,file);
       return {imports,computedRequire,frameworkBoundary};
     })());
     return sources.get(file);

package/build/source-analysis.mjs

@@ -1,11 +1,64 @@
 import {parseSync} from 'oxc-parser';
 import {createHash} from 'node:crypto';
+import parserPackage from 'oxc-parser/package' with {type:'json'};
+import {cachedValidatedTransform} from './transform-cache.mjs';
 
 // Read-only analyses share one Rust parse. Transformations still use Babel's
 // binding-aware AST: ESTree nodes must never be passed to Babel transforms.
 const cache=new Map();
 let bytes=0,hits=0,misses=0;
-export const sourceAnalysisStats=()=>({entries:cache.size,bytes,hits,misses});
+const summaries=new Map();
+let summaryBytes=0,summaryHits=0,summaryMisses=0,summaryReplays=0;
+const SUMMARY_BYTES=8*1024*1024,SUMMARY_ENTRIES=4096,SUMMARY_ITEM=128*1024;
+export const sourceAnalysisStats=()=>({entries:cache.size,bytes,hits,misses,
+  summaries:{entries:summaries.size,bytes:summaryBytes,hits:summaryHits,misses:summaryMisses,replays:summaryReplays}});
+const summaryFields=['directives','imports','computedRequire','hasServerDirective','runtimeExports','exportStars','frameworkBoundary'];
+const text=value=>typeof value==='string'&&value.length<=32768;
+const texts=value=>Array.isArray(value)&&value.length<=4096&&value.every(text);
+function validSummary(value){
+  return value&&Object.getPrototypeOf(value)===Object.prototype&&Object.keys(value).length===summaryFields.length
+    &&summaryFields.every(name=>Object.hasOwn(value,name))&&texts(value.directives)&&texts(value.runtimeExports)&&texts(value.exportStars)
+    &&['computedRequire','hasServerDirective','frameworkBoundary'].every(name=>typeof value[name]==='boolean')
+    &&Array.isArray(value.imports)&&value.imports.length<=4096&&value.imports.every(item=>item&&Object.getPrototypeOf(item)===Object.prototype
+      &&Object.keys(item).length===2&&text(item.path)&&['import-statement','dynamic-import','require-call'].includes(item.kind));
+}
+function immutableSummary(value){
+  return Object.freeze({directives:Object.freeze([...value.directives]),imports:Object.freeze(value.imports.map(item=>Object.freeze({path:item.path,kind:item.kind}))),
+    computedRequire:value.computedRequire,hasServerDirective:value.hasServerDirective,runtimeExports:Object.freeze([...value.runtimeExports]),
+    exportStars:Object.freeze([...value.exportStars]),frameworkBoundary:value.frameworkBoundary});
+}
+
+/** Pure, versioned facts only: no AST, source, resolver, registry or generation. */
+export function analyzeSourceSummary(source,file='source.js'){
+  const digest=createHash('sha256').update(source).digest('hex'),key=file+'\0'+digest;
+  const found=summaries.get(key);
+  if(found){summaries.delete(key);summaries.set(key,found);summaryHits++;return found.value;}
+  summaryMisses++;
+  let produced=false,producedAnalysis;
+  const validate=raw=>{
+    if(typeof raw!=='string'||Buffer.byteLength(raw)>SUMMARY_ITEM)return false;
+    const record=JSON.parse(raw);
+    return record&&Object.keys(record).length===5&&record.version===1&&record.parser===parserPackage.version
+      &&record.file===file&&record.digest===digest&&validSummary(record.analysis);
+  };
+  const produce=()=>{
+    produced=true;
+    const analysis=producedAnalysis=analyzeSource(source,file);
+    return JSON.stringify({version:1,parser:parserPackage.version,file,digest,analysis:Object.fromEntries(summaryFields.map(name=>[name,analysis[name]]))});
+  };
+  // Oversized summaries remain ordinary uncached parses, preserving the old
+  // accepted input surface without weakening bounded disk/memory retention.
+  let raw,value;
+  try{raw=cachedValidatedTransform('source-summary',source,[file,parserPackage.version,'v1'],validate,produce);value=JSON.parse(raw).analysis;}
+  catch(error){if(error?.message!=='Invalid typed compiler cache result')throw error;value=Object.fromEntries(summaryFields.map(name=>[name,producedAnalysis[name]]));}
+  if(!produced)summaryReplays++;
+  const immutable=immutableSummary(value),size=Buffer.byteLength(JSON.stringify(value))*2+Buffer.byteLength(key)*2;
+  if(size<=SUMMARY_ITEM){
+    while(summaries.size&&(summaries.size>=SUMMARY_ENTRIES||summaryBytes+size>SUMMARY_BYTES)){const[old,entry]=summaries.entries().next().value;summaries.delete(old);summaryBytes-=entry.size;}
+    summaries.set(key,{value:immutable,size});summaryBytes+=size;
+  }
+  return immutable;
+}
 const identifier=(node,name)=>node?.type==='Identifier'&&(name===undefined||node.name===name);
 const property=node=>node?.computed?node.property?.value:node?.property?.name;
 const moduleExports=node=>node?.type==='MemberExpression'&&identifier(node.object,'module')&&property(node)==='exports';