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

package/src/typescript-contract-probe.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Read-only applicability probe for the deliberately narrow npm/tsc --noEmit
+// contract. It emits one digest; failures emit only a fixed diagnostic code.
+import {compilerFiles} from './typescript-list.mjs';
+import {contextOnly,probeResult} from './probe-result.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {createRequire} from 'node:module';
+import {spawnSync} from 'node:child_process';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+import {timing} from './decision-profile.mjs';
+
+const [rootArg,scriptName,npmArg]=process.argv.slice(2);
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const fail=code=>{throw Object.assign(Error(code),{code});};
+const digestFile=file=>hash(fs.readFileSync(file));
+const require=createRequire(import.meta.url);
+function treeHash(dir){
+  const digest=createHash('sha256');let count=0;
+  const visit=(folder,rel='')=>{
+    for(const entry of fs.readdirSync(folder,{withFileTypes:true}).sort((a,b)=>
+      a.name.localeCompare(b.name))){
+      const name=rel?rel+'/'+entry.name:entry.name,full=path.join(folder,entry.name);
+      if(entry.isDirectory())visit(full,name);
+      else if(entry.isFile()){digest.update(name+'\0'+digestFile(full)+'\0');count++;}
+      else fail('npm-installation-unobservable');
+    }
+  };
+  visit(dir);return [digest.digest('hex'),count];
+}
+function npmRcKeys(file){
+  if(!fs.existsSync(file))return null;
+  const keys=[];
+  for(const line of fs.readFileSync(file,'utf8').split(/\r?\n/)){
+    const trimmed=line.trim();if(!trimmed||/^[#;]/.test(trimmed))continue;
+    const at=trimmed.indexOf('=');if(at<0)fail('npm-configuration-unsupported');
+    const key=trimmed.slice(0,at).trim();
+    if(key!=='registry'&&!/^\/\/[^\s]+\/:_authToken$/.test(key))
+      fail('npm-configuration-unsupported');
+    keys.push(key);
+  }
+  return keys.sort();
+}
+try{
+  if(!rootArg||!scriptName||!npmArg)fail('probe-arguments');
+  const root=realObservedPath(rootArg),npm=realObservedPath(npmArg);
+  const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+  if(pkg.scripts?.[scriptName]?.trim()!=='tsc --noEmit'||
+    pkg.scripts?.['pre'+scriptName]||pkg.scripts?.['post'+scriptName])
+    fail('typecheck-script-changed');
+  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'){
+        // The Windows runner supplies a global npm prefix independently of
+        // the selected local compiler. Its value is part of caller context.
+        return !path.isAbsolute(value);
+      }
+      return /^(npm_config_|DYLD_|TSGO_)/i.test(key);
+    }))fail('execution-environment-unsupported');
+  let npmRoot;
+  if(process.platform==='win32'){
+    if(path.basename(npm).toLowerCase()!=='npm.cmd')
+      fail('npm-installation-layout-unsupported');
+    npmRoot=path.join(path.dirname(npm),'node_modules','npm');
+    const body=fs.readFileSync(npm,'utf8');
+    if(!body.includes('node_modules\\npm\\bin\\npm-cli.js')||
+      !body.includes('node_modules\\npm\\bin\\npm-prefix.js')||
+      !body.includes('"%NODE_EXE%" "%NPM_CLI_JS%" %*'))
+      fail('npm-installation-layout-unsupported');
+    const prefix=spawnSync(process.execPath,[path.join(npmRoot,'bin','npm-prefix.js')],
+      {cwd:root,env:process.env,encoding:'utf8',timeout:4000,stdio:['ignore','pipe','ignore']});
+    const selectedPrefix=prefix.stdout?.trim();
+    if(prefix.error||prefix.status!==0||!selectedPrefix||
+      !path.isAbsolute(selectedPrefix))fail('npm-installation-layout-unsupported');
+    // npm.cmd selects the prefix's CLI only when that file exists. Otherwise
+    // it runs the bundled CLI beside npm.cmd; observe the same branch here.
+    const alternate=path.join(selectedPrefix,'node_modules','npm','bin','npm-cli.js');
+    if(fs.existsSync(alternate)&&
+      realObservedPath(alternate)!==realObservedPath(path.join(npmRoot,'bin','npm-cli.js')))
+      fail('npm-installation-layout-unsupported');
+  }else npmRoot=path.dirname(path.dirname(npm));
+  if(path.basename(npmRoot)!=='npm'||path.basename(path.dirname(npmRoot))!=='node_modules')
+    fail('npm-installation-layout-unsupported');
+  const home=process.platform==='win32'?os.homedir():process.env.HOME;
+  if(!home||!path.isAbsolute(home))fail('home-context-unavailable');
+  const npmConfig=[path.join(root,'.npmrc'),path.join(home,'.npmrc')]
+    .map(file=>[hash(file),npmRcKeys(file)]);
+  const contextFacts={
+    npmTree:treeHash(npmRoot),npmConfig,
+    node:hash(JSON.stringify([process.version,realObservedPath(process.execPath),
+      fs.statSync(process.execPath).size])),
+    shell:process.platform==='win32'?hash(JSON.stringify([
+      realObservedPath(process.env.ComSpec||process.env.COMSPEC||''),
+      digestFile(process.env.ComSpec||process.env.COMSPEC||''),
+      process.env.PATHEXT||'',digestFile(npm),
+      digestFile(path.join(root,'node_modules','.bin','tsc.cmd'))])):
+      digestFile('/bin/sh')};
+  const contextHash=hash(JSON.stringify(contextFacts));
+  if(contextOnly(contextHash))process.exit(0);
+  const tsRoot=path.join(root,'node_modules','typescript');
+  let tsc;
+  if(process.platform==='win32'){
+    const shim=path.join(root,'node_modules','.bin','tsc.cmd');
+    const body=fs.readFileSync(shim,'utf8').replace(/\r\n/g,'\n').trim();
+    const expected=`@ECHO off
+GOTO start
+:find_dp0
+SET dp0=%~dp0
+EXIT /b
+:start
+SETLOCAL
+CALL :find_dp0
+
+IF EXIST "%dp0%\\node.exe" (
+  SET "_prog=%dp0%\\node.exe"
+) ELSE (
+  SET "_prog=node"
+  SET PATHEXT=%PATHEXT:;.JS;=;%
+)
+
+endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\..\\typescript\\bin\\tsc" %*`;
+    if(body!==expected)fail('typescript-executable-changed');
+    tsc=realObservedPath(path.join(tsRoot,'bin','tsc'));
+  }else{
+    tsc=realObservedPath(path.join(root,'node_modules','.bin','tsc'));
+    if(tsc!==path.join(tsRoot,'bin','tsc'))fail('typescript-executable-changed');
+  }
+  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');
+  const facts={schema:1,root:hash(root),script:scriptName,
+    configs:[...configReads].sort().map(file=>[hash(file),digestFile(file)]),
+    files:[...new Set(files)].sort().map(file=>[hash(file),digestFile(file)]),
+    ...contextFacts};
+  probeResult(hash(JSON.stringify(facts)),contextHash,captured?.queries);
+}catch(e){console.error(`VSTATE_REASON:${e.code&&/^[a-z-]+$/.test(e.code)?e.code:
+  'typescript-contract-unavailable'}`);process.exitCode=2;}

