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

package/build/check.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile,open } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { loadProjectConfig } from './config.mjs';
 import { validateCompilerConfig } from './compiler.mjs';
@@ -10,11 +10,43 @@ import { snapshotEnvConfig } from '../runtime/env.mjs';
 import { environmentDiagnostics } from '../native/diagnostics.mjs';
 import { packageManifest } from '../native/resolve.mjs';
 import { projectTsconfig } from './typescript.mjs';
+import {productionDiagnostics} from './production-check.mjs';
+import {readBuildDirectory} from '../runtime/build-directory.mjs';
+import {validateServerConfig} from './server-config.mjs';
+
+async function artifactDiagnostics(root,config){
+  let file;
+  const diagnostic=(code,severity,message,action)=>({id:code,code,path:'server',severity,message,action});
+  try{
+    const output=await readBuildDirectory(root);
+    file=await open(path.join(root,output,'manifest.json'),'r');
+    const limit=16*1024*1024,info=await file.stat();
+    if(!info.isFile()||info.size>limit)throw new Error('Uninspectable build manifest.');
+    const buffer=Buffer.alloc(Math.min(info.size+1,limit+1));let length=0;
+    while(length<buffer.length){const {bytesRead}=await file.read(buffer,length,buffer.length-length,length);if(!bytesRead)break;length+=bytesRead;}
+    const after=await file.stat();
+    if(length!==info.size||after.size!==info.size||after.mtimeMs!==info.mtimeMs||after.ctimeMs!==info.ctimeMs)throw new Error('Unstable build manifest.');
+    const manifest=JSON.parse(buffer.subarray(0,length).toString());
+    if(manifest.version!==1||!Array.isArray(manifest.routes))throw new Error('Unsupported build manifest.');
+    const diagnostics=[];
+    if(manifest.dev)diagnostics.push(diagnostic('production-artifact-development','error','The selected build is a development artifact.','Run prnext build and deploy the final production output.'));
+    if(output!==config.distDir)diagnostics.push({...diagnostic('production-artifact-directory','warning','The selected build directory differs from the current configuration.','Rebuild the application before deployment; prnext start uses the existing output selector.'),path:'distDir'});
+    const signature=server=>{const value=validateServerConfig(server);return JSON.stringify({publicOrigin:value.publicOrigin||null,trustedProxies:[...value.trustedProxies].sort()});};
+    if(signature(manifest.config?.server)!==signature(config.server))diagnostics.push(diagnostic('production-artifact-origin','warning','The selected build uses different public origin or proxy trust settings.','Rebuild and deploy the artifact with the intended production configuration; start does not reevaluate the source config.'));
+    const retention=value=>JSON.stringify({maxEntries:value===false?0:value?.maxEntries??4,authCookies:value?.authCookies===undefined?null:[...value.authCookies].sort()});
+    if(retention(manifest.config?.navigationCache)!==retention(config.navigationCache))diagnostics.push({...diagnostic('production-artifact-auth-cookies','warning','The selected build uses different page-retention or authentication cookie settings.','Rebuild before deployment, then test account changes on the resulting artifact.'),path:'navigationCache.authCookies'});
+    return diagnostics;
+  }catch(error){
+    if(error.code==='ENOENT')return [diagnostic('production-artifact-missing','info','No existing build was found at the selected output path.','Run prnext build after preflight, then qualify the resulting artifact.')];
+    return [diagnostic('production-artifact-unreadable','warning','The existing build metadata could not be inspected.','Run a fresh production build and verify its output contract before deployment.')];
+  }finally{await file?.close();}
+}
 
 /** Preflight an existing project without rewriting sources, dependencies or build output. */
