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

package/runtime/dev-lazy-imports.mjs

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import {constants} from 'node:fs';
+import {readdir,readFile,writeFile,stat,lstat,open,mkdtemp,link,rm} from 'node:fs/promises';
+
+export const MAX_LAZY_ASSET_BYTES=128*1024*1024;
+export const MAX_LAZY_ASSET_FILES=16384;
+const token=/^\/_prnext\/lazy\/([a-f0-9]{24})$/;
+export function lazyImportIdentifier(raw){return token.exec(new URL(raw,'http://local').pathname)?.[1];}
+
+function receiptFiles(receipt,cacheId){
+  if(!receipt||receipt.version!==1||typeof cacheId!=='string'||!cacheId||cacheId.length>256||receipt.baseCacheId!==cacheId||!Array.isArray(receipt.files))throw Error('Invalid or obsolete deferred asset receipt');
+  if(receipt.files.length>MAX_LAZY_ASSET_FILES)throw Error('Deferred import exceeded the asset count budget');
+  const names=new Set(),files=[];let total=0;
+  for(const file of receipt.files){
+    const name=file?.name;
+    if(typeof name!=='string'||!name||name.length>255||!/^[A-Za-z0-9_.-]+$/.test(name)||name==='.'||name==='..'||name.endsWith('.')||/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name)||names.has(name.toLowerCase()))throw Error('Invalid or duplicate deferred asset receipt name');
+    if(!Number.isSafeInteger(file.bytes)||file.bytes<0||file.bytes>MAX_LAZY_ASSET_BYTES||(total+=file.bytes)>MAX_LAZY_ASSET_BYTES)throw Error('Deferred asset receipt exceeded the 128 MiB generation budget');
+    names.add(name.toLowerCase());files.push({name,bytes:file.bytes});
+  }
+  return files;
+}
+
+function regularAsset(info,bytes){
+  if(!info.isFile()||info.isSymbolicLink())throw Error('Invalid deferred asset: expected a regular file without symbolic links');
+  if(info.size!==bytes)throw Error('Deferred asset does not match the receipt byte size');
+  return info;
+}
+
+async function readReceiptAsset(filename,bytes,checked){
+  const expected=checked||regularAsset(await lstat(filename),bytes);
+  const file=await open(filename,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+  try{
+    const info=regularAsset(await file.stat(),bytes);
+    if(info.dev!==expected.dev||info.ino!==expected.ino)throw Error('Deferred asset changed after receipt validation');
+    // Metadata can race a writer. Read only the declared size plus one byte,
+    // rather than letting readFile allocate for a later, unbounded file size.
+    const data=Buffer.allocUnsafe(bytes);let offset=0;
+    while(offset<bytes){
+      const {bytesRead}=await file.read(data,offset,bytes-offset,offset);
+      if(!bytesRead)throw Error('Deferred asset ended before the receipt byte size');
+      offset+=bytesRead;
+    }
+    if((await file.read(Buffer.allocUnsafe(1),0,1,bytes)).bytesRead)throw Error('Deferred asset exceeded the receipt byte size');
+    return data;
+  }finally{await file.close();}
+}
+
+async function readExistingReceiptAsset(filename,bytes){
+  const info=await lstat(filename);
+  if(!info.isFile()||info.isSymbolicLink())throw Error('Invalid deferred asset: expected a regular file without symbolic links');
+  if(info.size!==bytes)throw Error('Deferred compilation produced a conflicting immutable asset');
+  return readReceiptAsset(filename,bytes,info);
+}
+
+/** Only registered tokens can reach the compiler. The caller serializes builds. */
+export async function materializeDevImport({root,current,id,compile}){
+  const registry=current.manifest.devLazy;
+  if(!registry||!registry.modules.some(item=>item.id===id))throw Error('Unknown deferred import identifier');
+  if(registry.outputs[id])return registry.outputs[id];
+  const built=await compile({id,modules:registry.modules,bridges:registry.bridges,shared:registry.shared});
+  const next=built.devLazy,target=next?.outputs?.[id];
+  if(!target)throw Error('The compiler did not produce the requested deferred import');
+  // New server implementations cannot be added to a running immutable runtime.
+  // Existing Server Action proxies are reused through the static ESM bridges.
+  if(Object.keys(built.app?.actions||{}).some(key=>!Object.hasOwn(current.manifest.app?.actions||{},key)))throw Error('A deferred module introduced a new Server Action. Import that action statically or disable experimental.lazyDynamicImports.');
+  const source=path.join(built.outputDirectory,'assets'),destination=path.join(root,current.directory,'assets');
+  const received=Object.hasOwn(built,'devLazyAssets');
+  const files=received?receiptFiles(built.devLazyAssets,current.manifest.cacheId):await readdir(source,{withFileTypes:true}),pending=[];let bytes=0;
+  if(files.length>MAX_LAZY_ASSET_FILES)throw Error('Deferred import exceeded the asset count budget');
+  if(received){
+    for(const directory of [source,destination]){const info=await lstat(directory);if(!info.isDirectory()||info.isSymbolicLink())throw Error('Invalid deferred asset directory');}
+    // Validate every declared file before reading any payload or publishing.
+    for(const file of files)file.info=regularAsset(await lstat(path.join(source,file.name)),file.bytes);
+  }
+  for(const file of files){
+    if(!received&&(!file.isFile()||file.name!==path.basename(file.name)))throw Error('Invalid deferred asset');
+    if(!received&&(await stat(path.join(source,file.name))).size>MAX_LAZY_ASSET_BYTES)throw Error('Deferred import asset exceeded the 128 MiB generation budget');
+    const data=received?await readReceiptAsset(path.join(source,file.name),file.bytes,file.info):await readFile(path.join(source,file.name));
+    const previous=await(received?readExistingReceiptAsset(path.join(destination,file.name),file.bytes):readFile(path.join(destination,file.name))).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    if(previous){if(!previous.equals(data))throw Error('Deferred compilation produced a conflicting immutable asset');continue;}
+    bytes+=data.length;
+    if(bytes+(current.lazyAssetBytes||0)>MAX_LAZY_ASSET_BYTES)throw Error('Deferred import assets exceeded the 128 MiB generation budget');
+    pending.push([file.name,data]);
+  }
+  if(pending.length){
+    // Partial writes stay outside the served assets directory. A hard link
+    // publishes a complete file atomically and exclusively without replacing an
+    // immutable asset, even if another writer wins between inspection and I/O.
+    const temporary=await mkdtemp(path.join(root,current.directory,'.lazy-publish-'));
+    current.lazyAssetBytes=(current.lazyAssetBytes||0)+bytes;
+    let retained=0,failure;
+    try{
+      for(const [name,data]of pending)await writeFile(path.join(temporary,name),data,{flag:'wx'});
+      for(const [name,data]of pending){
+        // A failed publication can have an uncertain outcome. Keep its charge
+        // conservatively; a retry can reuse a complete asset without recharging.
+        retained+=data.length;
+        try{await link(path.join(temporary,name),path.join(destination,name));}
+        catch(error){
+          if(error.code!=='EEXIST')throw error;
+          const existing=received?await readExistingReceiptAsset(path.join(destination,name),data.length):await readFile(path.join(destination,name));
+          if(!existing.equals(data))throw Error('Deferred compilation produced a conflicting immutable asset');
+          retained-=data.length;
+        }
+      }
+    }catch(error){failure=error;}
+    try{
+      await rm(temporary,{recursive:true,force:true,maxRetries:10,retryDelay:100});
+      // Reclaim only unpublished bytes after deletion of our private staging
+      // files is confirmed. Complete public files are never removed on failure.
+      current.lazyAssetBytes-=bytes-retained;
+    }catch(error){
+      if(failure){failure.cleanupError=error;failure.message+='; deferred asset staging cleanup also failed';}
+      else failure=error;
+    }
+    if(failure)throw failure;
+  }
+  registry.modules=next.modules;registry.bridges=next.bridges;registry.shared=next.shared;
+  Object.assign(registry.outputs,next.outputs);
+  return target;
+}

package/runtime/dev-lazy-staging.mjs

@@ -0,0 +1,14 @@
+import { lstat, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Delete only an unpublished direct-child stage created by our lazy compiler. */
+export async function discardLazyBuild(root, built) {
+  if (!built?.devLazyTemporary) return;
+  const canonicalRoot = await realpath(root), directory = path.resolve(built.outputDirectory);
+  if (path.dirname(directory) !== canonicalRoot ||
+      !/^\.prnext-build-[a-f0-9-]{36}$/.test(path.basename(directory))) throw Error('Invalid deferred staging directory');
+  const info = await lstat(directory).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  if (!info) return;
+  if (!info.isDirectory() || info.isSymbolicLink() || await realpath(directory) !== directory) throw Error('Invalid deferred staging directory');
+  await rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}

package/runtime/dev-route-selection.mjs

@@ -0,0 +1,64 @@
+const globalInput = /(?:^|\/)(?:package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|(?:tsconfig|jsconfig)\.json|(?:prnext|next|contentlayer|postcss|tailwind)\.config\.|\.env|(?:src\/)?(?:middleware|proxy)\.[^/]+$|pages\/_document\.|(?:global-error|global-not-found)\.)/;
+const generatedRouteFields = new Set(['module', 'client', 'css', 'cssScopes']);
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+  return value;
+}
+const signature = value => JSON.stringify(stable(value));
+const routeContract = manifest => manifest.routes.map(route => Object.fromEntries(Object.entries(route).filter(([key]) => !generatedRouteFields.has(key)))).sort((a, b) => a.id.localeCompare(b.id));
+function actionContract(manifest) {
+  const ids = Object.keys(manifest.app?.actions || {}).sort();
+  if (!ids.length) return [];
+  const metadata = manifest.devActions;
+  if (metadata?.version !== 1 || metadata.complete !== true || manifest.devDependencyStatus?.complete !== true || !Array.isArray(metadata.actions)) return;
+  const modules = new Set((manifest.devModules || []).map(record => record.route));
+  const routed = new Set((manifest.devDependencies || []).flatMap(record => record.files));
+  if (signature(metadata.actions.map(action => action.id).sort()) !== signature(ids)) return;
+  const owners = new Set();
+  for (const action of metadata.actions) {
+    const owner = action.file + '\0' + action.binding;
+    if (!modules.has(action.file) || !routed.has(action.file) || owners.has(owner) || !Array.isArray(action.runtimes)) return;
+    owners.add(owner);
+  }
+  return [...metadata.actions].sort((a, b) => (a.file + '\0' + a.binding).localeCompare(b.file + '\0' + b.binding));
+}
+
+// Both committed graphs participate: removed imports belong to the old graph,
+// newly introduced imports to the new one. No partial/unknown graph is proof.
+export function selectiveDevelopmentRoutes(previous, next, { changed, affectedRoutes, affectedModules = [], nextAffected } = {}) {
+  if (!previous || !changed?.length || !Array.isArray(affectedRoutes) || !nextAffected || nextAffected.complete !== true || !Array.isArray(nextAffected.unknown) || nextAffected.unknown.length || !Array.isArray(nextAffected.routes) ||
+      previous.devDependencyStatus?.complete === false || next.devDependencyStatus?.complete === false || changed.some(file => globalInput.test(file))) return;
+  // The visible URL is not proof of the rendered route under server rewrites,
+  // localized routing, or intercepted/parallel branches. Keep these global
+  // until the browser can certify every visible route identity.
+  for (const manifest of [previous, next]) if (manifest.middleware || manifest.config?.i18n ||
+      Object.values(manifest.customRoutes?.rewrites || {}).some(rules => rules.length) ||
+      manifest.routes.some(route => route.parallel || route.interception)) return;
+  if (signature([previous.config, previous.customRoutes, routeContract(previous)]) !== signature([next.config, next.customRoutes, routeContract(next)])) return;
+  const before = actionContract(previous), after = actionContract(next);
+  if (!before || !after || previous.app?.actionKey !== next.app?.actionKey ||
+      signature(before.map(({id, ...action}) => action)) !== signature(after.map(({id, ...action}) => action))) return;
+  const modules = new Set([...affectedModules, ...(nextAffected.modules || [])]);
+  for (let i = 0; i < before.length; i++) if (before[i].id !== after[i].id && !modules.has(before[i].file)) return;
+  const routes = [...new Set([...affectedRoutes, ...nextAffected.routes])].sort();
+  return Buffer.byteLength(JSON.stringify(routes)) <= 32 * 1024 ? routes : undefined;
+}
+
+// An ensure/navigation transaction must prepare the new loader even when its
+// destination differs from location.pathname until history is committed.
+export function canSkipDevelopmentUpdate({ confirmed, navigation, ensuring, affectedRoutes, routes, pathname }) {
+  if (!confirmed || navigation || ensuring || !Array.isArray(affectedRoutes) || !Array.isArray(routes)) return false;
+  let parts; try { parts = pathname.split('/').filter(Boolean).map(decodeURIComponent); } catch { return false; }
+  const matches = pattern => {
+    const segments = pattern.split('/').filter(Boolean); let index = 0;
+    for (const segment of segments) {
+      if (/^\[\[\.\.\.[^\]]+\]\]$/.test(segment)) return true;
+      if (/^\[\.\.\.[^\]]+\]$/.test(segment)) return index < parts.length;
+      if (index >= parts.length || !(segment.startsWith('[') && segment.endsWith(']')) && segment !== parts[index]) return false;
+      index++;
+    }
+    return index === parts.length;
+  };
+  return routes.some(matches) && !affectedRoutes.some(matches);
+}

