@redue/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/src/index.mjs

@@ -5,7 +5,7 @@ import {createHash} from 'node:crypto';
 import micromatch from './glob.mjs';
 import {sha} from './plan.mjs';
 import {resolveLinks} from './installed-inputs.mjs';
-import {validInputRelative} from './path-identity.mjs';
+import {validInputRelative,identityFields,racyUntil} from './path-identity.mjs';
 
 const tracked = root => [...new Set(execFileSync('git',
   ['ls-files','--cached','--others','--exclude-standard','-z'],
@@ -35,37 +35,43 @@ const pathPrefixes = rel => {
   return prefixes;
 };
 
+// An installed file is observed by identity, not content: every write changes
+// ctime, so its entry changes without reading the whole installation. The
+// compiler's own reads are content-checked by its probe and certificate. A file
+// changed within the racy window could still be rewritten in the same timestamp
+// tick at the same size; such files are tracked in `racy`, and the daemon waits
+// the window out and records them again before it writes a run checkpoint.
+const identity=st=>identityFields.map(key=>String(st[key])).join(':');
 function fileHash(root, rel,installed=false,before=fs.lstatSync(path.join(root,rel),
   {bigint:true})) {
   const file=path.join(root, rel);
-  let value,references=[],bytes=Number(before.size);
+  let value,references=[],bytes=installed?0:Number(before.size),racy=0;
   if(before.isSymbolicLink()){
     const resolution=resolveLinks(file,root,[],true);
     if(!resolution.physical)throw Error(`symlink input target observation unavailable: ${rel}: ${resolution.reason}`);
     const target=fs.statSync(resolution.physical,{bigint:true});
     if(!target.isFile())throw Error(`directory input symlink unsupported: ${rel}`);
-    value='link:'+JSON.stringify(resolution.links)+':'+target.mode+':'+
-      (installed&&target.nlink>1?target.nlink+':':'')+
-      hashRegular(resolution.physical).hash;
+    if(installed)racy=racyUntil(target);else bytes=Number(target.size);
+    value='link:'+JSON.stringify(resolution.links)+':'+(installed?'stat:'+identity(target):
+      target.mode+':'+hashRegular(resolution.physical).hash);
     references=[...new Set([...resolution.links.map(link=>path.relative(root,link.path)
       .split(path.sep).join('/')),path.relative(root,resolution.physical)
       .split(path.sep).join('/')])];
-    bytes=Number(target.size);
     const targetAfter=fs.statSync(resolution.physical,{bigint:true});
-    for(const key of ['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'])
+    for(const key of identityFields)
       if(target[key]!==targetAfter[key])throw Error(`input changed during inspection: ${rel}`);
     const resolutionAfter=resolveLinks(file,root,[],true);
     if(resolutionAfter.physical!==resolution.physical||
       JSON.stringify(resolutionAfter.links)!==JSON.stringify(resolution.links))
       throw Error(`input link changed during inspection: ${rel}`);
   }
-  else if(before.isFile()) value='file:'+before.mode+':'+
-    (installed&&before.nlink>1?before.nlink+':':'')+hashRegular(file).hash;
+  else if(before.isFile()&&installed){value='stat:'+identity(before);racy=racyUntil(before);}
+  else if(before.isFile()) value='file:'+before.mode+':'+hashRegular(file).hash;
   else throw Error(`non-file input: ${rel}`);
   const after=fs.lstatSync(file,{bigint:true});
-  for(const key of ['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'])
+  for(const key of identityFields)
     if(before[key]!==after[key]) throw Error(`input changed during inspection: ${rel}`);
-  return {hash:sha(value),references,bytes};
+  return {hash:sha(value),references,bytes,racy};
 }
 const readBuffer=Buffer.allocUnsafe(65536);
 function hashRegular(file) {
@@ -81,6 +87,7 @@ export class InputIndex {
     const matcherStarted=performance.now();
     this.bundle=bundle; this.root=bundle.root; this.files=new Map(); this.members=new Map();
     this.symlinkRefs=new Map();this.aliasDependencies=new Map();
+    this.racy=new Map();
     this.trackGit=options.trackGit!==false;
     this.installedRoots=[...new Set(Object.values(bundle.plans).flatMap(plan=>
       plan.installedPhysicalRoots||[]))];
@@ -149,6 +156,17 @@ export class InputIndex {
     }
     return {files,bytes,durationMs:performance.now()-started};
   }
+  // When the racy window of the named checks' installed members ends (0: none).
+  racyUntil(names=null) {
+    let until=0;
+    for(const [rel,time] of this.racy)
+      if(!names||[...this.members.get(rel)||[]].some(name=>names.includes(name)))until=Math.max(until,time);
+    return until;
+  }
+  // Records again every installed file whose racy window has passed.
+  settleRacy() {
+    for(const [rel,time] of [...this.racy])if(time<=Date.now())this.record(rel,rel+' changed');
+  }
   summary(name) { const row=this.checks.get(name); return {fingerprint:this.fingerprint(name),
     revision:row.revision,planId:row.plan.id,files:row.files.size,probeAt:row.probeAt}; }
   record(rel, changeReason=rel+' changed', observedStat=null) {
@@ -182,6 +200,7 @@ export class InputIndex {
       }
     }
     const oldNames=this.members.get(rel)||new Set(), newNames=new Set(fresh===undefined?[]:matched);
+    if(inspection?.racy>Date.now()&&newNames.size)this.racy.set(rel,inspection.racy);else this.racy.delete(rel);
     if(old===fresh && oldNames.size===newNames.size && [...oldNames].every(n=>newNames.has(n))) return false;
     for(const name of new Set([...oldNames,...newNames])) {
       const row=this.checks.get(name);
@@ -304,3 +323,14 @@ export class InputIndex {
     return out;
   }
 }
+
+// The index state a worker sends and a restart retains; hydrate() in daemon.mjs
+// reads it back.
+export function dehydrateIndex(value) {
+  return {files:[...value.files],
+    aliasDependencies:[...value.aliasDependencies].map(([name,refs])=>[name,[...refs]]),
+    rows:[...value.checks].map(([name,row])=>({name,files:[...row.files],
+      sum:row.sum.toString('hex'),revision:row.revision,lastReason:row.lastReason})),
+    eventCount:value.eventCount,rehashedFiles:value.rehashedFiles,
+    rehashedBytes:value.rehashedBytes,profile:value.profile,racy:[...value.racy]};
+}

package/src/linux-inotify.py

@@ -73,10 +73,18 @@ def main(root):
     file_paths = {}
     intentional_removals = set()
 
+    # No input lies in a .git directory (config refuses such patterns and the
+    # index skips them), so none is watched: git creates object directories
+    # there on most commits, and each would be an observation gap.
+    def in_git(target):
+        return '.git' in os.path.relpath(target, root).split(os.sep)
+
     def add_tree(folder):
         stack = [folder]
         while stack:
             current = stack.pop()
+            if in_git(current):
+                continue
             wd = libc.inotify_add_watch(fd, os.fsencode(current), MASK)
             if wd < 0:
                 raise OSError(ctypes.get_errno(), 'inotify_add_watch failed')
@@ -119,6 +127,8 @@ def main(root):
                     emit('gap', reason='inotify_watch_unknown')
                     return False
                 target = os.path.join(parent, os.fsdecode(raw)) if raw else parent
+                if in_git(target):
+                    continue
                 if mask & (IN_UNMOUNT | IN_DELETE_SELF | IN_MOVE_SELF | IN_IGNORED):
                     emit('gap', reason='inotify_watch_lost')
                     return False

package/src/observation.mjs

@@ -9,17 +9,39 @@ import {fileURLToPath} from 'node:url';
 // subscription is healthy; history may accelerate catch-up; a fresh scan is
 // the deterministic fallback. A failed history operation never updates cursor.
 const workerFile=path.join(path.dirname(fileURLToPath(import.meta.url)),'history-worker.mjs');
+// Each query runs in a fresh helper: a reused native history session can take
+// ten times longer. The next helper is forked once a query settles, so its
+// startup is off the decision path. A failed or late helper is killed.
+let spare=null,queue=Promise.resolve(),closed=false;
+// After the observer's last query no helper is kept or started.
+export function closeHistory() {closed=true;spare?.kill('SIGKILL');spare=null;}
+function startHelper() {
+  const child=fork(workerFile,[],{stdio:['ignore','ignore','ignore','ipc'],env:traceEnvironment()});
+  child.abandoned=new Set();child.on('error',()=>{});
+  child.once('exit',()=>{if(spare===child)spare=null;
+    child.reply?.({ok:false,lost:Error(`history helper exited ${child.exitCode??child.signalCode}`)});
+    for(const next of child.abandoned)try{fs.unlinkSync(next);}catch{}});
+  return child;
+}
 export function history(root,cursor,backend,deadlineMs,faultFile) {
+  const run=()=>query(root,cursor,backend,deadlineMs,faultFile);
+  const result=queue.then(run,run);queue=result.catch(()=>{});return result;
+}
+function query(root,cursor,backend,deadlineMs,faultFile) {
   const next=cursor+'.'+randomUUID()+'.next';
   return new Promise((resolve,reject)=>{
     mark('history.submit',{deadlineMs});
-    const worker=fork(workerFile,[root,fs.existsSync(cursor)?cursor:'',next,backend,
-      faultFile||''],{stdio:['ignore','ignore','ignore','ipc'],env:traceEnvironment()});
-    let settled=false,abandoned=false;
+    const worker=spare??startHelper();spare=null;
+    worker.ref();worker.channel?.ref();
+    let settled=false;
     const finish=(error,value)=>{
-      if(settled)return;settled=true;mark('history.complete',{childPid:worker.pid,outcome:error?.code||error?.name||'ok',events:value?.length});clearTimeout(timer);
+      if(settled)return;settled=true;worker.reply=null;clearTimeout(timer);
+      mark('history.complete',{childPid:worker.pid,outcome:error?.code||error?.name||'ok',events:value?.length});
+      if(error)worker.abandoned.add(next);
       worker.kill('SIGKILL');
-      if(error){abandoned=true;try{fs.unlinkSync(next);}catch{}
+      // A failed query disables history for this observer; keep no helper.
+      if(!closed&&!error){spare=startHelper();spare.unref();spare.channel?.unref();}
+      if(error){try{fs.unlinkSync(next);}catch{}
         reject(error);return;}
       try{fs.renameSync(next,cursor);resolve(value);}
       catch(e){try{fs.unlinkSync(next);}catch{}reject(e);}
@@ -28,12 +50,10 @@ export function history(root,cursor,backend,deadlineMs,faultFile) {
       const e=Error(`history query did not settle within ${deadlineMs} ms`);
       e.code='ETIMEDOUT';finish(e);
     },deadlineMs);
-    worker.on('message',message=>message.ok?finish(null,message.changes):
-      finish(Object.assign(Error(message.error),{code:message.code})));
-    worker.once('error',e=>finish(e));
-    worker.once('exit',(code,signal)=>{
-      if(abandoned)try{fs.unlinkSync(next);}catch{}
-      if(!settled)finish(Error(`history helper exited ${code??signal}`));
-    });
+    worker.reply=message=>message.lost?finish(message.lost):message.ok?finish(null,message.changes):
+      finish(Object.assign(Error(message.error),{code:message.code}));
+    worker.on('message',message=>worker.reply?.(message));
+    try{worker.send({root,previous:fs.existsSync(cursor)?cursor:'',next,backend,faultFile:faultFile||''});}
+    catch(e){finish(e);}
   });
 }

package/src/path-identity.mjs

@@ -41,3 +41,11 @@ export function validInputRelative(rel,platform=process.platform) {
     rel.includes('\\')))return false;
   return true;
 }
+
+// File identity fields. Any write changes ctime, but timestamps tick in
+// milliseconds: a file changed within the racy window could be rewritten in the
+// same tick at the same size without changing them (git's racy rule).
+export const identityFields=['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'];
+export const racyWindowMs=2000;
+// ctime, which no ordinary tool can set ahead, ends the window.
+export const racyUntil=st=>Number(st.ctimeNs/1000000n)+racyWindowMs;

package/src/plan-worker.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {discover} from './plan.mjs';
-import {InputIndex} from './index.mjs';
+import {InputIndex,dehydrateIndex} from './index.mjs';
 import {directProject,directQualification} from './direct-typescript.mjs';
 import {queriesMatch} from './typescript-list.mjs';
 import {planGuard,inputKey} from './decision-validation.mjs';
@@ -113,26 +113,14 @@ try {
     const outside=new InputIndex({root:boundary,plans},{trackGit:false,includeInstalled:true});
     outside.coldScan();
     if(outside.unavailable)throw Error(outside.unavailable);
-    external[boundary]={files:[...outside.files],
-      aliasDependencies:[...outside.aliasDependencies].map(([name,refs])=>[name,[...refs]]),
-      rows:[...outside.checks]
-      .map(([name,row])=>({name,files:[...row.files],sum:row.sum.toString('hex'),
-        revision:row.revision,lastReason:row.lastReason})),
-      eventCount:outside.eventCount,rehashedFiles:outside.rehashedFiles,
-      rehashedBytes:outside.rehashedBytes,profile:outside.profile};
+    external[boundary]=dehydrateIndex(outside);
   }
   timing('worker.total',totalStarted,{mode:'cold',files:index.files.size});
   parentPort.postMessage({ok:true,bundle,discoveryMs,indexingMs,guard,planReused,
     inputKeys:Object.fromEntries([...index.checks].map(([name,row])=>[name,inputKey(row)])),
     restartMode:'cold-index',
     external,
-    index:{files:[...index.files],
-      aliasDependencies:[...index.aliasDependencies].map(([name,refs])=>[name,[...refs]]),
-      rows:[...index.checks].map(([name,row])=>({
-      name,files:[...row.files],sum:row.sum.toString('hex'),revision:row.revision,
-      lastReason:row.lastReason})),
-    eventCount:index.eventCount,rehashedFiles:index.rehashedFiles,
-    rehashedBytes:index.rehashedBytes,profile:index.profile}});
+    index:dehydrateIndex(index)});
   }
 } catch(error) {
   parentPort.postMessage({ok:false,error:error?.message||String(error),

package/src/probe-result.mjs

@@ -9,11 +9,15 @@ export function contextOnly(context) {
   }
   return false;
 }
-export function probeResult(output,context,queries=null) {
+// A layout lets a recorded run rebuild the output after a content-only edit.
+export function probeResult(output,context,queries=null,layout=null) {
   if(!process.argv.includes('--redue-checkpoint')){process.stdout.write(output);return;}
   const raw=queries?JSON.stringify(queries):null;
-  let value=JSON.stringify({output,context,queryData:raw&&Buffer.byteLength(raw)<=8*1024*1024?
-    deflateSync(raw).toString('base64'):null});
+  const queryData=raw&&Buffer.byteLength(raw)<=8*1024*1024?deflateSync(raw).toString('base64'):null;
+  let value=JSON.stringify({output,context,queryData,
+    ...(layout?{layoutData:deflateSync(JSON.stringify(layout)).toString('base64')}:{})});
+  // The layout is dropped first: it only shortens the run after an edit.
+  if(Buffer.byteLength(value)>512*1024)value=JSON.stringify({output,context,queryData});
   // Optimization metadata must not overflow the ordinary probe channel.
   // Larger contracts keep the normal complete probe, without result reuse.
   if(Buffer.byteLength(value)>512*1024)value=JSON.stringify({output,context,queries:null});

package/src/run-recorder.cjs

@@ -0,0 +1,91 @@
+// Preload for a direct compiler run: node --require <this> <tsc> ... with a
+// pipe on fd 3. Records the answers the compiler received from node:fs, in the
+// terms of queryAnswer, and writes them to fd 3 at exit. It never changes an
+// answer, an output or the exit code; any failure only makes the record unusable.
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),{createHash}=require('node:crypto');
+const original={readFileSync:fs.readFileSync,statSync:fs.statSync,readdirSync:fs.readdirSync,
+  realpathSync:fs.realpathSync,native:fs.realpathSync.native,writeSync:fs.writeSync,openSync:fs.openSync};
+const real=file=>(process.platform==='win32'?original.native:original.realpathSync)(file);
+const facts=new Map(),compilerReads=new Set();let unsupported=null,conflict=null,main=null,compilerRoot=null;
+try{main=real(process.argv[1]);compilerRoot=path.dirname(path.dirname(main));}
+catch{unsupported='main module unavailable';}
+const kindOf=st=>st.isFile()?'f':st.isDirectory()?'d':'o';
+const missing=error=>['ENOENT','ENOTDIR'].includes(error?.code);
+// The compiler tree (lib/<entry>/../..) is covered by the daemon's toolchain
+// identity, not by this record. tsc also stats a case-swapped copy of its own path.
+const inCompiler=full=>full===compilerRoot||full.startsWith(compilerRoot+path.sep)||
+  full!==main&&full.toLowerCase()===main.toLowerCase();
+function observe(kind,call,answer) {
+  return function(file,...rest){
+    let value,full=null;
+    // Compiler-tree reads are named only: which lib files a program loads.
+    try{if(typeof file==='string'){full=path.resolve(file);
+      if(inCompiler(full)){if(kind==='read')compilerReads.add(full);full=null;}}
+      else unsupported??=`${kind} of a non-string path`;}
+    catch{unsupported??='recorder failure';}
+    if(full===null)return call.call(this,file,...rest);
+    let recorded;
+    try{value=call.call(this,file,...rest);}
+    catch(error){recorded=missing(error)?null:{error:error?.code||'error'};note(kind,full,recorded);throw error;}
+    try{recorded=answer(value,file);}catch{unsupported??='recorder failure';return value;}
+    note(kind,full,recorded);
+    return value;
+  };
+}
+function note(kind,full,answer) {
+  try{const key=kind+'\0'+full,value=JSON.stringify(answer),seen=facts.get(key);
+    if(seen===undefined)facts.set(key,value);else if(seen!==value)conflict??=`${kind} ${full}`;}
+  catch{unsupported??='recorder failure';}
+}
+fs.readFileSync=observe('read',original.readFileSync,value=>
+  createHash('sha256').update(JSON.stringify(typeof value==='string'?value:value.toString('utf8'))).digest('hex'));
+fs.statSync=observe('stat',original.statSync,value=>value?kindOf(value):null);
+fs.readdirSync=observe('readdir',original.readdirSync,(value,dir)=>value.map(entry=>{
+  if(typeof entry==='string')return [entry,'?'];
+  if(!entry.isSymbolicLink())return [entry.name,kindOf(entry)];
+  let target=null;try{target=kindOf(original.statSync(path.join(dir,entry.name)));}catch{}
+  return [entry.name,'l',target];
+}).sort((a,b)=>a[0]<b[0]?-1:a[0]>b[0]?1:0));
+const realpath=observe('realpath',original.realpathSync,value=>value);
+realpath.native=observe('realpath',original.native,value=>value);
+fs.realpathSync=realpath;
+// readFileSync opens through fs.openSync; only a writable open is a write.
+// The one write a direct run may make is its build-info file (incremental);
+// it is recorded, and the caller checks it is the configured one.
+const buildInfo=file=>typeof file==='string'&&file.endsWith('.tsbuildinfo');
+fs.openSync=function(file,flags,...rest){
+  if(!(flags===undefined||flags==='r'||flags==='rs'||flags===fs.constants.O_RDONLY)){
+    if(flags==='w'&&buildInfo(file))note('write',path.resolve(file),null);
+    else unsupported??='openSync';
+  }
+  return original.openSync.call(this,file,flags,...rest);
+};
+// tsc creates the build-info directory one level at a time; each is recorded.
+const mkdirSync=fs.mkdirSync;
+fs.mkdirSync=function(file,options,...rest){
+  if(typeof file==='string'&&options===undefined)note('mkdir',path.resolve(file),null);
+  else unsupported??='mkdirSync';
+  return mkdirSync.call(this,file,options,...rest);
+};
+// Writes, and reads this record cannot answer for, make it unusable. readSync
+// and fstatSync stay open: readFileSync reads through them.
+for(const name of ['writeFileSync','appendFileSync','unlinkSync','utimesSync',
+  'renameSync','rmSync','watch','watchFile','existsSync','lstatSync','accessSync','opendirSync',
+  'readlinkSync','readFile','stat','lstat','readdir','realpath','access','exists','open','opendir',
+  'readlink','createReadStream']){
+  const call=fs[name];
+  fs[name]=Object.assign(function(...args){unsupported??=name;return call.apply(this,args);},call);
+}
+for(const name of ['readFile','stat','lstat','readdir','realpath','access','open','opendir','readlink']){
+  const call=fs.promises[name];
+  fs.promises[name]=function(...args){unsupported??=`promises.${name}`;return call.apply(this,args);};
+}
+process.on('exit',()=>{
+  try{
+    const buffer=Buffer.from(JSON.stringify({schema:1,node:[real(process.execPath),process.version],main,
+      unsupported,conflict,compilerReads:[...compilerReads],facts:[...facts].map(([key,value])=>{const at=key.indexOf('\0');
+        return [key.slice(0,at),key.slice(at+1),JSON.parse(value)];})}));
+    for(let at=0;at<buffer.length;)at+=original.writeSync(3,buffer,at,buffer.length-at);
+  }catch{}
+});

package/src/typescript-input-facts.mjs

@@ -2,18 +2,20 @@
 import fs from 'node:fs';import path from 'node:path';import {createHash} from 'node:crypto';
 import {createRequire} from 'node:module';import {spawnSync} from 'node:child_process';
 import {compilerFiles} from './typescript-list.mjs';
+import {buildInfoFor} from './direct-typescript.mjs';
 import {withinPath as within,realObservedPath} from './path-identity.mjs';
 import {timing} from './decision-profile.mjs';
 const require=createRequire(import.meta.url),hash=value=>createHash('sha256').update(value).digest('hex');
 const digestFile=file=>hash(fs.readFileSync(file));
 const fail=code=>{throw Object.assign(Error(code),{code});};
 export function typeScriptInputFacts(root,tsRoot,tsc){
-  const configReads=new Set(),visited=new Set();
+  const configReads=new Set(),visited=new Set(),referenced=[];
+  let buildInfo=null;
   let ts;try{ts=require(tsRoot);}catch{}
   if(typeof ts?.getParsedCommandLineOfConfigFile==='function'){
     const host={...ts.sys,readFile(file){configReads.add(path.resolve(file));
       return ts.sys.readFile(file);},onUnRecoverableConfigFileDiagnostic(){}};
-    const parseConfig=file=>{
+    const parseConfig=(file,top=false)=>{
       const absolute=path.resolve(file);
       if(!within(absolute,root))fail('typescript-config-outside-repository');
       if(visited.has(absolute))return;visited.add(absolute);
@@ -21,13 +23,20 @@ export function typeScriptInputFacts(root,tsRoot,tsc){
       const parsed=ts.getParsedCommandLineOfConfigFile(absolute,{},host);
       if(!parsed||parsed.errors?.length)fail('typescript-config-unavailable');
       if(parsed.options?.plugins?.length)fail('typescript-plugin-unsupported');
-      if(parsed.options?.incremental||parsed.options?.composite)
-        fail('typescript-incremental-unsupported');
+      // Plain tsc reads a referenced config but never builds it, so only the
+      // root config's build settings matter. An incremental root reads and
+      // writes one build-info file, which must be inside the checkout.
+      if(top){
+        if(parsed.options?.composite)fail('typescript-incremental-unsupported');
+        const found=buildInfoFor(ts,parsed.options,root);
+        if(found.issue)fail(found.issue);
+        buildInfo=found.file||null;
+      }else referenced.push(parsed);
       for(const reference of parsed.projectReferences||[])
         parseConfig(reference.path.endsWith('.json')?reference.path:
           path.join(reference.path,'tsconfig.json'));
     };
-    parseConfig(path.join(root,'tsconfig.json'));
+    parseConfig(path.join(root,'tsconfig.json'),true);
   }else{
     // TypeScript 7's native compiler does not expose the previous config API.
     // Its CLI reports the effective config; restrict this path to one direct
@@ -60,6 +69,23 @@ export function typeScriptInputFacts(root,tsRoot,tsc){
     .map(file=>path.resolve(file));
   if(!files.length||files.some(file=>!within(realObservedPath(file),root)))
     fail('typescript-input-outside-repository');
-  return {configs:[...configReads].sort().map(file=>[hash(file),digestFile(file)]),
-    files:[...new Set(files)].sort().map(file=>[hash(file),digestFile(file)]),queries:captured?.queries};
+  // A program that uses a referenced project's sources or outputs depends on
+  // that project's build, which plain tsc does not run. tsc redirects only
+  // TypeScript sources; a shared .d.ts or .json is an ordinary input.
+  const declaration=/\.d\.[cm]?ts$|\.json$/;
+  const sources=new Set(),outputs=new Set(),outDirs=[];
+  for(const parsed of referenced){
+    const dirs=[parsed.options.outDir,parsed.options.declarationDir].filter(Boolean).map(dir=>path.resolve(dir));
+    outDirs.push(...dirs);
+    for(const file of parsed.fileNames.map(name=>path.resolve(name)))if(!declaration.test(file)){
+      sources.add(file);if(!dirs.length)outputs.add(file.replace(/\.[cm]?tsx?$/,ext=>ext.replace(/tsx?$/,'d.ts')));}
+  }
+  if(files.some(file=>sources.has(file)||outputs.has(file)||outDirs.some(dir=>within(file,dir))))
+    fail('typescript-project-reference-consumed');
+  // Every hashed configuration must also be a certified question.
+  const queries=captured?.queries&&[...configReads].every(file=>
+    captured.queries.some(([kind,read])=>kind==='readFile'&&read===file))?captured.queries:null;
+  return {configs:[...configReads].sort().map(file=>[file,digestFile(file)]),
+    files:[...new Set(files)].sort().map(file=>[file,digestFile(file)]),queries,
+    ...(buildInfo?{buildInfo}:{})};
 }

package/src/typescript-list.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {createRequire} from 'node:module';
+import {identityFields,racyUntil} from './path-identity.mjs';
 const require=createRequire(import.meta.url);
 const hash=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export function queryAnswer(kind,file,options) {
@@ -14,16 +15,48 @@ export function queryAnswer(kind,file,options) {
     if(kind==='readFile')return hash(fs.readFileSync(file,'utf8'));
     if(kind==='fileExists')return fs.statSync(file).isFile();
     if(kind==='directoryExists')return fs.statSync(file).isDirectory();
-    if(kind==='realpath')return fs.realpathSync(file);
+    // The compiler resolves through realpathSync.native outside Windows.
+    if(kind==='realpath')return process.platform==='win32'?fs.realpathSync(file):fs.realpathSync.native(file);
     if(kind==='directories')return fs.readdirSync(file,{withFileTypes:true})
       .filter(entry=>entry.isDirectory()||entry.isSymbolicLink()&&
         fs.statSync(path.join(file,entry.name)).isDirectory()).map(entry=>entry.name).sort();
     // Directory entries include names/types, including newly created candidates.
     if(kind==='entries')return fs.readdirSync(file,{withFileTypes:true})
       .map(entry=>[entry.name,entry.isDirectory()?'d':entry.isSymbolicLink()?'l':'f']).sort();
+    // A compiler directory listing: subdirectories and files with a requested
+    // extension, classifying links by their targets as matchFiles does.
+    if(kind==='listing'){
+      const suffixes=options?.extensions?.map(value=>value.toLowerCase());
+      return fs.readdirSync(file,{withFileTypes:true}).flatMap(entry=>{
+        let type=entry;
+        if(entry.isSymbolicLink())try{type=fs.statSync(path.join(file,entry.name));}catch{return [];}
+        if(type.isDirectory())return [[entry.name,'d']];
+        if(type.isFile()&&(!suffixes||suffixes.some(value=>entry.name.toLowerCase().endsWith(value))))
+          return [[entry.name,'f']];
+        return [];
+      }).sort();
+    }
     throw Error('unknown compiler filesystem question');
   }catch(error){if(['ENOENT','ENOTDIR'].includes(error.code))return null;throw error;}
 }
+// Null when every run fact answers as it did during the run, otherwise the
+// first path that does not. Asked in-process; nothing is launched.
+export function runFactChange(facts) {
+  if(!Array.isArray(facts))return 'an unreadable run fact';
+  for(const fact of facts){
+    if(!Array.isArray(fact)||!['fileExists','directoryExists','realpath','readFile'].includes(fact[0])||
+      typeof fact[1]!=='string')return 'an unreadable run fact';
+    const [kind,file,answer]=fact;
+    let now;try{now=queryAnswer(kind,file);}catch{return file;}
+    if(now!==answer)return file;
+  }
+  return null;
+}
+// Why a receipt's run facts no longer hold, or null when they all do.
+export function runFactReason(facts) {
+  const changed=runFactChange(facts);
+  return changed&&`a lookup the last run made answers differently now: ${changed}`;
+}
 export function queriesMatch(queries) {
   if(!queries?.length)return false;
   return queries.every(([kind,file,answer,options])=>
@@ -33,31 +66,60 @@ export function compilerFiles(tsRoot,cwd) {
   const require=createRequire(import.meta.url),ts=require(tsRoot);
   if(typeof ts.createProgram!=='function'||typeof ts.createCompilerHost!=='function')return null;
   const queries=new Map();
-  const remember=(kind,file)=>{
-    const full=path.resolve(file),answer=queryAnswer(kind,full);
-    queries.set(kind+'\0'+full,[kind,full,answer]);return answer;
+  const remember=(kind,file,options)=>{
+    const full=path.resolve(file),answer=queryAnswer(kind,full,options);
+    queries.set(kind+'\0'+full+(options?JSON.stringify(options):''),
+      options?[kind,full,answer,options]:[kind,full,answer]);return answer;
   };
   const readFile=file=>{remember('readFile',file);return ts.sys.readFile(file);};
   const fileExists=file=>{remember('fileExists',file);return ts.sys.fileExists(file);};
   const directoryExists=file=>{remember('directoryExists',file);return ts.sys.directoryExists(file);};
   const getDirectories=file=>{remember('directories',file);return ts.sys.getDirectories(file);};
   const readDirectory=(dir,...args)=>{
-    const result=ts.sys.readDirectory(dir,...args);
+    // Reviewed compilers enumerate each visited directory through fs.readdirSync.
+    // Record those listings as ordinary questions so a validator without the
+    // compiler API can replay this answer; the listing itself stays authoritative.
+    const listed=[],readdirSync=fs.readdirSync;
+    fs.readdirSync=function(file,...rest){listed.push(path.resolve(String(file)));
+      return readdirSync.call(this,file,...rest);};
+    let result;try{result=ts.sys.readDirectory(dir,...args);}finally{fs.readdirSync=readdirSync;}
     // JSON turns undefined array entries into null. TypeScript distinguishes
     // them (an omitted exclude list is not a null list), so retain that fact.
     const full=path.resolve(dir),options={tsRoot,args,argsVersion:1,
       undefinedArguments:args.flatMap((value,i)=>value===undefined?[i]:[])};
+    const visited=new Set(listed);
+    if(typeof ts.getFileMatcherPatterns==='function'&&
+      result.every(file=>visited.has(path.dirname(path.resolve(file)))))try{
+      // Base paths and symlinked directories reach matchFiles through realpath
+      // deduplication without a listing; a retargeted link changes this answer.
+      for(const base of ts.getFileMatcherPatterns(full,args[1],args[2],
+        ts.sys.useCaseSensitiveFileNames,process.cwd()).basePaths)remember('realpath',base);
+      const extensions=Array.isArray(args[0])?args[0]:null;
+      for(const directory of visited){
+        // matchFiles also resolves every visited directory to detect cycles.
+        remember('realpath',directory);
+        remember('listing',directory,{extensions});
+        let entries=[];
+        try{entries=fs.readdirSync(directory,{withFileTypes:true});}
+        catch(error){if(!['ENOENT','ENOTDIR'].includes(error.code))throw error;}
+        for(const entry of entries)
+          if(entry.isSymbolicLink())remember('realpath',path.join(directory,entry.name));
+      }
+      options.covered=1;
+    }catch{/* uncovered listings are replayed only through the compiler API */}
     queries.set('readDirectory\0'+full+JSON.stringify(args),
       ['readDirectory',full,[...result].sort(),options]);
     return result;
   };
+  const realpath=file=>{remember('realpath',file);return ts.sys.realpath(file);};
+  // `extends` of a package config resolves through realpath too.
   const parsed=ts.getParsedCommandLineOfConfigFile(path.join(cwd,'tsconfig.json'),{},
-    {...ts.sys,readFile,fileExists,directoryExists,getDirectories,readDirectory,
+    {...ts.sys,readFile,fileExists,directoryExists,getDirectories,readDirectory,realpath,
       onUnRecoverableConfigFileDiagnostic(){}});
   if(!parsed||parsed.errors?.length)throw Error('TypeScript configuration unavailable');
   const host=ts.createCompilerHost(parsed.options);
-  Object.assign(host,{readFile,fileExists,directoryExists,getDirectories,
-    realpath(file){remember('realpath',file);return ts.sys.realpath(file);},
+  Object.assign(host,{readFile,fileExists,directoryExists,getDirectories,readDirectory,
+    realpath,
     getSourceFile(file,languageVersion,onError){
       const text=readFile(file);return text===undefined?undefined:
         ts.createSourceFile(file,text,languageVersion);
@@ -68,5 +130,33 @@ export function compilerFiles(tsRoot,cwd) {
   // Stable answers are necessary even at first capture; a concurrent edit
   // cannot become the basis for a reusable discovery result.
   const facts=[...queries.values()];
-  return {files,queries:queriesMatch(facts)?facts:null};
+  // A certificate must cover every program file. Referenced configurations
+  // are parsed through this host, so their reads and listings are certified.
+  const complete=files.every(file=>queries.has('readFile\0'+file));
+  return {files,queries:complete&&queriesMatch(facts)?facts:null};
+}
+// Identity of a read file and, for a link, of its target. Writes through any
+// alias change ctime. A file changed within the last 2 s has no identity, so a
+// coarse timestamp cannot hide a second write in the same tick (git's racy rule).
+export function fileIdentity(file,now=Date.now()) {
+  try{const link=fs.lstatSync(file,{bigint:true}),target=link.isSymbolicLink()?fs.statSync(file,{bigint:true}):link;
+    if(racyUntil(link)>=now||racyUntil(target)>=now)return null;
+    const fields=st=>identityFields.map(key=>String(st[key]));
+    return JSON.stringify([fields(target),target===link?null:[fs.realpathSync(file),...fields(link)]]);}
+  catch(error){if(['ENOENT','ENOTDIR'].includes(error.code))return null;throw error;}
+}
+// In-process replay of a certificate. Covered directory listings are checked
+// through their recorded listings instead of loading the compiler API. A read
+// file is re-hashed until a match records its identity, taken before the read,
+// and again whenever that identity changes.
+export function queriesHold(queries,identities=new Map()) {
+  if(!queries?.length)return false;
+  return queries.every(([kind,file,answer,options])=>{
+    if(kind==='readDirectory')return options?.covered===1;
+    const identity=kind==='readFile'?fileIdentity(file):null;
+    if(identity&&identities.get(file)===identity)return true;
+    const held=JSON.stringify(queryAnswer(kind,file,options))===JSON.stringify(answer);
+    if(kind==='readFile'){if(held&&identity)identities.set(file,identity);else identities.delete(file);}
+    return held;
+  });
 }