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

package/src/decision-profile.mjs

@@ -0,0 +1,18 @@
+// Opt-in, bounded local diagnostics. Never include paths, command arguments,
+// environment values, source, or probe output in a timing record.
+import fs from 'node:fs';
+
+const file=process.env.REDUE_DECISION_PROFILE_FILE;
+export const profiling=process.env.REDUE_DECISION_PROFILE==='1'&&!!file;
+
+export function timing(phase,started,counts={}) {
+  if(!profiling)return;
+  const memory=process.memoryUsage();
+  try{fs.appendFileSync(file,'REDUE_TIMING '+JSON.stringify({
+      at:Date.now(),pid:process.pid,phase,
+      ms:Math.round((performance.now()-started)*10)/10,
+      rssMiB:Math.round(memory.rss/1048576*10)/10,
+      ...counts
+    })+'\n');}
+  catch{/* Diagnostics must never change probe or verification behavior. */}
+}

package/src/decision-validation.mjs

@@ -0,0 +1,41 @@
+// Deterministic reuse keys for already-resolved plans. These are not receipts
+// or a second content cache: the existing InputIndex still reads current bytes
+// and membership. A changed key falls back to provider discovery.
+import fs from 'node:fs';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import micromatch from './glob.mjs';
+import {sha} from './plan.mjs';
+
+export function inputKey(row) {
+  return sha(JSON.stringify([row.plan.id,row.files.size,row.sum.toString('hex')]));
+}
+export function planGuard(bundle) {
+  const root=bundle.root;
+  const paths=new Set(['package.json','package-lock.json','.npmrc','.yarnrc.yml',
+    'pnpm-workspace.yaml','.pnpmfile.cjs','.pnpmfile.mjs',
+    ...bundle.workspaceManifests||[],...bundle.configurationInputs||[],
+    ...Object.values(bundle.plans).flatMap(plan=>plan.resolutionTriggers||[])]);
+  const patterns=bundle.workspacePatterns?.length?bundle.workspacePatterns:
+    (()=>{const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json')));
+      return Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages||[];})();
+  if(patterns.length){
+    const files=execFileSync('git',['ls-files','--cached','--others','--exclude-standard',
+      '-z','--',':(glob)**/package.json'],{cwd:root,
+      env:{...process.env,GIT_OPTIONAL_LOCKS:'0'},timeout:5000,maxBuffer:32*1024*1024})
+      .toString().split('\0').filter(Boolean);
+    for(const file of files)if(micromatch.isMatch(path.posix.dirname(file),patterns,{dot:true}))
+      paths.add(file);
+  }
+  const values=[...paths].sort().map(rel=>{
+    const file=path.isAbsolute(rel)?rel:path.join(root,rel);
+    try{const st=fs.lstatSync(file,{bigint:true});
+      if(st.isSymbolicLink())return [rel,'link',fs.readlinkSync(file)];
+      if(st.isDirectory())return [rel,'directory',String(st.dev),String(st.ino)];
+      if(!st.isFile())throw Error('unobservable plan dependency');
+      return [rel,sha(fs.readFileSync(file))];
+    }catch(e){if(e.code==='ENOENT')return [rel,'missing'];throw e;}
+  });
+  const rootStat=fs.statSync(root,{bigint:true});
+  return sha(JSON.stringify([String(rootStat.dev),String(rootStat.ino),values]));
+}

package/src/declared-plan.mjs

