@redue/cli 0.0.0-stage → 0.1.0-alpha.11

package/src/probe-result.mjs

@@ -0,0 +1,25 @@
+// Internal supported-provider protocol. Default stdout is unchanged, so
+// ordinary run checkpoints keep the same probe/result identity. The daemon
+// may reuse a complete result only after revalidating its input key AND this
+// independently checked execution/toolchain context. No TTL grants trust.
+import {deflateSync} from 'node:zlib';
+export function contextOnly(context) {
+  if(process.argv.includes('--redue-context')){
+    process.stdout.write(context);return true;
+  }
+  return false;
+}
+// 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;
+  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});
+  process.stdout.write(value);
+}

package/src/process-liveness.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+
+export function processAlive(pid) {
+  if(!Number.isSafeInteger(pid)||pid<1)return true;
+  if(process.platform==='linux')try{
+    const stat=fs.readFileSync(`/proc/${pid}/stat`,'utf8');
+    if(['Z','X'].includes(stat.slice(stat.lastIndexOf(')')+2)[0]))return false;
+  }catch(e){if(e.code!=='ENOENT'&&e.code!=='ESRCH')return true;}
+  try{process.kill(pid,0);return true;}
+  catch(e){return e.code!=='ESRCH';}
+}

package/src/project-location.mjs

@@ -0,0 +1,34 @@
+// Shared project selection only; evidence and caller-context semantics stay in the kernel.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {realObservedPath} from './path-identity.mjs';
+import {stateIdentity,userStateBase} from './platform-state.mjs';
+
+export function discoverConfig(cwd=process.cwd()) {
+  let dir=path.resolve(cwd);const found=[];
+  for(;;){
+    for(const name of ['redue.config.json','vstate.config.json']) {
+      const file=path.join(dir,name);
+      if(fs.existsSync(file))found.push(file);
+    }
+    if(fs.existsSync(path.join(dir,'.git'))||path.dirname(dir)===dir)break;
+    dir=path.dirname(dir);
+  }
+  if(found.length>1)throw Error('multiple REDUE configurations apply; select the intended one with --config FILE');
+  return found[0]||path.resolve(cwd,'redue.config.json');
+}
+export function canonicalConfig(configFile) {
+  return path.join(realObservedPath(path.dirname(configFile)),path.basename(configFile));
+}
+export function projectState(root,configFile) {
+  return path.join(userStateBase(process.platform,process.env,os.homedir()),'vstate',
+    `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+stateIdentity(canonicalConfig(configFile))).digest('hex').slice(0,16)}`);
+}
+export function readProject(configFile) {
+  const config=JSON.parse(fs.readFileSync(configFile,'utf8'));
+  if(config.schema!==1||!Array.isArray(config.checks)||!config.checks.length)
+    throw Error('config needs schema 1 and at least one check');
+  return {config,root:realObservedPath(path.resolve(path.dirname(configFile),config.root||'.'))};
+}

