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

package/src/plan-worker.mjs

@@ -0,0 +1,140 @@
+import {parentPort,workerData} from 'node:worker_threads';
+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 {directProject,directQualification} from './direct-typescript.mjs';
+import {queriesMatch} from './typescript-list.mjs';
+import {planGuard,inputKey} from './decision-validation.mjs';
+import {timing,traceBase} from './decision-profile.mjs';
+
+traceBase(workerData.diagnostic);
+try {
+  const totalStarted=performance.now();
+  const configStarted=performance.now();
+  const config=JSON.parse(fs.readFileSync(workerData.config));
+  timing('worker.config_load',configStarted);
+  let discoveryStarted=performance.now();
+  let bundle=workerData.reuse?.bundle;
+  let validatedIndex=null,guard=null,reuseReason='no_validated_plan',planReused=false;
+  if(bundle){
+    const started=performance.now();
+    try{
+      guard=planGuard(bundle);
+      const queryStarted=performance.now();
+      // Cached membership queries load the compiler API; establish its reviewed
+      // implementation before that optimization can execute project code.
+      const directRoots=new Set(config.checks.filter(check=>check.qualification===directQualification)
+        .map(check=>directProject(config.root,check.script).tsRoot));
+      if(directRoots.size&&(workerData.reuse.queries||[]).some(([kind,,,options])=>
+        kind==='readDirectory'&&!directRoots.has(options?.tsRoot)))throw Error('retained compiler implementation changed');
+      const queriesValid=guard===workerData.reuse.guard&&
+        (!workerData.reuse.queries?.length||queriesMatch(workerData.reuse.queries));
+      timing('worker.compiler_queries',queryStarted,{queries:workerData.reuse.queries?.length||0,matched:queriesValid?1:0});
+      if(guard!==workerData.reuse.guard||!queriesValid)reuseReason='configuration_or_resolution_changed';
+      else {
+        validatedIndex=new InputIndex(bundle);
+        validatedIndex.coldScan(progress=>parentPort.postMessage({kind:'progress',
+          phase:'validating',scanned:progress.scanned,total:progress.total}));
+        if(validatedIndex.unavailable)throw Error(validatedIndex.unavailable);
+        if(planGuard(bundle)!==guard)throw Error('plan dependencies changed during validation');
+        // Compiler imports can change effective membership. Until that content
+        // has been rediscovered, never reuse a compiler input contract.
+        const changed=[...validatedIndex.checks].some(([name,row])=>
+          row.plan.qualification&&inputKey(row)!==workerData.reuse.inputs[name]);
+        reuseReason=changed?'compiler_inputs_changed':'dependencies_unchanged';
+        planReused=!changed;
+      }
+    }catch{reuseReason='validation_unavailable';}
+    timing('worker.plan_validation',started,{reason:reuseReason,
+      files:validatedIndex?.files.size||0,
+      bytes:validatedIndex?.rehashedBytes||0,
+      hashingMs:Math.round(validatedIndex?.profile.hashingMs||0),
+      enumerationMs:Math.round(validatedIndex?.profile.enumerationMs||0)});
+  }
+  discoveryStarted=performance.now();
+  if(!planReused){bundle=discover(config,workerData.state);validatedIndex=null;
+    guard=planGuard(bundle);}
+  timing('worker.discovery_reason',performance.now(),{reason:reuseReason,reused:planReused?1:0});
+  const discoveryMs=performance.now()-discoveryStarted;
+  timing(planReused?'worker.discovery_reused':'worker.discovery',discoveryStarted,{checks:Object.keys(bundle.plans).length});
+  parentPort.postMessage({kind:'progress',phase:'indexing',discoveryMs,scanned:0,total:null});
+  const digest=file=>createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  let retained=null;
+  const retainedStarted=performance.now();
+  try {if(workerData.forceCold)throw Error('fresh reconciliation required');
+    retained=JSON.parse(fs.readFileSync(path.join(workerData.state,'index-v1.json')));
+    const identity=fs.statSync(bundle.root,{bigint:true});
+    if(retained.schema!==1||retained.root!==bundle.root||
+      JSON.stringify(retained.identity)!==JSON.stringify([String(identity.dev),String(identity.ino)])||
+      JSON.stringify(retained.planIds)!==JSON.stringify(Object.fromEntries(
+        Object.entries(bundle.plans).map(([name,plan])=>[name,plan.id])))||
+      retained.cursor!==digest(path.join(workerData.state,'fs-events.snapshot'))||
+      Object.keys(retained.external||{}).length!==new Set(Object.values(bundle.plans)
+        .flatMap(plan=>plan.externalObservationRoots||
+          Object.keys(plan.externalPatterns||{}))).size||
+      Object.entries(retained.external||{}).some(([root,value])=>
+        value.cursor!==digest(path.join(workerData.state,
+          `external-${createHash('sha256').update(root).digest('hex').slice(0,16)}.snapshot`))))
+      retained=null;
+  } catch {retained=null;}
+  timing('worker.retained_state_validation',retainedStarted,{reused:retained?1:0});
+  if(retained){
+    timing('worker.total',totalStarted,{mode:'retained'});
+    parentPort.postMessage({ok:true,bundle,discoveryMs,indexingMs:0,
+      restartMode:'retained-replay',index:retained.index,
+      external:Object.fromEntries(Object.entries(retained.external||{})
+        .map(([root,value])=>[root,value.index]))});
+  } else {
+  if(workerData.reconcileFaultFile&&fs.existsSync(workerData.reconcileFaultFile))
+    throw Error('injected reconciliation failure');
+  const indexingStarted=performance.now(), index=validatedIndex||new InputIndex(bundle);
+  if(!validatedIndex){const report=progress=>parentPort.postMessage({kind:'progress',phase:'indexing',discoveryMs,...progress});
+    index.coldScan(report);}
+  const indexingMs=performance.now()-indexingStarted;
+  timing(validatedIndex?'worker.index_reused':'worker.index',indexingStarted,{files:index.files.size,
+    entries:index.profile.enumeratedEntries,hashed:index.rehashedFiles,
+    bytes:index.rehashedBytes,enumerationMs:Math.round(index.profile.enumerationMs),
+    matchingMs:Math.round(index.profile.matchingMs),
+    hashingMs:Math.round(index.profile.hashingMs)});
+  if(index.unavailable)throw Error(index.unavailable);
+  const external={};
+  for(const boundary of [...new Set(Object.values(bundle.plans)
+    .flatMap(plan=>plan.externalObservationRoots||
+      Object.keys(plan.externalPatterns||{})))]) {
+    const plans=Object.fromEntries(Object.entries(bundle.plans)
+      .filter(([,plan])=>(plan.externalObservationRoots||
+        Object.keys(plan.externalPatterns||{})).includes(boundary))
+      .map(([name,plan])=>[name,{...plan,patterns:plan.externalPatterns[boundary],
+        sourcePatterns:[],
+        additivePatterns:plan.externalPatterns[boundary]||[],
+        installedPhysicalRoots:[]}]));
+    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};
+  }
+  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}});
+  }
+} catch(error) {
+  parentPort.postMessage({ok:false,error:error?.message||String(error),
+    classification:error?.name||'Error'});
+}

