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

package/build/build-retention.mjs

@@ -0,0 +1,119 @@
+// Recovery journal for framework-owned build stages. Uncommitted backups can
+// be the only working build after a crash: keep them for explicit recovery.
+import {mkdir,open,opendir,lstat,rename,unlink,rm,realpath} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+import path from 'node:path';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from '../runtime/storage-path.mjs';
+const uuid='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+const recordName=new RegExp('^'+uuid+'\\.json$'),stageName=new RegExp('^\\.prnext-build-'+uuid+'$'),backupName=new RegExp('^\\.prnext-backup-'+uuid+'$');
+const MAX_JOURNAL_NAMES=32768,MAX_PAGE=128;
+async function container(root){
+  const directory=path.join(root,'.prnext-gc');
+  await mkdir(directory,{mode:0o700}).catch(error=>{if(error.code!=='EEXIST')throw error;});
+  const info=await lstat(directory);if(!info.isDirectory()||info.isSymbolicLink())throw Error('Build recovery journal must be a real directory.');
+  return directory;
+}
+async function readValue(file){
+  let handle;
+  try{
+    const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink()||info.size>4096)return null;
+    handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));if((await handle.stat()).size>4096)return null;
+    return JSON.parse(await handle.readFile('utf8'));
+  }catch{return null;}finally{await handle?.close().catch(()=>{});}
+}
+async function read(file){
+  const value=await readValue(file);
+  if(!value||value.version!==1||!Number.isSafeInteger(value.pid)||value.pid<1||typeof value.host!=='string'||!Number.isSafeInteger(value.createdAt)||!stageName.test(value.stage)||!backupName.test(value.backup)||typeof value.committed!=='boolean')return null;
+  return value;
+}
+async function save(file,value){
+  const temporary=file+'.'+randomUUID()+'.tmp';
+  try{const handle=await open(temporary,'wx',0o600);try{await handle.writeFile(JSON.stringify(value));}finally{await handle.close();}await rename(temporary,file);}
+  finally{await unlink(temporary).catch(()=>{});}
+}
+function alive(pid){try{process.kill(pid,0);return true;}catch(error){return error.code!=='ESRCH';}}
+async function remove(root,name,pattern){
+  if(!pattern.test(name))return false;
+  const target=path.resolve(root,name);if(path.dirname(target)!==root)return false;
+  const rootGuard=await captureStorageDirectory(root);if(!rootGuard)return false;
+  const info=await lstat(target).catch(error=>{if(error.code!=='ENOENT')throw error;});
+  if(!info)return 'missing';if(!info.isDirectory()||info.isSymbolicLink())return false;
+  const targetGuard=await captureStorageDirectory(target);
+  if(!targetGuard||!await verifyStorageDirectories([rootGuard,targetGuard]))return false;
+  // Root and basename were checked immediately before this scoped removal.
+  await rm(target,{recursive:true,force:true,maxRetries:3,retryDelay:50});return 'removed';
+}
+
+/** Caller holds withBuildLock for this canonical root. No age-only deletion. */
+export async function reclaimBuildStages(root,{now=Date.now(),graceMs=3600000,maxEntries=MAX_PAGE,maxListingEntries=MAX_JOURNAL_NAMES}={}){
+  const report={scanned:0,listed:0,removedStages:0,removedBackups:0,retainedRecoveryBackups:0,scanComplete:true,deferred:false};
+  const pageSize=Number.isSafeInteger(maxEntries)&&maxEntries>0?Math.min(maxEntries,MAX_PAGE):MAX_PAGE;
+  const listingLimit=Number.isSafeInteger(maxListingEntries)&&maxListingEntries>0?Math.min(maxListingEntries,MAX_JOURNAL_NAMES):MAX_JOURNAL_NAMES;
+  try{
+    root=path.resolve(root);const rootGuard=await captureStorageDirectory(root);
+    if(!rootGuard)return {...report,scanComplete:false,deferred:true,reason:'The build recovery root changed.'};
+    const directory=await container(root);
+    const guards=[rootGuard,await captureStorageDirectory(directory)];
+    if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+    const cursorFile=path.join(directory,'cursor.json');
+    const cursorInfo=await lstat(cursorFile).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    if(cursorInfo&&(!cursorInfo.isFile()||cursorInfo.isSymbolicLink()))return {...report,scanComplete:false,deferred:true,reason:'The build recovery cursor is not an ordinary file.'};
+    const saved=await readValue(cursorFile);
+    const after=saved?.version===1&&typeof saved.after==='string'&&recordName.test(saved.after)?saved.after:null;
+    const names=[];
+    for await(const entry of await opendir(directory)){
+      if(report.listed>=listingLimit)return {...report,scanComplete:false,deferred:true,reason:'The build recovery journal listing limit was reached; no stages were removed.'};
+      report.listed++;
+      if(recordName.test(entry.name))names.push(entry.name);
+    }
+    names.sort();
+    let start=after?names.findIndex(name=>name>after):0;if(start<0)start=0;
+    const page=names.slice(start,start+pageSize);
+    report.scanComplete=start+page.length>=names.length;
+    report.deferred=!report.scanComplete;
+    if(report.deferred)report.reason='More build recovery journals remain; the next build resumes this scan.';
+    for(const name of page){
+      if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+      report.scanned++;
+      const file=path.join(directory,name),owner=await read(file);
+      if(!owner||owner.host!==hostname()||alive(owner.pid)||now-owner.createdAt<graceMs)continue;
+      let stageGone=false,backupGone=false;
+      try{stageGone=await remove(root,owner.stage,stageName);if(stageGone==='removed')report.removedStages++;}catch{}
+      if(owner.committed){try{backupGone=await remove(root,owner.backup,backupName);if(backupGone==='removed')report.removedBackups++;}catch{}}
+      else{
+        const backup=await lstat(path.join(root,owner.backup)).catch(()=>null);
+        backupGone=!backup;if(backup)report.retainedRecoveryBackups++;
+      }
+      if(stageGone&&backupGone&&await verifyStorageDirectories(guards))await unlink(file).catch(()=>{});
+    }
+    if(!await verifyStorageDirectories(guards))return {...report,scanComplete:false,deferred:true,reason:'The build recovery directory changed.'};
+    // The caller owns the publisher lock, so a single persistent cursor advances
+    // across fresh CLI processes without renaming any live owner's journals.
+    await save(cursorFile,{version:1,after:report.scanComplete?null:page.at(-1)||null});
+  }catch{report.scanComplete=false;report.deferred=true;report.reason='Build recovery maintenance is unavailable; retry on a later build.';}
+  return report;
+}
+
+export async function trackBuildStage(root,{stage,backup}){
+  root=path.resolve(root);const rootGuard=await captureStorageDirectory(root);
+  if(!rootGuard)throw Error('Build recovery root must be a canonical physical directory.');
+  const value={version:1,pid:process.pid,host:hostname(),createdAt:Date.now(),stage:path.basename(stage),backup:path.basename(backup),committed:false};
+  if(!stageName.test(value.stage)||!backupName.test(value.backup)||!sameStoragePath(await realpath(path.dirname(path.resolve(stage))),root)||!sameStoragePath(await realpath(path.dirname(path.resolve(backup))),root))throw Error('Build recovery paths must be owned stages inside the project.');
+  const file=path.join(await container(root),randomUUID()+'.json');
+  const guards=[rootGuard,await captureStorageDirectory(path.dirname(file))];
+  if(!await verifyStorageDirectories(guards))throw Error('Build recovery directory changed before publication.');
+  await save(file,value);
+  return {
+    async committed(){value.committed=true;if(await verifyStorageDirectories(guards))await save(file,value);},
+    async cleanup(){
+      try{
+        const stageGone=await remove(root,value.stage,stageName);
+        // An uncommitted backup is kept until rollback has restored it.
+        const backupGone=value.committed?await remove(root,value.backup,backupName):!await lstat(path.join(root,value.backup)).catch(()=>null);
+        if(stageGone&&backupGone&&await verifyStorageDirectories(guards))await unlink(file);
+      }catch{/* Keep the journal so a later build can retry Windows busy files. */}
+    },
+  };
+}