package/src/run-lock.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {processAlive} from './process-liveness.mjs';
+
+const alive=processAlive;
+const write=(file,value)=>{
+  const temp=file+`.${process.pid}.tmp`;
+  fs.writeFileSync(temp,JSON.stringify(value),{mode:0o600});
+  fs.renameSync(temp,file);
+};
+
+export function inspectRunLock(state) {
+  const lock=path.join(state,'run.lock');
+  if(!fs.existsSync(lock))return {state:'absent'};
+  let owner;
+  try{owner=JSON.parse(fs.readFileSync(path.join(lock,'owner.json'),'utf8'));}
+  catch{return {state:'uncertain',reason:'lock owner record missing or unreadable'};}
+  if(owner.schema!==1||!owner.token||!Number.isSafeInteger(owner.pid))
+    return {state:'uncertain',reason:'lock owner record invalid'};
+  if(alive(owner.pid))return {state:'live',reason:'wrapper process exists',owner};
+  if(owner.phase==='running'&&Number.isSafeInteger(owner.childPid)&&alive(owner.childPid))
+    return {state:'uncertain',reason:'recorded check process is still running',owner};
+  if(['launching','running','finished'].includes(owner.phase))
+    return {state:'uncertain',reason:'a descendant check process may survive; operator review required',owner};
+  if(owner.phase!=='prepared')
+    return {state:'uncertain',reason:'unknown wrapper phase',owner};
+  return {state:'abandoned',reason:'wrapper died before child launch',owner};
+}
+
+function reclaim(state,confirmed=false){
+  const lock=path.join(state,'run.lock'),guard=path.join(state,'run-recovery.lock');
+  fs.mkdirSync(guard);
+  try{
+    const status=inspectRunLock(state);
+    if(status.state!=='abandoned'){
+      const owner=status.owner;
+      const candidate=confirmed&&status.state==='uncertain'&&owner&&
+        !alive(owner.pid)&&(!Number.isSafeInteger(owner.childPid)||!alive(owner.childPid));
+      if(!candidate)throw Error(`run lock ${status.state}: ${status.reason}; inspect ${lock}`);
+    }
+    const entries=fs.readdirSync(lock);
+    if(entries.length!==1||entries[0]!=='owner.json')
+      throw Error('run lock has unexpected files; operator inspection required');
+    const quarantined=path.join(state,`abandoned-run-${randomUUID()}`);
+    fs.renameSync(lock,quarantined);
+    fs.unlinkSync(path.join(quarantined,'owner.json'));fs.rmdirSync(quarantined);
+  }finally{fs.rmdirSync(guard);}
+}
+
+export function recoverRunLock(state,confirmed=false){
+  if(!confirmed)throw Error('explicit --confirm-check-stopped required');
+  reclaim(state,true);
+  return {recovered:true};
+}
+
+export function acquireRunLock(state) {
+  const lock=path.join(state,'run.lock');
+  const token=randomUUID();
+  try{fs.mkdirSync(lock);}
+  catch(e){
+    if(e.code!=='EEXIST')throw e;
+    reclaim(state);
+    fs.mkdirSync(lock);
+  }
+  const owner={schema:1,token,pid:process.pid,phase:'prepared',childPid:null,
+    startedAt:Date.now()};
+  const file=path.join(lock,'owner.json');write(file,owner);
+  return {
+    phase(value,childPid=null){owner.phase=value;owner.childPid=childPid;write(file,owner);},
+    release(){
+      const current=JSON.parse(fs.readFileSync(file,'utf8'));
+      if(current.token!==token)throw Error('run lock ownership changed; refusing removal');
+      fs.unlinkSync(file);fs.rmdirSync(lock);
+    }
+  };
+}

package/src/run-recorder.cjs

