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

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,52 @@
+// 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}.`);
+    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');
+}

package/src/probe-result.mjs

@@ -0,0 +1,21 @@
+// 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;
+}
+export function probeResult(output,context,queries=null) {
+  if(!process.argv.includes('--redue-checkpoint')){process.stdout.write(output);return;}
+  const raw=queries?JSON.stringify(queries):null;
+  let value=JSON.stringify({output,context,queryData:raw&&Buffer.byteLength(raw)<=8*1024*1024?
+    deflateSync(raw).toString('base64'):null});
+  // 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/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/state-store.mjs

@@ -0,0 +1,37 @@
+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.schema!==STATE_SCHEMA||!value.checks||typeof value.checks!=='object')
+    throw Error(`incompatible receipt state in ${state}; inspect or remove only this vstate state directory`);
+  return 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});
+  // 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);
+}

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)}));