@ttsc/unplugin 0.30.2 → 0.30.4

package/src/core/transform.ts

@@ -129,6 +129,8 @@ interface TtscProjectMutationTracker {
    * whole, which cannot answer for one name.
    */
   covered?: ReadonlySet<string>;
+  /** Whether this is the repository-owned backend with content-event coverage. */
+  contentAuthoritative?: boolean;
   /**
    * Wait until every event this tracker's watcher has already dispatched has
    * been applied to it.
@@ -142,6 +144,8 @@ interface TtscProjectMutationTracker {
   drain?: () => Promise<void>;
   failed: boolean;
   membershipChanged: boolean;
+  /** Compare event and input paths through this tracker's filesystem identity. */
+  overlaps?: (input: string, changed: string) => boolean;
   settle?: Promise<void>;
 }
 
@@ -239,14 +243,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
@@ -316,6 +319,9 @@ 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;
 
@@ -563,6 +569,7 @@ export interface TtscTransformFilesystemOperations {
     directory: string,
     listener: (eventType: string, filename: string | null) => void,
     onError: () => void,
+    recursive?: boolean,
   ): { close: () => void };
 }
 
@@ -811,10 +818,12 @@ export interface TtscTransformHooks {
   addWatchFile?: (file: string, evidence?: TtscWatchInputEvidence) => void;
   /**
    * Batched form of {@link addWatchFile}. When supplied, the transform calls it
-   * once per delivered module and does not call `addWatchFile` for that
-   * module.
+   * once per delivered module and does not call `addWatchFile` for that module.
+   * `failed` marks a recovery batch: a failed compiler can omit inputs from its
+   * previous successful result, so replacing hosts should retain those
+   * spellings until the next successful delivery.
    */
-  addWatchFiles?: (inputs: readonly TtscWatchInput[]) => void;
+  addWatchFiles?: (inputs: readonly TtscWatchInput[], failed?: boolean) => void;
   /**
    * Invoked when the plugin declared the transformed file volatile (the
    * envelope's `volatile` list): its output depends on non-file inputs that no
@@ -985,6 +994,11 @@ export async function transformTtsc(
         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,
       });
@@ -1317,10 +1331,14 @@ interface TtscHostInputValidation {
     {
       path: string;
       /**
-       * Whether the recorded state of this input came from reading its bytes.
-       * An input that existed but could not be read records a missing state, so
-       * no signature may stand in for it: its metadata holds still while the
-       * bytes behind it appear.
+       * Whether the recorded state of this input has been matched to readable
+       * bytes. Capture sets it immediately for compiler-proven inputs; a
+       * current module supplied from an editor buffer can earn it later after
+       * its disk bytes match the recorded source.
+       *
+       * An input that still cannot be read records a missing state, so no
+       * signature may stand in for it: its metadata holds still while the bytes
+       * behind it appear.
        */
       readable: boolean;
       realpath: string | null;
@@ -1947,11 +1965,11 @@ function collectDeclaredIdentities(
  * 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: TtscTransformHooks | undefined,
@@ -2002,7 +2020,7 @@ function notifyFailedGenerationInputs(
     }
   }
   if (addWatchFiles !== undefined) {
-    addWatchFiles(inputs);
+    addWatchFiles(inputs, true);
     return;
   }
   for (const input of inputs) {
@@ -2749,6 +2767,28 @@ function matchesNarrowPersistentInputs(
   return true;
 }
 
+/** Whether a healthy notification scope proves one exact input unchanged. */
+function trackerProvesInputUnchanged(
+  tracker: TtscProjectMutationTracker | undefined,
+  input: string,
+): boolean {
+  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
@@ -2776,6 +2816,12 @@ function matchesProvenInput(
   state: TtscEnvelopeDerivation,
   input: string,
 ): boolean {
+  if (
+    trackerProvesInputUnchanged(cached.projectMutationTracker, input) ||
+    trackerProvesInputUnchanged(cached.hostInputMutationTracker, input)
+  ) {
+    return true;
+  }
   const observation = cached.externalInputObservations?.[path.resolve(input)];
   if (observation !== undefined) {
     if (
@@ -2785,7 +2831,25 @@ function matchesProvenInput(
     ) {
       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) {
@@ -2839,12 +2903,7 @@ function notifiesAbsence(
   cached: TtscCachedProjectTransform,
   input: string,
 ): boolean {
-  const tracker = cached.candidateMutationTracker;
-  return (
-    tracker !== undefined &&
-    !tracker.failed &&
-    tracker.covered?.has(path.resolve(input)) === true
-  );
+  return trackerProvesInputUnchanged(cached.candidateMutationTracker, input);
 }
 
 /**
@@ -2905,6 +2964,14 @@ function matchesUniversalHostInputs(
   cached: TtscCachedProjectTransform,
   validation: TtscHostInputValidation,
 ): boolean {
+  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)
@@ -2939,6 +3006,15 @@ function matchesUniversalHostInputEntries(
     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
     // recorded state came from reading nothing keeps its content comparison, a
@@ -3177,6 +3253,43 @@ function captureUniversalHostInputValidation(
   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: TtscProjectMutationTracker | undefined,
+  cached: TtscCachedProjectTransform,
+  hostValidation: TtscHostInputValidation | undefined,
+): void {
+  if (!(tracker?.covered instanceof Set)) return;
+  const covered = tracker.covered as Set<string>;
+  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
@@ -3313,6 +3426,8 @@ function disposeFilesystemClockReference(referenceDirectory: string): void {
 interface TtscInputMetadataEvidence {
   /** The joined metadata signature of the lexical path and its link target. */
   signature: string;
+  /** Whether a directory observer can account for every content mutation. */
+  notificationAuthoritative: boolean;
   /**
    * Whether a later write is guaranteed to move this signature. Only a
    * signature captured with this evidence may be recorded to stand in for a
@@ -3358,6 +3473,7 @@ function inputMetadataEvidence(
             link.ctimeNs,
             "missing-target",
           ].join(":"),
+          notificationAuthoritative: false,
           separable: false,
         };
       }
@@ -3366,17 +3482,26 @@ function inputMetadataEvidence(
       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.
@@ -3902,12 +4027,14 @@ function captureExternalInputSnapshot(
         });
         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) {
         recordGenerationProofFailure(failures, {
@@ -3916,6 +4043,7 @@ function captureExternalInputSnapshot(
           path: input,
         });
       }
+      if (mismatches.length === 0) record(input, before, after);
       observations[spelling] = predicateObservation;
       continue;
     }
@@ -4291,12 +4419,14 @@ function collectProjectInputSnapshot(
   directoryComplete: boolean;
   fileSignatures: Record<string, string>;
   hashes: Record<string, string>;
+  notificationUnsafeInputs: Set<string>;
   projectDirectories: TtscProjectDirectorySnapshot[];
   provenSignatures: Record<string, string>;
   unstableFiles: Set<string>;
   walkFailures: TtscProjectWalkFailure[];
 } {
   const hashes: Record<string, string> = {};
+  const notificationUnsafeInputs = new Set<string>();
   const fileSignatures: Record<string, string> = {};
   const provenSignatures: Record<string, string> = {};
   const unstableFiles = new Set<string>();
@@ -4321,6 +4451,9 @@ function collectProjectInputSnapshot(
         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
@@ -4339,24 +4472,27 @@ function collectProjectInputSnapshot(
         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;
         }
       }
     } catch {
@@ -4378,6 +4514,7 @@ function collectProjectInputSnapshot(
     directoryComplete: walked.complete && attributed,
     fileSignatures,
     hashes,
+    notificationUnsafeInputs,
     projectDirectories: walked.directories,
     provenSignatures,
     unstableFiles,
@@ -4618,13 +4755,14 @@ function openDirectoryWatch(
   directory: string,
   listener: (eventType: string, filename: string | null) => void,
   onError: () => void,
+  recursive = false,
 ): { close: () => void } {
   if (filesystem.watch !== undefined) {
-    return filesystem.watch(directory, listener, onError);
+    return filesystem.watch(directory, listener, onError, recursive);
   }
   const watcher = fs.watch(
     directory,
-    { persistent: false },
+    { persistent: false, recursive },
     (eventType, filename) =>
       listener(eventType, filename === null ? null : String(filename)),
   );
@@ -4653,140 +4791,289 @@ function closeDirectoryWatches(watchers: { close: () => void }[]): void {
 /** Watch every walked directory for membership changes after generation. */
 async function createProjectMutationTracker(
   directories: readonly TtscProjectDirectorySnapshot[],
+  covered: ReadonlySet<string>,
   filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
   policy: ITtscProjectMembershipPolicy = PERMISSIVE_PROJECT_MEMBERSHIP_POLICY,
 ): Promise<TtscProjectMutationTracker> {
+  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<string>()
+      : covered;
   const tracker: TtscProjectMutationTracker = {
     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: string, filename: string): boolean => {
+    const changed = path.join(location, filename);
+    return (
+      knownDirectories.has(path.resolve(changed)) ||
+      reportsProgramMembership(
+        changed,
+        path.basename(filename),
+        policy,
+        filesystem,
+      )
+    );
+  };
+  const reportsNewMembership = (
+    location: string,
+    filename: string,
+  ): boolean => {
+    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 })),
+      [{ directory: root, recursive: true }],
       false,
       filesystem,
-      (location, filename) =>
-        reportsProgramMembership(
-          path.join(location, filename),
-          filename,
-          policy,
-          filesystem,
-        ),
+      reportsMembership,
+      (_location, filename) =>
+        isPossibleProgramFileName(path.basename(filename), policy),
+      reportsNewMembership,
     );
     return tracker;
   }
   const watchers: { close: () => void }[] = [];
-  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.failed = true;
-    }
+  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: readonly string[],
+): string | undefined {
+  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: readonly string[],
   filesystem: TtscTransformFilesystemOperations,
   covered: ReadonlySet<string>,
   events: "all" | "rename" = "all",
+  preferredRoot?: string,
 ): Promise<TtscProjectMutationTracker> {
   const identities = createHostPathIdentityContext(filesystem);
-  const namesByDirectory = new Map<
+  const linkedAncestors = new Map<string, boolean>();
+  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<
     string,
-    { directory: string; names: Set<string> }
+    {
+      directory: string;
+      names: Set<string>;
+      paths?: Set<string>;
+      recursive?: boolean;
+    }
   >();
+  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<string>(),
+        ...(internal ? { paths: new Set<string>(), 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: TtscProjectMutationTracker = {
     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: string, filename: string): boolean => {
+    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,
+      locations.map((location) => ({
+        directory: location.directory,
+        ...(location.recursive === true
+          ? { recursive: true }
+          : { names: [...location.names] }),
+      })),
       events === "all",
       filesystem,
+      matches,
+      matches,
     );
     return tracker;
   }
   const watchers: { close: () => void }[] = [];
-  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,
@@ -4795,22 +5082,22 @@ async function createHostInputMutationTracker(
             if (events === "rename" && eventType !== "rename") {
               return;
             }
-            const reported =
-              filename === null
-                ? null
-                : normalizeHostInputName(filename, caseSensitive);
-            if (reported === null || names.has(reported)) {
-              recordProjectMutation(
-                tracker,
+            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 {
@@ -4820,6 +5107,47 @@ async function createHostInputMutationTracker(
   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: string,
+  filesystem: TtscTransformFilesystemOperations,
+  memo: Map<string, boolean>,
+): boolean {
+  const visited: string[] = [];
+  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.
  *
@@ -4914,6 +5242,14 @@ function recordProjectMutation(
   changed: string,
 ): void {
   tracker.membershipChanged = true;
+  recordProjectChange(tracker, changed);
+}
+
+/** Record a content event without classifying it as a membership change. */
+function recordProjectChange(
+  tracker: TtscProjectMutationTracker,
+  changed: string,
+): void {
   if (tracker.changes.has(changed)) return;
   if (tracker.changes.size < MAX_GENERATION_MUTATION_PATHS) {
     tracker.changes.add(changed);
@@ -4941,6 +5277,10 @@ interface WindowsProjectMutationBroker {
        * have already narrowed theirs by construction.
        */
       membership?: (location: string, filename: string) => boolean;
+      /** Whether one named event can change compiler-consumed content. */
+      content?: (location: string, filename: string) => boolean;
+      /** Classify a backend `change` that can add one unknown program path. */
+      changeAddsMembership?: (location: string, filename: string) => boolean;
       ready: () => void;
       /**
        * The walk's own spelling for each canonical directory the child watches,
@@ -4962,6 +5302,7 @@ let windowsProjectMutationBroker: WindowsProjectMutationBroker | undefined;
 interface WindowsMutationLocation {
   directory: string;
   names?: string[];
+  recursive?: boolean;
 }
 
 /**
@@ -4982,6 +5323,8 @@ async function registerWindowsProjectMutationTracker(
    * name-watching trackers pass none, since they already watch exact names.
    */
   membership?: (location: string, filename: string) => boolean,
+  content?: (location: string, filename: string) => boolean,
+  changeAddsMembership?: (location: string, filename: string) => boolean,
 ): Promise<void> {
   const broker = getWindowsProjectMutationBroker();
   // The child watches canonical directories, and reports its events under that
@@ -5002,24 +5345,30 @@ async function registerWindowsProjectMutationTracker(
     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!: () => void;
   const ready = new Promise<void>((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;
     broker.trackers.delete(id);
@@ -5071,7 +5420,7 @@ async function registerWindowsProjectMutationTracker(
     // exit mid-build.
     if (broker.pendingRegistrations === 0 && broker.pendingDrains === 0) {
       broker.child.unref();
-      broker.child.channel?.unref();
+      broker.child.channel?.unref?.();
     }
   }
 }
@@ -5116,6 +5465,7 @@ function getWindowsProjectMutationBroker(): WindowsProjectMutationBroker {
       drained?: boolean;
       failed?: boolean;
       filename?: string | null;
+      eventType?: string;
       id?: number;
       ready?: boolean;
     };
@@ -5138,19 +5488,33 @@ function getWindowsProjectMutationBroker(): WindowsProjectMutationBroker {
         // 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;
       }
@@ -5199,7 +5563,7 @@ function startWindowsProjectMutationDrain(
       broker.pendingDrains -= 1;
       if (broker.pendingDrains === 0 && broker.pendingRegistrations === 0) {
         broker.child.unref();
-        broker.child.channel?.unref();
+        broker.child.channel?.unref?.();
       }
       resolve();
     };
@@ -5210,7 +5574,7 @@ function startWindowsProjectMutationDrain(
     // 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) {
@@ -5242,9 +5606,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);",
@@ -5266,16 +5630,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: TtscCachedProjectTransform): boolean {
-  return (
-    cached.projectMutationTracker?.membershipChanged === true ||
-    cached.hostInputMutationTracker?.membershipChanged === true ||
-    cached.candidateMutationTracker?.membershipChanged === true
-  );
+  return cached.projectMutationTracker?.membershipChanged === true;
 }
 
 /**
@@ -5326,11 +5692,18 @@ function drainOnNextTurn(): Promise<void> {
 async function settleProjectMutationEvents(
   cached: TtscCachedProjectTransform,
 ): Promise<void> {
-  const trackers = [
+  await settleMutationTrackers([
     cached.projectMutationTracker,
     cached.hostInputMutationTracker,
     cached.candidateMutationTracker,
-  ].filter(
+  ]);
+}
+
+/** Settle one set of optional trackers through one shared barrier each. */
+async function settleMutationTrackers(
+  candidates: readonly (TtscProjectMutationTracker | undefined)[],
+): Promise<void> {
+  const trackers = candidates.filter(
     (tracker): tracker is TtscProjectMutationTracker => tracker !== undefined,
   );
   await Promise.all(
@@ -5712,15 +6085,26 @@ function matchesCachedExternalInputs(cached: TtscCachedProjectTransform): {
     const spelling = path.resolve(file);
     const observation = cached.externalInputObservations?.[spelling];
     if (observation !== undefined) {
+      const before = inputMetadataEvidence(file, filesystem);
       if (
-        !matchesGraphInputObservation(
-          file,
-          observation,
-          filesystem,
-          state.identityContext,
-        )
+        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;
     }
@@ -6328,6 +6712,7 @@ function declaredProjectInputKeys(
   if (state.declaredInputKeysBuilt !== true) {
     state.declaredInputKeys = selectDeclaredProjectInputKeys({
       identities: state.identityContext,
+      projectInputHashes: cached.inputHashes,
       projectRoot: cached.projectRoot,
       result: cached.result,
       scratchDirectory: cached.scratchDirectory,
@@ -6340,11 +6725,16 @@ function declaredProjectInputKeys(
 /**
  * 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: {
   identities: FilesystemPathIdentityContext;
+  projectInputHashes: Readonly<Record<string, string>>;
   projectRoot: string;
   result: ITtscCompilerTransformation;
   scratchDirectory?: string;
@@ -6358,7 +6748,10 @@ function selectDeclaredProjectInputKeys(props: {
     if (typeof entry !== "string" || entry.length === 0) return;
     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);
@@ -6690,6 +7083,7 @@ async function transformProject(props: {
   deliveryEpoch?: number;
   filesystem: TtscTransformFilesystemOperations;
   plugins?: ResolvedTtscUnpluginOptions["plugins"];
+  retainProjectMembership: boolean;
   trackProjectMembership: boolean;
   tsconfig: string;
 }): Promise<TtscCachedProjectTransform> {
@@ -6698,8 +7092,7 @@ async function transformProject(props: {
     const cached = await captureTransformGeneration(props);
     if (
       cached.configStateComplete !== false &&
-      (!props.trackProjectMembership ||
-        cached.result.type !== "success" ||
+      (cached.result.type !== "success" ||
         cached.projectSnapshotComplete === true)
     ) {
       return cached;
@@ -6738,6 +7131,7 @@ async function captureTransformGeneration(props: {
   deliveryEpoch?: number;
   filesystem: TtscTransformFilesystemOperations;
   plugins?: ResolvedTtscUnpluginOptions["plugins"];
+  retainProjectMembership: boolean;
   trackProjectMembership: boolean;
   tsconfig: string;
 }): Promise<TtscCachedProjectTransform> {
@@ -6756,7 +7150,7 @@ async function captureTransformGeneration(props: {
   let retainCandidateTracker = false;
   let captured: TtscCachedProjectTransform | undefined;
   try {
-    if (props.trackProjectMembership) {
+    if (props.retainProjectMembership) {
       try {
         clockReferenceDirectory = createTransformScratchDirectory(
           projectRoot,
@@ -6807,6 +7201,11 @@ async function captureTransformGeneration(props: {
     tracker = props.trackProjectMembership
       ? 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,
         )
@@ -6846,15 +7245,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,
@@ -6863,14 +7273,18 @@ async function captureTransformGeneration(props: {
           temporaryTsconfig,
         })
       : { candidates: [], watched: [] };
-    hostInputTracker = props.trackProjectMembership
+    hostInputTracker = props.retainProjectMembership
       ? await createHostInputMutationTracker(
-          persistentHostInputs,
+          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,
@@ -6887,16 +7301,9 @@ async function captureTransformGeneration(props: {
             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,
@@ -6911,10 +7318,16 @@ 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) &&
@@ -6929,6 +7342,11 @@ async function captureTransformGeneration(props: {
         before.projectDirectories,
         inputSnapshot.projectDirectories,
       ) &&
+      !trackerChangedDeclaredProjectInput(
+        tracker,
+        declaredInputs,
+        projectRoot,
+      ) &&
       tracker?.membershipChanged !== true &&
       hostInputTracker?.membershipChanged !== true &&
       candidateTracker?.membershipChanged !== true;
@@ -7027,6 +7445,11 @@ async function captureTransformGeneration(props: {
       cached,
       props.currentFile,
     );
+    restrictNotificationCoverageToProvenInputs(
+      hostInputTracker,
+      cached,
+      universalInputCapture.validation,
+    );
     mergeGenerationProofFailures(failures, universalInputCapture.failures);
     const graphProofs =
       graphFailures.entries.length === 0 && graphFailures.omitted === 0;
@@ -7059,7 +7482,10 @@ 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;
     }
@@ -7152,6 +7578,31 @@ async function captureTransformGeneration(props: {
   return captured;
 }
 
+/** Whether a compile-time content event overlaps any declared project input. */
+function trackerChangedDeclaredProjectInput(
+  tracker: TtscProjectMutationTracker | undefined,
+  declared: ReadonlySet<string> | undefined,
+  projectRoot: string,
+): boolean {
+  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: {
   filesystem: TtscTransformFilesystemOperations;
@@ -7858,13 +8309,12 @@ function formatUnknownError(error: unknown): string {
 /**
  * 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