@ttsc/unplugin 0.26.1 → 0.27.0

package/lib/core/transform.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var node_child_process = require('node:child_process');
 var crypto = require('node:crypto');
 var fs = require('node:fs');
 var os = require('node:os');
@@ -8,19 +9,58 @@ var ttsc = require('ttsc');
 var pathIdentity = require('ttsc/path-identity');
 var tsconfigPaths = require('./tsconfigPaths.js');
 
+const DEFAULT_FILESYSTEM_OPERATIONS = Object.freeze({
+    exists: fs.existsSync,
+    lstat: (location) => fs.lstatSync(location, { bigint: true }),
+    readFile: (location) => fs.readFileSync(location),
+    readdir: (location) => fs.readdirSync(location, { withFileTypes: true }),
+    realpath: fs.realpathSync.native,
+    stat: fs.statSync,
+    statBigInt: (location) => fs.statSync(location, { bigint: true }),
+});
+const TRANSFORM_CACHE_FILESYSTEM = new WeakMap();
+const TRANSFORM_RESULT_FILESYSTEM = new WeakMap();
 /**
  * Caches whose owner has declared a real per-build lifecycle by calling
  * {@link beginTtscTransformBuild} before transforms begin.
  */
 const BUILD_SCOPED_TRANSFORM_CACHES = new WeakSet();