package/src/typescript-list.mjs

@@ -0,0 +1,68 @@
+// 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).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();
+    if(kind==='realpath')return fs.realpathSync(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();
+    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)=>{
+    const full=path.resolve(file),answer=queryAnswer(kind,full);
+    queries.set(kind+'\0'+full,[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);
+    const full=path.resolve(dir),options={tsRoot,args};
+    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,
+    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()];
+  return {files,queries:queriesMatch(facts)?facts:null};
+}

package/src/typescript-qualification.mjs

@@ -0,0 +1,96 @@
+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.
+// The read-only runtime probe separately checks the effective TypeScript file
+// list, config graph, npm toolchain and caller context on every sync/run.
+export function qualifyTypeScript(root,selected,discovered={}) {
+  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;
+  const issues=[];
+  let pkg;
+  try{pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));}
+  catch{issues.push('package manifest unavailable');}
+  if(!selected.script||pkg?.scripts?.[selected.script]?.trim()!=='tsc --noEmit'||
+    pkg?.scripts?.['pre'+selected.script]||pkg?.scripts?.['post'+selected.script])
+    issues.push('typecheck script is not the supported standalone tsc --noEmit invocation');
+  if(selected.command?.length!==3||selected.command[1]!=='run'||
+    selected.command[2]!==selected.script)
+    issues.push('package-manager invocation differs from the discovered script');
+  try{const npm=fs.realpathSync(selected.command[0]);
+    const supported=process.platform==='win32'?path.basename(npm).toLowerCase()==='npm.cmd'&&
+      fs.existsSync(path.join(path.dirname(npm),'node_modules','npm','bin','npm-cli.js')):
+      path.basename(npm)==='npm-cli.js'&&
+      path.basename(path.dirname(path.dirname(npm)))==='npm';
+    if(!supported)
+      issues.push('npm executable layout is not supported');}
+  catch{issues.push('npm executable unavailable');}
+  if(!fs.existsSync(path.join(root,'tsconfig.json')))
+    issues.push('tsconfig.json is missing');
+  if(!fs.existsSync(path.join(root,'node_modules','typescript','package.json'))||
+    !fs.existsSync(path.join(root,'node_modules','.bin',
+      process.platform==='win32'?'tsc.cmd':'tsc')))
+    issues.push('local TypeScript installation is missing');
+  if(!selected.inputs?.includes('**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}')||
+    !selected.inputs?.includes('package.json')||
+    !selected.inputs?.includes('tsconfig.json'))
+    issues.push('TypeScript source/config file-set declaration is incomplete');
+  if(!selected.installedInputs?.includes('node_modules/**'))
+    issues.push('installed package contents and membership are not declared');
+  if(!selected.environment?.executableIdentity||
+    !['node','npm'].every(name=>selected.environment?.pathExecutables?.includes(name))||
+    !['NODE_OPTIONS','NODE_PATH','HOME','BASH_ENV','ENV'].every(name=>
+      selected.environment?.variables?.includes(name))||
+    !['npm_config_','DYLD_','TSGO_'].every(name=>
+      selected.environment?.prefixes?.includes(name)))
+    issues.push('caller toolchain or execution context declaration is incomplete');
+  if(!selected.probes?.some(argv=>path.basename(argv[1]||'')==='typescript-contract-probe.mjs'&&
+    argv[2]&&fs.existsSync(argv[2])&&
+    realObservedPath(argv[2])===root&&argv[3]===selected.script&&
+    argv[4]===selected.command[0]))
+    issues.push('TypeScript input and toolchain probe is missing');
+  return {qualified:issues.length===0,issues};
+}

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'};
+}