package/src/plan.mjs

@@ -0,0 +1,10 @@
+import {createHash} from 'node:crypto';
+import {discoverDeclared} from './declared-plan.mjs';
+
+export const sha = value => createHash('sha256').update(value).digest('hex');
+
+export function discover(config) {
+  if (config.provider !== 'declared-project@1')
+    throw Error(`unsupported input-plan provider: ${config.provider}`);
+  return discoverDeclared(config);
+}

package/src/platform-observation.mjs

@@ -0,0 +1,17 @@
+import parcelWatcher from '@parcel/watcher';
+import {subscribeLinux} from './linux-observer.mjs';
+
+export const hasHistory=process.platform==='darwin';
+export const backend=process.platform==='win32'?'windows':hasHistory?'fs-events':'inotify';
+export function subscribe(root,callback){
+  if(process.platform!=='darwin'&&process.platform!=='linux'&&process.platform!=='win32')
+    throw Error(`filesystem observation is unavailable on ${process.platform}`);
+  if(process.platform==='linux')return subscribeLinux(root,callback);
+  if(process.platform==='win32')return parcelWatcher.subscribe(root,callback,{backend}).then(handle=>({
+    unsubscribe:()=>handle.unsubscribe(),
+    // This is not a continuity barrier. Decision-grade reads on Windows use
+    // deterministic reconciliation, including after a watcher restart.
+    synchronize:async()=>{},watchFiles:async()=>{}
+  }));
+  return parcelWatcher.subscribe(root,callback,{backend});
+}

package/src/platform-state.mjs

@@ -0,0 +1,14 @@
+import path from 'node:path';
+
+export function userStateBase(platform=process.platform,env=process.env,
+  home=process.env.HOME||'',paths=path) {
+  if(platform==='win32')return paths.isAbsolute(env.LOCALAPPDATA||'')?
+    env.LOCALAPPDATA:paths.join(home,'AppData','Local');
+  if(platform==='linux')return paths.isAbsolute(env.XDG_STATE_HOME||'')?
+    env.XDG_STATE_HOME:paths.join(home,'.local','state');
+  return paths.join(home,'Library','Application Support');
+}
+
+export function stateIdentity(value,platform=process.platform) {
+  return platform==='win32'?path.win32.normalize(value).toLowerCase():value;
+}