@@ -0,0 +1,125 @@
+// A single-project plan. Declarations are explicit;
+// this provider does not infer complete coverage from a successful command.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {permittedRoots,resolveDeclaredInstalled} from './installed-inputs.mjs';
+import {qualifyTypeScript} from './typescript-qualification.mjs';
+import {yarnWorkspaceTypecheckInputs} from './yarn-workspace-inputs.mjs';
+import {pnpmTypecheckInputs} from './pnpm-inputs.mjs';
+import {observedRelative,withinPath,realObservedPath} from './path-identity.mjs';
+import {timing} from './decision-profile.mjs';
+
+const identity=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const safePattern=value=>{
+  if(typeof value!=='string'||!value)throw Error('input pattern must be nonempty');
+  const raw=value.startsWith('!')?value.slice(1):value;
+  if(!raw||path.isAbsolute(raw)||raw.split(/[\\/]/).includes('..'))
+    throw Error(`unsafe repository-relative input pattern: ${value}`);
+  return value;
+};
+
+export function discoverDeclared(config) {
+  const root=realObservedPath(config.root),plans={},configurationInputs=new Set(),
+    workspaceManifests=new Set(),workspacePatterns=new Set();
+  if(!Array.isArray(config.checks)||!config.checks.length)throw Error('selected checks required');
+  for(const selected of config.checks){
+    if(typeof selected.name!=='string'||!selected.name||plans[selected.name])
+      throw Error('check names must be unique nonempty strings');
+    if(!Array.isArray(selected.command)||!selected.command.length||
+      !selected.command.every(item=>typeof item==='string'&&item))
+      throw Error(`exact command required for ${selected.name}`);
+    const cwd=path.resolve(root,selected.cwd||'.');
+    if(!withinPath(cwd,root))throw Error('check cwd escapes checkout');
+    for(const key of ['inputs','generatedInputs','installedInputs']){
+      if(!Array.isArray(selected[key]||[]))throw Error(`${key} must be a path-pattern array`);
+      for(const value of selected[key]||[])safePattern(value);
+    }
+    if(!selected.inputs?.some(value=>!value.startsWith('!')))
+      throw Error(`positive source inputs required for ${selected.name}`);
+    for(const argv of selected.probes||[])if(!Array.isArray(argv)||!argv.length||
+      !argv.every(value=>typeof value==='string'&&value))
+      throw Error('state probes must be exact nonempty argv arrays');
+    if(!Array.isArray(selected.environment?.variables||[])||
+      !(selected.environment?.variables||[]).every(value=>typeof value==='string'&&value))
+      throw Error('environment variables must be a string array');
+    if(!Array.isArray(selected.environment?.prefixes||[])||
+      !(selected.environment?.prefixes||[]).every(value=>
+        typeof value==='string'&&/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)))
+      throw Error('environment prefixes must be simple nonempty names');
+    if(!Array.isArray(selected.environment?.pathExecutables||[])||
+      !(selected.environment?.pathExecutables||[]).every(value=>
+        typeof value==='string'&&/^[A-Za-z_][A-Za-z0-9_-]*$/.test(value)))
+      throw Error('PATH executables must be simple command names');
+    const allowedRoots=permittedRoots(root,selected.allowedExternalRoots||[]);
+    let workspace=null,workspaceIssue=null;
+    const workspaceStarted=performance.now();
+    if(selected.qualification==='yarn-workspace-tsc-v1'){
+      try{workspace=yarnWorkspaceTypecheckInputs(root,selected.workspace,
+        selected.command[4]);}
+      catch(e){workspaceIssue=e.message;}
+    }
+    if(selected.qualification==='pnpm-tsc-v1'){
+      try{workspace=pnpmTypecheckInputs(root,selected.workspace||'.',
+        selected.script||selected.command.at(-1));}
+      catch(e){workspaceIssue=e.message;}
+    }
+    timing('plan.workspace_inputs',workspaceStarted,{available:workspace?1:0});
+    const installedStarted=performance.now();
+    const installed=resolveDeclaredInstalled(root,
+      [...(selected.installedInputs||[]),...(workspace?.installed||[])],allowedRoots);
+    timing('plan.installed_resolution',installedStarted,{mappings:installed.mappings.length});
+    const automatic=qualifyTypeScript(root,selected,
+      {workspace,issue:workspaceIssue});
+    const sourcePatterns=[...new Set([...selected.inputs,...(workspace?.source||[]),
+      ...(workspace?.generated||[])])].sort();
+    const additivePatterns=[...new Set([...(selected.generatedInputs||[]),
+      ...installed.internalPatterns])].sort();
+    const unresolved=[...installed.unresolved,...(automatic?.issues||[]),
+      ...(workspace?.limitations||[]),
+      ...(workspaceIssue?[workspaceIssue]:[])];
+    for(const item of workspace?.configurationInputs||[])configurationInputs.add(item);
+    for(const item of workspace?.workspacePatterns||[])workspacePatterns.add(item);
+    for(const item of workspace?.closure||[])workspaceManifests.add(item.manifest);
+    if(!automatic)for(const category of ['source','generated','installedDependencies',
+      'environment','toolchain','runtime'])if(!selected.coverage?.[category])
+      unresolved.push(selected.coverageReasons?.[category]||
+        `${category} coverage not reviewed for this command`);
+    if((selected.probes||[]).length&&!automatic&&!selected.coverage?.probeContinuity)
+      unresolved.push('probe state continuity during execution not established');
+    const installedPhysicalRoots=[...new Set(installed.physicalRoots
+      .filter(file=>withinPath(file,root)&&observedRelative(root,file)!=='')
+      .map(file=>observedRelative(root,file)))].sort();
+    const externalPatterns=installed.externalPatterns;
+    const plan={name:selected.name,provider:'declared-project@1',inputResolutionVersion:1,
+      root,cwd,selectedConfigHash:identity(selected),command:selected.command,
+      target:selected.name,taskCommand:null,taskGraph:[],
+      patterns:[...new Set([...sourcePatterns,...additivePatterns])].sort(),
+      sourcePatterns,additivePatterns,generated:[],
+      declaredGeneratedInputs:[...new Set([...(selected.generatedInputs||[]),
+        ...(workspace?.generated||[])])].sort(),
+      declaredInstalledInputs:[...new Set([...(selected.installedInputs||[]),
+        ...(workspace?.installed||[])])].sort(),
+      installation:workspace?.installation||null,
+      ...(workspace?.synchronizedInstalledRead?{synchronizedInstalledRead:true}:{}),
+      installedInstances:workspace?.installedInstances||[],
+      resolutionCandidates:[],resolutionFindings:workspace?.absences||[],
+      installedPhysicalRoots,externalPatterns,
+      externalObservationRoots:Object.keys(externalPatterns).sort(),
+      resolutionLinks:installed.links,
+      resolutionTriggers:[...new Set([...installed.triggers,
+        ...(workspace?.linkTriggers||[]),
+        ...(workspace?.resolutionCandidates||[]).map(row=>row.path)])],
+      installedMappings:installed.mappings,effectiveEnvironmentGlobs:{},
+      probes:selected.probes||[],environment:selected.environment||{},
+      qualification:selected.qualification||null,
+      executionProvenance:'declared-command',
+      unresolved:[...new Set(unresolved)].sort()};
+    plan.resolutionCandidates=workspace?.resolutionCandidates||[];
+    plan.id=identity(plan);plans[selected.name]=plan;
+  }
+  return {schema:1,provider:'declared-project@1',root,plans,discoveredAt:Date.now(),
+    workspaceCount:1,workspacePatterns:[...workspacePatterns],
+    configurationInputs:[...configurationInputs].sort(),
+    workspaceManifests:[...workspaceManifests].sort()};
+}