-export async function checkProject(directory, { dev = false, validateDependencies = true, validateEnvironment = validateDependencies } = {}, services = {}) {
+export async function checkProject(directory, { dev = false, production = false, validateDependencies = true, validateEnvironment = validateDependencies } = {}, services = {}) {
+  if(dev&&production)throw new TypeError('Choose development or production preflight, not both.');
   const root = path.resolve(directory);
-  const report = { root, ok: false, routes: [], versions: {}, errors: [], diagnostics: [], notes: [
+  const report = { root, mode:production?'production':dev?'development':'default', ok: false, routes: [], versions: {}, errors: [], diagnostics: [], notes: [
     'Preflight validates configuration, route conventions and installed React versions. A successful production build and browser tests are still required.',
     'Webpack plugin hooks are validated during compilation; preflight only validates plugin shape and translated configuration.',
     'Rust handles HTTP, routing, static files, images and persistent caches. React and npm JavaScript execute on Node/V8.',
@@ -26,6 +58,7 @@ export async function checkProject(directory, { dev = false, validateDependencie
   };
   const restore = snapshotEnvConfig();
   try {
+    if(production)process.env.NODE_ENV='production';
     let config, project;
     try { config = await loadProjectConfig(root, {dev}); }
     catch (error) { diagnostic('config', error, 'Correct the project configuration and run check again.'); }
@@ -59,6 +92,11 @@ export async function checkProject(directory, { dev = false, validateDependencie
     if (project) {
     report.routes = project.routes.filter(route=>!route.internal).map(({pattern,kind,router})=>({pattern,kind,router:router||'pages'}));
     }
+    if(production&&config){
+      const diagnostics=[...productionDiagnostics(config,project),...await artifactDiagnostics(root,config)];
+      report.diagnostics.push(...diagnostics);
+      report.errors.push(...diagnostics.filter(item=>item.severity==='error').map(item=>item.message));
+    }
     const resolve = createRequire(path.join(root,'package.json'));
     for (const name of ['next','react','react-dom','react-server-dom-webpack']) {
       try { report.versions[name] = JSON.parse(await readFile(resolve.resolve(`${name}/package.json`),'utf8')).version; }

package/build/compilation-cache.mjs

@@ -14,15 +14,15 @@ const MAX_FILES = 4096, MAX_DIRECTORIES = 8192, MAX_NAMES = 32768;
 const MAX_FILE_BYTES = 16 * 1024 * 1024, MAX_BYTES = 48 * 1024 * 1024;
 const RECORD_LIMIT = 64 * 1024 * 1024;
 const SHA = /^[a-f0-9]{64}$/;
-const frameworkDirectory=name=>['.git','.prnext-cache','.prnext','.prnext-incremental-stage'].includes(name)||/^\.prnext-(?:build|backup|config|postcss)-/.test(name);
+const frameworkDirectory=name=>['.git','.prnext-cache','.prnext','.prnext-gc','.prnext-incremental-stage'].includes(name)||/^\.prnext-(?:build|backup|config|postcss)-/.test(name);
 const frameworkPointer=name=>/^\.prnext-output(?:\.json|-.+\.tmp)$/.test(name);
 const ignored = entry => entry.isDirectory() && (entry.name==='node_modules'||frameworkDirectory(entry.name)) || frameworkPointer(entry.name);
 const safePath = file => typeof file === 'string' && file.length < 32768 && path.isAbsolute(file) && !file.includes('\0');
 const inside = (root, file) => { const relative = path.relative(root, file); return relative === '' || !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep); };
-export const withCompilationGraphCacheReporting = run => reports.run({ kinds: new Map(), identities:new Map(), listings:new Map(),listingNames:0 }, run);
+export const withCompilationGraphCacheReporting = run => reports.run({ kinds: new Map(), identities:new Map(), listings:new Map(),listingNames:0,discovery:{metadataReads:0,metadataHits:0,parentVisits:0} }, run);
 export function compilationGraphCacheReport() {
   const kinds = [...(reports.getStore()?.kinds || [])].map(([kind, value]) => ({ kind, ...value, reasons: { ...value.reasons } }));
-  return { version: 1, scope: 'eligible-production-compilation-graphs', kinds,
+  return { version: 1, scope: 'eligible-production-compilation-graphs', kinds,discovery:{...(reports.getStore()?.discovery||{metadataReads:0,metadataHits:0,parentVisits:0})},
     hits: kinds.reduce((sum, item) => sum + item.hits, 0), misses: kinds.reduce((sum, item) => sum + item.misses, 0),
     bypasses: kinds.reduce((sum, item) => sum + item.bypasses, 0), reusedBytes: kinds.reduce((sum, item) => sum + item.reusedBytes, 0) };
 }
@@ -83,20 +83,34 @@ async function directoryDigest(directory, budget, started = Infinity, lookup = f
 async function snapshot(root, dependencies, { started = Infinity, imports = [], rejectTsconfig = false, styleTargets=false, baseline, excluded = [] } = {}) {
   if (!Array.isArray(dependencies) || dependencies.length > MAX_FILES || dependencies.some(file => !safePath(file))) throw Error('dependency-limit');
   const files = new Set(dependencies), directories = new Set(), trees = new Set([root]), fullDirectories = new Set();
+  // Discovery metadata is shared only within this snapshot. The final source
+  // digests and directory listings below always perform their own validation.
+  const metadataCache=new Map(),expandedParents=new Set(),packageRoots=new Map(),stats=reports.getStore()?.discovery;
+  const metadata=async file=>{
+    if(metadataCache.has(file)){if(stats)stats.metadataHits++;return metadataCache.get(file);}
+    if(metadataCache.size>=MAX_DIRECTORIES*8)throw Error('resolution-limit');
+    if(stats)stats.metadataReads++;
+    const pending=lstat(file).catch(error=>{if(error.code==='ENOENT')return;throw error;});
+    metadataCache.set(file,pending);return pending;
+  };
   if(dependencies.some(file=>path.dirname(file).split(path.sep).some(frameworkDirectory)||frameworkPointer(path.basename(file))||excluded.some(directory=>inside(directory,file))))throw Error('generated-input');
   for(const name of ['package.json','package-lock.json','npm-shrinkwrap.json','pnpm-lock.yaml','yarn.lock','bun.lock','bun.lockb','.env','.env.local','.env.production','.env.production.local','.env.development','.env.development.local','.env.test','.env.test.local']){
-    const file=path.join(root,name);try{const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink())throw Error('unsafe-config');files.add(file);}catch(error){if(error.code!=='ENOENT')throw error;}
+    const file=path.join(root,name),info=await metadata(file);if(info){if(!info.isFile()||info.isSymbolicLink())throw Error('unsafe-config');files.add(file);}
   }
   const addParents = async file => {
     let directory = path.dirname(file);
     while (true) {
+      if(expandedParents.has(directory))break;
+      expandedParents.add(directory);if(stats)stats.parentVisits++;
       directories.add(directory);
       // Node's package search includes missing nearer node_modules directories.
       directories.add(path.join(directory, 'node_modules'));
+      if(directories.size>MAX_DIRECTORIES)throw Error('resolution-limit');
       for (const name of ['package.json', 'tsconfig.json', 'jsconfig.json', ...(styleTargets?['.browserslistrc','browserslist']:[])]) {
         const candidate = path.join(directory, name);
         try {
-          const info = await lstat(candidate);
+          const info = await metadata(candidate);
+          if(!info)continue;
           if(name==='browserslist'&&info.isDirectory())continue;
           if (rejectTsconfig && /^(?:ts|js)config\.json$/.test(name)) throw Error('untracked-tsconfig');
           if (!info.isFile() || info.isSymbolicLink() || info.size>MAX_FILE_BYTES) throw Error('unsafe-config');
@@ -111,16 +125,22 @@ async function snapshot(root, dependencies, { started = Infinity, imports = [],
       const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
     }
   };
+  const packageRoot=async file=>{
+    let directory=path.dirname(file),found,visited=[];
+    while(true){
+      if(packageRoots.has(directory)){found=packageRoots.get(directory);break;}
+      visited.push(directory);
+      if((await metadata(path.join(directory,'package.json')))?.isFile()){found=directory;break;}
+      const parent=path.dirname(directory);if(parent===directory)break;directory=parent;
+    }
+    for(const directory of visited)packageRoots.set(directory,found);
+    return found;
+  };
   for (const file of dependencies) {
     await addParents(file);
     // Package export/browser maps may choose an absent file anywhere inside the
     // package. Directory names, including absence, participate in invalidation.
-    let directory = path.dirname(file);
-    while (true) {
-      try { if ((await lstat(path.join(directory, 'package.json'))).isFile()) { trees.add(directory); break; } }
-      catch (error) { if (error.code !== 'ENOENT') throw error; }
-      const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
-    }
+    const tree=await packageRoot(file);if(tree)trees.add(tree);
   }
   for (const [importer, specifier] of imports) {
     if (typeof specifier !== 'string' || /^(?:node:|[./\\]|[A-Za-z]:)/.test(specifier)) continue;
@@ -129,7 +149,7 @@ async function snapshot(root, dependencies, { started = Infinity, imports = [],
     let directory = path.dirname(importer);
     while (true) {
       const candidate = path.join(directory, 'node_modules', name);
-      try { const info = await lstat(candidate); if (info.isSymbolicLink()) throw Error('linked-package'); if (info.isDirectory()) trees.add(candidate); }
+      try { const info = await metadata(candidate); if(info){if (info.isSymbolicLink()) throw Error('linked-package'); if (info.isDirectory()) trees.add(candidate);} }
       catch (error) { if (error.code !== 'ENOENT') throw error; }
       const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
     }

package/build/compilation-storage.mjs

@@ -0,0 +1,190 @@
+// Only these framework-owned, regenerable caches participate in the common
+// budget. Runtime data, page/image indexes, invalidations and app files do not.
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {lstat,open,opendir,realpath,rename,unlink} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {withBuildLock} from './build-lock.mjs';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from '../runtime/storage-path.mjs';
+
+const MiB=1024*1024,DEFAULT=256*MiB,MAX_SCAN=32768;
+const storage=new AsyncLocalStorage();
+const namespaces={
+  'transforms-v1':/^[a-f0-9]{64}\.json$/,
+  'transforms-dev-v1':/^[a-f0-9]{64}\.json$/,
+  'runtime-bundle-v2':/^[a-f0-9]{64}\.json$/,
+  'loaders-v2':/^[a-f0-9]{64}\.json$/,
+  'compilation-graphs-v1':/^[a-f0-9]{64}\.json$/,
+  'compilation-graphs-v2':/^[a-f0-9]{64}\.(?:graph|blob)$/,
+  'fonts-v1':/^[a-f0-9]{64}\.bin$/,
+  'precompress-v1':/^[a-f0-9]{64}\.(?:gz|br)$/,
+  'dev-compiler-v8':null,
+  'node-compile-v1':null,
+};
+export function validateCompilationCache(value={}){
+  if(!value||typeof value!=='object'||![Object.prototype,null].includes(Object.getPrototypeOf(value))||Reflect.ownKeys(value).some(key=>key!=='maxDiskSize'))throw new TypeError('compilationCache accepts only maxDiskSize, in bytes.');
+  const maxDiskSize=value.maxDiskSize===undefined?DEFAULT:value.maxDiskSize;
+  if(!Number.isSafeInteger(maxDiskSize)||maxDiskSize<0||maxDiskSize>4*1024*MiB)throw new TypeError('compilationCache.maxDiskSize must be an integer from 0 to 4294967296 bytes.');
+  return {maxDiskSize};
+}
+export function configureCompilationStorage(policy){const context=storage.getStore();if(context)context.policy=validateCompilationCache(policy);}
+async function realDirectory(directory){const info=await lstat(directory).catch(()=>null);return info?.isDirectory()&&!info.isSymbolicLink();}
+const sameFile=(left,right)=>left.isFile()&&!left.isSymbolicLink()&&left.ino===right.ino&&left.dev===right.dev&&left.size===right.size&&left.mtimeMs===right.mtimeMs;
+async function unchangedFile(file,snapshot,guards){
+  if(!await verifyStorageDirectories(guards))return false;
+  const current=await lstat(file).catch(()=>null);
+  return !!current&&sameFile(current,snapshot)&&sameStoragePath(await realpath(file),file)&&await verifyStorageDirectories(guards);
+}
+async function boundedJson(file,guards){
+  let descriptor;
+  try{
+    if(guards&&!await verifyStorageDirectories(guards))return null;
+    const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink()||info.size>4096)return null;
+    descriptor=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+    if(!sameFile(await descriptor.stat(),info))return null;
+    const contents=await descriptor.readFile('utf8');
+    if(guards&&!await unchangedFile(file,info,guards))return null;
+    return JSON.parse(contents);
+  }catch{return null;}finally{await descriptor?.close().catch(()=>{});}
+}
+function alive(pid){try{process.kill(pid,0);return true;}catch(error){return error.code!=='ESRCH';}}
+async function pinned(directory,{clean=false,guards}={}){
+  let scanned=0,active=false;
+  if(!await verifyStorageDirectories(guards))return {active:true,changed:true};
+  try{
+    for await(const entry of await opendir(directory)){
+      if(++scanned>8192)return {active:true,changed:false};
+      const name=entry.name;
+      if(!/^\.lease-\d+-[a-f0-9-]{36}\.json$/.test(name))continue;
+      const file=path.join(directory,name),info=await lstat(file).catch(()=>null),owner=await boundedJson(file,guards);
+      if(!owner||owner.host!==hostname()||!Number.isSafeInteger(owner.pid)||owner.pid<1||String(owner.pid)!==name.split('-')[1]||alive(owner.pid)){active=true;continue;}
+      if(clean&&info&&await unchangedFile(file,info,guards))await unlink(file).catch(()=>{});
+    }
+  }catch{return {active:true,changed:true};}
+  return {active,changed:!await verifyStorageDirectories(guards)};
+}
+async function storedPolicy(root){return validateCompilationCache(await boundedJson(path.join(root,'.prnext-cache','compilation-policy.json'))||{});}
+async function savePolicy(root,policy){
+  const directory=path.join(root,'.prnext-cache'),guards=[await captureStorageDirectory(root),await captureStorageDirectory(directory)];
+  if(!await verifyStorageDirectories(guards))return;
+  const temporary=path.join(directory,`.policy-${randomUUID()}.tmp`);
+  let temporaryInfo;
+  try{
+    if(!await verifyStorageDirectories(guards))return;
+    const file=await open(temporary,'wx',0o600);try{await file.writeFile(JSON.stringify(policy));temporaryInfo=await file.stat();}finally{await file.close();}
+    if(await unchangedFile(temporary,temporaryInfo,guards))await rename(temporary,path.join(directory,'compilation-policy.json'));
+  }catch{/* Optional cache metadata cannot fail compilation. */}
+  finally{if(temporaryInfo&&await unchangedFile(temporary,temporaryInfo,guards).catch(()=>false))await unlink(temporary).catch(()=>{});}
+}
+
+/** Stats never execute application config. The budget is from the last build. */
+export async function compilationStorageStats(root,{maxDiskSize}={}){
+  root=await realpath(root);const base=path.join(root,'.prnext-cache');
+  let policy;
+  if(maxDiskSize!==undefined)policy=validateCompilationCache({maxDiskSize});
+  else try{policy=await storedPolicy(root);}catch{policy=validateCompilationCache();}
+  const report={version:1,root,maxDiskSize:policy.maxDiskSize,bytes:0,files:0,scanComplete:true,categories:[],excluded:['runtime data and SQLite','page and image caches','unknown files and directories']};
+  if(!await realDirectory(base))return report;
+  const baseGuards=[await captureStorageDirectory(root),await captureStorageDirectory(base)];
+  if(!await verifyStorageDirectories(baseGuards)){report.scanComplete=false;return report;}
+  let scanned=0;
+  for(const [name,pattern] of Object.entries(namespaces)){
+    const directory=path.join(base,name);if(!await realDirectory(directory))continue;
+    const guards=[...baseGuards,await captureStorageDirectory(directory)],treeGuards=[...guards];
+    const lease=await pinned(directory,{guards});
+    if(lease.changed){report.scanComplete=false;break;}
+    const category={name,bytes:0,files:0,pinned:lease.active,entries:[],guards};
+    async function collect(folder,parentGuards,depth=0){
+      if(depth>3){report.scanComplete=false;return;}
+      if(!await verifyStorageDirectories(parentGuards)){report.scanComplete=false;return;}
+      try{
+        for await(const entry of await opendir(folder)){
+          if(++scanned>MAX_SCAN){report.scanComplete=false;return;}
+          const filename=path.join(folder,entry.name),info=await lstat(filename).catch(()=>null);
+          if(!info||info.isSymbolicLink())continue;
+          if(!pattern&&info.isDirectory()&&!entry.name.startsWith('.')){
+            const snapshot=await captureStorageDirectory(filename);treeGuards.push(snapshot);
+            await collect(filename,[...parentGuards,snapshot],depth+1);
+          }else if(info.isFile()){
+            const temporary=!!pattern&&/^[a-f0-9]{64}\.(?:json|graph|blob|bin|gz|br)\.[a-f0-9-]{36}\.tmp$/.test(entry.name);
+            if(!(pattern?pattern.test(entry.name)||temporary:!entry.name.startsWith('.')))continue;
+            category.entries.push({filename,size:info.size,time:info.mtimeMs,ino:info.ino,dev:info.dev,temporary,pinned:temporary&&Date.now()-info.mtimeMs<3600000,guards:parentGuards});category.bytes+=info.size;category.files++;
+          }
+          if(!report.scanComplete)return;
+        }
+      }catch{report.scanComplete=false;}
+      if(!await verifyStorageDirectories(parentGuards))report.scanComplete=false;
+    }
+    await collect(directory,guards);
+    if(!await verifyStorageDirectories(treeGuards))report.scanComplete=false;
+    report.categories.push(category);report.bytes+=category.bytes;report.files+=category.files;
+    if(!report.scanComplete)break;
+  }
+  return report;
+}
+function publicReport(report){return {...report,categories:report.categories.map(({entries,guards,...category})=>category)};}
+export async function inspectCompilationStorage(root,options){return publicReport(await compilationStorageStats(root,options));}
+
+// Called only under the existing interprocess publisher lock. Long-lived dev
+// compilers retain their cache until shutdown; managed V8 workers pin theirs.
+export async function pruneCompilationStorage(root,{maxDiskSize,dryRun=false,locked=false}={}){
+  if(!locked)return withBuildLock(root,canonical=>pruneCompilationStorage(canonical,{maxDiskSize,dryRun,locked:true}));
+  const report=await compilationStorageStats(root,{maxDiskSize});
+  let dev=false;try{await lstat(path.join(report.root,'.prnext-dev.lock'));dev=true;}catch(error){if(error.code!=='ENOENT')dev=true;}
+  const result={...publicReport(report),dryRun,beforeBytes:report.bytes,afterBytes:report.bytes,removedBytes:0,removedFiles:0,deferred:dev||!report.scanComplete,reason:dev?'Development is running; stop it to reclaim compilation caches.':!report.scanComplete?'The scan limit was reached; no files were removed.':undefined};
+  if(result.deferred)return result;
+  const units=[];
+  for(const category of report.categories){
+    if(category.pinned)continue;
+    const lease=await pinned(path.join(report.root,'.prnext-cache',category.name),{clean:!dryRun,guards:category.guards});
+    if(lease.changed){result.scanComplete=false;result.deferred=true;result.reason='A compiler cache directory changed; no further files were removed.';return result;}
+    if(lease.active){result.categories.find(value=>value.name===category.name).pinned=true;continue;}
+    // Graph records share content-addressed blobs. Evict this bounded namespace
+    // together so a global trim cannot strand metadata or remove shared bytes.
+    if(category.name==='compilation-graphs-v2'&&category.entries.length){
+      const graphs=category.entries.filter(entry=>!entry.temporary);if(graphs.length)units.push(graphs);
+      for(const entry of category.entries)if(entry.temporary&&!entry.pinned)units.push([entry]);
+    }
+    else for(const entry of category.entries)if(!entry.pinned)units.push([entry]);
+  }
+  units.sort((a,b)=>Math.max(...a.map(e=>e.time))-Math.max(...b.map(e=>e.time)));
+  for(const entries of units){
+    if(result.afterBytes<=report.maxDiskSize&&!entries.some(entry=>entry.temporary))continue;
+    for(const entry of entries){
+      try{
+        // Do not unlink an entry replaced after this snapshot (or a symlink).
+        if(!await verifyStorageDirectories(entry.guards)){result.scanComplete=false;result.deferred=true;result.reason='A compiler cache directory changed; no further files were removed.';return result;}
+        const current=await lstat(entry.filename);
+        if(!current.isFile()||current.isSymbolicLink()||current.ino!==entry.ino||current.dev!==entry.dev||current.size!==entry.size||current.mtimeMs!==entry.time)continue;
+        if(!sameStoragePath(await realpath(entry.filename),entry.filename)||!await verifyStorageDirectories(entry.guards)){result.scanComplete=false;result.deferred=true;result.reason='A compiler cache directory changed; no further files were removed.';return result;}
+        if(!dryRun)await unlink(entry.filename);
+        result.afterBytes-=entry.size;result.removedBytes+=entry.size;result.removedFiles++;
+      }catch{/* Busy/changed files remain visible and retryable next time. */}
+    }
+  }
+  result.overBudget=result.afterBytes>report.maxDiskSize;
+  return result;
+}
+
+export async function withCompilationStorage(root,run){
+  if(process.env.PRNEXT_BUILD_CACHE==='0')return run();
+  let policy;try{policy=await storedPolicy(root);}catch{policy=validateCompilationCache();}
+  const context={policy};
+  return storage.run(context,async()=>{
+    let value;
+    try{value=await run();return value;}
+    finally{
+      await savePolicy(root,context.policy);
+      try{
+        // A live dev session pins compiler state. Avoid a full disk scan after
+        // every keystroke; shutdown applies the stored policy once it drains.
+        const dev=await lstat(path.join(root,'.prnext-dev.lock')).catch(()=>null);
+        const report=dev?{version:1,...context.policy,deferred:true,reason:'Development is running; maintenance runs after shutdown.'}:await pruneCompilationStorage(root,{...context.policy,locked:true});
+        if(value&&typeof value==='object')value.compilationStorage=report;
+      }
+      catch{/* Retention failure must not hide a build error. */}
+    }
+  });
+}

package/build/compiler.mjs

@@ -16,9 +16,10 @@ import {withSourceMaps,configureSourceMaps,inlineSourceMap} from './source-maps.
 import { optimizeImportsPlugins } from './optimize-imports.mjs';
 import {recordBuildAnalysis} from './analyze.mjs';
 import {recordDevDependencies,developmentDependencies,developmentStylePlans,developmentStyleDependencies,developmentModules} from './dev-dependencies.mjs';
-import {normalizeReactCompilerConfig,REACT_COMPILER_VERSION} from './react-compiler.mjs';
+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';
 
@@ -27,7 +28,7 @@ const compilation = new AsyncLocalStorage();
 export const withCompilation = callback => withCompilationGraphCacheReporting(()=>withReactCompilerReporting(()=>withSourceMaps(()=>compilation.run({ targets: new Map(), loaded: new Map() }, callback))));
 export function configureCompiler(options) {
   Object.assign(compilation.getStore() || {}, options);configureSourceMaps(options.dev || options.config?.productionBrowserSourceMaps);
-  configureReactCompilerReporting({...options,config:{reactCompiler:options.config?.reactCompiler ? normalizeReactCompilerConfig(options.config.reactCompiler) : false},compilerVersion:REACT_COMPILER_VERSION});
+  configureReactCompilerReporting({...options,config:{reactCompiler:options.config?.reactCompiler ? normalizeReactCompilerConfig(options.config.reactCompiler) : false},compilerVersion:reactCompilerVersion(options.config?.reactCompiler,options.root)});
 }
 export const buildAnalysisRecords=()=>compilation.getStore()?.analysis;
 export const buildAnalysisRoutes=()=>compilation.getStore()?.analysisRoutes;
@@ -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);
@@ -165,7 +166,7 @@ async function compileGraph(options,role) {
   // no hooks or runtime output and leaves the opt-out graph exactly as before.
   if ((options.plugins || []).some(plugin => framework.test(plugin.name)) && state?.config?.reactCompiler) {
     const settings=normalizeReactCompilerConfig(state.config.reactCompiler);
-    const fingerprint=createHash('sha256').update(JSON.stringify([REACT_COMPILER_VERSION,settings])).digest('hex').slice(0,24);
+    const fingerprint=createHash('sha256').update(JSON.stringify([reactCompilerVersion(settings,state.root),settings])).digest('hex').slice(0,24);
     options={...options,plugins:[...options.plugins,{name:'prnext-react-compiler-'+fingerprint,setup(){}}]};
   }
   if ((options.plugins || []).some(plugin => framework.test(plugin.name))) options = { ...options, plugins: optimizeImportsPlugins(options.plugins, state?.config?.experimental?.optimizePackageImports) };

package/build/config.mjs

@@ -25,6 +25,8 @@ import {validatePrerenderConfig} from './prerender-config.mjs';
 import {validateHtmlOnly} from './html-only-config.mjs';
 import { validateProxyBodySize } from './proxy-body-config.mjs';
 import { normalizeReactCompilerConfig } from './react-compiler.mjs';
+import {validateCompilationCache} from './compilation-storage.mjs';
+import {validateServerConfig} from './server-config.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const configName = /^(?:next|prnext)\.config\.(?:js|mjs|cjs|ts)$/;
@@ -37,6 +39,8 @@ supported.add('workerMemory');
 supported.add('workerRetirement');
 supported.add('workerPreload');
 supported.add('deploymentRetention');
+supported.add('compilationCache');
+supported.add('server');
 supported.add('prerender');
 supported.add('htmlOnly');
 supported.add('cssEngine');
@@ -107,6 +111,7 @@ export function validateProjectConfig(input, filename = 'project config') {
   config.workerRetirement = validateWorkerRetirement(config.workerRetirement);
   config.workerPreload=validateWorkerPreload(config.workerPreload);
   config.deploymentRetention=validateDeploymentRetention(config.deploymentRetention);
+  config.compilationCache=validateCompilationCache(config.compilationCache);
   config.prerender=validatePrerenderConfig(config.prerender);
   config.htmlOnly=validateHtmlOnly(config.htmlOnly);
   config.cssEngine ??= 'auto';
@@ -127,6 +132,7 @@ export function validateProjectConfig(input, filename = 'project config') {
   }
   if (config.webpack !== undefined && typeof config.webpack !== 'function') throw new TypeError('webpack must be a configuration function');
   config.turbopack = validateTurbopack(config.turbopack);
+  config.server = validateServerConfig(config.server);
   config.i18n = validateI18n(config.i18n);
   if (config.i18n && config.output === 'export') throw new Error("i18n and output: 'export' cannot be combined; use explicit locale routes for static exports");
   validateStandaloneConfig(config);
@@ -164,13 +170,28 @@ export function validateProjectConfig(input, filename = 'project config') {
   if (config.sassOptions !== undefined && (!config.sassOptions || typeof config.sassOptions !== 'object' || Array.isArray(config.sassOptions))) throw new Error(`${filename}: sassOptions must be an object.`);
   if (!config.experimental || typeof config.experimental !== 'object' || Array.isArray(config.experimental)) throw new Error(`${filename}: experimental must be an object.`);
   for (const key of Object.keys(config.experimental)) {
-    if (!['nextScriptWorkers', 'serverActions', 'optimizePackageImports', 'proxyClientMaxBodySize', 'lazyDynamicImports'].includes(key)) throw new Error(`${filename}: experimental.${key} is not supported by PRNext. It cannot be silently ignored.`);
+    if (!['nextScriptWorkers', 'serverActions', 'optimizePackageImports', 'proxyClientMaxBodySize', 'lazyDynamicImports', 'streamingRequestBodies', 'nativePprShell', 'parallelBuilds'].includes(key)) throw new Error(`${filename}: experimental.${key} is not supported by PRNext. It cannot be silently ignored.`);
   }
   const nextScriptWorkers = config.experimental.nextScriptWorkers === undefined ? false : config.experimental.nextScriptWorkers;
   if (typeof nextScriptWorkers !== 'boolean') throw new Error(`${filename}: experimental.nextScriptWorkers must be a boolean.`);
   const lazyDynamicImports=config.experimental.lazyDynamicImports===undefined?false:config.experimental.lazyDynamicImports;
   if(typeof lazyDynamicImports!=='boolean')throw new Error(`${filename}: experimental.lazyDynamicImports must be a boolean.`);
-  config.experimental = { nextScriptWorkers, lazyDynamicImports, serverActions: validateServerActions(config.experimental.serverActions), optimizePackageImports: validateOptimizePackageImports(config.experimental.optimizePackageImports), proxyClientMaxBodySize: validateProxyBodySize(config.experimental.proxyClientMaxBodySize) };
+  const streamingRequestBodies = config.experimental.streamingRequestBodies === undefined ? false : config.experimental.streamingRequestBodies;
+  const nativePprShell = config.experimental.nativePprShell === undefined ? false : config.experimental.nativePprShell;
+  for (const [key, value] of Object.entries({streamingRequestBodies, nativePprShell})) {
+    if (typeof value !== 'boolean') throw new Error(`${filename}: experimental.${key} must be a boolean.`);
+  }
+  if (nativePprShell && !config.cacheComponents) throw new Error(`${filename}: experimental.nativePprShell requires cacheComponents: true.`);
+  let parallelBuilds = config.experimental.parallelBuilds === undefined ? false : config.experimental.parallelBuilds;
+  if (parallelBuilds !== false) {
+    if (parallelBuilds === true) parallelBuilds = {};
+    if (!parallelBuilds || typeof parallelBuilds !== 'object' || Array.isArray(parallelBuilds)) throw new Error(`${filename}: experimental.parallelBuilds must be a boolean or an object.`);
+    for (const key of Object.keys(parallelBuilds)) if (!['maxWorkers', 'maxMemoryMb'].includes(key)) throw new Error(`${filename}: unknown parallelBuilds option ${key}.`);
+    parallelBuilds = {maxWorkers: parallelBuilds.maxWorkers === undefined ? 4 : parallelBuilds.maxWorkers, maxMemoryMb: parallelBuilds.maxMemoryMb === undefined ? 1024 : parallelBuilds.maxMemoryMb};
+    if (!Number.isInteger(parallelBuilds.maxWorkers) || parallelBuilds.maxWorkers < 1 || parallelBuilds.maxWorkers > 8) throw new Error(`${filename}: parallelBuilds.maxWorkers must be between 1 and 8.`);
+    if (!Number.isInteger(parallelBuilds.maxMemoryMb) || parallelBuilds.maxMemoryMb < 256 || parallelBuilds.maxMemoryMb > 8192) throw new Error(`${filename}: parallelBuilds.maxMemoryMb must be between 256 and 8192.`);
+  }
+  config.experimental = { nextScriptWorkers, lazyDynamicImports, streamingRequestBodies, nativePprShell, parallelBuilds, serverActions: validateServerActions(config.experimental.serverActions), optimizePackageImports: validateOptimizePackageImports(config.experimental.optimizePackageImports), proxyClientMaxBodySize: validateProxyBodySize(config.experimental.proxyClientMaxBodySize) };
   for (const key of ['basePath', 'assetPrefix']) {
     if (typeof config[key] !== 'string' || Buffer.byteLength(config[key]) > 4096) throw new Error(`${filename}: ${key} must be a string of at most 4096 bytes.`);
   }

package/build/create.mjs

@@ -129,7 +129,7 @@ h1 { font-size: clamp(2.5rem, 8vw, 4rem); letter-spacing: -.04em; }
 p { line-height: 1.6; }
 code { font-size: .95em; }
 `],
-    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
+    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.prnext-gc/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
     ['README.md', `# ${name}\n\nA minimal PRNext application.\n\nRun \`npm install\` if dependencies have not been installed, then:\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nEdit \`app/page.${extension}\`. Use the local URL printed by the server.\n\n\`\`\`sh\nnpm run check\n${typescript ? 'npm run typecheck\n' : ''}npm run build\nnpm start\n\`\`\`\n\nUse another port with \`npm run dev -- --port 3001\` when needed.\n\n[PRNext documentation](https://prnext.dev) · Installed AI guide: \`npx --no-install prnext docs --ai\`.\nPRNext is experimental; Next.js compatibility is partial.\n`],
     ['AGENTS.md', `# PRNext project\n\nThis application uses \`@thomas.f/prnext\`. Before changing routing, configuration, data fetching or deployment, read the installed guide at \`node_modules/@thomas.f/prnext/AI.md\` or run:\n\n\`\`\`sh\nnpx --no-install prnext docs --ai\nnpx --no-install prnext docs --ai --list\n\`\`\`\n\nRead only the relevant topic with \`npx --no-install prnext docs --ai <topic>\`. The installed documentation is version-specific; do not assume full Next.js compatibility. Preserve the project's package manager and lockfile.\n`],
   ]);

package/build/css-modules.mjs

@@ -138,6 +138,10 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
 
   return {
     compile:get,
+    async parallelSafe() {
+      eligibility ??= cacheEligible();
+      return typeof sassOptions?.additionalData !== 'function' && await eligibility;
+    },
     async mappings(){return Promise.all([...cache].map(async([file,result])=>({file,mapping:(await result).mapping,watchFiles:(await result).watchFiles})));},
     plugin(browser, { emitStyles = () => true } = {}) {
       return {

package/build/dev-action-graph.mjs

@@ -0,0 +1,21 @@
+import path from 'node:path';
+
+// Build-private provenance, never Action arguments, source text or encryption
+// material. Unknown/external owners deliberately disable selective refresh.
+export function developmentActionMetadata(root, actions) {
+  const records = [], identities = new Set(); let bytes = 0;
+  for (const action of actions) {
+    const file = path.relative(root, action.file).replaceAll(path.sep, '/');
+    const runtimes = [...(action.runtimes?.size ? action.runtimes : ['nodejs'])].sort();
+    const record = { id: action.id, file, binding: action.binding, runtimes };
+    const identity = file + '\0' + action.binding;
+    if (!/^[a-f0-9]{64}$/.test(action.id) || !file || file.startsWith('../') || path.isAbsolute(file) || /[:?\0]/.test(file) || file.startsWith('node_modules/') ||
+        typeof action.binding !== 'string' || !action.binding || action.binding.length > 1024 || identities.has(identity) ||
+        runtimes.some(runtime => !['nodejs', 'edge'].includes(runtime)) || records.length >= 10000 ||
+        (bytes += Buffer.byteLength(JSON.stringify(record))) > 1024 * 1024)
+      return { version: 1, complete: false, actions: [] };
+    identities.add(identity); records.push(record);
+  }
+  records.sort((a, b) => a.file.localeCompare(b.file) || a.binding.localeCompare(b.binding));
+  return { version: 1, complete: true, actions: records };
+}

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/font-cache.mjs

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile, rename, rm, readdir, lstat } from 'node:fs/promises';
+import { open, writeFile, rename, rm, readdir, lstat } from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {privateCacheDirectory} from './persistent-cache.mjs';
 import path from 'node:path';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
@@ -11,12 +13,14 @@ let writes = Promise.resolve();
  */
 export async function cachedFontResource(root, url, maximum, accept, download) {
   if (!root) return download();
-  const directory = path.join(root, '.prnext-cache', 'fonts-v1');
+  const directory = await privateCacheDirectory(root,'fonts-v1');
+  if(!directory)return download();
   const file = path.join(directory, hash(JSON.stringify([url, accept])) + '.bin');
   try {
     const metadata = await lstat(file);
-    if (metadata.isFile() && metadata.size > 65 && metadata.size <= maximum + 65) {
-      const stored = await readFile(file);
+    if (metadata.isFile() && !metadata.isSymbolicLink() && metadata.size > 65 && metadata.size <= maximum + 65) {
+      const handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+      let stored;try{const info=await handle.stat();if(!info.isFile()||info.size>maximum+65)throw Object.assign(Error('Font cache changed'),{code:'ENOENT'});stored=await handle.readFile();}finally{await handle.close();}
       const bytes = stored.subarray(65);
       if (stored[64] === 10 && hash(bytes) === stored.toString('ascii', 0, 64)) return bytes;
     }
@@ -24,10 +28,9 @@ export async function cachedFontResource(root, url, maximum, accept, download) {
   const bytes = await download();
   if (!bytes.length || bytes.length > maximum) throw new Error('Font resource exceeds its cache input limit');
   const task = writes.catch(() => {}).then(async () => {
-    await mkdir(directory, { recursive: true });
     const temporary = file + '.' + randomUUID() + '.tmp';
     try {
-      await writeFile(temporary, Buffer.concat([Buffer.from(hash(bytes) + '\n'), bytes]), { flag: 'wx' });
+      await writeFile(temporary, Buffer.concat([Buffer.from(hash(bytes) + '\n'), bytes]), { flag: 'wx',mode:0o600 });
       await rename(temporary, file);
     } finally { await rm(temporary, { force: true }); }
     const entries = [];