@@ -0,0 +1,78 @@
+// 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.
+fs.openSync=function(file,flags,...rest){
+  if(!(flags===undefined||flags==='r'||flags==='rs'||flags===fs.constants.O_RDONLY))unsupported??='openSync';
+  return original.openSync.call(this,file,flags,...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','mkdirSync','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/state-store.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const STATE_SCHEMA=1;
+
+export function atomicJson(file,value){
+  const temp=file+`.`+process.pid+`.tmp`;
+  fs.writeFileSync(temp,JSON.stringify(value),{mode:0o600});
+  // Windows readers and AV can briefly hold the replaced name open. Keep the
+  // old complete file until replacement succeeds; never delete it first.
+  for(let attempt=0;;attempt++)try{fs.renameSync(temp,file);break;}catch(e){
+    if(process.platform!=='win32'||!['EPERM','EACCES','EBUSY'].includes(e.code)||attempt===9)
+      throw e;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,10*(attempt+1));
+  }
+}
+
+export function readReceipts(state){
+  let value;
+  try{value=JSON.parse(fs.readFileSync(path.join(state,'receipts-v1.json'),'utf8'));}
+  catch(e){if(e.code==='ENOENT')return {schema:STATE_SCHEMA,checks:{}};throw e;}
+  if(!value||typeof value!=='object'||Array.isArray(value)||value.schema!==STATE_SCHEMA||
+    !value.checks||typeof value.checks!=='object'||Array.isArray(value.checks))
+    throw Error(`incompatible receipt state in ${state}; inspect or remove only this vstate state directory`);
+  return value;
+}
+
+// This identity detects replacement of REDUE's owned, atomically written receipt
+// selector. It is not an input-content fingerprint or permission to reuse inputs.
+export function receiptRevision(state){
+  // A failed/crashed owned writer may have persisted a new immutable outcome
+  // without replacing the selector. Never certify its older selection.
+  try {fs.lstatSync(path.join(state,'receipt-selection-pending-v1.json'));
+    throw Error('receipt selection update incomplete; inspect the failed run, then record a new execution to recover');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  try {const stat=fs.statSync(path.join(state,'receipts-v1.json'),{bigint:true});
+    if(!stat.isFile())throw Error('receipt selector is not a file');
+    return JSON.stringify(['dev','ino','size','mtimeNs','ctimeNs'].map(key=>String(stat[key])));
+  }catch(error){if(error.code==='ENOENT')return 'absent';throw error;}
+}
+
+export function readReceiptSnapshot(state){
+  const revision=receiptRevision(state),value=readReceipts(state);
+  if(receiptRevision(state)!==revision)
+    throw Error('receipt selection changed during read; retry status');
+  return {revision,value};
+}
+
+export function commitReceipt(state,name,receipt){
+  const prior=readReceipts(state),runId=receipt.invocation?.runId;
+  if(!/^[0-9a-f-]{36}$/.test(runId||''))throw Error('receipt lacks a valid run ID');
+  const runs=path.join(state,'runs-v1');
+  fs.mkdirSync(runs,{recursive:true,mode:0o700});
+  // The caller holds the state run lock. Leave this marker on any write failure;
+  // only a later successful owned commit may clear it. No journal scan guesses
+  // which incomplete execution should become the selected evidence.
+  const pending=path.join(state,'receipt-selection-pending-v1.json');
+  let updates={schema:STATE_SCHEMA,checks:{}};
+  try {updates=JSON.parse(fs.readFileSync(pending,'utf8'));
+    if(updates?.schema!==STATE_SCHEMA||!updates.checks||typeof updates.checks!=='object'||Array.isArray(updates.checks))
+      throw Error('incompatible incomplete receipt update; inspect owned state before recording');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  updates.checks[name]={runId};
+  atomicJson(pending,updates);
+  // One immutable outcome per invocation. Never overwrite an existing run.
+  fs.writeFileSync(path.join(runs,runId+'.json'),
+    JSON.stringify({schema:STATE_SCHEMA,check:name,receipt}),{flag:'wx',mode:0o600});
+  prior.checks[name]=receipt;
+  atomicJson(path.join(state,'receipts-v1.json'),prior);
+  delete updates.checks[name];
+  if(Object.keys(updates.checks).length)atomicJson(pending,updates);
+  else fs.unlinkSync(pending);
+}

package/src/toolchain-probe.mjs

@@ -0,0 +1,21 @@
+// Read-only execution identity for explicitly named local tools. Output contains
+// hashes and metadata only; the verifier hashes the output again for its receipt.
+import fs from 'node:fs';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+
+const sha=value=>createHash('sha256').update(value).digest('hex');
+function identity(file) {
+  const real=fs.realpathSync(file),stat=fs.statSync(real,{bigint:true});
+  if(!stat.isFile())throw Error('toolchain identity requires a regular file');
+  const facts=[sha(real),...['dev','ino','mode','size','mtimeNs','ctimeNs']
+    .map(key=>String(stat[key]))];
+  // Hash small scripts/bundles on each probe. For large native executables,
+  // version plus identity/metadata keeps synchronized reads inexpensive.
+  if(stat.size<=16n*1024n*1024n)facts.push(sha(fs.readFileSync(real)));
+  return facts;
+}
+const own=fileURLToPath(import.meta.url);
+process.stdout.write(JSON.stringify({schema:1,nodeVersion:process.version,
+  node:identity(process.execPath),probe:identity(own),
+  tools:process.argv.slice(2).map(identity)}));

package/src/typescript-contract-probe.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Retired npm-launcher interpretation. Do not return even a context-only digest:
+// old receipts and cached compiler certificates cannot qualify this obligation.
+console.error('VSTATE_REASON:npm-launcher-unobserved-inputs');
+process.exitCode=2;

package/src/typescript-input-facts.mjs

@@ -0,0 +1,68 @@
+// Extracted from the existing npm TypeScript probe; shared compiler input logic.
+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 {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();
+  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 absolute=path.resolve(file);
+      if(!within(absolute,root))fail('typescript-config-outside-repository');
+      if(visited.has(absolute))return;visited.add(absolute);
+      if(visited.size>64)fail('typescript-config-graph-too-large');
+      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');
+      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'));
+  }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
+    // config rather than guessing about extends/reference provenance.
+    const config=path.join(root,'tsconfig.json'),raw=fs.readFileSync(config,'utf8');
+    if(/"(?:extends|references|plugins|incremental|composite)"\s*:/.test(raw))
+      fail('typescript-config-graph-unsupported');
+    const shown=spawnSync(process.execPath,[tsc,'--showConfig'],{cwd:root,
+      env:process.env,encoding:'utf8',timeout:4000,maxBuffer:16*1024*1024,
+      stdio:['ignore','pipe','pipe']});
+    if(shown.error||shown.signal||shown.status!==0)fail('typescript-config-unavailable');
+    const effective=JSON.parse(shown.stdout);
+    if(effective.compilerOptions?.plugins?.length||
+      effective.compilerOptions?.incremental||effective.compilerOptions?.composite)
+      fail('typescript-config-graph-unsupported');
+    configReads.add(config);
+  }
+  for(const file of configReads)if(!within(realObservedPath(file),root))
+    fail('typescript-config-outside-repository');
+  const listingStarted=performance.now();
+  const captured=process.argv.includes('--redue-checkpoint')?compilerFiles(tsRoot,root):null;
+  const listed=captured?{status:0,stdout:captured.files.join('\n')}:spawnSync(process.execPath,[tsc,'--noEmit','--listFilesOnly'],
+    {cwd:root,env:process.env,encoding:'utf8',timeout:process.platform==='win32'?10000:4000,
+      maxBuffer:16*1024*1024,
+      stdio:['ignore','pipe','pipe']});
+  timing('typescript_contract.list_files',listingStarted,{status:listed.status??null,
+    error:listed.error?.code||null});
+  if(listed.error||listed.signal||listed.status!==0)fail('typescript-input-list-unavailable');
+  const files=listed.stdout.trim().split(/\r?\n/).filter(Boolean)
+    .map(file=>path.resolve(file));
+  if(!files.length||files.some(file=>!within(realObservedPath(file),root)))
+    fail('typescript-input-outside-repository');
+  // 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};
+}

package/src/typescript-list.mjs

@@ -0,0 +1,141 @@
+// TypeScript's compiler host exposes the filesystem questions used to resolve
+// a program. Capture those answers, not runtime application accesses. Reuse is
+// allowed only while every answer and the observed input content still matches.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {createRequire} from 'node:module';
+const require=createRequire(import.meta.url);
+const hash=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function queryAnswer(kind,file,options) {
+  try{
+    if(kind==='readDirectory')return require(options.tsRoot).sys.readDirectory(file,
+      ...options.args.map((value,i)=>options.undefinedArguments?.includes(i)?undefined:value)).sort();
+    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();
+    // 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;}
+}
+export function queriesMatch(queries) {
+  if(!queries?.length)return false;
+  return queries.every(([kind,file,answer,options])=>
+    JSON.stringify(queryAnswer(kind,file,options))===JSON.stringify(answer));
+}
+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,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)=>{
+    // 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 parsed=ts.getParsedCommandLineOfConfigFile(path.join(cwd,'tsconfig.json'),{},
+    {...ts.sys,readFile,fileExists,directoryExists,getDirectories,readDirectory,
+      onUnRecoverableConfigFileDiagnostic(){}});
+  if(!parsed||parsed.errors?.length)throw Error('TypeScript configuration unavailable');
+  const host=ts.createCompilerHost(parsed.options);
+  Object.assign(host,{readFile,fileExists,directoryExists,getDirectories,readDirectory,
+    realpath(file){remember('realpath',file);return ts.sys.realpath(file);},
+    getSourceFile(file,languageVersion,onError){
+      const text=readFile(file);return text===undefined?undefined:
+        ts.createSourceFile(file,text,languageVersion);
+    }});
+  const program=ts.createProgram({rootNames:parsed.fileNames,options:parsed.options,
+    projectReferences:parsed.projectReferences,host});
+  const files=program.getSourceFiles().map(file=>path.resolve(file.fileName));
+  // Stable answers are necessary even at first capture; a concurrent edit
+  // cannot become the basis for a reusable discovery result.
+  const facts=[...queries.values()];
+  // A certificate must cover every program file; references parse further
+  // configurations outside this host and are not certified.
+  const complete=!parsed.projectReferences?.length&&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(Number(link.ctimeNs/1000000n)>=now-2000||Number(target.ctimeNs/1000000n)>=now-2000)return null;
+    const fields=st=>['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'].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;
+  });
+}