package/src/executable-lookup.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Resolve the same project-local PATH that will be used for execution. Windows
+// command shims have no extension in package scripts but normally end in .cmd.
+export function findExecutable(name,{platform=process.platform,env=process.env,
+  cwd=process.cwd(),paths=path,access=fs.accessSync,realpath=fs.realpathSync}={}) {
+  if(!name||paths.basename(name)!==name)return null;
+  // An extensionless POSIX shell shim can coexist with npm.cmd on Windows.
+  // CreateProcess cannot run the shell shim, so prefer native PATHEXT files.
+  const suffixes=platform==='win32'&&!paths.extname(name)?
+    [...(env.PATHEXT||'.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean),'']:[''];
+  for(const folder of (env.PATH||'').split(paths.delimiter))for(const suffix of suffixes) {
+    const candidate=paths.join(folder||cwd,name+suffix);
+    try{access(candidate,fs.constants.X_OK);return realpath(candidate);}catch{}
+  }
+  return null;
+}

package/src/glob.mjs

@@ -0,0 +1,9 @@
+import picomatch from 'picomatch';
+
+// These are the exact delegates used by micromatch 4.0.8 matcher/isMatch,
+// with the same pinned picomatch 2.3.2. REDUE does not use brace expansion;
+// importing the smaller dependency avoids shipping its unused vulnerable parser.
+export default {
+  matcher(pattern,options){return picomatch(pattern,options);},
+  isMatch(file,patterns,options){return picomatch(patterns,options)(file);}
+};

package/src/history-worker.mjs

@@ -0,0 +1,18 @@
+// Native history is an optional acceleration. Keep its operations off the
+// control thread so a wedged native call cannot block status or shutdown.
+import fs from 'node:fs';
+import watcher from '@parcel/watcher';
+
+try {
+  const [root,previous,next,backend,faultFile]=process.argv.slice(2);
+  let fault;
+  try {fault=faultFile&&fs.readFileSync(faultFile,'utf8').trim();}
+  catch(e){if(e.code!=='ENOENT')throw e;}
+  if(fault==='hang')Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0);
+  if(fault==='fail')throw Error('injected history failure');
+  await watcher.writeSnapshot(root,next,{backend});
+  const changes=previous?await watcher.getEventsSince(root,previous,{backend}):[];
+  process.send({ok:true,changes});
+} catch(error) {
+  process.send({ok:false,error:error.message,code:error.code||error.name});
+}

package/src/index.mjs

@@ -0,0 +1,306 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import micromatch from './glob.mjs';
+import {sha} from './plan.mjs';
+import {resolveLinks} from './installed-inputs.mjs';
+import {validInputRelative} from './path-identity.mjs';
+
+const tracked = root => [...new Set(execFileSync('git',
+  ['ls-files','--cached','--others','--exclude-standard','-z'],
+  {cwd:root,env:{...process.env,GIT_OPTIONAL_LOCKS:'0'},maxBuffer:64*1024*1024})
+  .toString().split('\0').filter(Boolean))];
+const xor = (left,right) => { for(let i=0;i<32;i++) left[i]^=right[i]; };
+const token = (file,hash) => createHash('sha256').update(file+'\0'+hash).digest();
+const stablePrefix = glob => {
+  const parts=glob.replace(/^!/, '').split('/'), fixed=[];
+  for(const p of parts) { if(/[?*[{(]/.test(p)) break; fixed.push(p); }
+  // An exact file is its own scan root. Scanning its parent could enumerate an
+  // entire ignored installation tree for one declared metadata file.
+  return fixed.join('/');
+};
+const groupMatchers = patterns => {
+  const groups=new Map();
+  for(const pattern of patterns) {
+    const prefix=stablePrefix(pattern);
+    if(!groups.has(prefix))groups.set(prefix,[]);
+    groups.get(prefix).push(micromatch.matcher(pattern,{dot:true}));
+  }
+  return groups;
+};
+const pathPrefixes = rel => {
+  const parts=rel.split('/'), prefixes=[''];
+  for(let i=1;i<=parts.length;i++)prefixes.push(parts.slice(0,i).join('/'));
+  return prefixes;
+};
+
+function fileHash(root, rel,installed=false,before=fs.lstatSync(path.join(root,rel),
+  {bigint:true})) {
+  const file=path.join(root, rel);
+  let value,references=[],bytes=Number(before.size);
+  if(before.isSymbolicLink()){
+    const resolution=resolveLinks(file,root,[],true);
+    if(!resolution.physical)throw Error(`symlink input target observation unavailable: ${rel}: ${resolution.reason}`);
+    const target=fs.statSync(resolution.physical,{bigint:true});
+    if(!target.isFile())throw Error(`directory input symlink unsupported: ${rel}`);
+    value='link:'+JSON.stringify(resolution.links)+':'+target.mode+':'+
+      (installed&&target.nlink>1?target.nlink+':':'')+
+      hashRegular(resolution.physical).hash;
+    references=[...new Set([...resolution.links.map(link=>path.relative(root,link.path)
+      .split(path.sep).join('/')),path.relative(root,resolution.physical)
+      .split(path.sep).join('/')])];
+    bytes=Number(target.size);
+    const targetAfter=fs.statSync(resolution.physical,{bigint:true});
+    for(const key of ['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'])
+      if(target[key]!==targetAfter[key])throw Error(`input changed during inspection: ${rel}`);
+    const resolutionAfter=resolveLinks(file,root,[],true);
+    if(resolutionAfter.physical!==resolution.physical||
+      JSON.stringify(resolutionAfter.links)!==JSON.stringify(resolution.links))
+      throw Error(`input link changed during inspection: ${rel}`);
+  }
+  else if(before.isFile()) value='file:'+before.mode+':'+
+    (installed&&before.nlink>1?before.nlink+':':'')+hashRegular(file).hash;
+  else throw Error(`non-file input: ${rel}`);
+  const after=fs.lstatSync(file,{bigint:true});
+  for(const key of ['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'])
+    if(before[key]!==after[key]) throw Error(`input changed during inspection: ${rel}`);
+  return {hash:sha(value),references,bytes};
+}
+const readBuffer=Buffer.allocUnsafe(65536);
+function hashRegular(file) {
+  const h=createHash('sha256'), fd=fs.openSync(file,'r');
+  try { let n; while((n=fs.readSync(fd,readBuffer,0,readBuffer.length,null))>0)
+    h.update(readBuffer.subarray(0,n)); }
+  finally { fs.closeSync(fd); }
+  return {hash:h.digest('hex')};
+}
+
+export class InputIndex {
+  constructor(bundle, options={}) {
+    const matcherStarted=performance.now();
+    this.bundle=bundle; this.root=bundle.root; this.files=new Map(); this.members=new Map();
+    this.symlinkRefs=new Map();this.aliasDependencies=new Map();
+    this.trackGit=options.trackGit!==false;
+    this.installedRoots=[...new Set(Object.values(bundle.plans).flatMap(plan=>
+      plan.installedPhysicalRoots||[]))];
+    this.installedRootSet=new Set(this.installedRoots);
+    this.installedAncestors=new Set(this.installedRoots.flatMap(pathPrefixes));
+    this.includeInstalled=options.includeInstalled||false;
+    this.checks=new Map(); this.prefixes=new Map(); this.eventCount=0; this.rehashedFiles=0;
+    this.rehashedBytes=0; this.lastChange=0; this.unavailable=null;
+    this.profile={matcherMs:0,trackedMs:0,enumerationMs:0,matchingMs:0,
+      hashingMs:0,recordMs:0,enumeratedEntries:0};
+    for(const [name,plan] of Object.entries(bundle.plans)) {
+      const source=plan.sourcePatterns||plan.patterns;
+      const positive=source.filter(p=>!p.startsWith('!'));
+      const negative=source.filter(p=>p.startsWith('!')).map(p=>p.slice(1));
+      const additivePositive=(plan.additivePatterns||[]).filter(p=>!p.startsWith('!'));
+      const additiveNegative=(plan.additivePatterns||[]).filter(p=>p.startsWith('!'))
+        .map(p=>p.slice(1));
+      const row={plan,positive:groupMatchers(positive),negative:groupMatchers(negative),
+        additivePositive:groupMatchers(additivePositive),
+        additiveNegative:groupMatchers(additiveNegative),
+        files:new Set(),sum:Buffer.alloc(32),revision:0,lastReason:null,probeHash:null,probeAt:0};
+      this.checks.set(name,row);
+      for(const p of [...positive,...additivePositive]) {
+        const prefix=stablePrefix(p);
+        if(!this.prefixes.has(prefix)) this.prefixes.set(prefix,new Set());
+        this.prefixes.get(prefix).add(name);
+      }
+    }
+    this.profile.matcherMs=performance.now()-matcherStarted;
+  }
+  candidates(rel) {
+    const names=new Set(this.prefixes.get('')||[]);
+    const parts=rel.split('/');
+    for(let i=1;i<=parts.length;i++)
+      for(const name of this.prefixes.get(parts.slice(0,i).join('/'))||[]) names.add(name);
+    return names;
+  }
+  matches(row,rel) { const started=performance.now(), prefixes=pathPrefixes(rel);
+    const any=(groups)=>prefixes.some(prefix=>(groups.get(prefix)||[]).some(fn=>fn(rel)));
+    const result=(any(row.positive) && !any(row.negative))||
+      (any(row.additivePositive)&&!any(row.additiveNegative));
+    this.profile.matchingMs+=performance.now()-started;return result; }
+  installedPath(rel) {
+    if(this.includeInstalled||this.installedAncestors.has(rel))return true;
+    for(let slash=rel.length;slash>0;slash=rel.lastIndexOf('/',slash-1)){
+      if(this.installedRootSet.has(rel.slice(0,slash)))return true;
+      if(slash===0)break;
+    }
+    return false;
+  }
+  fingerprint(name) {
+    const row=this.checks.get(name);
+    return sha(row.plan.id+'\0'+row.files.size+'\0'+row.sum.toString('hex')+'\0'+(row.probeHash||''));
+  }
+  async recheckInstalled(names) {
+    const selected=new Set(names),started=performance.now();
+    let files=0,bytes=0;
+    for(const rel of [...this.files.keys()]){
+      if(!this.installedPath(rel)||![...this.members.get(rel)||[]]
+        .some(name=>selected.has(name)))continue;
+      const before=this.rehashedBytes;
+      this.record(rel,rel+' changed');
+      if(this.unavailable)throw Error(this.unavailable);
+      files++;bytes+=this.rehashedBytes-before;
+      if(files%32===0)await new Promise(resolve=>setImmediate(resolve));
+    }
+    return {files,bytes,durationMs:performance.now()-started};
+  }
+  summary(name) { const row=this.checks.get(name); return {fingerprint:this.fingerprint(name),
+    revision:row.revision,planId:row.plan.id,files:row.files.size,probeAt:row.probeAt}; }
+  record(rel, changeReason=rel+' changed', observedStat=null) {
+    if(!validInputRelative(rel)) {
+      this.unavailable='invalid event path'; return false;
+    }
+    const names=this.candidates(rel), old=this.files.get(rel), matched=[];
+    for(const name of names) if(this.matches(this.checks.get(name),rel)) matched.push(name);
+    if(!matched.length && old===undefined) return false;
+    let fresh,stat,inspection;
+    try{stat=observedStat||fs.lstatSync(path.join(this.root,rel),{bigint:true});}
+    catch(e){if(e.code!=='ENOENT'){this.unavailable=String(e);return false;}}
+    if(stat&&(stat.isFile()||stat.isSymbolicLink())) {
+      const installed=this.installedPath(rel);
+      try{const started=performance.now();inspection=fileHash(this.root,rel,installed,stat);
+        fresh=inspection.hash;
+        this.profile.hashingMs+=performance.now()-started;
+        this.rehashedFiles++;this.rehashedBytes+=inspection.bytes;}
+      catch(e){this.unavailable=String(e);return false;}
+    } else if(stat){this.unavailable=`non-file input: ${rel}`;return false;}
+    for(const reference of this.aliasDependencies.get(rel)||[]){
+      const aliases=this.symlinkRefs.get(reference);
+      aliases?.delete(rel);if(aliases?.size===0)this.symlinkRefs.delete(reference);
+    }
+    this.aliasDependencies.delete(rel);
+    if(inspection?.references.length){
+      this.aliasDependencies.set(rel,new Set(inspection.references));
+      for(const reference of inspection.references){
+        if(!this.symlinkRefs.has(reference))this.symlinkRefs.set(reference,new Set());
+        this.symlinkRefs.get(reference).add(rel);
+      }
+    }
+    const oldNames=this.members.get(rel)||new Set(), newNames=new Set(fresh===undefined?[]:matched);
+    if(old===fresh && oldNames.size===newNames.size && [...oldNames].every(n=>newNames.has(n))) return false;
+    for(const name of new Set([...oldNames,...newNames])) {
+      const row=this.checks.get(name);
+      if(oldNames.has(name) && old!==undefined) {xor(row.sum,token(rel,old));row.files.delete(rel);}
+      if(newNames.has(name) && fresh!==undefined) {xor(row.sum,token(rel,fresh));row.files.add(rel);}
+      row.revision++;row.lastReason=changeReason;
+    }
+    if(fresh!==undefined && newNames.size) {this.files.set(rel,fresh);this.members.set(rel,newNames);}
+    else {this.files.delete(rel);this.members.delete(rel);}
+    if(old!==fresh || oldNames.size!==newNames.size) {
+      this.eventCount++;this.lastChange=Date.now();return true;
+    }
+    return false;
+  }
+  scanSubtree(rel) {
+    const found=new Set(), roots=new Set();
+    // Directory notifications can name only an ancestor of an exact input.
+    // Revisit matching declared roots without traversing unrelated siblings.
+    if([...this.prefixes.keys()].some(prefix=>!prefix||prefix===rel||rel.startsWith(prefix+'/')))
+      roots.add(rel);
+    for(const prefix of this.prefixes.keys())
+      if(!rel||prefix.startsWith(rel+'/'))roots.add(prefix);
+    const visit=(file,r)=>{
+      let st;try{st=fs.lstatSync(file);}catch(e){if(e.code==='ENOENT')return;throw e;}
+      if(st.isDirectory()) {
+        if(r && (path.posix.basename(r)==='.git'||
+          (path.posix.basename(r)==='node_modules'&&!this.installedPath(r)))&&
+          !this.prefixes.has(r)) return;
+        for(const entry of fs.readdirSync(file,{withFileTypes:true}))
+          visit(path.join(file,entry.name),r?r+'/'+entry.name:entry.name);
+      } else if(!found.has(r)) {found.add(r);this.record(r);}
+    };
+    for(const root of roots) {
+      const base=path.join(this.root,root);
+      let present=true;
+      try{fs.lstatSync(base);}catch(e){if(e.code==='ENOENT')present=false;else throw e;}
+      if(present)visit(base,root);
+    }
+    for(const old of [...this.files.keys()]) if((old===rel||old.startsWith(rel+'/'))&&!found.has(old)) this.record(old);
+  }
+  coldScan(progress) {
+    this.unavailable=null;
+    const trackedStarted=performance.now();
+    const names=new Set(this.trackGit?tracked(this.root):[]);
+    this.profile.trackedMs+=performance.now()-trackedStarted;
+    const enumerationStarted=performance.now();
+    // Traverse declared input roots to include ignored/generated inputs. Avoid unrelated
+    // node_modules/.git trees unless a pattern explicitly names them.
+    const roots=[...this.prefixes.keys()].filter(prefix=>prefix||!this.trackGit)
+      .sort((a,b)=>a.length-b.length);
+    const selected=[], selectedSet=new Set();
+    for(const prefix of roots) {
+      const parts=prefix.split('/');
+      if(parts.some((_,i)=>selectedSet.has(parts.slice(0,i+1).join('/'))))continue;
+      selected.push(prefix);selectedSet.add(prefix);
+    }
+    let scanned=0,processingMs=0;
+    for(const prefix of selected) {
+      const base=path.join(this.root,prefix);
+      const visit=(file,rel)=>{
+        this.profile.enumeratedEntries++;
+        let st;try{st=fs.lstatSync(file,{bigint:true});}
+        catch(e){if(e.code==='ENOENT')return;throw e;}
+        if(st.isDirectory()) {
+          if((path.posix.basename(rel)==='.git'||
+            (path.posix.basename(rel)==='node_modules'&&!this.installedPath(rel))) &&
+            !this.prefixes.has(rel))return;
+          for(const ent of fs.readdirSync(file,{withFileTypes:true}))
+            visit(path.join(file,ent.name),rel?rel+'/'+ent.name:ent.name);
+        } else {
+          names.delete(rel);
+          const started=performance.now();
+          if(this.candidates(rel).size)this.record(rel,'cold reconciliation',st);
+          processingMs+=performance.now()-started;
+          scanned++;
+          if(progress&&scanned%256===0)progress({scanned,total:null});
+        }
+      };
+      let st;try{st=fs.lstatSync(base,{bigint:true});}
+      catch(e){if(e.code==='ENOENT')continue;throw e;}
+      if(st.isSymbolicLink()) {
+        try{if(fs.statSync(base).isDirectory()){
+          this.unavailable=`glob rooted at directory symlink unsupported: ${prefix}`;continue;}}
+        catch(e){if(e.code!=='ENOENT')throw e;}
+      }
+      visit(base,prefix);
+    }
+    this.profile.enumerationMs+=performance.now()-enumerationStarted-processingMs;
+    const recordStarted=performance.now();
+    for(const rel of names) {
+      if(this.candidates(rel).size)this.record(rel,'cold reconciliation');
+      scanned++;
+      if(progress&&scanned%256===0)progress({scanned,total:null});
+    }
+    if(progress)progress({scanned,total:scanned});
+    this.profile.recordMs+=processingMs+performance.now()-recordStarted;
+  }
+  updatePath(rel) {
+    const full=path.join(this.root,rel);
+    let subtree=false;
+    try {
+      if(fs.lstatSync(full).isSymbolicLink()&&fs.statSync(full).isDirectory()){
+        this.unavailable=`directory symlink input unsupported: ${rel}`;return;}
+      if(fs.statSync(full).isDirectory()) {this.scanSubtree(rel);subtree=true;}
+      else this.record(rel);
+    } catch(e) {
+      if(e.code==='ENOENT') {
+        if([...this.files.keys()].some(p=>p.startsWith(rel+'/'))) {
+          this.scanSubtree(rel);subtree=true;}
+        else this.record(rel);
+      } else {this.unavailable=String(e);}
+    }
+    const aliases=new Set(this.symlinkRefs.get(rel)||[]);
+    if(subtree)for(const [reference,names] of this.symlinkRefs)
+      if(reference.startsWith(rel+'/'))for(const name of names)aliases.add(name);
+    for(const alias of aliases)if(alias!==rel)this.record(alias,`${rel} changed`);
+  }
+  exportFiles(name) { const row=this.checks.get(name), out={};
+    for(const file of row.files) out[file]=this.files.get(file);
+    return out;
+  }
+}

package/src/installed-inputs.mjs

@@ -0,0 +1,110 @@
+// Declared installed-input paths, link resolution, and permitted observation roots.
+// Physical contents and membership are observed separately by InputIndex.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {normalizedPath,samePath,withinPath as within,realObservedPath} from './path-identity.mjs';
+
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const posix=file=>file.split(path.sep).join('/');
+export function resolveLinks(file,checkout,allowedRoots=[],allowFile=false) {
+  const roots=[checkout,...allowedRoots],links=[],seen=new Set();
+  let candidate=normalizedPath(file);
+  for(let depth=0;depth<40;depth++){
+    let current=path.parse(candidate).root,redirected=false;
+    const parts=candidate.slice(current.length).split(path.sep).filter(Boolean);
+    for(let i=0;i<parts.length;i++){
+      current=path.join(current,parts[i]);
+      let st;try{st=fs.lstatSync(current);}catch(e){
+        return {physical:null,links,prospective:candidate,
+          reason:e.code==='ENOENT'?'resolved target missing':
+          `resolution unavailable: ${e.code||e.name}`};}
+      if(!st.isSymbolicLink()){
+        // NTFS may spell an existing component as RUNNER~1 or its long name.
+        // Normalize that component without skipping a later reparse point.
+        if(process.platform==='win32')current=fs.realpathSync.native(current);
+        continue;
+      }
+      if(!roots.some(root=>within(current,root)))
+        return {physical:null,links,reason:'link redirect outside observed roots'};
+      if([...seen].some(previous=>samePath(previous,current)))
+        return {physical:null,links,reason:'symlink cycle'};
+      seen.add(current);
+      const target=fs.readlinkSync(current),signature=hash(target);
+      links.push({path:current,targetHash:signature});
+      candidate=normalizedPath(path.resolve(path.dirname(current),target,...parts.slice(i+1)));
+      redirected=true;break;
+    }
+    if(redirected)continue;
+    candidate=current;
+    if(!roots.some(root=>within(candidate,root)))
+      return {physical:null,links,reason:'resolved target outside permitted roots'};
+    let st;try{st=fs.statSync(candidate);}catch(e){
+      return {physical:null,links,reason:e.code==='ENOENT'?'resolved target missing':
+        `resolution unavailable: ${e.code||e.name}`};}
+    if(!st.isDirectory()&&!(allowFile&&st.isFile()))
+      return {physical:null,links,reason:'resolved input has unsupported type'};
+    return {physical:candidate,links,reason:null};
+  }
+  return {physical:null,links,reason:'symlink resolution depth exceeded'};
+}
+
+export function permittedRoots(root,values=[]) {
+  const allowed=[];
+  for(const value of values) {
+    if(typeof value!=='string'||!path.isAbsolute(value))
+      throw Error('external observation root must be absolute');
+    const real=realObservedPath(value);
+    if([path.parse(real).root,os.homedir()].includes(real)||within(root,real))
+      throw Error('external observation root is too broad');
+    if(!within(real,root))allowed.push(real);
+  }
+  return [...new Set(allowed)];
+}
+
+export function resolveDeclaredInstalled(root,patterns,allowed=[]) {
+  const result={internalPatterns:[],externalPatterns:{},links:[],triggers:[],
+    unresolved:[],mappings:[],physicalRoots:[]};
+  const internal=new Set(),external=new Map(),links=new Map(),triggers=new Set(),roots=new Set();
+  for(const pattern of patterns||[]) {
+    const negative=pattern.startsWith('!'),raw=negative?pattern.slice(1):pattern;
+    // Exclusions must also apply at the logical link location. The mapped
+    // physical exclusion alone cannot stop a broad installed-tree scan from
+    // trying to hash a workspace directory symlink as a file.
+    if(negative)internal.add(pattern);
+    const parts=raw.split('/'),fixed=[];
+    for(const part of parts){if(/[?*[{(]/.test(part))break;fixed.push(part);}
+    if(!fixed.length){internal.add(pattern);continue;}
+    const prefix=fixed.join('/'),suffix=parts.slice(fixed.length).join('/'),
+      logical=path.join(root,prefix);
+    const resolved=resolveLinks(logical,root,allowed,!suffix);
+    for(const link of resolved.links){links.set(link.path,link);
+      if(within(link.path,root))triggers.add(posix(path.relative(root,link.path)));}
+    if(!resolved.physical){
+      if(resolved.reason==='resolved target missing'&&!resolved.links.length){
+        internal.add(pattern);continue;}
+      result.unresolved.push(`${prefix}: ${resolved.reason}`);continue;
+    }
+    const boundary=within(resolved.physical,root)?root:
+      allowed.find(allowedRoot=>within(resolved.physical,allowedRoot));
+    if(!boundary){result.unresolved.push(`${prefix}: resolved target outside permitted roots`);continue;}
+    if(boundary!==root&&resolved.physical===boundary){
+      result.unresolved.push(`${prefix}: external target needs a stable permitted parent root`);continue;}
+    const rel=posix(path.relative(boundary,resolved.physical));
+    const directory=fs.statSync(resolved.physical).isDirectory();
+    const mapped=(negative?'!':'')+(suffix?(rel?rel+'/':'')+suffix:
+      directory?(rel?rel+'/**':'**/*'):rel);
+    if(boundary===root)internal.add(mapped);
+    else {if(!external.has(boundary))external.set(boundary,new Set());
+      external.get(boundary).add(mapped);}
+    if(!negative)roots.add(resolved.physical);
+    result.mappings.push({logical:pattern,physical:resolved.physical,root:boundary,
+      links:resolved.links.map(link=>link.path)});
+  }
+  result.internalPatterns=[...internal].sort();
+  result.externalPatterns=Object.fromEntries([...external].map(([key,values])=>[key,[...values].sort()]));
+  result.links=[...links.values()].sort((a,b)=>a.path.localeCompare(b.path));
+  result.triggers=[...triggers].sort();result.physicalRoots=[...roots].sort();
+  return result;
+}