@ttsc/unplugin 0.30.2 → 0.30.4

package/lib/core/transform.mjs

@@ -63,14 +63,13 @@ class TtscUnstableGenerationError extends TtscTerminalGenerationError {
 /**
  * A compile this pass already attempted, whose envelope failed outright.
  *
- * The envelope cannot say whether the host reported diagnostics about the
- * project or failed to run at all: an ordinary type error arrives as an
- * `"exception"` carrying the compiler's own diagnostic text, exactly as a
- * crashed host would. Sniffing that message to tell the two apart would be a
- * guess, so the adapter uses the one boundary it genuinely owns. Inside a pass
- * the answer is already settled, so every later module replays it instead of
- * repeating a whole-project transform to reach the same verdict, which is what
- * made a single broken save cost one compile per delivered module
+ * Native project diagnostics carry a structured failure envelope; setup and
+ * host failures can still arrive as opaque exceptions. Both settle the current
+ * attempt, so the adapter uses the delivery boundary it owns rather than
+ * guessing retryability from a diagnostic message. Inside a pass the answer is
+ * already settled, so every later module replays it instead of repeating a
+ * whole-project transform to reach the same verdict, which is what made a
+ * single broken save cost one compile per delivered module
  * (samchon/ttsc#1303).
  *
  * The scope is exactly the pass. A host whose `buildStart` repeats drops the
@@ -119,6 +118,8 @@ const TERMINAL_TRANSFORM_GENERATIONS = new WeakMap();
 const MAX_GENERATION_PROOF_FAILURES = 8;
 /** Maximum exact mutation paths kept after a tracker already proved a change. */
 const MAX_GENERATION_MUTATION_PATHS = 8;
+/** Maximum unrelated roots watched before snapshot validation takes over. */
+const MAX_HOST_INPUT_WATCH_SCOPES = 16;
 /** One retry absorbs a transient watch write without admitting an infinite loop. */
 const TRANSFORM_GENERATION_ATTEMPTS = 2;
 const DEFAULT_FILESYSTEM_OPERATIONS = Object.freeze({
@@ -381,6 +382,11 @@ async function transformTtsc(id, source, options, aliases, cache, hooks) {
                 deliveryEpoch: epoch,
                 filesystem,
                 plugins: options.plugins,
+                // One bounded recursive project observer witnesses content restored
+                // during the compile itself. Build-scoped adapters close it with the
+                // attempt; persistent adapters retain it to make later validations
+                // constant-cost while the generation remains live.
+                retainProjectMembership: cache !== undefined && epoch === undefined,
                 trackProjectMembership: cache !== undefined,
                 tsconfig,
             });
@@ -1049,11 +1055,11 @@ function collectDeclaredIdentities(state, projectRoot, listed) {
  * invalidated, and the error stays on screen (samchon/ttsc#1312).
  *
  * A failure envelope can retain exact external input spellings from its graph
- * and host metadata. A pre-transform typecheck failure may have no graph yet;
- * its structured diagnostics, or the host's standard diagnostic lines when it
- * could return only an exception, still name the external files that need a
- * repair. The cost is paid only on a failure, and only until the next compile
- * succeeds and narrows the set back to the derived inputs.
+ * and host metadata, including missing resolution candidates on native
+ * typecheck failures. For hosts that return no graph, structured diagnostics or
+ * standard diagnostic lines provide only the paths they actually name. The cost
+ * is paid only on a failure, and only until the next compile succeeds and
+ * narrows the set back to the derived inputs.
  */
 function notifyFailedGenerationInputs(hooks, cached) {
     const addWatchFile = hooks?.addWatchFile;
@@ -1098,7 +1104,7 @@ function notifyFailedGenerationInputs(hooks, cached) {
         }
     }
     if (addWatchFiles !== undefined) {
-        addWatchFiles(inputs);
+        addWatchFiles(inputs, true);
         return;
     }
     for (const input of inputs) {
@@ -1678,6 +1684,24 @@ function matchesNarrowPersistentInputs(cached, file) {
     }
     return true;
 }
+/** Whether a healthy notification scope proves one exact input unchanged. */
+function trackerProvesInputUnchanged(tracker, input) {
+    if (tracker === undefined || tracker.failed || tracker.changesOmitted) {
+        return false;
+    }
+    if (tracker.contentAuthoritative !== true)
+        return false;
+    const absolute = path.resolve(input);
+    if (tracker.covered?.has(absolute) !== true)
+        return false;
+    for (const changed of tracker.changes) {
+        if (tracker.overlaps?.(absolute, changed) ??
+            (pathIsWithin(absolute, changed) || pathIsWithin(changed, absolute))) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Validate one derived input against the generation, skipping the content read
  * while the recorded metadata signature still holds and its freshly minted
@@ -1701,6 +1725,10 @@ function matchesNarrowPersistentInputs(cached, file) {
  * junction moves it and the skipped realpath comparison cannot be evaded.
  */
 function matchesProvenInput(cached, state, input) {
+    if (trackerProvesInputUnchanged(cached.projectMutationTracker, input) ||
+        trackerProvesInputUnchanged(cached.hostInputMutationTracker, input)) {
+        return true;
+    }
     const observation = cached.externalInputObservations?.[path.resolve(input)];
     if (observation !== undefined) {
         if (observation.fileExists === false &&
@@ -1708,7 +1736,25 @@ function matchesProvenInput(cached, state, input) {
             notifiesAbsence(cached, input)) {
             return true;
         }
-        return matchesRecordedInput(cached, input);
+        const filesystem = resultFilesystem(cached.result);
+        const spelling = path.resolve(input);
+        const before = inputMetadataEvidence(input, filesystem);
+        if (before !== undefined &&
+            before.separable &&
+            cached.externalInputSignatures?.[spelling] === before.signature) {
+            return true;
+        }
+        if (!matchesRecordedInput(cached, input))
+            return false;
+        const after = inputMetadataSignature(input, filesystem);
+        const signatures = (cached.externalInputSignatures ??= {});
+        if (before?.separable === true && before.signature === after) {
+            signatures[spelling] = after;
+        }
+        else {
+            delete signatures[spelling];
+        }
+        return true;
     }
     const slot = inputSignatureSlot(cached, state, input);
     if (slot === undefined) {
@@ -1756,10 +1802,7 @@ function matchesProvenInput(cached, state, input) {
  * the whole generation back to complete-snapshot validation.
  */
 function notifiesAbsence(cached, input) {
-    const tracker = cached.candidateMutationTracker;
-    return (tracker !== undefined &&
-        !tracker.failed &&
-        tracker.covered?.has(path.resolve(input)) === true);
+    return trackerProvesInputUnchanged(cached.candidateMutationTracker, input);
 }
 /**
  * Locate the signature manifest that owns one recorded input, mirroring
@@ -1805,6 +1848,15 @@ function inputSignatureSlot(cached, state, input) {
  * existing directory and checked through one exact membership listing.
  */
 function matchesUniversalHostInputs(cached, validation) {
+    let notificationsProveAll = true;
+    for (const input of validation.covered) {
+        if (!trackerProvesInputUnchanged(cached.hostInputMutationTracker, input)) {
+            notificationsProveAll = false;
+            break;
+        }
+    }
+    if (notificationsProveAll)
+        return true;
     return (matchesUniversalHostInputEntries(cached, validation) &&
         matchesUniversalHostInputProbes(cached, validation));
 }
@@ -1832,6 +1884,11 @@ function matchesUniversalHostInputEntries(cached, validation) {
         if (!matchesRecordedInput(cached, entry.path)) {
             return false;
         }
+        if (entry.readable === false) {
+            const slot = inputSignatureSlot(cached, envelopeDerivation(cached), entry.path);
+            entry.readable =
+                slot !== undefined && slot.recorded !== MISSING_INPUT_STATE;
+        }
         if (evidence === undefined)
             return false;
         // Re-earn the proof under the rules the capture applies: an entry whose
@@ -2040,6 +2097,37 @@ function captureUniversalHostInputValidation(cached, currentFile) {
     cached.hostInputValidation = validation;
     return { failures, validation };
 }
+/**
+ * Keep watcher silence as a content proof only for inputs whose bytes capture
+ * actually proved.
+ *
+ * The observers must open before the post-compile snapshots so they can witness
+ * an A-B-A race. Their exact coverage can only be narrowed after those reads.
+ * Existing-but-unreadable and absent inputs record the same `missing` state;
+ * neither may inherit a content shortcut because its metadata can stay fixed
+ * while bytes become readable. Missing resolver candidates inside the project
+ * retain their separate component-aware candidate tracker, while every other
+ * such input continues through the recorded predicate or directory-list proof.
+ */
+function restrictNotificationCoverageToProvenInputs(tracker, cached, hostValidation) {
+    if (!(tracker?.covered instanceof Set))
+        return;
+    const covered = tracker.covered;
+    const state = envelopeDerivation(cached);
+    for (const input of [...covered]) {
+        const absolute = path.resolve(input);
+        const hostEntry = hostValidation?.entries.get(absolute);
+        if ((hostValidation?.covered.has(absolute) === true &&
+            (hostEntry === undefined ||
+                (hostEntry.readable === false && hostEntry.strict !== true))) ||
+            cached.externalInputHashes?.[derivationIdentity(state, absolute)] ===
+                MISSING_INPUT_STATE ||
+            cached.externalInputObservations?.[absolute]?.readFile?.ok === false ||
+            cached.externalInputObservations?.[absolute]?.fileExists === false) {
+            covered.delete(input);
+        }
+    }
+}
 /**
  * The recorded state of an input the generation read nothing from: absent, or
  * present but unreadable. It is deliberately not a hash, so no signature may
@@ -2186,6 +2274,7 @@ function inputMetadataEvidence(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS)
                         link.ctimeNs,
                         "missing-target",
                     ].join(":"),
+                    notificationAuthoritative: false,
                     separable: false,
                 };
             }
@@ -2194,17 +2283,25 @@ function inputMetadataEvidence(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS)
             signature: [
                 link.dev,
                 link.ino,
+                link.nlink,
                 link.mode,
                 link.size,
                 link.mtimeNs,
                 link.ctimeNs,
                 target.dev,
                 target.ino,
+                target.nlink,
                 target.mode,
                 target.size,
                 target.mtimeNs,
                 target.ctimeNs,
             ].join(":"),
+            // A write through a hardlink outside the watched tree changes this inode
+            // without notifying either the original directory or a watcher opened on
+            // the original path. Keep such files on metadata validation. Symlinks are
+            // likewise governed by the target path, outside the lexical observer.
+            notificationAuthoritative: !link.isSymbolicLink() &&
+                !(link.isFile() && (link.nlink > 1n || target.nlink > 1n)),
             // Both halves must be separable: a write remints the target's stamp, a
             // link retarget the link's own, and either one hiding inside its recorded
             // tick would evade the skipped content and realpath comparisons.
@@ -2599,7 +2696,9 @@ function captureExternalInputSnapshot(cached, paths) {
                 });
                 continue;
             }
+            const before = inputMetadataEvidence(input, filesystem);
             const mismatches = graphInputObservationFailures(input, predicateObservation, filesystem, state.identityContext);
+            const after = inputMetadataSignature(input, filesystem);
             if (mismatches.length !== 0)
                 complete = false;
             for (const kind of mismatches) {
@@ -2609,6 +2708,8 @@ function captureExternalInputSnapshot(cached, paths) {
                     path: input,
                 });
             }
+            if (mismatches.length === 0)
+                record(input, before, after);
             observations[spelling] = predicateObservation;
             continue;
         }
@@ -2876,6 +2977,7 @@ function collectProjectInputHashSnapshot(projectRoot, identities = createHostPat
 /** Hash project files and snapshot the directory topology in one walk. */
 function collectProjectInputSnapshot(projectRoot, identities, filesystem = DEFAULT_FILESYSTEM_OPERATIONS, proven, options) {
     const hashes = {};
+    const notificationUnsafeInputs = new Set();
     const fileSignatures = {};
     const provenSignatures = {};
     const unstableFiles = new Set();
@@ -2898,6 +3000,9 @@ function collectProjectInputSnapshot(projectRoot, identities, filesystem = DEFAU
                 continue;
             }
             const before = inputMetadataEvidence(file, filesystem);
+            if (before?.notificationAuthoritative !== true) {
+                notificationUnsafeInputs.add(key);
+            }
             // A file whose signature still equals the one captured around the read
             // that produced the recorded hash carries that content, so the whole
             // project does not have to be re-read to prove one delivery. Recheck the
@@ -2914,23 +3019,26 @@ function collectProjectInputSnapshot(projectRoot, identities, filesystem = DEFAU
                 continue;
             }
             const contents = filesystem.readFile(file);
-            const after = inputMetadataSignature(file, filesystem);
+            const after = inputMetadataEvidence(file, filesystem);
+            if (after?.notificationAuthoritative !== true) {
+                notificationUnsafeInputs.add(key);
+            }
             hashes[key] = hashText(contents);
             if (before === undefined ||
                 after === undefined ||
-                before.signature !== after) {
+                before.signature !== after.signature) {
                 complete = false;
                 unstableFiles.add(key);
                 walkFailures.push({ kind: "file-changed-during-read", path: file });
             }
             else {
-                fileSignatures[key] = after;
+                fileSignatures[key] = after.signature;
                 // Only a signature whose stamp's tick the filesystem's clock provably
                 // left before this read may later stand in for the content comparison
                 // ({@link stampSeparable}); the raw signature above still participates
                 // in the generation-time stability comparison.
                 if (before.separable) {
-                    provenSignatures[key] = after;
+                    provenSignatures[key] = after.signature;
                 }
             }
         }
@@ -2954,6 +3062,7 @@ function collectProjectInputSnapshot(projectRoot, identities, filesystem = DEFAU
         directoryComplete: walked.complete && attributed,
         fileSignatures,
         hashes,
+        notificationUnsafeInputs,
         projectDirectories: walked.directories,
         provenSignatures,
         unstableFiles,
@@ -3148,11 +3257,11 @@ function sameProjectDirectories(left, right) {
  * underlying watch does, so callers classify a registration failure
  * themselves.
  */
-function openDirectoryWatch(filesystem, directory, listener, onError) {
+function openDirectoryWatch(filesystem, directory, listener, onError, recursive = false) {
     if (filesystem.watch !== undefined) {
-        return filesystem.watch(directory, listener, onError);
+        return filesystem.watch(directory, listener, onError, recursive);
     }
-    const watcher = fs.watch(directory, { persistent: false }, (eventType, filename) => listener(eventType, filename === null ? null : String(filename)));
+    const watcher = fs.watch(directory, { persistent: false, recursive }, (eventType, filename) => listener(eventType, filename === null ? null : String(filename)));
     watcher.on("error", onError);
     return { close: () => watcher.close() };
 }
@@ -3176,106 +3285,223 @@ function closeDirectoryWatches(watchers) {
         throw failure;
 }
 /** Watch every walked directory for membership changes after generation. */
-async function createProjectMutationTracker(directories, filesystem = DEFAULT_FILESYSTEM_OPERATIONS, policy = PERMISSIVE_PROJECT_MEMBERSHIP_POLICY) {
+async function createProjectMutationTracker(directories, covered, filesystem = DEFAULT_FILESYSTEM_OPERATIONS, policy = PERMISSIVE_PROJECT_MEMBERSHIP_POLICY) {
+    const identities = createHostPathIdentityContext(filesystem);
+    const root = commonDirectoryRoot(directories.map((directory) => directory.path));
+    const authoritative = root !== undefined &&
+        filesystem.watch === undefined &&
+        pathTraversesSymbolicLink(path.join(root, ".ttsc-notification-authority"), filesystem, new Map())
+        ? new Set()
+        : covered;
     const tracker = {
         changes: new Set(),
         changesOmitted: false,
-        close: () => undefined,
+        close: () => {
+            tracker.failed = true;
+        },
+        covered: authoritative,
         failed: false,
         membershipChanged: false,
+        overlaps: (input, changed) => identities.isWithin(input, changed) ||
+            identities.isWithin(changed, input),
+        contentAuthoritative: filesystem.watch === undefined,
+    };
+    if (root === undefined)
+        return tracker;
+    const knownDirectories = new Set(directories
+        .filter((directory) => directory.relevant)
+        .map((directory) => path.resolve(directory.path)));
+    const reportsMembership = (location, filename) => {
+        const changed = path.join(location, filename);
+        return (knownDirectories.has(path.resolve(changed)) ||
+            reportsProgramMembership(changed, path.basename(filename), policy, filesystem));
+    };
+    const reportsNewMembership = (location, filename) => {
+        const changed = path.resolve(location, filename);
+        return (!knownDirectories.has(changed) && tracker.covered?.has(changed) !== true);
     };
     if (process.platform === "win32" && filesystem.watch === undefined) {
-        await registerWindowsProjectMutationTracker(tracker, directories.map((directory) => ({ directory: directory.path })), false, filesystem, (location, filename) => reportsProgramMembership(path.join(location, filename), filename, policy, filesystem));
+        await registerWindowsProjectMutationTracker(tracker, [{ directory: root, recursive: true }], false, filesystem, reportsMembership, (_location, filename) => isPossibleProgramFileName(path.basename(filename), policy), reportsNewMembership);
         return tracker;
     }
     const watchers = [];
-    tracker.close = () => closeDirectoryWatches(watchers);
-    for (const directory of directories) {
-        try {
-            watchers.push(openDirectoryWatch(filesystem, directory.path, (eventType, filename) => {
-                if (eventType !== "rename") {
-                    return;
-                }
-                if (filename !== null &&
-                    !reportsProgramMembership(path.join(directory.path, filename), filename, policy, filesystem)) {
-                    return;
-                }
-                recordProjectMutation(tracker, filename === null
-                    ? directory.path
-                    : path.join(directory.path, filename));
-            }, () => {
-                tracker.failed = true;
-            }));
-        }
-        catch {
+    tracker.close = () => {
+        tracker.failed = true;
+        closeDirectoryWatches(watchers);
+    };
+    try {
+        watchers.push(openDirectoryWatch(filesystem, root, (eventType, filename) => {
+            const changed = filename === null ? root : path.join(root, filename);
+            const membership = filename === null || reportsMembership(root, filename);
+            if (membership &&
+                (eventType === "rename" ||
+                    reportsNewMembership(root, filename ?? ""))) {
+                recordProjectMutation(tracker, changed);
+            }
+            else if (filename === null ||
+                isPossibleProgramFileName(path.basename(filename), policy)) {
+                recordProjectChange(tracker, changed);
+            }
+        }, () => {
             tracker.failed = true;
-        }
+        }, true));
+    }
+    catch {
+        tracker.failed = true;
     }
     return tracker;
 }
+/** Common ancestor owned by every project directory snapshot. */
+function commonDirectoryRoot(directories) {
+    if (directories.length === 0)
+        return undefined;
+    let root = path.resolve(directories[0]);
+    for (const directory of directories.slice(1)) {
+        const absolute = path.resolve(directory);
+        while (!pathIsWithin(absolute, root)) {
+            const parent = path.dirname(root);
+            if (parent === root)
+                return root;
+            root = parent;
+        }
+    }
+    return root;
+}
 /** Watch exact universal inputs, or their nearest existing parent if missing. */
-async function createHostInputMutationTracker(inputs, filesystem, covered, events = "all") {
+async function createHostInputMutationTracker(inputs, filesystem, covered, events = "all", preferredRoot) {
     const identities = createHostPathIdentityContext(filesystem);
-    const namesByDirectory = new Map();
+    const linkedAncestors = new Map();
+    const authoritative = new Set([...covered]
+        .map((input) => path.resolve(input))
+        .filter((input) => {
+        if (pathTraversesSymbolicLink(input, filesystem, linkedAncestors)) {
+            return false;
+        }
+        try {
+            // A lexical symlink can keep its own directory silent while a target
+            // elsewhere changes or appears. Its joined metadata proof must stay
+            // on the validation path, including while the link is broken.
+            const lexical = filesystem.lstat(input);
+            if (lexical.isSymbolicLink() ||
+                (lexical.isFile() && lexical.nlink > 1n))
+                return false;
+        }
+        catch {
+            // A genuinely absent lexical path is covered by its nearest existing
+            // ancestor and remains eligible for notification proof.
+        }
+        const target = hostInputRealpath(input, filesystem);
+        return (target === null ||
+            pathIdentityKey(target, identities) ===
+                pathIdentityKey(input, identities));
+    }));
+    const locationsByDirectory = new Map();
+    const internalRoot = preferredRoot === undefined ? undefined : path.resolve(preferredRoot);
     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);
+        const internal = internalRoot !== undefined && pathIsWithin(absolute, internalRoot);
+        const directory = internal ? internalRoot : probe.directory;
+        const directoryIdentity = identities.resolve(directory);
+        let location = locationsByDirectory.get(directoryIdentity.key);
         if (location === undefined) {
             location = {
                 directory: directoryIdentity.path,
                 names: new Set(),
+                ...(internal ? { paths: new Set(), recursive: true } : {}),
             };
-            namesByDirectory.set(directoryIdentity.key, location);
+            locationsByDirectory.set(directoryIdentity.key, location);
+        }
+        if (location.paths !== undefined) {
+            location.paths.add(pathIdentityKey(path.resolve(probe.directory, probe.name), identities));
+        }
+        else {
+            location.names.add(normalizeHostInputName(probe.name, identities.caseSensitive(directoryIdentity.path)));
         }
-        location.names.add(normalizeHostInputName(probe.name, identities.caseSensitive(directoryIdentity.path)));
     }
-    const locations = [...namesByDirectory.values()].map((location) => ({
-        directory: location.directory,
-        names: [...location.names],
-    }));
+    const locations = [...locationsByDirectory.values()];
     const tracker = {
         changes: new Set(),
         changesOmitted: false,
-        close: () => undefined,
+        close: () => {
+            tracker.failed = true;
+        },
         // Coverage is the caller's claim, and it is required rather than derived
         // from the input list: an input is watched by its exact name here, but only
         // the caller knows whether the path leading to it is watched as well, which
         // is what a later validation needs before it trusts the watcher instead of
         // probing the path again. Deriving it here would hand that claim to every
         // future caller by default (samchon/ttsc#1261).
-        covered,
+        covered: authoritative,
+        contentAuthoritative: filesystem.watch === undefined,
         failed: false,
         membershipChanged: false,
+        overlaps: (input, changed) => identities.isWithin(input, changed) ||
+            identities.isWithin(changed, input),
+    };
+    if (locations.length > MAX_HOST_INPUT_WATCH_SCOPES) {
+        // A graph spread over unrelated external roots cannot be folded into one
+        // recursive observer without watching an arbitrarily broad filesystem
+        // ancestor. Decline the notification proof and use the recorded snapshots;
+        // descriptor count must never scale with an adversarial input graph.
+        tracker.failed = true;
+        return tracker;
+    }
+    const matches = (directory, filename) => {
+        const location = locationsByDirectory.get(identities.resolve(directory).key);
+        if (location === undefined)
+            return false;
+        if (location.paths !== undefined) {
+            let changed = path.resolve(directory, filename);
+            for (;;) {
+                if (location.paths.has(pathIdentityKey(changed, identities))) {
+                    return true;
+                }
+                const parent = path.dirname(changed);
+                if (parent === changed || !pathIsWithin(parent, location.directory)) {
+                    return false;
+                }
+                changed = parent;
+            }
+        }
+        return location.names.has(normalizeHostInputName(filename, identities.caseSensitive(directory)));
     };
     if (process.platform === "win32" && filesystem.watch === undefined) {
-        await registerWindowsProjectMutationTracker(tracker, locations, events === "all", filesystem);
+        await registerWindowsProjectMutationTracker(tracker, locations.map((location) => ({
+            directory: location.directory,
+            ...(location.recursive === true
+                ? { recursive: true }
+                : { names: [...location.names] }),
+        })), events === "all", filesystem, matches, matches);
         return tracker;
     }
     const watchers = [];
-    tracker.close = () => closeDirectoryWatches(watchers);
+    tracker.close = () => {
+        tracker.failed = true;
+        closeDirectoryWatches(watchers);
+    };
     for (const location of locations) {
         try {
-            const names = new Set(location.names);
-            const caseSensitive = identities.caseSensitive(location.directory);
             watchers.push(openDirectoryWatch(filesystem, location.directory, (eventType, filename) => {
                 if (events === "rename" && eventType !== "rename") {
                     return;
                 }
-                const reported = filename === null
-                    ? null
-                    : normalizeHostInputName(filename, caseSensitive);
-                if (reported === null || names.has(reported)) {
-                    recordProjectMutation(tracker, filename === null
+                if (filename === null || matches(location.directory, filename)) {
+                    const changed = filename === null
                         ? location.directory
-                        : path.join(location.directory, filename));
+                        : path.join(location.directory, filename);
+                    if (eventType === "rename") {
+                        recordProjectMutation(tracker, changed);
+                    }
+                    else {
+                        recordProjectChange(tracker, changed);
+                    }
                 }
             }, () => {
                 tracker.failed = true;
-            }));
+            }, location.recursive === true));
         }
         catch {
             tracker.failed = true;
@@ -3283,6 +3509,45 @@ async function createHostInputMutationTracker(inputs, filesystem, covered, event
     }
     return tracker;
 }
+/**
+ * Whether any lexical component above an input is a symbolic link or junction.
+ *
+ * A recursive observer follows the component to its current physical target.
+ * Retargeting it can therefore move the input without producing an event on the
+ * old target. Keep those spellings on metadata/realpath validation. The memo
+ * makes this one lstat per distinct directory component for the generation,
+ * rather than one walk per graph input.
+ */
+function pathTraversesSymbolicLink(input, filesystem, memo) {
+    const visited = [];
+    let current = path.dirname(path.resolve(input));
+    let linked = false;
+    for (;;) {
+        const known = memo.get(current);
+        if (known !== undefined) {
+            linked = known;
+            break;
+        }
+        visited.push(current);
+        try {
+            if (filesystem.lstat(current).isSymbolicLink()) {
+                linked = true;
+                break;
+            }
+        }
+        catch {
+            // A missing component is not a link. Its nearest existing ancestor will
+            // still be inspected before the walk reaches the volume root.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const directory of visited)
+        memo.set(directory, linked);
+    return linked;
+}
 /**
  * Whether a path lies inside a directory the configuration excludes.
  *
@@ -3358,6 +3623,10 @@ function reportsProgramMembership(location, filename, policy, filesystem) {
 /** Record enough exact mutation evidence without retaining an event stream. */
 function recordProjectMutation(tracker, changed) {
     tracker.membershipChanged = true;
+    recordProjectChange(tracker, changed);
+}
+/** Record a content event without classifying it as a membership change. */
+function recordProjectChange(tracker, changed) {
     if (tracker.changes.has(changed))
         return;
     if (tracker.changes.size < MAX_GENERATION_MUTATION_PATHS) {
@@ -3381,7 +3650,7 @@ async function registerWindowsProjectMutationTracker(tracker, locations, allEven
  * narrowed to program membership exactly as the in-process watcher's are. The
  * name-watching trackers pass none, since they already watch exact names.
  */
-membership) {
+membership, content, changeAddsMembership) {
     const broker = getWindowsProjectMutationBroker();
     // The child watches canonical directories, and reports its events under that
     // spelling. Everything else in the adapter speaks the walk's own spelling,
@@ -3402,24 +3671,30 @@ membership) {
         return {
             directory,
             ...(location.names === undefined ? {} : { names: location.names }),
+            ...(location.recursive === true ? { recursive: true } : {}),
         };
     });
     broker.pendingRegistrations += 1;
     broker.child.ref();
-    broker.child.channel?.ref();
+    // Bun's IPC channel omits Node's Control.ref/unref methods. The child itself
+    // still owns the outstanding acknowledgement on that runtime.
+    broker.child.channel?.ref?.();
     const id = broker.nextId++;
     let resolveReady;
     const ready = new Promise((resolve) => {
         resolveReady = resolve;
     });
     broker.trackers.set(id, {
-        membership,
+        ...(changeAddsMembership === undefined ? {} : { changeAddsMembership }),
+        ...(content === undefined ? {} : { content }),
+        ...(membership === undefined ? {} : { membership }),
         ready: resolveReady,
         spellings,
         tracker,
     });
     tracker.drain = () => drainWindowsProjectMutationBroker(broker);
     tracker.close = () => {
+        tracker.failed = true;
         const active = broker.trackers.get(id);
         if (active === undefined)
             return;
@@ -3477,7 +3752,7 @@ membership) {
         // exit mid-build.
         if (broker.pendingRegistrations === 0 && broker.pendingDrains === 0) {
             broker.child.unref();
-            broker.child.channel?.unref();
+            broker.child.channel?.unref?.();
         }
     }
 }
@@ -3541,14 +3816,26 @@ function getWindowsProjectMutationBroker() {
                 // The walk's spelling for this directory, which is what every
                 // comparison and every recorded witness downstream expects.
                 const reported = registration.spellings.get(record.directory) ?? record.directory;
+                const changed = typeof record.filename === "string"
+                    ? path.join(reported, record.filename)
+                    : reported;
                 if (typeof record.filename === "string" &&
-                    registration.membership !== undefined &&
-                    !registration.membership(reported, record.filename)) {
+                    registration.membership !== undefined) {
+                    const membership = registration.membership(reported, record.filename);
+                    if (membership &&
+                        (record.eventType === "rename" ||
+                            registration.changeAddsMembership?.(reported, record.filename) ===
+                                true)) {
+                        recordProjectMutation(registration.tracker, changed);
+                        return;
+                    }
+                    if (record.eventType !== "rename" &&
+                        registration.content?.(reported, record.filename) === true) {
+                        recordProjectChange(registration.tracker, changed);
+                    }
                     return;
                 }
-                recordProjectMutation(registration.tracker, typeof record.filename === "string"
-                    ? path.join(reported, record.filename)
-                    : reported);
+                recordProjectMutation(registration.tracker, changed);
             }
             else {
                 registration.tracker.membershipChanged = true;
@@ -3593,7 +3880,7 @@ function startWindowsProjectMutationDrain(broker) {
             broker.pendingDrains -= 1;
             if (broker.pendingDrains === 0 && broker.pendingRegistrations === 0) {
                 broker.child.unref();
-                broker.child.channel?.unref();
+                broker.child.channel?.unref?.();
             }
             resolve();
         };
@@ -3604,7 +3891,7 @@ function startWindowsProjectMutationDrain(broker) {
         // process exits mid-build with nothing to report.
         broker.pendingDrains += 1;
         broker.child.ref();
-        broker.child.channel?.ref();
+        broker.child.channel?.ref?.();
         const timer = setTimeout(release, WINDOWS_MUTATION_DRAIN_FALLBACK_MS);
         broker.drains.set(id, release);
         if (broker.child.send?.({ id, op: "drain" }) !== true) {
@@ -3634,9 +3921,9 @@ const WINDOWS_WATCH_BROKER_SOURCE = [
     "  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 watcher = fs.watch(location.directory, { persistent: false, recursive: location.recursive === true }, (event, filename) => {",
     "        const matches = names === undefined || filename === null || names.has(String(filename).toLowerCase());",
-    '        if (matches && (message.allEvents || event === "rename")) process.send?.({ directory: location.directory, filename: filename === null ? null : String(filename), id: message.id });',
+    '        if (matches && (message.allEvents || event === "rename" || location.recursive === true)) process.send?.({ directory: location.directory, eventType: event, filename: filename === null ? null : String(filename), id: message.id });',
     "      });",
     '      watcher.on("error", () => process.send?.({ failed: true, id: message.id }));',
     "      watchers.push(watcher);",
@@ -3657,14 +3944,18 @@ const WINDOWS_WATCH_BROKER_SOURCE = [
     "}",
 ].join("\n");
 /**
- * Report whether either live notification observed a membership event. This is
- * positive evidence that the generation is stale, so it outranks the question
- * of whether the notifications still work.
+ * Report whether the project walk observed a membership event. This is positive
+ * evidence that the program's root set changed, so it outranks the question of
+ * whether the notifications still work.
+ *
+ * Host and resolution-candidate trackers cover the union of every module's
+ * inputs. Their events remain path witnesses: the requested module's narrow
+ * validation decides whether that path is relevant. Promoting one of them to a
+ * project-wide verdict would discard a generation when an unreachable external
+ * input changes, defeating per-file completeness and doing needless compiles.
  */
 function reportsMembershipChange(cached) {
-    return (cached.projectMutationTracker?.membershipChanged === true ||
-        cached.hostInputMutationTracker?.membershipChanged === true ||
-        cached.candidateMutationTracker?.membershipChanged === true);
+    return cached.projectMutationTracker?.membershipChanged === true;
 }
 /**
  * Report whether the live notifications can still prove membership. A watcher
@@ -3706,11 +3997,15 @@ function drainOnNextTurn() {
  * broker. Concurrent sibling deliveries share the barrier one of them started.
  */
 async function settleProjectMutationEvents(cached) {
-    const trackers = [
+    await settleMutationTrackers([
         cached.projectMutationTracker,
         cached.hostInputMutationTracker,
         cached.candidateMutationTracker,
-    ].filter((tracker) => tracker !== undefined);
+    ]);
+}
+/** Settle one set of optional trackers through one shared barrier each. */
+async function settleMutationTrackers(candidates) {
+    const trackers = candidates.filter((tracker) => tracker !== undefined);
     await Promise.all(trackers.map(async (tracker) => {
         tracker.settle ??= (tracker.drain ?? drainOnNextTurn)().finally(() => {
             tracker.settle = undefined;
@@ -4016,9 +4311,21 @@ function matchesCachedExternalInputs(cached) {
         const spelling = path.resolve(file);
         const observation = cached.externalInputObservations?.[spelling];
         if (observation !== undefined) {
-            if (!matchesGraphInputObservation(file, observation, filesystem, state.identityContext)) {
+            const before = inputMetadataEvidence(file, filesystem);
+            if (before !== undefined &&
+                before.separable &&
+                recordedSignatures[spelling] === before.signature) {
+                signatures[spelling] = before.signature;
+                continue;
+            }
+            const observed = matchesGraphInputObservation(file, observation, filesystem, state.identityContext);
+            const after = inputMetadataSignature(file, filesystem);
+            if (!observed) {
                 matches = false;
             }
+            else if (before?.separable === true && before.signature === after) {
+                signatures[spelling] = after;
+            }
             continue;
         }
         // Reuse the recorded hash of an out-of-walk input whose signature still
@@ -4516,6 +4823,7 @@ function declaredProjectInputKeys(state, cached) {
     if (state.declaredInputKeysBuilt !== true) {
         state.declaredInputKeys = selectDeclaredProjectInputKeys({
             identities: state.identityContext,
+            projectInputHashes: cached.inputHashes,
             projectRoot: cached.projectRoot,
             result: cached.result,
             scratchDirectory: cached.scratchDirectory,
@@ -4527,8 +4835,12 @@ function declaredProjectInputKeys(state, cached) {
 /**
  * Project-walk keys of every input the envelope declares: the reference graph's
  * edge endpoints, globals, config chain, and resolution candidates, plus the
- * universal host inputs. Returns `undefined` for an envelope with no graph,
- * which declares no input set and therefore keeps whole-walk comparison.
+ * universal host inputs, intersected with the files the project walk actually
+ * hashed. Out-of-walk declarations and candidates carry their own graph proof;
+ * asking the project observer to witness them as well makes unrelated activity
+ * in ignored directories invalidate an otherwise complete generation. Returns
+ * `undefined` for an envelope with no graph, which declares no input set and
+ * therefore keeps whole-walk comparison.
  */
 function selectDeclaredProjectInputKeys(props) {
     if (props.result.type === "exception" || props.result.graph === undefined) {
@@ -4542,7 +4854,10 @@ function selectDeclaredProjectInputKeys(props) {
         const absolute = path.resolve(props.projectRoot, entry);
         if (isTransformScratchInput(absolute, props.scratchDirectory))
             return;
-        keys.add(toProjectKey(props.projectRoot, absolute, props.identities));
+        const key = toProjectKey(props.projectRoot, absolute, props.identities);
+        if (Object.prototype.hasOwnProperty.call(props.projectInputHashes, key)) {
+            keys.add(key);
+        }
     };
     for (const [source, targets] of Object.entries(graph.edges ?? {})) {
         add(source);
@@ -4786,8 +5101,7 @@ async function transformProject(props) {
     for (let attempt = 0; attempt < TRANSFORM_GENERATION_ATTEMPTS; attempt += 1) {
         const cached = await captureTransformGeneration(props);
         if (cached.configStateComplete !== false &&
-            (!props.trackProjectMembership ||
-                cached.result.type !== "success" ||
+            (cached.result.type !== "success" ||
                 cached.projectSnapshotComplete === true)) {
             return cached;
         }
@@ -4819,7 +5133,7 @@ async function captureTransformGeneration(props) {
     let retainCandidateTracker = false;
     let captured;
     try {
-        if (props.trackProjectMembership) {
+        if (props.retainProjectMembership) {
             try {
                 clockReferenceDirectory = createTransformScratchDirectory(projectRoot, props.filesystem);
             }
@@ -4848,7 +5162,9 @@ async function captureTransformGeneration(props) {
         const membershipPolicy = mergeMembershipPolicyOverlay(tsconfigState.membershipPolicy, props.compilerOptions, projectRoot);
         const before = collectProjectInputSnapshot(projectRoot, identities, props.filesystem, undefined, { policy: membershipPolicy });
         tracker = props.trackProjectMembership
-            ? await createProjectMutationTracker(before.projectDirectories, props.filesystem, membershipPolicy)
+            ? await createProjectMutationTracker(before.projectDirectories, new Set(Object.keys(before.hashes)
+                .filter((key) => !before.notificationUnsafeInputs.has(key))
+                .map((key) => path.resolve(projectRoot, key))), props.filesystem, membershipPolicy)
             : undefined;
         const result = withTransformScratchEnvironment(scratchDirectory, () => new TtscCompiler({
             cwd: projectRoot,
@@ -4879,15 +5195,26 @@ async function captureTransformGeneration(props) {
             scratchDirectory,
             temporaryTsconfig,
         });
+        const externalInputPaths = selectExternalInputPaths({
+            filesystem: props.filesystem,
+            membershipPolicy,
+            projectRoot,
+            result,
+            scratchDirectory,
+            temporaryTsconfig,
+        });
+        const persistentValidationInputs = [
+            ...new Set([...persistentHostInputs, ...externalInputPaths]),
+        ];
         // The generation's absent resolution candidates, which get a watcher of
         // their own below; watching one is what lets a delivery stop probing it
         // (samchon/ttsc#1261). The validation manifest stays built from the
         // universal inputs alone, so nothing else about a candidate changes.
         //
-        // Derived only where a tracker could carry it: a build-scoped adapter opens
-        // no watcher, so probing every candidate's existence here would be work
-        // whose answer nothing can read.
-        const notifiableAbsence = props.trackProjectMembership
+        // Derived only where a retained tracker could carry it: a build-scoped
+        // adapter keeps only the compile-time project observer, so probing every
+        // candidate here would be work whose answer nothing can later read.
+        const notifiableAbsence = props.retainProjectMembership
             ? selectNotifiableAbsentInputs({
                 filesystem: props.filesystem,
                 projectRoot,
@@ -4896,12 +5223,12 @@ async function captureTransformGeneration(props) {
                 temporaryTsconfig,
             })
             : { candidates: [], watched: [] };
-        hostInputTracker = props.trackProjectMembership
-            ? await createHostInputMutationTracker(persistentHostInputs, props.filesystem, 
+        hostInputTracker = props.retainProjectMembership
+            ? await createHostInputMutationTracker(persistentValidationInputs, props.filesystem, 
             // A universal input never reaches the per-input loop that consults a
             // coverage claim: an absent one is proven by its directory listing
             // instead, which re-resolves the spelling every delivery.
-            new Set())
+            new Set(persistentValidationInputs.map((input) => path.resolve(input))), "all", projectRoot)
             : undefined;
         // The candidates and the directories carrying them get their own tracker,
         // listening for renames alone. Every event that can make one of these
@@ -4912,16 +5239,8 @@ async function captureTransformGeneration(props) {
         // every time a bundler wrote inside `node_modules`.
         candidateTracker =
             notifiableAbsence.watched.length !== 0
-                ? await createHostInputMutationTracker(notifiableAbsence.watched, props.filesystem, new Set(notifiableAbsence.candidates), "rename")
+                ? await createHostInputMutationTracker(notifiableAbsence.watched, props.filesystem, new Set(notifiableAbsence.candidates), "rename", projectRoot)
                 : undefined;
-        const externalInputPaths = selectExternalInputPaths({
-            filesystem: props.filesystem,
-            membershipPolicy,
-            projectRoot,
-            result,
-            scratchDirectory,
-            temporaryTsconfig,
-        });
         const inputSnapshot = collectProjectInputSnapshot(projectRoot, identities, props.filesystem, undefined, { policy: membershipPolicy });
         // Whether the recorded snapshot describes one coherent state of the
         // project. A membership event during the compile taints it exactly like an
@@ -4930,16 +5249,23 @@ async function captureTransformGeneration(props) {
         // provable from its own recorded state.
         const declaredInputs = selectDeclaredProjectInputKeys({
             identities,
+            projectInputHashes: inputSnapshot.hashes,
             projectRoot,
             result,
             scratchDirectory,
         });
+        // The before/after snapshots prove bytes and metadata. Drain the watcher
+        // opened before compilation as the independent A-B-A witness: a producer
+        // can restore both bytes and timestamps before the second walk, but it
+        // cannot withdraw the already queued content event.
+        await settleMutationTrackers([tracker, hostInputTracker, candidateTracker]);
         const walkStable = configStable &&
             walkSnapshotComplete(before, declaredInputs) &&
             walkSnapshotComplete(inputSnapshot, declaredInputs) &&
             sameHashes(before.hashes, inputSnapshot.hashes, declaredInputs) &&
             sameHashes(before.fileSignatures, inputSnapshot.fileSignatures, declaredInputs) &&
             sameProjectDirectories(before.projectDirectories, inputSnapshot.projectDirectories) &&
+            !trackerChangedDeclaredProjectInput(tracker, declaredInputs, projectRoot) &&
             tracker?.membershipChanged !== true &&
             hostInputTracker?.membershipChanged !== true &&
             candidateTracker?.membershipChanged !== true;
@@ -5021,6 +5347,7 @@ async function captureTransformGeneration(props) {
         mergeGenerationProofFailures(failures, graphFailures);
         mergeGenerationProofFailures(failures, externalInputSnapshot.failures);
         const universalInputCapture = captureUniversalHostInputValidation(cached, props.currentFile);
+        restrictNotificationCoverageToProvenInputs(hostInputTracker, cached, universalInputCapture.validation);
         mergeGenerationProofFailures(failures, universalInputCapture.failures);
         const graphProofs = graphFailures.entries.length === 0 && graphFailures.omitted === 0;
         const universalInputs = universalInputCapture.validation !== undefined;
@@ -5043,7 +5370,9 @@ async function captureTransformGeneration(props) {
         // Attach notifications only while they can actually prove membership. A
         // generation that could not open its watchers keeps its recorded snapshot
         // and validates through it, rather than losing the cache entirely.
-        const notifying = stableProjectSnapshot && notificationsAvailable;
+        const notifying = props.retainProjectMembership &&
+            stableProjectSnapshot &&
+            notificationsAvailable;
         if (notifying && tracker !== undefined) {
             cached.projectMutationTracker = tracker;
         }
@@ -5135,6 +5464,25 @@ async function captureTransformGeneration(props) {
     }
     return captured;
 }
+/** Whether a compile-time content event overlaps any declared project input. */
+function trackerChangedDeclaredProjectInput(tracker, declared, projectRoot) {
+    if (tracker === undefined)
+        return false;
+    if (tracker.changesOmitted)
+        return true;
+    if (tracker.changes.size === 0)
+        return false;
+    if (declared === undefined)
+        return true;
+    const inputs = [...declared].map((input) => path.resolve(projectRoot, input));
+    for (const changed of tracker.changes) {
+        if (inputs.some((input) => tracker.overlaps?.(input, changed) ??
+            (pathIsWithin(input, changed) || pathIsWithin(changed, input)))) {
+            return true;
+        }
+    }
+    return false;
+}
 /** Exclude disposed transform scratch from live host-input tracking. */
 function selectPersistentHostInputs(props) {
     if (props.result.type === "exception")
@@ -5697,13 +6045,12 @@ function formatUnknownError(error) {
 /**
  * Remove terminal colour and cursor sequences from text the adapter surfaces.
  *
- * An ordinary type error reaches the adapter as an `"exception"` envelope whose
- * `error` is the host's own rendered output, colour and all, and the envelope
- * carries no structured diagnostics to format instead. What the adapter hands
- * back is not going to a terminal: it becomes the `Error` a bundler reports, so
- * it lands in a Vite overlay, a webpack error report or a CI annotation, where
- * the escapes render as literal noise around the file and line the reader needs
- * (samchon/ttsc#1312).
+ * An opaque host exception can contain the host's own rendered output, colour
+ * and all, with no structured diagnostics to format instead. What the adapter
+ * hands back is not going to a terminal: it becomes the `Error` a bundler
+ * reports, so it lands in a Vite overlay, a webpack error report or a CI
+ * annotation, where the escapes render as literal noise around the file and
+ * line the reader needs (samchon/ttsc#1312).
  *
  * The colour originates in the host's rendering rather than in anything this
  * adapter configures, so this is the adapter-side repair, applied to every