package/src/pnpm-inputs.mjs

@@ -0,0 +1,355 @@
+// Pinned pnpm 12 node-modules installation provider. The engine sees only
+// repository-relative input sets and resolution relationships, never pnpm
+// virtual-store names as semantic identities.
+import {compilerFiles} from './typescript-list.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {execFileSync,spawnSync} from 'node:child_process';
+import micromatch from './glob.mjs';
+import YAML from 'yaml';
+import {resolveLinks} from './installed-inputs.mjs';
+import {withinPath as within,realObservedPath,samePath} from './path-identity.mjs';
+import {timing} from './decision-profile.mjs';
+
+const rel=(root,file)=>path.relative(root,file).split(path.sep).join('/');
+const read=file=>JSON.parse(fs.readFileSync(file,'utf8'));
+const exists=file=>{try{fs.lstatSync(file);return true;}catch{return false;}};
+function yaml(file){
+  const doc=YAML.parseDocument(fs.readFileSync(file,'utf8'),{uniqueKeys:true});
+  if(doc.errors.length)throw Error(`${path.basename(file)} cannot be interpreted safely`);
+  return doc.toJS()||{};
+}
+function safePatterns(values){
+  if(!Array.isArray(values)||values.some(v=>typeof v!=='string'||!v||
+    path.isAbsolute(v)||v.split('/').includes('..')))
+    throw Error('pnpm workspace patterns are unsupported');
+  return values;
+}
+export function pnpmProjectInfo(root){
+  root=realObservedPath(root);
+  const pkg=read(path.join(root,'package.json'));
+  const pin=/^pnpm@(12\.\d+\.\d+)(?:\+[^\s]+)?$/.exec(pkg.packageManager||'');
+  if(!pin)throw Error('an exact pnpm 12 packageManager pin is required');
+  const workspaceFile=path.join(root,'pnpm-workspace.yaml');
+  const settings=exists(workspaceFile)?yaml(workspaceFile):{};
+  const patterns=safePatterns(settings.packages||[]);
+  const linker=settings.nodeLinker||'isolated';
+  return {version:pin[1],linker,patterns,settings};
+}
+export function pnpmInstallInfo(root){
+  const started=performance.now();
+  root=realObservedPath(root);
+  const pkg=read(path.join(root,'package.json'));
+  const {version,linker,patterns,settings}=pnpmProjectInfo(root);
+  const workspaceFile=path.join(root,'pnpm-workspace.yaml');
+  if(!['isolated','hoisted'].includes(linker))throw Error(`pnpm ${linker} linker is recording-only`);
+  if(settings.modulesDir||settings.virtualStoreDir||settings.enableGlobalVirtualStore)
+    throw Error('custom pnpm modules or virtual-store location is recording-only');
+  if(settings.injectWorkspacePackages)
+    throw Error('injected workspace dependencies are recording-only');
+  if(settings.sharedWorkspaceLockfile===false)
+    throw Error('separate workspace lockfiles are recording-only');
+  if(exists(path.join(root,'.pnpmfile.cjs'))||exists(path.join(root,'.pnpmfile.mjs')))
+    throw Error('custom pnpm installation hooks need review');
+  const modulesFile=path.join(root,'node_modules','.modules.yaml');
+  if(!exists(modulesFile))throw Error('installed pnpm module metadata is missing');
+  const modules=yaml(modulesFile);
+  if(modules.nodeLinker!==linker||modules.packageManager!==pkg.packageManager)
+    throw Error('installed pnpm linker or version differs from project configuration');
+  const virtualStore=path.join(root,'node_modules','.pnpm');
+  // pnpm 12 on Windows can omit virtualStoreDir when using its project-local
+  // default. Accept only the observed, ordinary local directory in that case.
+  const declared=modules.virtualStoreDir;
+  const selected=declared===undefined?virtualStore:
+    path.resolve(path.dirname(modulesFile),declared);
+  let localStore=false;
+  try{localStore=fs.lstatSync(virtualStore).isDirectory()&&
+    samePath(realObservedPath(virtualStore),realObservedPath(selected));}
+  catch{}
+  if(!localStore||!exists(path.join(virtualStore,'lock.yaml')))
+    throw Error('nonstandard or incomplete project-local pnpm virtual store');
+  if(!exists(path.join(root,'pnpm-lock.yaml')))
+    throw Error('pnpm lockfile is missing');
+  if(exists(path.join(root,'.npmrc'))){
+    // pnpm 12 reads project settings from pnpm-workspace.yaml. Registry/auth
+    // entries affect acquisition, not a completed local TypeScript invocation.
+    for(const line of fs.readFileSync(path.join(root,'.npmrc'),'utf8').split(/\r?\n/)){
+      const trimmed=line.trim();if(!trimmed||/^[#;]/.test(trimmed))continue;
+      const key=trimmed.split('=')[0].trim();
+      if(key!=='registry'&&!/^\/\/[^\s]+\/:_authToken$/.test(key))
+        throw Error('project .npmrc has execution-relevant pnpm settings requiring review');
+    }
+  }
+  timing('pnpm.install_metadata',started);
+  return {version,linker,patterns,settings,modulesFile,
+    configurationInputs:['package.json','pnpm-lock.yaml',
+      ...(exists(workspaceFile)?['pnpm-workspace.yaml']:[]),
+      ...(exists(path.join(root,'.npmrc'))?['.npmrc']:[]),
+      'node_modules/.modules.yaml','node_modules/.pnpm/lock.yaml']};
+}
+export function pnpmWorkspacePackages(root,patterns){
+  const started=performance.now();
+  root=realObservedPath(root);
+  const found=new Map();
+  if(!patterns.length)return found;
+  const files=execFileSync('git',['ls-files','--cached','--others','--exclude-standard',
+    '-z','--',':(glob)**/package.json'],{cwd:root,
+    env:{...process.env,GIT_OPTIONAL_LOCKS:'0'},maxBuffer:32*1024*1024,
+    timeout:5000}).toString().split('\0').filter(Boolean);
+  for(const file of files){
+    const dir=path.posix.dirname(file);
+    if(dir==='.'||dir.split('/').includes('node_modules')||
+      !micromatch.isMatch(dir,patterns,{dot:true}))continue;
+    const pkg=read(path.join(root,file));
+    if(!pkg.name||found.has(pkg.name))throw Error('pnpm workspace name missing or duplicated');
+    found.set(pkg.name,{name:pkg.name,dir,manifest:file,pkg});
+  }
+  if(found.size>100)throw Error('pnpm workspace count exceeds the narrow Node onboarding contract');
+  timing('pnpm.workspace_discovery',started,{packages:found.size});
+  return found;
+}
+const deps=(pkg,includeDev)=>({...pkg.dependencies,
+  ...(includeDev?pkg.devDependencies:{}),
+  ...pkg.optionalDependencies,...pkg.peerDependencies});
+function typeOutputs(member){
+  const values=new Set();
+  if(typeof member.pkg.types==='string')values.add(member.pkg.types);
+  if(typeof member.pkg.typings==='string')values.add(member.pkg.typings);
+  const visit=(value,key)=>{
+    if(typeof value==='string'&&key==='types')values.add(value);
+    else if(value&&typeof value==='object')for(const [k,v] of Object.entries(value))visit(v,k);
+  };
+  visit(member.pkg.exports,'');
+  if(!values.size)throw Error(`${member.name} has no declared TypeScript output boundary`);
+  return [...values].map(value=>{
+    if(path.isAbsolute(value)||value.split('/').includes('..'))
+      throw Error(`${member.name} has an unsupported declaration path`);
+    const folder=path.posix.dirname(value.replace(/^\.\//,''));
+    if(folder==='.')throw Error(`${member.name} has a root declaration requiring review`);
+    return `${member.dir}/${folder}/**`;
+  });
+}
+function nodeCandidates(root,requester,name){
+  const result=[];let current=requester;
+  for(;;){
+    if(!within(current,root))break;
+    if(path.basename(current)!=='node_modules')
+      result.push(path.join(current,'node_modules',name));
+    if(current===root)break;
+    current=path.dirname(current);
+  }
+  return result;
+}
+function outsideNodeCandidates(root,name){
+  const result=[];let current=path.dirname(root);
+  for(;;){
+    if(path.basename(current)!=='node_modules')result.push(path.join(current,'node_modules',name));
+    const parent=path.dirname(current);if(parent===current)break;current=parent;
+  }
+  return result;
+}
+function packageAt(root,requester,name){
+  const candidates=nodeCandidates(root,requester,name);
+  for(const candidate of candidates){
+    let stat;try{stat=fs.statSync(candidate);}catch(e){
+      if(e.code==='ENOENT')continue;
+      throw Error(`${name} resolution cannot be inspected: ${e.code||e.name}`);
+    }
+    if(!stat.isDirectory())throw Error(`${name} resolves to an unsupported entry`);
+    const resolution=resolveLinks(candidate,root);
+    if(!resolution.physical)throw Error(`${name} resolution is unavailable: ${resolution.reason}`);
+    const physical=resolution.physical;
+    if(!within(physical,root))throw Error(`${name} resolves outside the observed checkout`);
+    const manifest=path.join(physical,'package.json');
+    if(!exists(manifest))throw Error(`${name} installed manifest is missing`);
+    return {physical,logical:candidate,candidates,pkg:read(manifest),
+      links:resolution.links};
+  }
+  for(const candidate of outsideNodeCandidates(root,name)){
+    try{fs.lstatSync(candidate);throw Error(`${name} may resolve outside the observed checkout`);}
+    catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+  return {physical:null,candidates};
+}
+function parsedTypeScript(root,dir,ts){
+  const config=path.join(root,dir,'tsconfig.json'),reads=new Set();
+  const host={...ts.sys,readFile(file){reads.add(path.resolve(file));return ts.sys.readFile(file);},
+    onUnRecoverableConfigFileDiagnostic(){}};
+  const parsed=ts.getParsedCommandLineOfConfigFile(config,{},host);
+  if(!parsed||parsed.errors?.length)throw Error('TypeScript configuration unavailable');
+  const raw=ts.readConfigFile(config,ts.sys.readFile);
+  if(raw.error||!Array.isArray(raw.config?.include)||raw.config.include.length!==1||
+    !/^src(?:$|\/)/.test(raw.config.include[0]))
+    throw Error('TypeScript source file membership is outside the supported src include');
+  if(parsed.options.plugins?.length||parsed.options.incremental||parsed.options.composite||
+    parsed.projectReferences?.length||parsed.options.paths||parsed.options.baseUrl||
+    parsed.options.rootDirs?.length||parsed.options.typeRoots?.length||
+    parsed.options.customConditions?.length||parsed.options.moduleSuffixes?.length)
+    throw Error('custom TypeScript compiler or resolution options need review');
+  const supported=new Set([undefined,ts.ModuleResolutionKind.Node10,
+    ts.ModuleResolutionKind.Node16,ts.ModuleResolutionKind.NodeNext]);
+  if(!supported.has(parsed.options.moduleResolution))
+    throw Error('TypeScript module resolver is outside the supported Node contract');
+  for(const file of reads)if(!within(realObservedPath(file),root))
+    throw Error('TypeScript configuration escapes the checkout');
+  return {parsed,configs:[...reads].map(file=>rel(root,file)).sort()};
+}
+function listedTypeScriptFiles(root,selected,tsc){
+  // --listFilesOnly resolves the compiler's effective module/file set but
+  // performs no typecheck and emits no project outputs.
+  const out=spawnSync(process.execPath,[tsc,'-p','tsconfig.json','--listFilesOnly'],
+    {cwd:path.join(root,selected.dir),env:process.env,encoding:'utf8',
+      // The native NTFS public workspace takes 3-5 s to list ~770 inputs;
+      // 5 s sometimes expired despite bounded, progressing compiler work.
+      timeout:10000,maxBuffer:32*1024*1024,stdio:['ignore','pipe','pipe']});
+  if(out.error||out.signal||out.status!==0)
+    throw Error('TypeScript input listing is unavailable');
+  const files=out.stdout.trim().split(/\r?\n/).filter(Boolean)
+    .map(file=>realObservedPath(file));
+  if(!files.length)throw Error('TypeScript input listing is empty');
+  return files;
+}
+function installedPackageRoot(root,file){
+  const modules=path.join(root,'node_modules');
+  if(!within(file,modules))return null;
+  const parts=rel(root,file).split('/');
+  const at=parts.lastIndexOf('node_modules');
+  if(at<0||!parts[at+1])return null;
+  const count=parts[at+1].startsWith('@')?2:1;
+  const packageRoot=path.join(root,...parts.slice(0,at+1+count));
+  const manifest=path.join(packageRoot,'package.json');
+  return exists(manifest)&&read(manifest).name?packageRoot:null;
+}
+function sharedHardlinkIn(folder){
+  const stack=[folder];
+  while(stack.length){
+    const current=stack.pop();
+    for(const item of fs.readdirSync(current,{withFileTypes:true})){
+      if(item.name==='node_modules')continue;
+      const file=path.join(current,item.name);
+      if(item.isDirectory())stack.push(file);
+      else if(item.isFile()&&fs.statSync(file).nlink>1)return true;
+      else if(item.isSymbolicLink())throw Error('installed package contains an unmodeled link');
+    }
+  }
+  return false;
+}
+export function pnpmTypecheckInputs(root,workspace,script,{captureQueries=false}={}){
+  const totalStarted=performance.now();
+  root=realObservedPath(root);
+  const install=pnpmInstallInfo(root),members=pnpmWorkspacePackages(root,install.patterns);
+  const selected=workspace==='.'?{name:'.',dir:'.',manifest:'package.json',
+    pkg:read(path.join(root,'package.json'))}:members.get(workspace);
+  if(!selected)throw Error(`workspace ${workspace} is not declared`);
+  if(!/^(?:tsc --noEmit|tsc -p (?:\.|tsconfig\.json)(?: --noEmit)?)$/.test(
+    selected.pkg.scripts?.[script]?.trim()||'')||
+    selected.pkg.scripts?.['pre'+script]||selected.pkg.scripts?.['post'+script])
+    throw Error('typecheck must be one standalone TypeScript invocation');
+  const selectedDir=path.join(root,selected.dir),lookup=createRequire(path.join(selectedDir,'package.json'));
+  let tsPackage;try{tsPackage=realObservedPath(lookup.resolve('typescript/package.json'));}
+  catch{throw Error('installed TypeScript compiler cannot be resolved');}
+  if(!within(tsPackage,root))throw Error('TypeScript compiler is outside the observed checkout');
+  const tsRoot=path.dirname(tsPackage),ts=lookup('typescript');
+  const tsc=path.join(tsRoot,'bin','tsc');
+  if(!exists(tsc))throw Error('installed TypeScript executable is missing');
+  const configStarted=performance.now();
+  const {configs}=parsedTypeScript(root,selected.dir,ts);
+  timing('pnpm.ts_config',configStarted,{configs:configs.length});
+  const closure=new Map(),installed=new Set(),generated=new Set(),
+    links=new Set(),candidates=new Set(),absences=[],instances=new Map();
+  let resolutionMs=0,resolutionCount=0;
+  const closureStarted=performance.now();
+  const visit=(requester,owner,includeDev=false)=>{
+    for(const [name,spec] of Object.entries(deps(owner.pkg,includeDev))){
+      if(owner.pkg.dependenciesMeta?.[name]?.injected)
+        throw Error(`injected workspace dependency ${name} is recording-only`);
+      const resolutionStarted=performance.now();
+      const found=packageAt(root,path.join(root,requester.dir),name);
+      resolutionMs+=performance.now()-resolutionStarted;resolutionCount++;
+      const optional=Object.hasOwn(owner.pkg.optionalDependencies||{},name)||
+        owner.pkg.peerDependenciesMeta?.[name]?.optional===true;
+      if(!found.physical){
+        if(!optional)throw Error(`${owner.name} requires unresolved installed package ${name}`);
+        absences.push({requester:owner.name,name});
+        for(const candidate of found.candidates)if(within(candidate,root))
+          candidates.add(rel(root,candidate));
+        // An outside ancestor can shadow a supported absence without a root event.
+        // For this alpha, a missing optional is qualified only when the caller's
+        // Node lookup boundary is explicitly observed by the project checkout.
+        continue;
+      }
+      for(const candidate of found.candidates){
+        if(candidate===found.logical)break;
+        if(within(candidate,root))candidates.add(rel(root,candidate));
+      }
+      for(const link of found.links||[])if(within(link.path,root))
+        links.add(rel(root,link.path));
+      const member=[...members.values()].find(row=>
+        path.join(root,row.dir)===found.physical);
+      if(String(spec).startsWith('workspace:')&&member?.name!==name)
+        throw Error(`${owner.name} workspace dependency ${name} is not linked to its workspace`);
+      if(member){
+        if(owner.name===member.name||member.name===selected.name)continue;
+        if(!closure.has(member.name)){
+          closure.set(member.name,member);
+          for(const value of typeOutputs(member))generated.add(value);
+          visit(member,member,true);
+        }
+      }
+    }
+  };
+  visit(selected,selected,true);
+  timing('pnpm.dependency_closure',closureStarted,{relationships:resolutionCount,
+    resolutionMs:Math.round(resolutionMs),workspaceLinks:links.size,
+    candidates:candidates.size});
+  const listingStarted=performance.now();
+  const captured=captureQueries?compilerFiles(tsRoot,path.join(root,selected.dir)):null;
+  const files=captured?captured.files.map(realObservedPath):listedTypeScriptFiles(root,selected,tsc);
+  timing('pnpm.ts_input_listing',listingStarted,{files:files.length});
+  const mappingStarted=performance.now();
+  for(const file of files){
+    if(within(file,path.join(selectedDir,'src'))||
+      [...closure.values()].some(member=>within(file,path.join(root,member.dir))))continue;
+    const packageRoot=installedPackageRoot(root,file);
+    if(!packageRoot)throw Error(`TypeScript consumes a file outside the observed pnpm contract: ${rel(root,file)}`);
+    if(!instances.has(packageRoot))instances.set(packageRoot,{name:read(path.join(packageRoot,'package.json')).name,
+      physicalRoot:rel(root,packageRoot)});
+    installed.add(`${rel(root,packageRoot)}/**`);
+    installed.add(`!${rel(root,packageRoot)}/node_modules/**`);
+  }
+  timing('pnpm.input_mapping',mappingStarted,{instances:instances.size,
+    installedPatterns:installed.size});
+  installed.add(`${rel(root,tsRoot)}/**`);
+  installed.add(`!${rel(root,tsRoot)}/node_modules/**`);
+  if(!instances.has(tsRoot))instances.set(tsRoot,{name:'typescript',physicalRoot:rel(root,tsRoot)});
+  const sharedStarted=performance.now();
+  const shared=[...instances.keys()].filter(sharedHardlinkIn);
+  timing('pnpm.hardlink_inspection',sharedStarted,{instances:instances.size,
+    shared:shared.length});
+  const source=[...new Set([...install.configurationInputs,selected.manifest,
+    ...configs,`${selected.dir==='.'?'':selected.dir+'/'}src/**`,
+    ...closure.values().map(member=>member.manifest),...generated])];
+  timing('pnpm.total_discovery',totalStarted,{instances:instances.size,
+    inputFiles:files.length});
+  return {install,workspace:selected,closure:[...closure.values()],source,
+    installed:[...installed],generated:[...generated],
+    // The read-only state probe consumes this same resolved compiler file set.
+    // It is deliberately omitted from the persisted user-facing input plan.
+    listedFiles:files,discoveryQueries:captured?.queries,
+    configs,configurationInputs:[...new Set([...install.configurationInputs,
+      ...configs,...members.values().map(member=>member.manifest)])],
+    installation:{provider:'pnpm',version:install.version,linker:install.linker},
+    installedInstances:[...instances.values()],
+    linkTriggers:[...links],absences,
+    limitations:[...(absences.length?[
+      'optional dependency absence has ancestor Node lookup locations outside the observed checkout']:[]),
+      ...(shared.length&&!['linux','win32'].includes(process.platform)?
+        ['installed package hardlinks have unobserved storage aliases']:[])],
+    // Installed hardlinks can change through a store alias without a project
+    // directory notification. A decision-grade read must rehash them.
+    synchronizedInstalledRead:['linux','win32'].includes(process.platform),
+    resolutionCandidates:[...candidates].map(value=>
+      ({path:value,observedPath:value})),workspacePatterns:install.patterns,
+    tsc,tsRoot};
+}

package/src/pnpm-typecheck-probe.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Read-only pnpm/TypeScript applicability probe. Only a digest or fixed
+// diagnostic leaves the process; no source, configuration, or environment
+// value is emitted.
+import {contextOnly,probeResult} from './probe-result.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {pnpmTypecheckInputs} from './pnpm-inputs.mjs';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+
+const [rootArg,workspace,script]=process.argv.slice(2);
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const digest=file=>hash(fs.readFileSync(file));
+const fail=code=>{throw Object.assign(Error(code),{code});};
+try{
+  if(!rootArg||!workspace||!script)fail('probe-arguments');
+  const root=realObservedPath(rootArg);
+  if(process.env.NODE_OPTIONS||process.env.NODE_PATH||process.env.BASH_ENV||
+    process.env.ENV||Object.entries(process.env).some(([key,value])=>{
+      if(/^npm_config_prefix$/i.test(key)&&process.platform==='win32'){
+        return !path.isAbsolute(value);
+      }
+      return /^(PNPM_|COREPACK_|npm_config_|DYLD_|TSGO_)/i.test(key);
+    }))
+    fail('pnpm-execution-environment-unsupported');
+  const contextHash=hash(JSON.stringify([root,workspace,script,process.version]));
+  if(contextOnly(contextHash))process.exit(0);
+  const contract=pnpmTypecheckInputs(root,workspace,script,{captureQueries:process.argv.includes('--redue-checkpoint')});
+  if(contract.limitations.length)fail('pnpm-input-coverage-unavailable');
+  const selected=path.join(root,contract.workspace.dir),tsc=contract.tsc;
+  const inputs=contract.listedFiles;
+  if(!inputs.length)fail('typescript-input-list-unavailable');
+  const inputRoots=[path.join(selected,'src'),...contract.generated.map(pattern=>
+    path.join(root,pattern.slice(0,-3))),...contract.installed.filter(p=>!p.startsWith('!'))
+      .map(pattern=>path.join(root,pattern.slice(0,-3)))];
+  for(const file of inputs)if(!within(file,root)||
+    !inputRoots.some(boundary=>within(file,boundary)))
+    fail('typescript-input-outside-pnpm-contract');
+  const files=[...new Set(inputs)].sort().map(file=>
+    [hash(path.relative(root,file)),digest(file)]);
+  const configs=contract.configs.map(file=>[hash(file),digest(path.join(root,file))]);
+  probeResult(hash(JSON.stringify({schema:1,workspace,script,
+    files,configs,node:process.version,tsc:digest(tsc),
+    packageManager:contract.install.version,linker:contract.install.linker})),contextHash,contract.discoveryQueries);
+}catch(e){console.error(`VSTATE_REASON:${e.code&&/^[a-z-]+$/.test(e.code)?e.code:
+  'pnpm-typecheck-contract-unavailable'}`);process.exitCode=2;}

package/src/presentation.mjs

@@ -0,0 +1,53 @@
+// Presentation consumes evidence; it never grants applicability.
+export function checkLabel(row) {
+  return row.result==='FAIL'?'FAILED':row.freshness;
+}
+export function explanation(row) {
+  const reason=row.reason||'No verification evidence is available.';
+  if(reason==='no receipt')return 'No execution has been recorded. Run this check when verification is needed.';
+  if(reason==='declared inputs match')return 'Recorded evidence still applies to the declared inputs.';
+  if(reason==='execution environment context not supplied')return 'Cached status cannot confirm your execution context. Use --sync if worthwhile, or rerun the check.';
+  if(/requires? a synchronized content read/.test(reason))return 'Cached status cannot establish applicability here. Use --sync if worthwhile, or rerun the check.';
+  if(reason.startsWith('input coverage unresolved: '))return 'Recording-only: '+reason.slice(27);
+  if(/input plan (rebuilding|indexing)|observer initialization|input observation reconciliation pending/.test(reason))
+    return 'Checking inputs after startup or changes. Wait for observation to finish, then query again.';
+  if(/observer (heartbeat|process|stopping)/.test(reason))return 'Observer unavailable. Run redue start; previous outcomes remain recorded.';
+  return reason;
+}
+export function renderStatus(value,{short=false}={}) {
+  if(short)return `REDUE ${String(value.state||'unverified').toUpperCase()}`;
+  const lines=[];
+  for(const row of value.checks||[]) {
+    const label=checkLabel(row),symbol=label==='CURRENT'&&row.result==='PASS'?'✓':label==='FAILED'?'✗':'?';
+    const mark=label==='STALE'?'⚠':symbol;
+    const historical=row.result?` / ${row.result}`:'';
+    lines.push(`${mark} ${row.name}  ${label}${historical}`);
+    if(label!=='CURRENT')lines.push(`  ${row.result==='FAIL'?`Historical failure; applicability ${row.freshness}. `:''}${explanation(row)}`);
+  }
+  if(!lines.length)lines.push('UNVERIFIED — observation is initializing; no check state is available yet.');
+  if(!value.observation?.healthy)lines.push('Observation unavailable or pending. Previous results are not reusable.');
+  return lines.join('\n');
+}
+export function renderExplain(value,name) {
+  const rows=name?value.checks.filter(row=>row.name===name):value.checks;
+  return rows.map(row=>{
+    const lines=[`${row.name}: ${checkLabel(row)}${row.result?` / ${row.result}`:''}`];
+    if(row.result==='FAIL')lines.push(`Historical failure; applicability: ${row.freshness}.`);
+    if(row.verification_recipe==='npm-direct-typescript@1')lines.push('Recorded recipe: direct local TypeScript compiler; npm and lifecycle scripts were not executed.');
+    lines.push(explanation(row));
+    if(row.changed_inputs?.length)lines.push('Relevant inputs changed:',...row.changed_inputs.map(file=>`  ${file}`));
+    if(row.freshness==='STALE')lines.push(`Due again when verification is needed: redue run ${JSON.stringify(row.name)}`);
+    if(row.invocation)lines.push(`Last invocation: ${row.invocation.status}`+
+      (Number.isFinite(row.invocation.durationMs)?` (${(row.invocation.durationMs/1000).toFixed(2)}s)`:'')+'.');
+    return lines.join('\n');
+  }).join('\n\n');
+}
+export function renderRun(value) {
+  const label=value.result==='FAIL'?'FAILED':value.result||String(value.invocation).toUpperCase();
+  const lines=[`${value.check}: ${label} recorded.`];
+  if(value.invocation!=='exited')lines.push(`Invocation ${value.invocation}; no reusable passing evidence.`);
+  else if(!value.coverage_qualified)lines.push('Applicability remains UNVERIFIED: input coverage is incomplete.');
+  else if(!value.stable)lines.push('Applicability remains UNVERIFIED: inputs changed or observation was unavailable during execution.');
+  else lines.push('Inspect redue status before reusing this evidence. Cached status may require --sync to establish applicability.');
+  return lines.join('\n');
+}