package/build/bundle-runtime.mjs

@@ -15,7 +15,7 @@ export const runtimeEntryNames = Object.freeze([
 ].sort());
 
 /** Run once, after compiling application/Edge graphs and before any prerender. */
-export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
+export async function bundleRuntime(stage,{projectRoot,sourceDirectory,imageResponse=true}={}) {
   const resolvedStage = path.resolve(stage);
   if (!path.basename(resolvedStage).startsWith('.prnext-build-')) {
     throw new Error('Runtime bundling requires an unpublished PRNext build stage.');
@@ -35,7 +35,8 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   if (originals.some(entry => !entry.isFile() || entry.isSymbolicLink())) {
     throw new Error('Runtime source modules must be ordinary files.');
   }
-  for (const name of runtimeEntryNames) {
+  const selectedEntries = imageResponse ? runtimeEntryNames : runtimeEntryNames.filter(name => name !== 'og-loader');
+  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();
@@ -52,7 +53,7 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   if(projectRoot){
     directory=await privateCacheDirectory(projectRoot,'runtime-bundle-v2');
     if(directory){
-      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(runtimeEntryNames)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
+      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(selectedEntries)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
       for(const entry of [...originals].sort((a,b)=>a.name.localeCompare(b.name)))hash.update(JSON.stringify([entry.name,createHash('sha256').update(sources.get(path.join(input,entry.name))).digest('hex')]));
       key=hash.digest('hex');cached=await readCacheRecord(directory,key);
     }
@@ -61,10 +62,10 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   // no files change if parsing or resolution fails. The virtual output is a
   // sibling so all relative paths have the same depth as the final runtime.
   const virtualOutput = path.join(resolvedStage, '.runtime-bundle');
-  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&runtimeEntryNames.every(name=>cached.files.some(([file])=>file===name+'.mjs'));
+  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&selectedEntries.every(name=>cached.files.some(([file])=>file===name+'.mjs'))&& (imageResponse || !cached.files.some(([file])=>file==='og-loader.mjs'));
   const result = validCache?null:await build({
     absWorkingDir: input,
-    entryPoints: runtimeEntryNames.map(name => path.join(input, `${name}.mjs`)),
+    entryPoints: selectedEntries.map(name => path.join(input, `${name}.mjs`)),
     outdir: virtualOutput,
     outbase: input,
     entryNames: '[name]',
@@ -78,7 +79,7 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
     packages: 'external',
     // Edge's prepared VM is already a self-contained CJS artifact. Keeping it
     // external preserves its delayed import and original execution boundary.
-    external: ['../compat/*', './profiles.json', './*.cjs'],
+    external: ['../compat/*', './profiles.json', './*.cjs', './og/*'],
     minify: false,
     sourcemap: false,
     metafile: true,
@@ -94,7 +95,7 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
     }
     emitted.set(path.basename(file.path), file.contents);
   }
-  if (runtimeEntryNames.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
+  if (selectedEntries.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
   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.
@@ -105,6 +106,6 @@ export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   }
   // 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: runtimeEntryNames.length, moduleCount: emitted.size,cached:!!validCache,
+  return { entryCount: selectedEntries.length, moduleCount: emitted.size,cached:!!validCache,
     bytes: [...emitted.values()].reduce((sum, contents) => sum + contents.length, 0) };
 }

package/build/cache-command.mjs

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import {inspectCompilationStorage,pruneCompilationStorage,validateCompilationCache} from './compilation-storage.mjs';
+
+export async function cacheCommand(args){
+  if(args.length===1&&['--help','-h'].includes(args[0])){
+    console.log('prnext cache [directory] [--json]\nprnext cache [directory] --prune [--dry-run] [--max-bytes N] [--json]\n\nInspect compiler caches without executing application config. The budget comes\nfrom the last build (default 256 MiB). --max-bytes overrides this purge only.\nRuntime data, SQLite, page/image caches and application files are excluded.\nStop development before purging. Active worker caches remain pinned.');return;
+  }
+  let directory,prune=false,dryRun=false,json=false,maxDiskSize;
+  const seen=new Set();
+  for(let i=0;i<args.length;i++){
+    const arg=args[i];
+    if(arg.startsWith('--')){if(seen.has(arg))throw Error(`Duplicate cache option: ${arg}`);seen.add(arg);}
+    if(arg==='--prune')prune=true;
+    else if(arg==='--dry-run')dryRun=true;
+    else if(arg==='--json')json=true;
+    else if(arg==='--max-bytes'){
+      const value=args[++i];if(!/^\d+$/.test(value||''))throw Error('--max-bytes requires a byte count from 0 to 4294967296.');
+      maxDiskSize=validateCompilationCache({maxDiskSize:Number(value)}).maxDiskSize;
+    }else if(arg.startsWith('-')||directory!==undefined)throw Error('cache accepts one directory, --prune, --dry-run, --max-bytes N and --json.');
+    else directory=arg;
+  }
+  if((dryRun||maxDiskSize!==undefined)&&!prune)throw Error('--dry-run and --max-bytes require --prune.');
+  const root=path.resolve(directory||'.');
+  const report=prune?await pruneCompilationStorage(root,{maxDiskSize,dryRun}):await inspectCompilationStorage(root);
+  if(json){console.log(JSON.stringify(report,null,2));return;}
+  const size=value=>(value/1024/1024).toFixed(2)+' MiB';
+  console.log(`Compilation caches: ${size(report.bytes)} / ${size(report.maxDiskSize)}`);
+  for(const category of report.categories)console.log(`  ${category.name}: ${size(category.bytes)}, ${category.files} files${category.pinned?' (active worker)':''}`);
+  if(prune)console.log(report.deferred?report.reason:`${dryRun?'Would reclaim':'Reclaimed'} ${size(report.removedBytes)} in ${report.removedFiles} files; ${size(report.afterBytes)} retained.${report.overBudget?' Active or busy files remain above the budget.':''}`);
+  else if(!report.scanComplete)console.log('The scan limit was reached; totals are a lower bound.');
+}

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. */}
+    }
+  });
+}