-function createHostPathIdentityContext() {
+function createHostPathIdentityContext(filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
     return pathIdentity.createFilesystemPathIdentityContext({
+        caseSensitive: filesystem.caseSensitive,
+        lstat: filesystem.lstat,
+        platform: filesystem.platform,
+        readdir: (directory) => filesystem.readdir(directory).map((entry) => entry.name),
+        realpath: filesystem.realpath,
         throwOnRealpathError: false,
     });
 }
-/** Create an empty persistent transform cache. */
-function createTtscTransformCache() {
-    return new Map();
+/** Normalize one directory entry under the owning filesystem's case policy. */
+function normalizeHostInputName(name, caseSensitive) {
+    return caseSensitive ? name : name.toLowerCase();
+}
+/** Create an empty persistent transform cache with isolated filesystem reads. */
+function createTtscTransformCache(operations = {}) {
+    const cache = new Map();
+    TRANSFORM_CACHE_FILESYSTEM.set(cache, {
+        caseSensitive: operations.caseSensitive,
+        exists: operations.exists ?? DEFAULT_FILESYSTEM_OPERATIONS.exists,
+        lstat: operations.lstat ?? DEFAULT_FILESYSTEM_OPERATIONS.lstat,
+        readFile: operations.readFile ?? DEFAULT_FILESYSTEM_OPERATIONS.readFile,
+        readdir: operations.readdir ?? DEFAULT_FILESYSTEM_OPERATIONS.readdir,
+        realpath: operations.realpath ?? DEFAULT_FILESYSTEM_OPERATIONS.realpath,
+        stat: operations.stat ?? DEFAULT_FILESYSTEM_OPERATIONS.stat,
+        statBigInt: operations.statBigInt ?? DEFAULT_FILESYSTEM_OPERATIONS.statBigInt,
+        platform: operations.platform,
+    });
+    return cache;
+}
+function transformFilesystem(cache) {
+    return ((cache === undefined ? undefined : TRANSFORM_CACHE_FILESYSTEM.get(cache)) ??
+        DEFAULT_FILESYSTEM_OPERATIONS);
+}
+function resultFilesystem(result) {
+    return (TRANSFORM_RESULT_FILESYSTEM.get(result) ?? DEFAULT_FILESYSTEM_OPERATIONS);
 }
 /**
  * Start a host build, clearing its prior generation and enabling constant-time
@@ -31,7 +71,7 @@ function createTtscTransformCache() {
  * defines one process-scoped module-loading session.
  */
 function beginTtscTransformBuild(cache) {
-    cache.clear();
+    clearTtscTransformCache(cache);
     BUILD_SCOPED_TRANSFORM_CACHES.add(cache);
 }
 /**
@@ -42,9 +82,17 @@ function beginTtscTransformBuild(cache) {
  * many edits, so that callback cannot authorize build-scoped shortcuts.
  */
 function resetTtscTransformCache(cache) {
-    cache.clear();
+    clearTtscTransformCache(cache);
     BUILD_SCOPED_TRANSFORM_CACHES.delete(cache);
 }
+/** Dispose generation-owned filesystem resources before clearing a cache. */
+function clearTtscTransformCache(cache) {
+    const generations = [...cache.values()];
+    cache.clear();
+    for (const generation of generations) {
+        void generation.then(disposeCachedTransform, () => undefined);
+    }
+}
 /**
  * Apply the ttsc plugin transform to a single source file.
  *
@@ -70,6 +118,7 @@ function resetTtscTransformCache(cache) {
  *   per build, not per compilation.
  */
 async function transformTtsc(id, source, options, aliases, cache, hooks) {
+    const filesystem = transformFilesystem(cache);
     const clean = stripQuery(id);
     if (clean.includes("\0")) {
         return undefined;
@@ -81,7 +130,7 @@ async function transformTtsc(id, source, options, aliases, cache, hooks) {
     if (pluginsAreDisabled(options.plugins)) {
         return undefined;
     }
-    const tsconfig = resolveTsconfig(file, options.project);
+    const tsconfig = resolveTsconfig(file, options.project, filesystem);
     const aliasPaths = createAliasPaths(aliases);
     const key = createTransformCacheKey({
         aliasPaths,
@@ -95,11 +144,19 @@ async function transformTtsc(id, source, options, aliases, cache, hooks) {
             // A rejected in-flight generation must not stay cached: evict it (only if
             // it is still the current entry) so a later call re-runs the transform.
             const cached = await awaitOrEvict(cache, key, transformed);
+            TRANSFORM_RESULT_FILESYSTEM.set(cached.result, filesystem);
             // While this caller awaited the old Promise, another caller may have
             // invalidated it and installed a newer authoritative generation.
             if (cache?.get(key) !== transformed) {
                 continue;
             }
+            const buildScoped = cache !== undefined && BUILD_SCOPED_TRANSFORM_CACHES.has(cache);
+            if (!buildScoped) {
+                await settleProjectMutationEvents(cached);
+                if (cache?.get(key) !== transformed) {
+                    continue;
+                }
+            }
             if (
             // A file the plugin declared volatile must never be served from the
             // cache: its output depends on non-file inputs, so the input-hash
@@ -109,7 +166,7 @@ async function transformTtsc(id, source, options, aliases, cache, hooks) {
                 projectRoot: cached.projectRoot,
                 result: cached.result,
             }) &&
-                matchesCachedSource(cached, file, source, cache !== undefined && BUILD_SCOPED_TRANSFORM_CACHES.has(cache))) {
+                matchesCachedSource(cached, file, source, buildScoped)) {
                 reportSuccessDiagnostics(cached.result);
                 // A resolved `"exception"` / `"failure"` envelope makes this throw;
                 // that is a failed generation too, so evict before surfacing it.
@@ -142,7 +199,9 @@ async function transformTtsc(id, source, options, aliases, cache, hooks) {
                 compilerOptions: options.compilerOptions,
                 currentFile: file,
                 currentSource: source,
+                filesystem,
                 plugins: options.plugins,
+                trackProjectMembership: cache !== undefined,
                 tsconfig,
             });
             cache?.set(key, transformed);
@@ -209,8 +268,20 @@ function selectOrEvict(cache, key, generation, props) {
 function evictGeneration(cache, key, generation) {
     if (cache?.get(key) === generation) {
         cache.delete(key);
+        void generation.then(disposeCachedTransform, () => undefined);
     }
 }
+/** Close one generation's directory watchers exactly once. */
+function disposeCachedTransform(cached) {
+    const trackers = [
+        cached.projectMutationTracker,
+        cached.hostInputMutationTracker,
+    ];
+    cached.projectMutationTracker = undefined;
+    cached.hostInputMutationTracker = undefined;
+    for (const tracker of trackers)
+        tracker?.close();
+}
 /**
  * Derivation states keyed by the compiler result object. One result object is
  * produced by one compile against one project root, so the root captured at
@@ -224,7 +295,7 @@ function envelopeDerivation(props) {
         return existing;
     }
     const created = {
-        identityContext: createHostPathIdentityContext(),
+        identityContext: createHostPathIdentityContext(resultFilesystem(props.result)),
         identities: new Map(),
         watchInputs: new Map(),
     };
@@ -246,6 +317,9 @@ function envelopeGraphIndexes(state, props) {
         candidates: [],
         globals: [],
         configs: [],
+        members: new Set(),
+        inputProofs: new Map(),
+        inputProofConflicts: new Set(),
     };
     const graph = props.result.type === "exception" ? undefined : props.result.graph;
     if (graph !== undefined) {
@@ -255,23 +329,73 @@ function envelopeGraphIndexes(state, props) {
             }
             const absolute = path.resolve(props.projectRoot, source);
             const identity = derivationIdentity(state, absolute);
+            built.members.add(identity);
             built.spellings.set(identity, absolute);
             const entries = built.edges.get(identity) ?? [];
             entries.push(...targets
                 .filter((target) => typeof target === "string" && target.length !== 0)
-                .map((target) => path.resolve(props.projectRoot, target)));
+                .map((target) => {
+                const absoluteTarget = path.resolve(props.projectRoot, target);
+                built.members.add(derivationIdentity(state, absoluteTarget));
+                return absoluteTarget;
+            }));
             built.edges.set(identity, entries);
         }
         built.globals.push(...selectListedFiles(props.projectRoot, graph.globals));
         built.configs.push(...selectListedFiles(props.projectRoot, graph.configs));
+        for (const input of [...built.globals, ...built.configs]) {
+            built.members.add(derivationIdentity(state, input));
+        }
         for (const [source, candidates] of Object.entries(graph.candidates ?? {})) {
             if (!Array.isArray(candidates)) {
                 continue;
             }
+            const sourceIdentity = derivationIdentity(state, path.resolve(props.projectRoot, source));
+            built.members.add(sourceIdentity);
             built.candidates.push({
-                source: derivationIdentity(state, path.resolve(props.projectRoot, source)),
+                source: sourceIdentity,
                 files: selectListedFiles(props.projectRoot, candidates),
             });
+            for (const candidate of candidates) {
+                if (typeof candidate !== "string" || candidate.length === 0)
+                    continue;
+                built.members.add(derivationIdentity(state, path.resolve(props.projectRoot, candidate)));
+            }
+        }
+        for (const [input, hash] of Object.entries(graph.inputHashes ?? {})) {
+            if (hash !== null &&
+                (typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash))) {
+                continue;
+            }
+            if (graph.inputRealpaths === undefined ||
+                !Object.prototype.hasOwnProperty.call(graph.inputRealpaths, input)) {
+                continue;
+            }
+            const reportedRealpath = graph.inputRealpaths[input];
+            if (reportedRealpath !== null &&
+                (typeof reportedRealpath !== "string" ||
+                    !path.isAbsolute(reportedRealpath))) {
+                continue;
+            }
+            const absolute = path.resolve(props.projectRoot, input);
+            const identity = derivationIdentity(state, absolute);
+            if (!built.members.has(identity))
+                continue;
+            const proof = {
+                hash,
+                path: absolute,
+                realpath: reportedRealpath === null ? null : path.resolve(reportedRealpath),
+            };
+            const previous = built.inputProofs.get(identity);
+            if (previous !== undefined &&
+                (previous.hash !== proof.hash ||
+                    !sameHostInputRealpath(previous.realpath, proof.realpath, state.identityContext))) {
+                built.inputProofs.delete(identity);
+                built.inputProofConflicts.add(identity);
+            }
+            else if (!built.inputProofConflicts.has(identity)) {
+                built.inputProofs.set(identity, proof);
+            }
         }
     }
     state.graph = built;
@@ -372,29 +496,59 @@ function selectWatchInputs(props) {
 function deriveWatchInputs(state, props, fileIdentity) {
     const graph = envelopeGraphIndexes(state, props);
     const output = [];
-    const seen = new Set();
+    const physicalSeen = new Set();
+    const lexicalSeen = new Set();
     const excluded = new Set([fileIdentity]);
     if (props.temporaryTsconfig !== undefined) {
         excluded.add(derivationIdentity(state, props.temporaryTsconfig));
     }
-    for (const absolute of [
-        ...selectFileDependencies(props),
-        ...selectGraphInputs(graph, state, {
-            ...props,
-            complete: declaresCompleteDependencies(state, props) &&
-                !isVolatileFile(state, props),
-        }),
-        ...selectResolutionCandidateInputs(graph, state, props),
-    ]) {
-        const identity = derivationIdentity(state, absolute);
-        if (excluded.has(identity) || seen.has(identity)) {
-            continue;
+    const currentSpelling = path.resolve(props.file);
+    const temporarySpelling = props.temporaryTsconfig === undefined
+        ? undefined
+        : path.resolve(props.temporaryTsconfig);
+    const appendLexical = (input) => {
+        const spelling = path.resolve(input);
+        if (spelling === currentSpelling ||
+            spelling === temporarySpelling ||
+            lexicalSeen.has(spelling)) {
+            return;
         }
-        seen.add(identity);
-        output.push(absolute);
-    }
+        lexicalSeen.add(spelling);
+        physicalSeen.add(derivationIdentity(state, input));
+        output.push(input);
+    };
+    const appendPhysical = (input) => {
+        const identity = derivationIdentity(state, input);
+        if (excluded.has(identity) || physicalSeen.has(identity))
+            return;
+        physicalSeen.add(identity);
+        lexicalSeen.add(path.resolve(input));
+        output.push(input);
+    };
+    for (const input of selectFileDependencies(props))
+        appendLexical(input);
+    for (const input of selectGraphInputs(graph, state, {
+        ...props,
+        complete: declaresCompleteDependencies(state, props) &&
+            !isVolatileFile(state, props),
+    }))
+        appendPhysical(input);
+    // Resolution candidates, plugin dependencies, and universal host inputs
+    // preserve lexical aliases. Physical deduplication would collapse
+    // `alias/selection.cjs` into the selected target path, so a bundler would
+    // watch only the target and miss a symlink/junction retarget.
+    for (const input of selectResolutionCandidateInputs(graph, state, props))
+        appendLexical(input);
+    for (const input of selectHostInputs(props))
+        appendLexical(input);
     return output;
 }
+/** Return exact host-wide descriptor/config inputs for every output file. */
+function selectHostInputs(props) {
+    return props.result.type === "exception"
+        ? []
+        : selectListedFiles(props.projectRoot, props.result.hostInputs);
+}
 /**
  * Return the module-resolution paths that can supersede a currently resolved
  * module reachable from `file`. They remain host-owned even when a plugin
@@ -640,14 +794,13 @@ function createTransformResult(source, code) {
  *
  * Always compares the current module's in-memory source with the generation
  * snapshot. A cache whose owner called {@link beginTtscTransformBuild} can use
- * that comparison alone for the module's first delivery in the current build;
- * repeated requests re-hash every project and out-of-walk input. Persistent
- * caches with no guaranteed build boundary perform complete validation on every
- * hit. Any mismatch forces a complete re-transform.
- *
- * The complete validation snapshot and {@link collectInputHashes} draw their
- * keys from the exact same {@link collectProjectInputHashes} walk, so the two
- * agree on the key universe.
+ * that comparison alone for a stable generation's first module delivery in the
+ * current build. An incomplete generation may not take this shortcut: otherwise
+ * a sibling output captured during a filesystem race could still be served
+ * once. Later graph-bearing requests validate the file's derived input set and
+ * project membership; graph-free envelopes conservatively re-hash the complete
+ * project and out-of-walk snapshots. Any mismatch forces a complete
+ * re-transform.
  */
 function matchesCachedSource(cached, file, source, buildScoped) {
     const identities = envelopeDerivation(cached).identityContext;
@@ -656,12 +809,346 @@ function matchesCachedSource(cached, file, source, buildScoped) {
         return false;
     }
     if (buildScoped &&
+        cached.projectSnapshotComplete === true &&
         !cached.servedFiles?.has(pathIdentityKey(file, identities))) {
         return true;
     }
-    const currentHashes = collectProjectInputHashes(cached.projectRoot, identities);
-    currentHashes[currentKey] = hashText(source);
-    if (!sameHashes(cached.inputHashes, currentHashes)) {
+    if (cached.result.type !== "exception" &&
+        cached.result.graph !== undefined &&
+        cached.projectSnapshotComplete === true &&
+        cached.projectDirectories !== undefined &&
+        cached.projectMutationTracker !== undefined &&
+        cached.hostInputMutationTracker !== undefined) {
+        return matchesNarrowPersistentInputs(cached, file);
+    }
+    return matchesCompleteInputSnapshot(cached, currentKey, source);
+}
+/**
+ * Validate one graph-bearing cached output against only the inputs that can
+ * affect that file. Project membership is validated once per event-loop turn,
+ * so sibling module deliveries share one directory-metadata pass instead of
+ * multiplying it by module count.
+ */
+function matchesNarrowPersistentInputs(cached, file) {
+    if (!matchesProjectMembership(cached)) {
+        return false;
+    }
+    const hostTracker = cached.hostInputMutationTracker;
+    if (hostTracker === undefined ||
+        hostTracker.failed ||
+        hostTracker.membershipChanged) {
+        return false;
+    }
+    const state = envelopeDerivation(cached);
+    const hostValidation = state.hostInputValidation;
+    if (hostValidation === undefined ||
+        !matchesUniversalHostInputs(cached, hostValidation)) {
+        return false;
+    }
+    const inputs = selectWatchInputs({
+        file,
+        projectRoot: cached.projectRoot,
+        result: cached.result,
+        temporaryTsconfig: cached.temporaryTsconfig,
+    });
+    for (const input of inputs) {
+        if (hostValidation.identities.has(derivationIdentity(state, input))) {
+            continue;
+        }
+        if (!matchesRecordedInput(cached, input)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Validate universal descriptor/config inputs without re-reading them for every
+ * module. Existing paths use the same nanosecond metadata manifest that guards
+ * GOROOT identity memoization; missing probes are grouped by the nearest
+ * existing directory and checked through one exact membership listing.
+ */
+function matchesUniversalHostInputs(cached, validation) {
+    const filesystem = resultFilesystem(cached.result);
+    for (const entry of validation.entries.values()) {
+        const signature = inputMetadataSignature(entry.path, filesystem);
+        if (signature === entry.signature)
+            continue;
+        if (entry.strict === true)
+            return false;
+        if (hostInputRealpath(entry.path, filesystem) !== entry.realpath)
+            return false;
+        if (!matchesRecordedInput(cached, entry.path)) {
+            return false;
+        }
+        if (signature === undefined)
+            return false;
+        entry.signature = signature;
+    }
+    for (const [directory, names] of validation.missing) {
+        let entries;
+        try {
+            entries = filesystem.readdir(directory);
+        }
+        catch (error) {
+            // Only a provably absent/non-directory ancestor keeps every descendant
+            // unreachable. Permission and transient I/O failures cannot prove that
+            // a candidate is still missing, while replacing the proving directory
+            // with an exact file can itself redirect module resolution.
+            try {
+                if (!filesystem.stat(directory).isDirectory())
+                    return false;
+            }
+            catch (statError) {
+                if (!isMissingPathError(statError))
+                    return false;
+                continue;
+            }
+            return false;
+        }
+        const identities = envelopeDerivation(cached).identityContext;
+        const caseSensitive = identities.caseSensitive(directory);
+        if (entries.some((entry) => names.has(normalizeHostInputName(entry.name, caseSensitive)))) {
+            return false;
+        }
+    }
+    return true;
+}
+/** True only for errors that prove a path cannot currently be traversed. */
+function isMissingPathError(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** Capture the universal-input manifest while the generation is still fresh. */
+function captureUniversalHostInputValidation(cached, currentFile) {
+    const filesystem = resultFilesystem(cached.result);
+    const state = envelopeDerivation(cached);
+    const validation = {
+        entries: new Map(),
+        identities: new Set(),
+        missing: new Map(),
+    };
+    for (const input of selectPersistentHostInputs({
+        filesystem,
+        projectRoot: cached.projectRoot,
+        result: cached.result,
+        temporaryTsconfig: cached.temporaryTsconfig,
+    })) {
+        const generationHashes = cached.result.type === "exception"
+            ? undefined
+            : cached.result.hostInputHashes;
+        const generationRealpaths = cached.result.type === "exception"
+            ? undefined
+            : cached.result.hostInputRealpaths;
+        const expected = generationHashes?.[path.resolve(input)];
+        // Every persistent universal input must carry an evaluation-time
+        // fingerprint. If a plugin/native host cannot provide one, keep the fresh
+        // result but decline narrow long-lived reuse.
+        if (expected === undefined) {
+            const current = path.resolve(currentFile);
+            if (path.resolve(input) !== current)
+                return undefined;
+            // The current module may be supplied from an unsaved editor buffer. Its
+            // generation snapshot is overlaid below from `currentSource`, so a disk
+            // fingerprint would be both unavailable and the wrong authority.
+        }
+        else if (expected !== hostInputStateHash(input, filesystem)) {
+            return undefined;
+        }
+        const absoluteInput = path.resolve(input);
+        if (generationRealpaths !== undefined) {
+            if (!Object.prototype.hasOwnProperty.call(generationRealpaths, absoluteInput) ||
+                !sameHostInputRealpath(generationRealpaths[absoluteInput], hostInputRealpath(input, filesystem), state.identityContext)) {
+                return undefined;
+            }
+        }
+        const identity = derivationIdentity(state, input);
+        validation.identities.add(identity);
+        const before = inputMetadataSignature(input, filesystem);
+        if (!matchesRecordedInput(cached, input))
+            return undefined;
+        const after = inputMetadataSignature(input, filesystem);
+        if (before !== after)
+            return undefined;
+        if (after !== undefined) {
+            // Do not key this manifest by physical identity. A symlink/junction
+            // spelling and its selected target deliberately share that identity,
+            // but both lexical paths must survive so retargeting the alias is visible.
+            validation.entries.set(path.resolve(input), {
+                path: input,
+                realpath: hostInputRealpath(input, filesystem),
+                signature: after,
+            });
+            continue;
+        }
+        const probe = missingPathProbe(input, filesystem);
+        if (probe.blocker !== undefined) {
+            const blockerIdentity = derivationIdentity(state, probe.blocker);
+            const signature = inputMetadataSignature(probe.blocker, filesystem);
+            if (signature === undefined)
+                return undefined;
+            validation.identities.add(blockerIdentity);
+            validation.entries.set(path.resolve(probe.blocker), {
+                path: probe.blocker,
+                realpath: hostInputRealpath(probe.blocker, filesystem),
+                signature,
+                strict: true,
+            });
+            continue;
+        }
+        let names = validation.missing.get(probe.directory);
+        if (names === undefined) {
+            names = new Set();
+            validation.missing.set(probe.directory, names);
+        }
+        names.add(normalizeHostInputName(probe.name, state.identityContext.caseSensitive(probe.directory)));
+    }
+    state.hostInputValidation = validation;
+    return validation;
+}
+/** Metadata identity whose stability lets a generation reuse a content hash. */
+function inputMetadataSignature(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        const link = filesystem.lstat(file);
+        let target = link;
+        if (link.isSymbolicLink()) {
+            try {
+                target = filesystem.statBigInt(file);
+            }
+            catch {
+                // Keep a broken link in the existing-input manifest. Its own metadata
+                // stays stable while the target is missing, and the first successful
+                // stat after the target appears changes this signature. Treating it as
+                // a plain missing path would watch/list only the link's parent, which
+                // cannot observe a target created in another directory.
+                return [
+                    link.dev,
+                    link.ino,
+                    link.mode,
+                    link.size,
+                    link.mtimeNs,
+                    link.ctimeNs,
+                    "missing-target",
+                ].join(":");
+            }
+        }
+        return [
+            link.dev,
+            link.ino,
+            link.mode,
+            link.size,
+            link.mtimeNs,
+            link.ctimeNs,
+            target.dev,
+            target.ino,
+            target.mode,
+            target.size,
+            target.mtimeNs,
+            target.ctimeNs,
+        ].join(":");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Content/kind fingerprint matching the compiler host-input contract. */
+function hostInputStateHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        return hashText(filesystem.readFile(file));
+    }
+    catch {
+        try {
+            return filesystem.stat(file).isDirectory()
+                ? hashText("ttsc:host-input:directory\0")
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Fingerprint the text/kind state returned by TypeScript-Go's filesystem. */
+function graphInputStateHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        const bytes = filesystem.readFile(file);
+        if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+            const even = bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2);
+            return hashText(Buffer.from(even.toString("utf16le"), "utf8"));
+        }
+        if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+            const even = Buffer.from(bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2));
+            even.swap16();
+            return hashText(Buffer.from(even.toString("utf16le"), "utf8"));
+        }
+        const content = bytes.length >= 3 &&
+            bytes[0] === 0xef &&
+            bytes[1] === 0xbb &&
+            bytes[2] === 0xbf
+            ? bytes.subarray(3)
+            : bytes;
+        return hashText(content);
+    }
+    catch {
+        try {
+            return filesystem.stat(file).isDirectory()
+                ? hashText("ttsc:host-input:directory\0")
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Physical target selected by a lexical host-input path. */
+function hostInputRealpath(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        return filesystem.realpath(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare two reported realpaths by filesystem identity, not Windows spelling. */
+function sameHostInputRealpath(left, right, identities) {
+    if (left === undefined || (left === null) !== (right === null))
+        return false;
+    if (left === null || right === null)
+        return true;
+    return (pathIdentityKey(left, identities) === pathIdentityKey(right, identities));
+}
+/** Find one directory listing that proves an absent path is still absent. */
+function missingPathProbe(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    let child = path.resolve(file);
+    for (;;) {
+        const directory = path.dirname(child);
+        try {
+            const stats = filesystem.stat(directory);
+            if (stats.isDirectory()) {
+                return { directory, name: path.basename(child) };
+            }
+            return {
+                blocker: directory,
+                directory: path.dirname(directory),
+                name: path.basename(directory),
+            };
+        }
+        catch { }
+        if (directory === child) {
+            return { directory, name: path.basename(child) };
+        }
+        child = directory;
+    }
+}
+/** Fall back to the historical whole-envelope validation without a graph. */
+function matchesCompleteInputSnapshot(cached, currentKey, source) {
+    if (cached.projectSnapshotComplete !== true) {
+        return false;
+    }
+    const current = collectProjectInputSnapshot(cached.projectRoot, envelopeDerivation(cached).identityContext, resultFilesystem(cached.result));
+    if (!current.complete) {
+        return false;
+    }
+    current.hashes[currentKey] = hashText(source);
+    if (!sameHashes(cached.inputHashes, current.hashes)) {
         return false;
     }
     // Re-hash the out-of-walk inputs the compiler reported for this generation
@@ -673,32 +1160,127 @@ function matchesCachedSource(cached, file, source, buildScoped) {
     // requires a tsconfig or package manifest change, both of which the project
     // walk above already detects.
     const externalHashes = cached.externalInputHashes ?? {};
-    return sameHashes(externalHashes, collectExternalInputHashes(cached.externalInputPaths ?? Object.keys(externalHashes)));
+    return (sameHashes(externalHashes, collectCachedExternalInputHashes(cached)) &&
+        matchesExternalInputRealpaths(cached));
 }
-/** Record a successfully selected module as delivered by this generation. */
-function markCachedSourceServed(cached, file) {
-    (cached.servedFiles ??= new Set()).add(pathIdentityKey(file, envelopeDerivation(cached).identityContext));
+/** Re-check graph-owned physical identities in complete-snapshot fallback. */
+function matchesExternalInputRealpaths(cached) {
+    const expected = cached.externalInputRealpaths;
+    if (expected === undefined || Object.keys(expected).length === 0)
+        return true;
+    const state = envelopeDerivation(cached);
+    const filesystem = resultFilesystem(cached.result);
+    for (const input of cached.externalInputPaths ?? []) {
+        const identity = derivationIdentity(state, input);
+        if (!Object.prototype.hasOwnProperty.call(expected, identity))
+            continue;
+        if (!sameHostInputRealpath(expected[identity], hostInputRealpath(input, filesystem), state.identityContext)) {
+            return false;
+        }
+    }
+    return true;
 }
 /**
- * Build the input-hash snapshot stored alongside a fresh compiler result.
- *
- * Hashes every file under the project directory (the exact universe
- * {@link matchesCachedSource} re-hashes to validate), then overlays the
- * in-memory source for the module that triggered the compile so unsaved editor
- * content is captured correctly.
- *
- * Only the project's own files are hashed. Out-of-walk program inputs the
- * compiler also read (`node_modules` declarations, sibling-package sources) are
- * deliberately excluded: the validator never reproduces those keys, so keying
- * them here would make every snapshot comparison fail and the cache never hit.
+ * Capture external-input hashes without attaching post-compile state to an
+ * earlier graph. Graph members must carry compiler-time proof and still match
+ * it now; plugin-declared dependency-only paths retain the historical
+ * post-compile snapshot because their own protocol does not claim generation
+ * fingerprints.
  */
-function collectInputHashes(props) {
-    const identities = createHostPathIdentityContext();
-    const hashes = collectProjectInputHashes(props.projectRoot, identities);
-    // Overlay the in-memory source so unsaved edits invalidate the cache.
-    hashes[toProjectKey(props.projectRoot, props.currentFile, identities)] =
-        hashText(props.currentSource);
-    return hashes;
+function captureExternalInputSnapshot(cached, paths) {
+    const state = envelopeDerivation(cached);
+    const filesystem = resultFilesystem(cached.result);
+    const graph = envelopeGraphIndexes(state, cached);
+    const hashes = {};
+    const realpaths = {};
+    let complete = true;
+    for (const input of paths) {
+        const identity = derivationIdentity(state, input);
+        if (graph.members.has(identity)) {
+            const proof = graph.inputProofs.get(identity);
+            if (proof === undefined || graph.inputProofConflicts.has(identity)) {
+                complete = false;
+                continue;
+            }
+            const currentHash = graphInputStateHash(input, filesystem);
+            if (currentHash !== proof.hash ||
+                !sameHostInputRealpath(proof.realpath, hostInputRealpath(input, filesystem), state.identityContext)) {
+                complete = false;
+            }
+            hashes[identity] = proof.hash ?? "missing";
+            realpaths[identity] = proof.realpath;
+            continue;
+        }
+        hashes[identity] = hostInputStateHash(input, filesystem) ?? "missing";
+    }
+    return { complete, hashes, realpaths };
+}
+/** Verify every graph member still has the state read by the compiler. */
+function matchesCompilerGraphInputProofs(cached) {
+    if (cached.result.type === "exception" ||
+        cached.result.graph === undefined ||
+        (cached.result.graph.inputHashes === undefined &&
+            cached.result.graph.inputRealpaths === undefined)) {
+        // Legacy sidecars remain compatible for ordinary in-project graphs. Their
+        // out-of-walk members are still rejected by captureExternalInputSnapshot,
+        // where a post-compile snapshot cannot prove the compiler's generation.
+        return true;
+    }
+    const state = envelopeDerivation(cached);
+    const filesystem = resultFilesystem(cached.result);
+    const graph = envelopeGraphIndexes(state, cached);
+    if (graph.inputProofConflicts.size !== 0 ||
+        graph.inputProofs.size !== graph.members.size) {
+        return false;
+    }
+    for (const identity of graph.members) {
+        const proof = graph.inputProofs.get(identity);
+        if (proof === undefined ||
+            graphInputStateHash(proof.path, filesystem) !== proof.hash ||
+            !sameHostInputRealpath(proof.realpath, hostInputRealpath(proof.path, filesystem), state.identityContext)) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Compare one derived input with the snapshot that owned it at generation. */
+function matchesRecordedInput(cached, input) {
+    const state = envelopeDerivation(cached);
+    const filesystem = resultFilesystem(cached.result);
+    const projectKey = toProjectKey(cached.projectRoot, input, state.identityContext);
+    const projectHash = Object.prototype.hasOwnProperty.call(cached.inputHashes, projectKey)
+        ? cached.inputHashes[projectKey]
+        : undefined;
+    const identity = derivationIdentity(state, input);
+    const externalHash = (cached.externalInputHashes ?? {})[identity];
+    const externalRealpaths = cached.externalInputRealpaths;
+    const graphInput = externalRealpaths !== undefined &&
+        Object.prototype.hasOwnProperty.call(externalRealpaths, identity);
+    if (externalRealpaths !== undefined &&
+        Object.prototype.hasOwnProperty.call(externalRealpaths, identity) &&
+        !sameHostInputRealpath(externalRealpaths[identity], hostInputRealpath(input, filesystem), state.identityContext)) {
+        return false;
+    }
+    // Prefer the out-of-walk spelling's own snapshot when it exists. A lexical
+    // alias can point back into the walked project, where the physical target's
+    // project hash is a different authority (and graph text uses BOM decoding).
+    const recorded = externalHash ?? projectHash;
+    if (recorded === undefined) {
+        return false;
+    }
+    try {
+        const current = graphInput
+            ? graphInputStateHash(input, filesystem)
+            : hostInputStateHash(input, filesystem);
+        return recorded === (current ?? "missing");
+    }
+    catch {
+        return recorded === "missing";
+    }
+}
+/** Record a successfully selected module as delivered by this generation. */
+function markCachedSourceServed(cached, file) {
+    (cached.servedFiles ??= new Set()).add(pathIdentityKey(file, envelopeDerivation(cached).identityContext));
 }
 /**
  * Hash every input file under `projectRoot` (the same walk universe
@@ -706,18 +1288,42 @@ function collectInputHashes(props) {
  * slash path. Exported so hosts without a per-build boundary (`@ttsc/metro`)
  * can fold the identical input universe into their own cache fingerprints.
  */
-function collectProjectInputHashes(projectRoot, identities = createHostPathIdentityContext()) {
+function collectProjectInputHashes(projectRoot, identities = createHostPathIdentityContext(), filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    return collectProjectInputSnapshot(projectRoot, identities, filesystem)
+        .hashes;
+}
+/** Hash project files and snapshot the directory topology in one walk. */
+function collectProjectInputSnapshot(projectRoot, identities, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
     const hashes = {};
-    for (const file of listProjectInputFiles(projectRoot)) {
+    const fileSignatures = {};
+    const walked = walkProjectInputs(projectRoot, filesystem);
+    let complete = walked.complete;
+    for (const file of walked.files) {
         try {
-            hashes[toProjectKey(projectRoot, file, identities)] = hashText(fs.readFileSync(file));
+            const before = inputMetadataSignature(file, filesystem);
+            const contents = filesystem.readFile(file);
+            const after = inputMetadataSignature(file, filesystem);
+            const key = toProjectKey(projectRoot, file, identities);
+            hashes[key] = hashText(contents);
+            if (before === undefined || after === undefined || before !== after) {
+                complete = false;
+            }
+            else {
+                fileSignatures[key] = after;
+            }
         }
         catch {
             // File watchers may observe a transform while another process is moving
             // or deleting files. The missing key invalidates older cache entries.
+            complete = false;
         }
     }
-    return hashes;
+    return {
+        complete,
+        fileSignatures,
+        hashes,
+        projectDirectories: walked.directories,
+    };
 }
 /**
  * Enumerate every regular file under `root`, skipping well-known output and
@@ -727,18 +1333,39 @@ function collectProjectInputHashes(projectRoot, identities = createHostPathIdent
  * unbounded call-stack depth on deep project trees. The result is sorted so
  * that hash comparisons are deterministic across OS-level directory orderings.
  */
-function listProjectInputFiles(root) {
-    const out = [];
+function walkProjectInputs(root, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    let complete = true;
+    const directories = [];
+    const files = [];
     const stack = [root];
     while (stack.length !== 0) {
         const current = stack.pop();
+        const before = projectDirectorySignature(current, filesystem);
+        if (before === undefined) {
+            complete = false;
+            continue;
+        }
         let entries;
         try {
-            entries = fs.readdirSync(current, { withFileTypes: true });
+            entries = filesystem.readdir(current);
         }
         catch {
+            complete = false;
             continue;
         }
+        const after = projectDirectorySignature(current, filesystem);
+        if (after === undefined || before !== after) {
+            complete = false;
+        }
+        directories.push({
+            path: current,
+            // If membership moved during enumeration, force the next delivery to
+            // replace this generation instead of blessing a torn directory/file
+            // snapshot as stable.
+            signature: after !== undefined && before === after
+                ? after
+                : `unstable:${before}:${after ?? "missing"}`,
+        });
         for (const entry of entries) {
             if (isIgnoredProjectDirectory(entry.name)) {
                 continue;
@@ -748,29 +1375,329 @@ function listProjectInputFiles(root) {
                 stack.push(file);
             }
             else if (entry.isFile()) {
-                out.push(file);
+                files.push(file);
             }
         }
     }
-    out.sort();
-    return out;
+    directories.sort((left, right) => left.path.localeCompare(right.path));
+    files.sort();
+    return { complete, directories, files };
+}
+/** Return a cheap identity for one directory's immediate membership. */
+function projectDirectorySignature(directory, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        const stats = filesystem.statBigInt(directory);
+        if (!stats.isDirectory()) {
+            return undefined;
+        }
+        return [
+            stats.dev,
+            stats.ino,
+            stats.mode,
+            stats.size,
+            stats.mtimeNs,
+            stats.ctimeNs,
+        ].join(":");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Compare two deterministic project-directory membership snapshots. */
+function sameProjectDirectories(left, right) {
+    return (left.length === right.length &&
+        left.every((directory, index) => directory.path === right[index]?.path &&
+            directory.signature === right[index]?.signature));
+}
+/** Watch every walked directory for membership changes after generation. */
+async function createProjectMutationTracker(directories, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const tracker = {
+        close: () => undefined,
+        failed: false,
+        membershipChanged: false,
+    };
+    if (process.platform === "win32") {
+        await registerWindowsProjectMutationTracker(tracker, directories.map((directory) => ({ directory: directory.path })), false, filesystem);
+        return tracker;
+    }
+    const watchers = [];
+    tracker.close = () => {
+        for (const watcher of watchers)
+            watcher.close();
+        watchers.length = 0;
+    };
+    for (const directory of directories) {
+        try {
+            const watcher = fs.watch(directory.path, { persistent: false }, (eventType) => {
+                if (eventType === "rename")
+                    tracker.membershipChanged = true;
+            });
+            watcher.on("error", () => {
+                tracker.failed = true;
+            });
+            watchers.push(watcher);
+        }
+        catch {
+            tracker.failed = true;
+        }
+    }
+    return tracker;
+}
+/** Watch exact universal inputs, or their nearest existing parent if missing. */
+async function createHostInputMutationTracker(inputs, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const identities = createHostPathIdentityContext(filesystem);
+    const namesByDirectory = new Map();
+    for (const input of inputs) {
+        const absolute = path.resolve(input);
+        const probe = filesystem.exists(absolute)
+            ? { directory: path.dirname(absolute), name: path.basename(absolute) }
+            : missingPathProbe(absolute, filesystem);
+        const directoryIdentity = identities.resolve(probe.directory);
+        let location = namesByDirectory.get(directoryIdentity.key);
+        if (location === undefined) {
+            location = {
+                directory: directoryIdentity.path,
+                names: new Set(),
+            };
+            namesByDirectory.set(directoryIdentity.key, location);
+        }
+        location.names.add(normalizeHostInputName(probe.name, identities.caseSensitive(directoryIdentity.path)));
+    }
+    const locations = [...namesByDirectory.values()].map((location) => ({
+        directory: location.directory,
+        names: [...location.names],
+    }));
+    const tracker = {
+        close: () => undefined,
+        failed: false,
+        membershipChanged: false,
+    };
+    if (process.platform === "win32") {
+        await registerWindowsProjectMutationTracker(tracker, locations, true, filesystem);
+        return tracker;
+    }
+    const watchers = [];
+    tracker.close = () => {
+        for (const watcher of watchers)
+            watcher.close();
+        watchers.length = 0;
+    };
+    for (const location of locations) {
+        try {
+            const names = new Set(location.names);
+            const caseSensitive = identities.caseSensitive(location.directory);
+            const watcher = fs.watch(location.directory, { persistent: false }, (_eventType, filename) => {
+                const reported = filename === null
+                    ? null
+                    : normalizeHostInputName(String(filename), caseSensitive);
+                if (reported === null || names.has(reported)) {
+                    tracker.membershipChanged = true;
+                }
+            });
+            watcher.on("error", () => {
+                tracker.failed = true;
+            });
+            watchers.push(watcher);
+        }
+        catch {
+            tracker.failed = true;
+        }
+    }
+    return tracker;
+}
+let windowsProjectMutationBroker;
+/**
+ * Register directory watches in an isolated Windows process.
+ *
+ * Node's Windows fs-event backend can assert in native code when a watched
+ * temporary tree is deleted. Isolation turns that unrecoverable process abort
+ * into an ordinary broker exit and a conservative cache miss in the host.
+ */
+async function registerWindowsProjectMutationTracker(tracker, locations, allEvents, filesystem) {
+    const broker = getWindowsProjectMutationBroker();
+    const normalized = locations.map((location) => {
+        let directory;
+        try {
+            directory = filesystem.realpath(location.directory);
+        }
+        catch {
+            directory = path.resolve(location.directory);
+        }
+        return {
+            directory,
+            ...(location.names === undefined ? {} : { names: location.names }),
+        };
+    });
+    broker.pendingRegistrations += 1;
+    broker.child.ref();
+    broker.child.channel?.ref();
+    const id = broker.nextId++;
+    let resolveReady;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    broker.trackers.set(id, { ready: resolveReady, tracker });
+    tracker.close = () => {
+        const active = broker.trackers.get(id);
+        if (active === undefined)
+            return;
+        broker.trackers.delete(id);
+        active.ready();
+        broker.child.send?.({ id, op: "remove" });
+        if (broker.trackers.size === 0) {
+            broker.child.disconnect?.();
+            broker.child.kill();
+            if (windowsProjectMutationBroker === broker) {
+                windowsProjectMutationBroker = undefined;
+            }
+        }
+    };
+    broker.child.send?.({
+        allEvents,
+        locations: normalized,
+        id,
+        op: "add",
+    });
+    try {
+        await ready;
+    }
+    finally {
+        broker.pendingRegistrations -= 1;
+        if (broker.pendingRegistrations === 0) {
+            broker.child.unref();
+            broker.child.channel?.unref();
+        }
+    }
+}
+function getWindowsProjectMutationBroker() {
+    if (windowsProjectMutationBroker !== undefined) {
+        return windowsProjectMutationBroker;
+    }
+    const child = node_child_process.spawn(process.execPath, ["-e", WINDOWS_WATCH_BROKER_SOURCE], {
+        stdio: ["ignore", "ignore", "ignore", "ipc"],
+        windowsHide: true,
+    });
+    const broker = {
+        child,
+        nextId: 1,
+        pendingRegistrations: 0,
+        trackers: new Map(),
+    };
+    const fail = () => {
+        for (const registration of broker.trackers.values()) {
+            registration.tracker.failed = true;
+            registration.ready();
+        }
+        broker.trackers.clear();
+        if (windowsProjectMutationBroker === broker) {
+            windowsProjectMutationBroker = undefined;
+        }
+    };
+    child.on("error", fail);
+    child.on("exit", fail);
+    child.on("message", (message) => {
+        if (message === null || typeof message !== "object")
+            return;
+        const record = message;
+        if (typeof record.id !== "number")
+            return;
+        const registration = broker.trackers.get(record.id);
+        if (registration === undefined)
+            return;
+        if (record.failed === true)
+            registration.tracker.failed = true;
+        if (record.ready === true)
+            registration.ready();
+        if (record.ready !== true && record.failed !== true) {
+            registration.tracker.membershipChanged = true;
+        }
+    });
+    windowsProjectMutationBroker = broker;
+    return broker;
+}
+const WINDOWS_WATCH_BROKER_SOURCE = [
+    'const fs = require("node:fs");',
+    "const groups = new Map();",
+    'process.on("message", (message) => {',
+    '  if (message.op === "remove") {',
+    "    close(message.id);",
+    "    return;",
+    "  }",
+    '  if (message.op !== "add") return;',
+    "  const watchers = [];",
+    "  let failed = false;",
+    "  for (const location of message.locations) {",
+    "    try {",
+    "      const names = location.names === undefined ? undefined : new Set(location.names.map((name) => name.toLowerCase()));",
+    "      const watcher = fs.watch(location.directory, { persistent: false }, (event, filename) => {",
+    "        const matches = names === undefined || filename === null || names.has(String(filename).toLowerCase());",
+    '        if (matches && (message.allEvents || event === "rename")) process.send?.({ id: message.id });',
+    "      });",
+    '      watcher.on("error", () => process.send?.({ failed: true, id: message.id }));',
+    "      watchers.push(watcher);",
+    "    } catch {",
+    "      failed = true;",
+    "    }",
+    "  }",
+    "  groups.set(message.id, watchers);",
+    "  process.send?.({ failed, id: message.id, ready: true });",
+    "});",
+    'process.on("disconnect", () => {',
+    "  for (const id of groups.keys()) close(id);",
+    "  process.exit(0);",
+    "});",
+    "function close(id) {",
+    "  for (const watcher of groups.get(id) ?? []) watcher.close();",
+    "  groups.delete(id);",
+    "}",
+].join("\n");
+/** Report whether live directory notifications preserve project membership. */
+function matchesProjectMembership(cached) {
+    const tracker = cached.projectMutationTracker;
+    return (tracker !== undefined &&
+        tracker.failed === false &&
+        tracker.membershipChanged === false);
+}
+/**
+ * Yield once before persistent validation so synchronous edits can reach the
+ * directory watchers that guard membership. Concurrent sibling deliveries share
+ * the same barrier.
+ */
+async function settleProjectMutationEvents(cached) {
+    const trackers = [
+        cached.projectMutationTracker,
+        cached.hostInputMutationTracker,
+    ].filter((tracker) => tracker !== undefined);
+    await Promise.all(trackers.map(async (tracker) => {
+        tracker.settle ??= new Promise((resolve) => {
+            const settled = () => {
+                tracker.settle = undefined;
+                resolve();
+            };
+            if (process.platform === "win32")
+                setTimeout(settled, 10);
+            else
+                setImmediate(settled);
+        });
+        await tracker.settle;
+    }));
 }
 /**
  * Report whether an absolute `file` belongs to the project walk universe of
  * `root`: it lies under `root`, every component exists without traversing a
  * symbolic link, the leaf is a regular file, and no segment of the relative
- * path is ignored. The predicate mirrors {@link listProjectInputFiles} exactly,
- * so "walk-visible" here means "hashed by {@link collectProjectInputHashes}".
+ * path is ignored. The predicate mirrors {@link walkProjectInputs} exactly, so
+ * "walk-visible" here means "hashed by {@link collectProjectInputHashes}".
  * Missing paths and files reached through symlinks or Windows junctions are
  * out-of-walk inputs that only the reference graph can prove relevant.
  */
-function isProjectWalkPath(root, file, identities = createHostPathIdentityContext()) {
-    if (!identities.isWithin(root, file)) {
-        return false;
-    }
-    const rootKey = pathIdentityKey(root, identities);
-    const fileKey = pathIdentityKey(file, identities);
-    const relative = fileKey.slice(rootKey.length).replace(/^[/\\]+/, "");
+function isProjectWalkPath(root, file, _identities = createHostPathIdentityContext(), filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    // Walk membership is lexical. Resolving `file` to physical identity first
+    // would turn `root/alias/value.ts` into `root/target/value.ts`, hide the
+    // symlink segment from the lstat loop below, and falsely claim the project
+    // walk hashed a path it deliberately never followed.
+    const resolvedRoot = path.resolve(root);
+    const relative = path.relative(resolvedRoot, path.resolve(file));
     if (relative.length === 0 ||
         relative === ".." ||
         relative.startsWith(`..${path.sep}`) ||
@@ -781,12 +1708,12 @@ function isProjectWalkPath(root, file, identities = createHostPathIdentityContex
     if (segments.some(isIgnoredProjectDirectory)) {
         return false;
     }
-    let current = path.resolve(root);
+    let current = resolvedRoot;
     for (let index = 0; index < segments.length; ++index) {
         current = path.join(current, segments[index]);
         let stats;
         try {
-            stats = fs.lstatSync(current);
+            stats = filesystem.lstat(current);
         }
         catch {
             return false;
@@ -803,27 +1730,41 @@ function isProjectWalkPath(root, file, identities = createHostPathIdentityContex
 }
 /**
  * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
- * readable file, a stable `missing` marker otherwise. Keys use filesystem
- * identity so case-only spellings share one snapshot entry, while reads retain
- * the original path supplied by the compiler. The marker is state, not an error
- * — a recorded input disappearing (or reappearing) must change the comparison
- * exactly like a content edit. Exported so `@ttsc/metro` can re-hash its
- * recorded snapshot with identical semantics at cache-key time.
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * case-only spellings share one snapshot entry, while reads retain the original
+ * path supplied by the compiler. The marker is state, not an error — a recorded
+ * input disappearing (or reappearing) must change the comparison exactly like a
+ * content edit. Exported so `@ttsc/metro` can re-hash its recorded snapshot
+ * with identical semantics at cache-key time.
  */
-function collectExternalInputHashes(paths) {
+function collectExternalInputHashes(paths, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
     const hashes = {};
-    const identities = createHostPathIdentityContext();
+    const identities = createHostPathIdentityContext(filesystem);
     for (const file of paths) {
         const identity = pathIdentityKey(file, identities);
         if (identity in hashes) {
             continue;
         }
-        try {
-            hashes[identity] = hashText(fs.readFileSync(file));
-        }
-        catch {
-            hashes[identity] = "missing";
-        }
+        hashes[identity] = hostInputStateHash(file, filesystem) ?? "missing";
+    }
+    return hashes;
+}
+/** Re-hash a cached mixed graph/dependency input set with its owning codec. */
+function collectCachedExternalInputHashes(cached) {
+    const hashes = {};
+    const state = envelopeDerivation(cached);
+    const graphRealpaths = cached.externalInputRealpaths ?? {};
+    const filesystem = resultFilesystem(cached.result);
+    for (const file of cached.externalInputPaths ??
+        Object.keys(cached.externalInputHashes ?? {})) {
+        const identity = derivationIdentity(state, file);
+        if (identity in hashes)
+            continue;
+        hashes[identity] =
+            (Object.prototype.hasOwnProperty.call(graphRealpaths, identity)
+                ? graphInputStateHash(file, filesystem)
+                : hostInputStateHash(file, filesystem)) ?? "missing";
     }
     return hashes;
 }
@@ -836,21 +1777,19 @@ function collectExternalInputHashes(paths) {
  * that are still missing remain in this set even under the project root: the
  * first walk cannot hash a file that has not been created yet.
  *
- * A `dependenciesComplete` declaration deliberately does not narrow this set,
- * unlike the per-file watch derivation. This cache replays one whole envelope,
- * so its validity condition is the union over every file the envelope carries
- * rather than one file's inputs; a miss here costs a re-transform, never a
- * stale output; and it is the layer that re-runs the plugin's analysis, which
- * is how a widened declaration is ever learned. The narrowing that matters
- * lands at the bundler boundary through {@link selectWatchInputs}, which is what
- * feeds persistent caches and watch graphs.
+ * A `dependenciesComplete` declaration deliberately does not narrow the stored
+ * set: other files in the same whole-project result can still own the omitted
+ * members. Persistent validation selects the requested file's subset through
+ * {@link selectWatchInputs}, while graph-free envelopes use this union as their
+ * conservative fallback.
  */
 function selectExternalInputPaths(props) {
     if (props.result.type === "exception") {
         return [];
     }
     const members = [];
-    const identities = createHostPathIdentityContext();
+    const filesystem = props.filesystem ?? DEFAULT_FILESYSTEM_OPERATIONS;
+    const identities = createHostPathIdentityContext(filesystem);
     const resolutionCandidates = new Set();
     const graph = props.result.graph;
     if (graph !== undefined) {
@@ -884,6 +1823,17 @@ function selectExternalInputPaths(props) {
             members.push(...entries);
         }
     }
+    if (Array.isArray(props.result.hostInputs)) {
+        for (const input of props.result.hostInputs) {
+            members.push(input);
+            if (typeof input === "string" && input.length !== 0) {
+                // Plugin discovery inputs deliberately include absent config and
+                // resolution probes. A project walk cannot snapshot a path that does
+                // not exist yet, even when its spelling lies below projectRoot.
+                resolutionCandidates.add(pathIdentityKey(path.resolve(props.projectRoot, input), identities));
+            }
+        }
+    }
     const excluded = props.temporaryTsconfig === undefined
         ? undefined
         : pathIdentityKey(props.temporaryTsconfig, identities);
@@ -894,15 +1844,18 @@ function selectExternalInputPaths(props) {
             continue;
         }
         const absolute = path.resolve(props.projectRoot, member);
+        const spelling = path.resolve(absolute);
         const identity = pathIdentityKey(absolute, identities);
-        const missingCandidate = resolutionCandidates.has(identity) && !fs.existsSync(absolute);
+        const missingCandidate = resolutionCandidates.has(identity) && !filesystem.exists(absolute);
         if (identity === excluded ||
-            seen.has(identity) ||
+            seen.has(spelling) ||
             (!missingCandidate &&
-                isProjectWalkPath(props.projectRoot, absolute, identities))) {
+                isProjectWalkPath(props.projectRoot, absolute, identities, filesystem))) {
             continue;
         }
-        seen.add(identity);
+        // Preserve distinct lexical aliases even when they currently select the
+        // same physical file. A later retarget must validate the alias itself.
+        seen.add(spelling);
         output.push(absolute);
     }
     output.sort();
@@ -937,12 +1890,22 @@ function hashText(input) {
     return crypto.createHash("sha256").update(input).digest("hex");
 }
 async function transformProject(props) {
-    const configured = createTransformTsconfig(props);
     const projectRoot = path.dirname(props.tsconfig);
+    const scratchDirectory = createTransformScratchDirectory(projectRoot, props.filesystem);
+    let tracker;
+    let retainTracker = false;
+    let hostInputTracker;
     try {
-        const result = new ttsc.TtscCompiler({
+        const configured = createTransformTsconfig(props, scratchDirectory);
+        const temporaryTsconfig = configured.path === props.tsconfig ? undefined : configured.path;
+        const identities = createHostPathIdentityContext(props.filesystem);
+        const before = collectProjectInputSnapshot(projectRoot, identities, props.filesystem);
+        tracker = props.trackProjectMembership
+            ? await createProjectMutationTracker(before.projectDirectories, props.filesystem)
+            : undefined;
+        const result = withTransformScratchEnvironment(scratchDirectory, () => new ttsc.TtscCompiler({
             cwd: projectRoot,
-            // The generated tsconfig (if any) lives in the system temp directory,
+            // The generated tsconfig (if any) lives outside the project directory,
             // so declare the real project as the plugin config anchor: utility
             // plugin config discovery (banner.config.*, strip.config.*,
             // lint.config.*) and relative configFile resolution walk the project,
@@ -952,24 +1915,47 @@ async function transformProject(props) {
             plugins: props.plugins,
             projectRoot,
             tsconfig: configured.path,
-        }).transform();
-        const temporaryTsconfig = configured.path === props.tsconfig ? undefined : configured.path;
+            env: transformScratchEnvironment(scratchDirectory),
+        }).transform());
+        TRANSFORM_RESULT_FILESYSTEM.set(result, props.filesystem);
+        const persistentHostInputs = selectPersistentHostInputs({
+            filesystem: props.filesystem,
+            projectRoot,
+            result,
+            temporaryTsconfig,
+        });
+        hostInputTracker = props.trackProjectMembership
+            ? await createHostInputMutationTracker(persistentHostInputs, props.filesystem)
+            : undefined;
         const externalInputPaths = selectExternalInputPaths({
+            filesystem: props.filesystem,
             projectRoot,
             result,
             temporaryTsconfig,
         });
-        return {
+        const inputSnapshot = collectProjectInputSnapshot(projectRoot, identities, props.filesystem);
+        let stableProjectSnapshot = before.complete &&
+            inputSnapshot.complete &&
+            sameHashes(before.hashes, inputSnapshot.hashes) &&
+            sameHashes(before.fileSignatures, inputSnapshot.fileSignatures) &&
+            sameProjectDirectories(before.projectDirectories, inputSnapshot.projectDirectories) &&
+            tracker?.failed !== true &&
+            tracker?.membershipChanged !== true &&
+            hostInputTracker?.failed !== true &&
+            hostInputTracker?.membershipChanged !== true;
+        // Overlay the in-memory source only after proving the two on-disk snapshots
+        // stable; an unsaved editor buffer must not look like a compile-time race.
+        inputSnapshot.hashes[toProjectKey(projectRoot, props.currentFile, identities)] = hashText(props.currentSource);
+        const cached = {
             // Capture the out-of-walk input hashes while the generation is fresh so
             // cache validation can re-check them; computed before dispose so the
             // exclusion of the temp-dir tsconfig is the only reason it never keys.
-            externalInputHashes: collectExternalInputHashes(externalInputPaths),
+            externalInputHashes: {},
+            externalInputRealpaths: {},
             externalInputPaths,
-            inputHashes: collectInputHashes({
-                currentFile: props.currentFile,
-                currentSource: props.currentSource,
-                projectRoot,
-            }),
+            inputHashes: inputSnapshot.hashes,
+            projectDirectories: inputSnapshot.projectDirectories,
+            projectSnapshotComplete: false,
             projectRoot,
             result,
             servedFiles: new Set(),
@@ -978,40 +1964,186 @@ async function transformProject(props) {
             // but deleted file would invalidate every persistent-cache snapshot.
             ...(temporaryTsconfig === undefined ? {} : { temporaryTsconfig }),
         };
+        const externalInputSnapshot = captureExternalInputSnapshot(cached, externalInputPaths);
+        cached.externalInputHashes = externalInputSnapshot.hashes;
+        cached.externalInputRealpaths = externalInputSnapshot.realpaths;
+        stableProjectSnapshot =
+            stableProjectSnapshot &&
+                matchesCompilerGraphInputProofs(cached) &&
+                externalInputSnapshot.complete &&
+                captureUniversalHostInputValidation(cached, props.currentFile) !==
+                    undefined;
+        cached.projectSnapshotComplete = stableProjectSnapshot;
+        if (stableProjectSnapshot && tracker !== undefined) {
+            cached.projectMutationTracker = tracker;
+        }
+        if (stableProjectSnapshot && hostInputTracker !== undefined) {
+            cached.hostInputMutationTracker = hostInputTracker;
+        }
+        retainTracker =
+            stableProjectSnapshot &&
+                tracker !== undefined &&
+                hostInputTracker !== undefined;
+        return cached;
     }
     finally {
-        configured.dispose();
+        try {
+            if (!retainTracker && tracker !== undefined) {
+                tracker.close();
+            }
+        }
+        finally {
+            try {
+                if (!retainTracker && hostInputTracker !== undefined) {
+                    hostInputTracker.close();
+                }
+            }
+            finally {
+                fs.rmSync(scratchDirectory, { force: true, recursive: true });
+            }
+        }
     }
 }
-function createTransformTsconfig(props) {
+/** Exclude the disposed overlay tsconfig from live host-input tracking. */
+function selectPersistentHostInputs(props) {
+    if (props.result.type === "exception")
+        return [];
+    const inputs = selectListedFiles(props.projectRoot, props.result.hostInputs);
+    if (props.temporaryTsconfig === undefined)
+        return inputs;
+    const identities = createHostPathIdentityContext(props.filesystem);
+    const temporary = pathIdentityKey(props.temporaryTsconfig, identities);
+    return inputs.filter((input) => pathIdentityKey(input, identities) !== temporary);
+}
+function createTransformTsconfig(props, scratchDirectory) {
     const compilerOptions = normalizeCompilerOptionsForGeneratedTsconfig({
         ...props.compilerOptions,
         ...createAliasCompilerOptions(props),
     }, path.dirname(props.tsconfig));
     if (Object.keys(compilerOptions).length === 0) {
-        return {
-            path: props.tsconfig,
-            dispose: () => undefined,
-        };
+        return { path: props.tsconfig };
     }
-    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-unplugin-"));
-    const file = path.join(directory, "tsconfig.json");
+    const file = path.join(scratchDirectory, "tsconfig.json");
     fs.writeFileSync(file, JSON.stringify({
         extends: normalizePath(props.tsconfig),
         compilerOptions,
     }, null, 2), "utf8");
+    return { path: file };
+}
+/** Create compiler scratch storage outside the project snapshot and watchers. */
+function createTransformScratchDirectory(projectRoot, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const root = path.resolve(projectRoot);
+    const canonicalRoot = filesystem.realpath(root);
+    const platformTemp = process.platform === "win32" && process.env.LOCALAPPDATA
+        ? path.join(process.env.LOCALAPPDATA, "Temp")
+        : "/tmp";
+    const candidates = [
+        os.tmpdir(),
+        platformTemp,
+        path.dirname(root),
+        os.homedir(),
+    ];
+    const canonicalCandidates = new Set();
+    let failure;
+    for (const candidate of new Set(candidates.map((dir) => path.resolve(dir)))) {
+        if (pathIsWithin(candidate, root))
+            continue;
+        let canonicalCandidate;
+        try {
+            canonicalCandidate = filesystem.realpath(candidate);
+        }
+        catch (error) {
+            failure = error;
+            continue;
+        }
+        if (pathIsWithin(canonicalCandidate, canonicalRoot) ||
+            canonicalCandidates.has(canonicalCandidate)) {
+            continue;
+        }
+        canonicalCandidates.add(canonicalCandidate);
+        let directory;
+        try {
+            directory = fs.mkdtempSync(path.join(canonicalCandidate, "ttsc-unplugin-"));
+        }
+        catch (error) {
+            failure = error;
+            continue;
+        }
+        let canonicalDirectory;
+        try {
+            canonicalDirectory = filesystem.realpath(directory);
+        }
+        catch (error) {
+            try {
+                fs.rmdirSync(directory);
+            }
+            catch (cleanupError) {
+                throw cleanupError;
+            }
+            failure = error;
+            continue;
+        }
+        // Use the postflight canonical spelling from this point onward. Returning
+        // the candidate-relative spelling would let another process retarget its
+        // parent symlink/junction after validation, redirecting compiler writes or
+        // the final recursive removal into the project.
+        if (!pathIsWithin(canonicalDirectory, canonicalRoot)) {
+            return canonicalDirectory;
+        }
+        // Refuse the result and synchronously remove only our empty random child
+        // through the identity that the postflight check just classified.
+        fs.rmdirSync(canonicalDirectory);
+    }
+    throw (failure ??
+        new Error("ttsc: no temporary directory exists outside the project"));
+}
+function pathIsWithin(child, parent) {
+    const relative = path.relative(parent, child);
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+/** Route all compiler/plugin scratch to one owned directory outside project. */
+function transformScratchEnvironment(directory) {
     return {
-        path: file,
-        dispose: () => fs.rmSync(directory, { force: true, recursive: true }),
+        ...process.env,
+        TEMP: directory,
+        TMP: directory,
+        TMPDIR: directory,
     };
 }
+/** Scope parent-process temp consumers to the same owned scratch directory. */
+function withTransformScratchEnvironment(scratchDirectory, callback) {
+    const environment = transformScratchEnvironment(scratchDirectory);
+    const previous = {
+        TEMP: process.env.TEMP,
+        TMP: process.env.TMP,
+        TMPDIR: process.env.TMPDIR,
+    };
+    process.env.TEMP = environment.TEMP;
+    process.env.TMP = environment.TMP;
+    process.env.TMPDIR = environment.TMPDIR;
+    try {
+        return callback();
+    }
+    finally {
+        for (const [name, value] of Object.entries(previous)) {
+            if (value === undefined)
+                delete process.env[name];
+            else
+                process.env[name] = value;
+        }
+    }
+}
 /**
  * Resolve all relative paths inside `compilerOptions` against `tsconfigDir`.
  *
- * The generated tsconfig lives in a system temp directory, so any relative path
- * (e.g. `"outDir": "../dist"`) that was meaningful relative to the original
- * tsconfig must be converted to an absolute path before writing the generated
- * file. Otherwise TypeScript-Go resolves it against the temp dir.
+ * The generated tsconfig lives in a temporary directory outside the project, so
+ * any relative path (e.g. `"outDir": "../dist"`) that was meaningful relative
+ * to the original tsconfig must be converted to an absolute path before writing
+ * the generated file. Otherwise TypeScript-Go resolves it against the temp
+ * dir.
  *
  * `paths` targets are absolutized for the same reason, with the extra twist
  * that TypeScript-Go rejects bare non-relative targets outright (TS5090) and
@@ -1284,7 +2416,7 @@ function formatUnknownError(error) {
  * compiler will error if that file does not exist, which is the correct
  * behavior for a mis-configured project.
  */
-function resolveTsconfig(file, tsconfig) {
+function resolveTsconfig(file, tsconfig, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
     if (tsconfig !== undefined) {
         return path.isAbsolute(tsconfig)
             ? tsconfig
@@ -1293,7 +2425,7 @@ function resolveTsconfig(file, tsconfig) {
     let current = path.dirname(file);
     while (true) {
         const candidate = path.join(current, "tsconfig.json");
-        if (fs.existsSync(candidate)) {
+        if (filesystem.exists(candidate)) {
             return candidate;
         }
         const parent = path.dirname(current);
@@ -1332,6 +2464,7 @@ exports.createTransformResult = createTransformResult;
 exports.createTtscTransformCache = createTtscTransformCache;
 exports.isDeclarationFile = isDeclarationFile;
 exports.isProjectWalkPath = isProjectWalkPath;
+exports.normalizeHostInputName = normalizeHostInputName;
 exports.pathIdentityKey = pathIdentityKey;
 exports.resetTtscTransformCache = resetTtscTransformCache;
 exports.stripQuery = stripQuery;