package/src/windows-process.mjs

@@ -0,0 +1,15 @@
+import {spawn} from 'node:child_process';
+
+// taskkill /T is the native narrow process-tree operation available without
+// elevation. It cannot own deliberately detached descendants.
+export function terminateWindowsTree(pid,{start=spawn,timeoutMs=5000}={}) {
+  if(!Number.isSafeInteger(pid)||pid<1)return Promise.reject(Error('invalid check PID'));
+  return new Promise((resolve,reject)=>{
+    const child=start('taskkill.exe',['/PID',String(pid),'/T','/F'],
+      {stdio:'ignore',windowsHide:true});
+    const timer=setTimeout(()=>{child.kill();reject(Error('taskkill deadline exceeded'));},timeoutMs);
+    child.once('error',error=>{clearTimeout(timer);reject(error);});
+    child.once('close',code=>{clearTimeout(timer);code===0?resolve():
+      reject(Error(`taskkill exited ${code}`));});
+  });
+}

package/src/yarn-workspace-inputs.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {createRequire} from 'node:module';
+import micromatch from './glob.mjs';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+
+export function yarnLocalTsc(root){
+  const expected=path.join(root,'node_modules','typescript','bin','tsc');
+  if(process.platform==='win32'){
+    const shim=path.join(root,'node_modules','.bin','tsc.cmd');
+    const body=fs.readFileSync(shim,'utf8').replace(/\r\n/g,'\n').trim();
+    const standard=`@IF EXIST "%~dp0\\node.exe" (
+  "%~dp0\\node.exe"  "%~dp0\\..\\typescript\\bin\\tsc" %*
+) ELSE (
+  @SETLOCAL
+  @SET PATHEXT=%PATHEXT:;.JS;=;%
+  node  "%~dp0\\..\\typescript\\bin\\tsc" %*
+)`;
+    if(body!==standard)throw Error('local TypeScript executable is not the installed compiler');
+    return realObservedPath(expected);
+  }
+  const tsc=realObservedPath(path.join(root,'node_modules','.bin','tsc'));
+  if(tsc!==expected)throw Error('local TypeScript executable is not the installed compiler');
+  return tsc;
+}
+
+const posix=file=>file.split(path.sep).join('/');
+const read=file=>JSON.parse(fs.readFileSync(file,'utf8'));
+const relative=(root,file)=>posix(path.relative(root,file));
+const safeDirectory=(root,dir)=>{
+  const full=path.resolve(root,dir);
+  if(!within(full,root))throw Error('workspace path escapes checkout');
+  return full;
+};
+
+export function yarnWorkspacePackages(root){
+  root=realObservedPath(root);
+  const pkg=read(path.join(root,'package.json'));
+  const patterns=Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages;
+  if(!Array.isArray(patterns)||!patterns.length||patterns.some(value=>
+    typeof value!=='string'||path.isAbsolute(value)||value.split('/').includes('..')))
+    throw Error('workspace declarations are unsupported');
+  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);
+  const found=new Map();
+  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 member=read(path.join(root,file));
+    if(!member.name||found.has(member.name))throw Error('workspace package name missing or duplicated');
+    found.set(member.name,{name:member.name,dir,manifest:file,pkg:member});
+  }
+  if(found.size>50)throw Error('workspace count exceeds narrow Node onboarding contract');
+  return found;
+}
+
+function parsedTypeScript(root,dir){
+  const require=createRequire(path.join(root,'package.json'));
+  const ts=require(path.join(root,'node_modules','typescript'));
+  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','src/**/*','src/**'].includes(raw.config.include[0]))
+    throw Error('workspace TypeScript file membership is outside the supported src include');
+  if(parsed.options.plugins?.length||parsed.options.incremental||parsed.options.composite)
+    throw Error('TypeScript plugins or incremental/project builds are outside this contract');
+  if(parsed.options.paths||parsed.options.baseUrl||parsed.options.rootDirs?.length||
+    parsed.options.typeRoots?.length||parsed.options.customConditions?.length||
+    parsed.options.moduleSuffixes?.length||
+    parsed.options.moduleResolution!==undefined&&
+      parsed.options.moduleResolution!==ts.ModuleResolutionKind.Node10)
+    throw Error('custom TypeScript module resolution needs explicit input coverage');
+  if(parsed.projectReferences?.length)throw Error('TypeScript project references need a separate contract');
+  for(const file of reads)if(!within(realObservedPath(file),root))
+    throw Error(`TypeScript configuration escapes the checkout: ${path.basename(file)}`);
+  return {parsed,configs:[...reads].map(file=>relative(root,file)).sort()};
+}
+
+export function yarnWorkspaceTypecheckInputs(root,workspace,script){
+  root=realObservedPath(root);
+  const rootPkg=read(path.join(root,'package.json'));
+  if(!/^yarn@4\./.test(rootPkg.packageManager||''))throw Error('pinned Yarn 4 required');
+  const yarnrc=fs.readFileSync(path.join(root,'.yarnrc.yml'),'utf8');
+  const linker=yarnrc.match(/^\s*nodeLinker\s*:\s*['"]?([\w-]+)/m)?.[1];
+  const mode=yarnrc.match(/^\s*nmMode\s*:\s*['"]?([\w-]+)/m)?.[1]||'classic';
+  if(linker!=='node-modules'||mode!=='classic')
+    throw Error('Yarn node-modules classic installation required');
+  if(/^\s*(?:yarnPath|plugins)\s*:/m.test(yarnrc))
+    throw Error('custom Yarn executable or plugins need explicit toolchain coverage');
+  const members=yarnWorkspacePackages(root),selected=members.get(workspace);
+  if(!selected)throw Error(`workspace ${workspace} is not declared`);
+  if(selected.pkg.scripts?.[script]?.trim()!=='tsc -p .'||
+    selected.pkg.scripts?.['pre'+script]||selected.pkg.scripts?.['post'+script])
+    throw Error('workspace typecheck must be standalone tsc -p .');
+  const packageDir=safeDirectory(root,selected.dir);
+  if(fs.existsSync(path.join(packageDir,'node_modules','.bin','tsc'))||
+    fs.existsSync(path.join(packageDir,'node_modules','.bin','tsc.cmd')))
+    throw Error('workspace-local TypeScript executable needs separate toolchain coverage');
+  const {parsed,configs}=parsedTypeScript(root,selected.dir);
+  const outDir=parsed.options.outDir&&within(path.resolve(parsed.options.outDir),root)?
+    relative(root,path.resolve(parsed.options.outDir)):null;
+  if(!parsed.options.noEmit&&!outDir)
+    throw Error('emitting TypeScript check needs an in-checkout outDir');
+  if(outDir&&within(path.join(root,outDir),path.join(packageDir,'src')))
+    throw Error('TypeScript output overlaps observed source inputs');
+  const closure=new Map(),visit=member=>{
+    for(const name of Object.keys({...member.pkg.dependencies,...member.pkg.devDependencies,
+      ...member.pkg.peerDependencies,...member.pkg.optionalDependencies})){
+      const dep=members.get(name);if(!dep||dep.name===selected.name||closure.has(name))continue;
+      closure.set(name,dep);visit(dep);
+    }
+  };
+  visit(selected);
+  const source=[...new Set(['package.json','yarn.lock','.yarnrc.yml',
+    selected.manifest,...configs,`${selected.dir}/src/**`])];
+  const installed=['node_modules/**',`${selected.dir}/node_modules/**`];
+  const generated=[];
+  const linkTriggers=[];
+  for(const member of members.values()){
+    const logical=`node_modules/${member.name}`;
+    installed.push(`!${logical}`,`!${logical}/**`);
+    if(!closure.has(member.name))continue;
+    installed.push(`${member.dir}/node_modules/**`);
+    const declaration=member.pkg.types||member.pkg.typings;
+    if(!declaration||path.isAbsolute(declaration)||declaration.split('/').includes('..'))
+      throw Error(`${member.name} has no supported declaration-output location`);
+    const output=path.posix.dirname(declaration);
+    const outputDir=output==='.'?member.dir:`${member.dir}/${output}`;
+    generated.push(`${outputDir}/**`);
+    source.push(member.manifest);
+    // The logical link is part of resolution identity even though its target
+    // contents are indexed at the physical workspace output location.
+    linkTriggers.push(logical);
+  }
+  yarnLocalTsc(root);
+  return {workspace:selected,closure:[...closure.values()],source:[...new Set(source)],
+    installed,generated:[...new Set(generated)],configs,
+    configurationInputs:[...new Set(['package.json','yarn.lock','.yarnrc.yml',
+      ...configs,...members.values().map(row=>row.manifest),
+      'node_modules/.yarn-state.yml'])],linkTriggers,outDir};
+}

package/src/yarn-workspace-typecheck-probe.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Read-only applicability probe. Its output is one digest or a fixed reason;
+// source, configuration, environment values, and command output are not logged.
+import {compilerFiles} from './typescript-list.mjs';
+import {contextOnly,probeResult} from './probe-result.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {yarnWorkspaceTypecheckInputs,yarnLocalTsc} from './yarn-workspace-inputs.mjs';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+import {windowsLaunch} from './windows-command.mjs';
+
+const [rootArg,workspace,script,yarnArg]=process.argv.slice(2);
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const digestFile=file=>hash(fs.readFileSync(file));
+const fail=code=>{throw Object.assign(Error(code),{code});};
+function yarnDistribution(yarn,version){
+  let loader=yarn;
+  if(process.platform==='win32'&&/\.cmd$/i.test(yarn)){
+    const body=fs.readFileSync(yarn,'utf8').replace(/\r\n/g,'\n').trim();
+    const line=body.split('\n')[2]||'';
+    const match=/^  "%~dp0\\node\.exe"  "%~dp0\\(.+\\corepack\\dist\\yarn\.js)" %\*$/.exec(line);
+    if(!match)fail('yarn-distribution-unobservable');
+    const relative=match[1];
+    const standard=`@SETLOCAL
+@IF EXIST "%~dp0\\node.exe" (
+  "%~dp0\\node.exe"  "%~dp0\\${relative}" %*
+) ELSE (
+  @SET PATHEXT=%PATHEXT:;.JS;=;%
+  node  "%~dp0\\${relative}" %*
+)`;
+    if(body!==standard)fail('yarn-distribution-unobservable');
+    loader=realObservedPath(path.resolve(path.dirname(yarn),relative));
+  }
+  if(!/[/\\]corepack[/\\]dist[/\\]yarn\.js$/.test(loader))
+    return {distribution:yarn,loader};
+  if(process.env.COREPACK_HOME&&!path.isAbsolute(process.env.COREPACK_HOME))
+    fail('yarn-distribution-unobservable');
+  const candidates=process.env.COREPACK_HOME?
+    [path.join(process.env.COREPACK_HOME,'v1/yarn',version,'yarn.js')]:[
+      ...(process.platform==='win32'&&path.isAbsolute(process.env.LOCALAPPDATA||'')?
+        [path.join(process.env.LOCALAPPDATA,'node/corepack/v1/yarn',version,'yarn.js')]:[]),
+      path.join(os.homedir(),'.cache/node/corepack/v1/yarn',version,'yarn.js'),
+      path.join(os.homedir(),'Library/Caches/node/corepack/v1/yarn',version,'yarn.js')];
+  const found=candidates.find(file=>fs.existsSync(file));
+  if(!found)fail('yarn-distribution-unobservable');
+  return {distribution:found,loader};
+}
+try{
+  if(!rootArg||!workspace||!script||!yarnArg)fail('probe-arguments');
+  const root=realObservedPath(rootArg),yarn=realObservedPath(yarnArg);
+  const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json')));
+  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);
+      }
+      if(key==='COREPACK_HOME')return !path.isAbsolute(value);
+      return /^(YARN_|COREPACK_|npm_config_|DYLD_|TSGO_)/i.test(key);
+    }))
+    fail('workspace-execution-environment-unsupported');
+  const launch=windowsLaunch([yarn,'--version']);
+  const version=spawnSync(launch.file,launch.args,{cwd:root,env:process.env,
+    ...launch.options,
+    encoding:'utf8',timeout:3000,maxBuffer:1024*1024,stdio:['ignore','pipe','pipe']});
+  if(version.error||version.signal||version.status!==0||
+    `yarn@${version.stdout.trim()}`!==pkg.packageManager)
+    fail('yarn-toolchain-unavailable');
+  const distribution=yarnDistribution(yarn,version.stdout.trim());
+  const contextFacts={yarnVersion:version.stdout.trim(),yarnShim:digestFile(yarn),
+    yarnLoader:digestFile(distribution.loader),
+    yarnDistribution:digestFile(distribution.distribution),node:process.version};
+  const contextHash=hash(JSON.stringify(contextFacts));
+  if(contextOnly(contextHash))process.exit(0);
+  const contract=yarnWorkspaceTypecheckInputs(root,workspace,script);
+  const cwd=path.join(root,contract.workspace.dir);
+  const tsc=yarnLocalTsc(root);
+  const captured=process.argv.includes('--redue-checkpoint')?compilerFiles(path.join(root,'node_modules/typescript'),cwd):null;
+  const listed=captured?{status:0,stdout:captured.files.join('\n')}:spawnSync(process.execPath,[tsc,'-p','.','--listFilesOnly'],
+    {cwd,env:process.env,encoding:'utf8',timeout:4000,maxBuffer:16*1024*1024,
+      stdio:['ignore','pipe','pipe']});
+  if(listed.error||listed.signal||listed.status!==0)fail('typescript-input-list-unavailable');
+  const inputs=listed.stdout.trim().split(/\r?\n/).filter(Boolean)
+    .map(file=>realObservedPath(file));
+  if(!inputs.length)fail('typescript-input-list-unavailable');
+  const selectedRoot=path.join(cwd,'src'),installedRoot=path.join(root,'node_modules');
+  const nestedInstalled=[contract.workspace,...contract.closure]
+    .map(member=>path.join(root,member.dir,'node_modules'));
+  const generated=contract.generated.map(value=>path.join(root,value.slice(0,-3)));
+  for(const file of inputs){
+    const covered=within(file,installedRoot)||nestedInstalled.some(dir=>within(file,dir))||
+      within(file,selectedRoot)||
+      generated.some(dir=>within(file,dir));
+    if(!covered||!within(file,root))fail('typescript-input-outside-workspace-contract');
+  }
+  const files=[...new Set(inputs)].sort().map(file=>
+    [hash(path.relative(root,file)),digestFile(file)]);
+  const configs=contract.configs.map(file=>[hash(file),digestFile(path.join(root,file))]);
+  probeResult(hash(JSON.stringify({schema:1,workspace,script,
+    files,configs,yarnVersion:version.stdout.trim(),yarnShim:digestFile(yarn),
+    yarnLoader:digestFile(distribution.loader),
+    yarnDistribution:digestFile(distribution.distribution),
+    node:process.version,tsc:digestFile(tsc)})),contextHash,captured?.queries);
+}catch(e){console.error(`VSTATE_REASON:${e.code&&/^[a-z-]+$/.test(e.code)?e.code:
+  'workspace-typecheck-contract-unavailable'}`);process.exitCode=2;}