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

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

package/src/linux-inotify.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Linux-only inotify transport. Emits paths and continuity faults, never file data.
+
+Unlike the pinned Parcel inotify backend, IN_Q_OVERFLOW is reported. The Node
+engine owns all content inspection and deterministic reconciliation.
+"""
+import ctypes
+import errno
+import json
+import os
+import re
+import select
+import struct
+import sys
+import time
+
+IN_MODIFY = 0x00000002
+IN_ATTRIB = 0x00000004
+IN_CLOSE_WRITE = 0x00000008
+IN_MOVED_FROM = 0x00000040
+IN_MOVED_TO = 0x00000080
+IN_CREATE = 0x00000100
+IN_DELETE = 0x00000200
+IN_DELETE_SELF = 0x00000400
+IN_MOVE_SELF = 0x00000800
+IN_UNMOUNT = 0x00002000
+IN_Q_OVERFLOW = 0x00004000
+IN_IGNORED = 0x00008000
+IN_ISDIR = 0x40000000
+FILE_MASK = IN_MODIFY | IN_ATTRIB | IN_CLOSE_WRITE | IN_DELETE_SELF | IN_MOVE_SELF
+MASK = (IN_MODIFY | IN_ATTRIB | IN_CLOSE_WRITE | IN_MOVED_FROM |
+        IN_MOVED_TO | IN_CREATE | IN_DELETE | IN_DELETE_SELF |
+        IN_MOVE_SELF | IN_UNMOUNT)
+HEADER = struct.Struct('iIII')
+LOCAL_FILESYSTEMS = {'ext2', 'ext3', 'ext4', 'xfs', 'btrfs', 'f2fs',
+                     'tmpfs', 'zfs'}
+
+
+def emit(kind, **fields):
+    print(json.dumps({'kind': kind, **fields}, ensure_ascii=True), flush=True)
+
+
+def filesystem_type(folder):
+    best = ('', None)
+    with open('/proc/self/mountinfo', encoding='utf-8') as mounts:
+        for line in mounts:
+            before, after = line.rstrip('\n').split(' - ', 1)
+            point = re.sub(r'\\([0-7]{3})', lambda m: chr(int(m[1], 8)),
+                           before.split()[4])
+            if (folder == point or folder.startswith(point.rstrip('/') + '/')) \
+                    and len(point) > len(best[0]):
+                best = (point, after.split()[0])
+    return best[1]
+
+
+def main(root):
+    root = os.path.realpath(root)
+    if filesystem_type(root) not in LOCAL_FILESYSTEMS:
+        emit('gap', reason='inotify_filesystem_untrusted')
+        return 2
+    libc = ctypes.CDLL(None, use_errno=True)
+    libc.inotify_init1.argtypes = [ctypes.c_int]
+    libc.inotify_init1.restype = ctypes.c_int
+    libc.inotify_add_watch.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_uint32]
+    libc.inotify_add_watch.restype = ctypes.c_int
+    libc.inotify_rm_watch.argtypes = [ctypes.c_int, ctypes.c_int]
+    libc.inotify_rm_watch.restype = ctypes.c_int
+    fd = libc.inotify_init1(os.O_NONBLOCK | os.O_CLOEXEC)
+    if fd < 0:
+        raise OSError(ctypes.get_errno(), 'inotify_init1 failed')
+    watches = {}
+    file_watches = {}
+    file_paths = {}
+    intentional_removals = set()
+
+    def add_tree(folder):
+        stack = [folder]
+        while stack:
+            current = stack.pop()
+            wd = libc.inotify_add_watch(fd, os.fsencode(current), MASK)
+            if wd < 0:
+                raise OSError(ctypes.get_errno(), 'inotify_add_watch failed')
+            watches[wd] = current
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    if entry.is_dir(follow_symlinks=False):
+                        stack.append(entry.path)
+
+    def drain():
+        while True:
+            try:
+                block = os.read(fd, 65536)
+            except BlockingIOError:
+                return True
+            if not block:
+                emit('gap', reason='inotify_closed')
+                return False
+            offset = 0
+            while offset < len(block):
+                wd, mask, _, length = HEADER.unpack_from(block, offset)
+                offset += HEADER.size
+                raw = block[offset:offset + length].split(b'\0', 1)[0]
+                offset += length
+                if mask & IN_Q_OVERFLOW:
+                    emit('gap', reason='inotify_overflow')
+                    return False
+                if wd in intentional_removals and mask & IN_IGNORED:
+                    intentional_removals.remove(wd)
+                    continue
+                if wd in file_watches:
+                    if mask & (IN_UNMOUNT | IN_DELETE_SELF | IN_MOVE_SELF | IN_IGNORED):
+                        emit('gap', reason='inotify_file_watch_lost')
+                        return False
+                    for watched in file_watches[wd]:
+                        emit('event', type='update', path=watched)
+                    continue
+                parent = watches.get(wd)
+                if parent is None:
+                    emit('gap', reason='inotify_watch_unknown')
+                    return False
+                target = os.path.join(parent, os.fsdecode(raw)) if raw else parent
+                if mask & (IN_UNMOUNT | IN_DELETE_SELF | IN_MOVE_SELF | IN_IGNORED):
+                    emit('gap', reason='inotify_watch_lost')
+                    return False
+                if (mask & IN_ISDIR) and (mask & (IN_CREATE | IN_MOVED_TO)):
+                    try:
+                        add_tree(target)
+                    except OSError as error:
+                        emit('gap', reason='inotify_watch_add_failed', errno=error.errno)
+                        return False
+                    # Contents can appear before their new directory receives
+                    # a watch. The engine reconciles instead of guessing.
+                    emit('gap', reason='inotify_new_directory')
+                    return False
+                if (mask & IN_ISDIR) and (mask & (IN_DELETE | IN_MOVED_FROM)):
+                    emit('gap', reason='inotify_directory_removed')
+                    return False
+                event = ('delete' if mask & (IN_DELETE | IN_MOVED_FROM) else
+                         'create' if mask & (IN_CREATE | IN_MOVED_TO) else 'update')
+                emit('event', type=event, path=target)
+
+    def replace_file_watches(paths):
+        requested = set(paths)
+        removed = False
+        for old in set(file_paths) - requested:
+            wd = file_paths.pop(old)
+            aliases = file_watches[wd]
+            aliases.remove(old)
+            if not aliases:
+                del file_watches[wd]
+                intentional_removals.add(wd)
+                libc.inotify_rm_watch(fd, wd)
+                removed = True
+        # Consume IN_IGNORED before adding new watches so a recycled watch
+        # descriptor cannot be mistaken for an intentionally removed one.
+        if removed and not drain():
+            return False
+        for added in requested - set(file_paths):
+            absolute = os.path.abspath(added)
+            if os.path.commonpath((root, absolute)) != root or \
+                    os.path.commonpath((root, os.path.realpath(absolute))) != root:
+                raise ValueError('installed watch escaped checkout')
+            wd = libc.inotify_add_watch(fd, os.fsencode(absolute), FILE_MASK)
+            if wd < 0:
+                raise OSError(ctypes.get_errno(), 'installed inotify_add_watch failed')
+            file_paths[added] = wd
+            file_watches.setdefault(wd, set()).add(added)
+        return True
+
+    try:
+        add_tree(root)
+        emit('ready', watches=len(watches))
+        stdin = b''
+        heartbeat = time.monotonic()
+        while True:
+            injected = os.environ.get('VSTATE_TEST_LINUX_GAP_FILE') if \
+                os.environ.get('VSTATE_TEST_FAULTS') == '1' else None
+            if injected and os.path.exists(injected):
+                with open(injected, encoding='utf-8') as source:
+                    reason = source.read(64).strip()
+                os.unlink(injected)
+                emit('gap', reason=reason if reason in
+                     ('inotify_overflow', 'inotify_watch_lost',
+                      'inotify_watch_add_failed') else 'inotify_test_gap')
+                return 2
+            readable, _, _ = select.select([fd, 0], [], [], 0.25)
+            if fd in readable and not drain():
+                return 2
+            if 0 in readable:
+                chunk = os.read(0, 4096)
+                if not chunk:
+                    return 0
+                stdin += chunk
+                while b'\n' in stdin:
+                    line, stdin = stdin.split(b'\n', 1)
+                    message = json.loads(line)
+                    if message.get('kind') == 'barrier':
+                        hang = os.environ.get('VSTATE_TEST_LINUX_HANG_FILE') if \
+                            os.environ.get('VSTATE_TEST_FAULTS') == '1' else None
+                        if hang and os.path.exists(hang):
+                            continue
+                        if not drain():
+                            return 2
+                        emit('barrier', id=message['id'])
+                    elif message.get('kind') == 'watch-files':
+                        try:
+                            if not replace_file_watches(message['paths']):
+                                return 2
+                        except (OSError, ValueError) as error:
+                            emit('gap', reason='inotify_file_watch_add_failed',
+                                 errno=getattr(error, 'errno', None))
+                            return 2
+                        if not drain():
+                            return 2
+                        emit('watched', id=message['id'], files=len(file_paths))
+            if time.monotonic() - heartbeat >= 1:
+                emit('heartbeat', watches=len(watches))
+                heartbeat = time.monotonic()
+    finally:
+        os.close(fd)
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main(sys.argv[1]))
+    except (OSError, ValueError, IndexError) as error:
+        emit('gap', reason='inotify_backend_error', errno=getattr(error, 'errno', None))
+        sys.exit(2)