package/src/typescript-qualification.mjs

@@ -0,0 +1,77 @@
+import {directProject,directQualification,directEnvironment} from './direct-typescript.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {realObservedPath} from './path-identity.mjs';
+
+// This is a machine-enforced contract, not a claim inferred from a script name.
+// Runtime validation checks effective compiler membership, configuration and
+// toolchain identity. Supported discovery certificates still validate those
+// filesystem queries; caller context is independently compared at the decision.
+export function qualifyTypeScript(root,selected,discovered={}) {
+  if(selected.qualification===directQualification){
+    const issues=[];
+    try{
+      const compiler=directProject(root,selected.script);
+      if(selected.command?.length!==3||selected.command[0]!==process.execPath||
+        selected.command[1]!==compiler.entry||selected.command[2]!=='--noEmit'||
+        selected.cwd&&selected.cwd!=='.')issues.push('direct compiler invocation changed');
+    }catch(e){issues.push(e.code||'direct compiler prerequisites unavailable');}
+    if(!selected.inputs?.includes('**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}')||
+      !selected.inputs?.includes('package.json')||!selected.inputs?.includes('tsconfig.json')||
+      !selected.installedInputs?.includes('node_modules/**'))issues.push('direct compiler source/config/installed inputs incomplete');
+    if(!selected.environment?.executableIdentity||
+      !directEnvironment.variables.every(key=>selected.environment?.variables?.includes(key))||
+      !directEnvironment.prefixes.every(key=>selected.environment?.prefixes?.includes(key)))
+      issues.push('direct compiler execution context incomplete');
+    if(selected.probes?.length!==1||!selected.probes?.some(argv=>path.basename(argv[1]||'')==='direct-typescript-probe.mjs'&&
+      argv[0]===process.execPath&&argv[2]===root&&argv[3]===selected.script))issues.push('direct compiler probe missing');
+    return {qualified:issues.length===0,issues};
+  }
+  if(selected.qualification==='pnpm-tsc-v1'){
+    const issues=[];
+    const workspace=selected.workspace||'.';
+    const script=selected.script||selected.command?.at(-1);
+    try{
+      if(discovered.issue)throw Error(discovered.issue);
+      const contract=discovered.workspace;
+      if(!contract)throw Error('pnpm TypeScript input discovery unavailable');
+      issues.push(...contract.limitations);
+      const declared=contract.workspace.pkg.scripts[script].trim().split(/\s+/).slice(1);
+      if(path.resolve(root,selected.cwd||'.')!==path.join(root,contract.workspace.dir)||
+        selected.command?.[0]!==process.execPath||
+        selected.command?.[1]!==contract.tsc||
+        JSON.stringify(selected.command.slice(2))!==JSON.stringify(declared))
+        issues.push('standalone TypeScript invocation changed');
+    }catch(e){issues.push(e.message);}
+    if(!selected.probes?.some(argv=>path.basename(argv[1]||'')==='pnpm-typecheck-probe.mjs'))
+      issues.push('pnpm TypeScript input probe missing');
+    if(!selected.environment?.executableIdentity||
+      !['node'].every(name=>selected.environment?.pathExecutables?.includes(name))||
+      !['PNPM_','COREPACK_','npm_config_','DYLD_','TSGO_'].every(name=>
+        selected.environment?.prefixes?.includes(name)))
+      issues.push('pnpm execution context declaration incomplete');
+    return {qualified:issues.length===0,issues};
+  }
+  if(selected.qualification==='yarn-workspace-tsc-v1'){
+    const issues=[];
+    try{
+      if(!selected.workspace||selected.command?.length!==5||
+        selected.command[1]!=='workspace'||selected.command[2]!==selected.workspace||
+        selected.command[3]!=='run')issues.push('workspace command changed');
+      else if(discovered.issue)throw Error(discovered.issue);
+      else if(!discovered.workspace)throw Error('Yarn workspace input discovery unavailable');
+    }catch(e){issues.push(e.message);}
+    if(!selected.probes?.some(argv=>path.basename(argv[1]||'')==='yarn-workspace-typecheck-probe.mjs'))
+      issues.push('workspace TypeScript input probe missing');
+    if(!selected.environment?.executableIdentity||
+      !['node','yarn'].every(name=>selected.environment?.pathExecutables?.includes(name))||
+      !['YARN_','COREPACK_','npm_config_','DYLD_','TSGO_'].every(name=>
+        selected.environment?.prefixes?.includes(name)))
+      issues.push('Yarn execution context declaration incomplete');
+    return {qualified:issues.length===0,issues};
+  }
+  if(selected.qualification!=='typescript-noemit-v1')return null;
+  // Retired automatic launcher contract: npm's notifier consumes unobserved
+  // remote/cache/time state. A successful execution is still an outcome.
+  return {qualified:false,issues:['npm launcher applicability is unqualified: update notification uses unobserved remote/cache/time inputs; run the npm script when needed']};
+}

package/src/windows-command.mjs

@@ -0,0 +1,16 @@
+import path from 'node:path';
+
+// Windows cannot CreateProcess a .cmd/.bat file directly. Keep the logical
+// argv in the receipt, and launch only the well-defined, quoted batch subset
+// through cmd.exe. Unrepresentable arguments fail instead of being altered.
+export function windowsLaunch(command,{platform=process.platform,
+  comspec=process.env.ComSpec||process.env.COMSPEC||'C:\\Windows\\System32\\cmd.exe'}={}) {
+  if(platform!=='win32')return {file:command[0],args:command.slice(1),options:{}};
+  if(!/\.(?:cmd|bat)$/i.test(path.win32.extname(command[0])))
+    return {file:command[0],args:command.slice(1),options:{}};
+  if(command.some(value=>/[\r\n"%!^&|<>]/.test(value)))
+    throw Error('Windows batch command contains characters that cannot be passed safely; use an executable or Node script as exact argv');
+  const line='"'+command.map(value=>'"'+value+'"').join(' ')+'"';
+  return {file:comspec,args:['/d','/s','/c',line],
+    options:{windowsVerbatimArguments:true,windowsHide:false},mechanism:'cmd-batch'};
+}