package/runtime/dev-runtime-pool.mjs

@@ -5,11 +5,12 @@ import {fileURLToPath} from 'node:url';
 import path from 'node:path';
 import {EventEmitter} from 'node:events';
 
-export function createDevRuntimePool({binary,root,home,environment={},onChild=()=>{}}){
+export function createDevRuntimePool({binary,root,home,environment={},onBeforeChild=()=>{},onChild=()=>{},onReady=()=>{}}){
   let spare,disposed=false;const children=new Set();
   function create(){
     if(disposed)throw Error('Development runtime is closed');
     const token=randomBytes(32).toString('base64url');
+    const ticket=onBeforeChild();
     const child=spawn(binary,['dev-spare',root,'--node',process.execPath,'--script',fileURLToPath(new URL('./dev-runtime-spare.mjs',import.meta.url))],{cwd:root,windowsHide:true,stdio:['pipe','pipe','pipe'],env:{...process.env,...environment,NODE_ENV:'development',PRNEXT_DEV_SPARE_TOKEN:token}});
     children.add(child);onChild(child);
     const messages=new EventEmitter();let buffer='';child.stdout.setEncoding('utf8');child.stdout.on('data',chunk=>{buffer+=chunk;if(buffer.length>65536){child.kill();return;}for(let end;(end=buffer.indexOf('\n'))>=0;){const line=buffer.slice(0,end);buffer=buffer.slice(end+1);try{const message=JSON.parse(line);if(message.type)messages.emit(message.type,message);}catch{}}});
@@ -22,7 +23,7 @@ export function createDevRuntimePool({binary,root,home,environment={},onChild=()
       const message=value=>{clean();resolve(value);};
       messages.on(type,message);child.once('exit',exit);child.once('error',fail);
     });
-    const ready=wait('warm');ready.catch(()=>{if(spare?.child===child)spare=undefined;void stop(child);});
+    const ready=wait('warm').then(info=>{onReady(child,info,ticket);return info;});ready.catch(()=>{if(spare?.child===child)spare=undefined;void stop(child);});
     return {child,token,ready,wait};
   }
   async function stop(child){

package/runtime/dev-runtime-spare.mjs

@@ -48,7 +48,7 @@ const broker=net.createServer(socket=>{
   socket.on('close',()=>{const owned=controls.delete(socket);if(owned&&!controls.size&&ready)process.stdin.emit('end');});
 });
 broker.maxConnections=16;
-broker.listen(0,'127.0.0.1',()=>{broker.unref();announce({type:'warm',port:broker.address().port});});
+broker.listen(0,'127.0.0.1',()=>{broker.unref();announce({type:'warm',port:broker.address().port,pid:process.pid});});
 let control='';const arm=chunk=>{control+=chunk;if(control.length>8192)process.exit(1);if(!control.includes('\n'))return;process.stdin.off('data',arm);
   let message;try{message=JSON.parse(control.trim());}catch{process.exit(1);}if(message?.type!=='arm'||armed)process.exit(1);
   void realpath(message.dist).then(dist=>{if(!dist.startsWith(root+path.sep))throw Error('Generation outside project');armed={dist};announce({type:'armed'});}).catch(()=>process.exit(1));

package/runtime/dev-session-retention.mjs

@@ -0,0 +1,154 @@
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+import {constants, writeFileSync, renameSync, rmSync} from 'node:fs';
+import {lstat, open, opendir, rm} from 'node:fs/promises';
+import path from 'node:path';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from './storage-path.mjs';
+
+const marker = '.owner.json', disabledMarker = '.recovery-disabled', uuid = /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/;
+const grace = 60_000, maxChildren = 4096, maxMarker = 64 * 1024;
+const alive = pid => {try {process.kill(pid, 0); return true;} catch (error) {return error.code !== 'ESRCH';}};
+const pid = value => Number.isSafeInteger(value) && value > 0;
+
+/** A ticket is durable before a spawn. An interrupted spawn/metadata update
+ * leaves the session ineligible for automatic recovery, never falsely idle. */
+export function createDevelopmentSessionOwner(home, {session, processId = process.pid, host = hostname(), now = Date.now, warn = console.warn} = {}) {
+  if (!uuid.test(session) || path.basename(home) !== session || !pid(processId)) throw Error('Invalid development session owner');
+  const state = {version: 1, session, token: randomUUID(), pid: processId, host, createdAt: now(), updatedAt: now(), eligible: true, children: [], pending: []};
+  function publish(initial = false) {
+    state.updatedAt = now();
+    const text = JSON.stringify(state) + '\n';
+    if (Buffer.byteLength(text) > maxMarker) throw Error('Development owner metadata exceeds its budget');
+    const file = path.join(home, marker);
+    if (initial) {writeFileSync(file, text, {flag: 'wx', mode: 0o600}); return;}
+    const temporary = file + '.' + randomUUID() + '.tmp';
+    try {writeFileSync(temporary, text, {flag: 'wx', mode: 0o600}); renameSync(temporary, file);}
+    finally {rmSync(temporary, {force: true});}
+  }
+  publish(true);
+  function disable() {
+    // A separate create-only marker also works if Windows has temporarily
+    // locked the owner receipt. A spawn may proceed only once this safeguard
+    // or its pending ticket is durable.
+    try {writeFileSync(path.join(home, disabledMarker), 'Incomplete development child ownership.\n', {flag: 'wx', mode: 0o600});}
+    catch (error) {if (error.code !== 'EEXIST') throw error;}
+    state.eligible = false; try {publish();} catch { /* The create-only marker forbids cleanup. */ }
+  }
+  return {
+    beforeSpawn() {
+      if (!state.eligible) return null;
+      if (state.pending.length >= 128 || state.children.length >= maxChildren) {disable(); return null;}
+      const ticket = randomUUID(); state.pending.push(ticket); try {publish();} catch {disable();} return ticket;
+    },
+    spawned(ticket, child, descendants = []) {
+      if (!state.eligible) return;
+      if (!state.pending.includes(ticket)) {disable(); return;}
+      if (!pid(child?.pid) || descendants.some(value => !pid(value))) {state.eligible = false; try {disable();} catch { /* The pre-spawn ticket remains durable. */ } return;}
+      for (const value of [child.pid, ...descendants]) if (!state.children.includes(value)) state.children.push(value);
+      state.pending = state.pending.filter(value => value !== ticket);
+      try {publish();} catch (error) {state.eligible = false; try {disable();} catch { /* The pre-spawn ticket remains durable. */ } warn('Development session recovery disabled: ' + (error.code || 'metadata publication failed'));}
+    },
+    disable,
+  };
+}
+
+async function readOwner(home) {
+  const name = path.join(home, marker), info = await lstat(name);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > maxMarker) return;
+  const file = await open(name, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const bytes = Buffer.alloc(maxMarker + 1), {bytesRead} = await file.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > maxMarker) return;
+    const text = bytes.toString('utf8', 0, bytesRead), value = JSON.parse(text);
+    if (value.version !== 1 || value.session !== path.basename(home) || !uuid.test(value.session) || !uuid.test(value.token) || !pid(value.pid) || typeof value.host !== 'string' || value.host.length > 255 || !Number.isSafeInteger(value.createdAt) || !Number.isSafeInteger(value.updatedAt) || value.updatedAt < value.createdAt || value.eligible !== true || !Array.isArray(value.pending) || value.pending.length || !Array.isArray(value.children) || value.children.length > maxChildren || value.children.some(value => !pid(value))) return;
+    return {value, text};
+  } finally {await file.close();}
+}
+
+async function ordinaryTree(home, budget, snapshots) {
+  const directory = await captureStorageDirectory(home);
+  if (!directory) return false;
+  snapshots.push(directory);
+  for await (const entry of await opendir(home)) {
+    if (++budget.files > 32_768) return false;
+    const file = path.join(home, entry.name), info = await lstat(file);
+    if (info.isSymbolicLink()) return false;
+    if (info.isDirectory()) {if (!await ordinaryTree(file, budget, snapshots)) return false;}
+    else if (!info.isFile() || (budget.bytes += info.size) > 2 * 1024 ** 3) return false;
+  }
+  return true;
+}
+
+/** Called while the project's exclusive development lock is held. Legacy,
+ * foreign, active, ambiguous and unmarked sessions are always preserved. */
+export async function pruneDevelopmentSessions(root, {host = hostname(), now = Date.now(), isAlive = alive, graceMs = grace, remove = rm} = {}) {
+  const report = {removed: 0, retained: 0, failed: 0};
+  // The caller already holds the canonical project's development lock. Do not
+  // recanonicalize a replaced root into a different project's storage.
+  root = path.resolve(root);
+  const container = path.join(root, '.prnext-dev');
+  let info;
+  try {info = await lstat(container);} catch (error) {if (error.code === 'ENOENT') return report; throw error;}
+  if (!info.isDirectory() || info.isSymbolicLink()) return report;
+  const ancestors = [await captureStorageDirectory(root), await captureStorageDirectory(container)];
+  if (!await verifyStorageDirectories(ancestors)) return report;
+  let scanned = 0;
+  for await (const entry of await opendir(container)) {
+    if (++scanned > 256) break;
+    if (!entry.isDirectory() || !uuid.test(entry.name)) {report.retained++; continue;}
+    const home = path.join(container, entry.name);
+    try {
+      const snapshots = [...ancestors, await captureStorageDirectory(home)];
+      if (!await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      const owner = await readOwner(home);
+      if (await lstat(path.join(home, disabledMarker)).then(() => true, error => {if (error.code === 'ENOENT') return false; throw error;})) {report.retained++; continue;}
+      const inactive = value => value.host === host && value.updatedAt <= now - graceMs && value.createdAt <= now && ![value.pid, ...value.children].some(isAlive);
+      if (!owner || !inactive(owner.value) || !await verifyStorageDirectories(snapshots) || !await ordinaryTree(home, {files: 0, bytes: 0}, snapshots) || !await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      // Validate the same marker and lifetime after the bounded tree walk. A
+      // currently running session can never be deleted merely because it is old.
+      const current = await readOwner(home), directory = await lstat(home);
+      const disabled = await lstat(path.join(home, disabledMarker)).then(() => true, error => {if (error.code === 'ENOENT') return false; throw error;});
+      if (disabled || !current || current.text !== owner.text || !inactive(current.value) || !directory.isDirectory() || directory.isSymbolicLink() || !await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      await remove(home, {recursive: true, force: true, maxRetries: 3, retryDelay: 100}); report.removed++;
+    } catch {report.failed++;}
+  }
+  return report;
+}
+
+/** Failed generation cleanup remains in this retryable queue, including the
+ * exact completed phase. Nothing is deleted before requests have drained. */
+export function createRetiredGenerationCleanup({root, home, gateway, stop, remove = rm, warn = console.warn}) {
+  const pending = new Map(); let running;
+  const ownedHome = path.resolve(home);
+  const ancestry = directory => [path.resolve(root), path.join(path.resolve(root), '.prnext-dev'), ownedHome, directory];
+  async function storage(item, directory) {
+    item.snapshots ??= await Promise.all(ancestry(directory).map(captureStorageDirectory));
+    return verifyStorageDirectories(item.snapshots);
+  }
+  async function clean(item) {
+    const directory = path.resolve(root, item.generation.directory);
+    if (!sameStoragePath(path.dirname(directory), ownedHome) || !uuid.test(path.basename(directory)) || item.generation.id !== path.basename(directory)) throw Error('Invalid retired development generation');
+    if (!await storage(item, directory)) throw Error('Development generation storage changed');
+    if (item.phase === 0) {await gateway.request('retire', {generation: item.generation.id}); item.phase++;}
+    if (!await storage(item, directory)) throw Error('Development generation storage changed');
+    if (item.phase === 1) {await item.generation.runtime?.close(); item.phase++;}
+    if (item.phase === 2) {await stop(item.generation.child); item.phase++;}
+    if (item.phase === 3) {await gateway.request('forget', {generation: item.generation.id}); item.phase++;}
+    const snapshots = [...item.snapshots];
+    if (!await storage(item, directory) || !await ordinaryTree(directory, {files: 0, bytes: 0}, snapshots) || !await verifyStorageDirectories(snapshots)) throw Error('Development generation storage changed');
+    await remove(directory, {recursive: true, force: true, maxRetries: 10, retryDelay: 100});
+  }
+  const retry = () => {
+    if (running) return running;
+    running = (async () => {
+      for (const [id, item] of [...pending]) {
+        try {await clean(item); pending.delete(id);}
+        catch (error) {warn('Development generation cleanup: ' + error.message);}
+      }
+    })().finally(() => {running = undefined;});
+    return running;
+  };
+  return {get pending() {return pending.size;}, enqueue(generation) {if (!pending.has(generation.id)) pending.set(generation.id, {generation, phase: 0}); return retry();}, retry,
+    async close() {await running; for (const item of pending.values()) {const directory=path.resolve(root,item.generation.directory);if(await storage(item,directory))await item.generation.runtime?.close();else await stop(item.generation.runtime?.child);await stop(item.generation.child);}},
+  };
+}

package/runtime/dev-style-retention.mjs

@@ -0,0 +1,15 @@
+import {rm} from 'node:fs/promises';
+import path from 'node:path';
+
+// Asset-only generations do not own backend/compiler requests. Drain their
+// asset leases and finish deleting the excess snapshot before announcing ready.
+export async function pruneDevelopmentStyles(generations,gateway,root){
+  while(generations.length>3){
+    const old=generations[0];
+    await gateway.request('retire',{generation:old.id});
+    await gateway.request('forget',{generation:old.id});
+    await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});
+    // Keep failed deletions tracked so a later update can retry their cleanup.
+    generations.shift();
+  }
+}