ttsc 0.30.3 → 0.31.0

package/src/launcher/internal/{watchTopology.ts → watch/WatchTopology.ts}

@@ -2,84 +2,70 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-import { readJsoncFile } from "../../compiler/internal/project/readConfigJson";
-import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
-import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
-import { outputText, spawnNative } from "../../compiler/internal/spawnNative";
-import { resolveFlagSpec } from "../../flags/schema";
-import {
-  type ProjectInputPathIdentity,
-  type ProjectInputPathIdentityContext,
-  createProjectInputPathIdentityContext,
-  isProjectInputPathIdentityWithin,
-  resolveProjectInputPath,
-} from "../../internal/projectInputPathIdentity";
-import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
-import type { ITtscProjectInputSnapshot } from "../../structures/internal/ITtscProjectInputSnapshot";
-import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
-import { resolveSingleFileOutput } from "./singleFileOutput";
-
-type WatchTopologyOptions = Pick<
-  TtscBuildOptions,
-  | "binary"
-  | "emit"
-  | "env"
-  | "outDir"
-  | "passthrough"
-  | "projectRoot"
-  | "tsconfig"
-> & {
-  cwd: string;
-  files: readonly string[];
-};
-
-type WatchTopologyCallbacks = {
-  onError(location: string, error: unknown): void;
-  onInputChange(change: WatchInputChange): void;
-  onProjectInputWatchUnavailable?(roots: readonly string[]): void;
-  onProjectInputWatchRoots?(roots: readonly string[]): void;
-  onTopologyChange(): void;
-};
-
-export type WatchInputChange = {
-  /** Keep the resident process but cold-load its compiler Program. */
-  invalidate?: boolean;
-  kind: "compiler" | "config" | "plugin" | "project";
-  path?: string;
-};
-
-type ResolvedWatchTopology = {
-  analysisOnly: boolean;
-  directories: Map<string, string>;
-  files: Map<string, string>;
-  outputFiles: Map<string, string>;
-  outputs: Map<string, string>;
-  reloadFiles: Map<string, string>;
-};
-
-type CompilerFileSnapshot = {
-  content: string;
-  owner: string;
-};
-
-type CompilerFileMovement = {
-  content: boolean;
-  owner: boolean;
-};
-
-export type CompilerDirectoryWatchEventPlan = {
-  changes: string[];
-  rearm: string[];
-  refresh: boolean;
-};
+import { outputText } from "../../../compiler/internal/outputText";
+import { CompilerProjectSelection } from "../../../compiler/internal/project/CompilerProjectSelection";
+import { readJsoncFile } from "../../../compiler/internal/project/readJsoncFile";
+import { readProjectConfig } from "../../../compiler/internal/project/readProjectConfig";
+import { resolveTsgo } from "../../../compiler/internal/resolveTsgo";
+import { spawnNative } from "../../../compiler/internal/spawnNative";
+import { normalizeCompilerEnumValue } from "../../../flags/normalizeCompilerEnumValue";
+import { readCompilerOptionValues } from "../../../flags/readCompilerOptionValues";
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import { isProjectInputPathIdentityWithin } from "../../../internal/pathIdentity/isProjectInputPathIdentityWithin";
+import { resolveProjectInputPath } from "../../../internal/pathIdentity/resolveProjectInputPath";
+import { collectPluginSourceDirectories } from "../../../plugin/internal/source/collectPluginSourceDirectories";
+import { pluginSourceCovers } from "../../../plugin/internal/source/pluginSourceCovers";
+import { pluginSourceDigest } from "../../../plugin/internal/source/pluginSourceDigest";
+import { prunesPluginSourceDirectory } from "../../../plugin/internal/source/prunesPluginSourceDirectory";
+import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOptions";
+import { resolveSingleFileOutput } from "../resolveSingleFileOutput";
+import type { DirectoryWatcher } from "./DirectoryWatcher";
+import { ProjectInputWatchRules } from "./ProjectInputWatchRules";
+import type { WatchInputChange } from "./WatchInputChange";
+import { WatchPaths } from "./WatchPaths";
+import { literalGlobRoot } from "./literalGlobRoot";
+import { planCompilerDirectoryWatchEvent } from "./planCompilerDirectoryWatchEvent";
+import { projectInputActiveWatchDirectories } from "./projectInputActiveWatchDirectories";
+import { projectInputAvailableWatchDirectory } from "./projectInputAvailableWatchDirectory";
+import { projectInputEventShouldNotify } from "./projectInputEventShouldNotify";
+import { projectInputMembershipInvalidatesProgram } from "./projectInputMembershipInvalidatesProgram";
+import { projectInputReloadEventShouldNotify } from "./projectInputReloadEventShouldNotify";
+import { projectInputReplacementStrandsWatchers } from "./projectInputReplacementStrandsWatchers";
+import { projectInputTopologyMayAffect } from "./projectInputTopologyMayAffect";
+import { reloadInputsForFailedTopologyRefresh } from "./reloadInputsForFailedTopologyRefresh";
+import { syncWatchers } from "./syncWatchers";
+import { watchDirectory } from "./watchDirectory";
 
 /**
  * Keeps the launcher watch set aligned with the compiler's current program.
  *
- * TypeScript-Go's `--listFilesOnly` output is the authority for source and
- * declaration inputs. Configuration files, project-reference roots, and the
- * source trees of selected native plugins supplement that list, while compiler
- * outputs are filtered before any watcher is installed.
+ * The default compiler-input reader uses TypeScript-Go's `--listFilesOnly`
+ * output for source and declaration membership. An explicit reader supplies the
+ * same absolute-path membership and failure contract for each resolved project.
+ * Configuration files, project-reference roots, output inference and native
+ * filesystem identity remain this topology's responsibility.
+ * Response frames are observed once per project refresh at its compiler cwd;
+ * that option view serves all project-output queries while the original argv
+ * reaches compiler membership. A second observation rejects response changes
+ * across membership resolution. Response files join the config reload set;
+ * these observations do not pin files or detect a change restored in between.
+ *
+ * `TTSC_WATCH_DEBUG_INPUTS` reports the named event, observed population deltas
+ * and reload decision. These diagnostics reuse the decision's existing inputs;
+ * they perform no extra filesystem observations.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler-input operation's membership, published rule inputs and actual content fingerprints qualify notifications; its native default obtains the real compiler list. Post-registration reconciliation compares baselines to recover observed handoff changes, not an atomic guarantee against every transient mutation. Explicit operations preserve native defaults without replacing global filesystem or compiler methods. Project-input attribution: Observed member deltas establish attribution; stale selected names cannot override them, while directory names retain supported population causality and unrelated multiple members remain unnamed.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler, plugin and project-input watch populations keep their own baselines and callbacks under one topology owner; small classifiers separate membership, selection and handle replacement. Four distinct operations own directory subscriptions, file subscriptions, immediate reload-directory reads and compiler membership; existing callers need no new argument. Project-input attribution: One private reconciliation separates member deltas from immediate resolution-directory digests before choosing a supported event name or an observed single member.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported native backends and explicit gap/replacement ownership replace foreign watcher patching; failed observation is reported rather than represented as complete coverage. The constructor manufactures no observations and bypasses no input or content proof; supplied operations retain the existing callback and result contracts. Project-input attribution: Native event names do not manufacture a delta; the current and previous physical membership identify already observed names without filename or fixture exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain membership authority, plugin fingerprinting, publication races, physical registration and public lifecycle operations following the documentation skill. Parameters identify each supplied operation and native default beside the constructor. Project-input attribution: Native paragraphs explain stale attention, directory causality, accompanying resolution digests and unselected immediate entries.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths use Node APIs and registration uses realpath; compiler/plugin maps preserve lexical aliases and fold only measured insensitive ASCII components. Project inputs use physical identities, while unknown/native Unicode relations remain conservative event candidates rather than identity proof. Registration paths and read options are passed unchanged; compiler-input readers supply absolute membership paths without replacing the topology's native identity policy. Project-input attribution: The supplied filesystem identity transaction establishes selected names and ancestry without an OS-wide case assumption or lexical alias guess.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms Identity-keyed maps separate membership, baselines and handle registries; reconciliation delegates project/config discovery, native compiler listing, filesystem traversal/hashing and backend callbacks, with costs described by its members. Construction retains operation references and empty indexes without a filesystem observation or build. Attribution indexed visits additionally pay path/key text, ancestor and native identity work; shared ancestor keys avoid repeating the same walk within a transaction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Current membership, content baselines and live registrations belong to one topology; reconciliation owners decide their reuse against fresh premises. Supplied operation identities are retained without adding an observation-result cache or assuming changed inputs remain equivalent. Project-input attribution: This classifier borrows one scan's deltas and identity transaction without retaining cross-event answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Current and pending maps and live subscriptions remain topology-owned without a population cap; reconciliation attempts obsolete handle retirement. Constructor acquires no handle; directory arrays and attribution deltas are call-local. close invokes supplied close methods but does not await backend closure, and a thrown close can interrupt later map cleanup; retained snapshots remain until the facade is released.
  */
 export class WatchTopology {
   private analysisOnly = false;
@@ -88,11 +74,31 @@ export class WatchTopology {
   private compilerPostRegistrationReconciliationScheduled = false;
   private compilerPostRegistrationSkipUnobservedProjectInputWatchRoots = true;
   private directories = new Map<string, string>();
-  private directoryWatchers = new Map<string, fs.FSWatcher>();
+  private directoryWatchers = new Map<string, DirectoryWatcher>();
   private extraInputs: readonly string[] = [];
-  private extraWatchers = new Map<string, fs.FSWatcher>();
+
+  /**
+   * What each plugin input held when last observed, by path key: the digest a
+   * plugin build keys it on (`pluginInputState`). A notification about an input
+   * whose state did not move is not a plugin change.
+   */
+  private pluginInputStates = new Map<string, string>();
+
+  /**
+   * The plugin inputs notifications named since the last decision, by path key,
+   * each with the locations noted for it (`notePluginNotification`).
+   */
+  private pendingPluginNotifications = new Map<string, Set<string>>();
+  private pluginNotificationsScheduled = false;
+  private extraWatchers = new Map<string, DirectoryWatcher>();
+
+  /** The plugin inputs whose directories the last sync already watched. */
+  private watchedExtraInputs = new Set<string>();
   private compilerFileSnapshots = new Map<string, CompilerFileSnapshot>();
   private files = new Map<string, string>();
+  private lexicalIdentities = createProjectInputPathIdentityContext({
+    throwOnRealpathError: false,
+  });
   private fileWatchers = new Map<string, fs.FSWatcher>();
   private observedDirectories = new Map<string, string>();
   private outputFiles = new Map<string, string>();
@@ -119,21 +125,53 @@ export class WatchTopology {
   private projectInputRequiredWatchRoots = new Map<string, string>();
   private projectInputUnobservedWatchRoots = new Map<string, string>();
   private projectInputWatchRoots = new Map<string, string>();
-  private projectInputWatchers = new Map<string, fs.FSWatcher>();
-  private projectInputLinkWatchers = new Map<string, fs.FSWatcher>();
+  private projectInputWatchers = new Map<string, DirectoryWatcher>();
+  private projectInputLinkWatchers = new Map<string, DirectoryWatcher>();
   private projectInputCompilerOutputOverlaps = new WeakMap<
     ProjectInputPathIdentityContext,
     Map<string, boolean>
   >();
-  private projectInputCompilerAcknowledgements = new Map<string, string>();
   private reloadFiles = new Map<string, string>();
 
+  /**
+   * @param options What to watch.
+   * @param callbacks What to tell about it.
+   * @param openDirectoryWatch The backend every directory watch goes through:
+   *   `watchDirectory`, which chooses the platform's, unless the caller
+   *   observes the watch set through another.
+   * @param openFileWatch File subscriptions use this owned observer; native
+   *   fs.watch by default.
+   * @param readDirectory Immediate reload-directory fingerprints use this
+   *   reader; native readdirSync by default.
+   * @param getCompilerInputs Read each resolved project's absolute compiler
+   *   membership; the default invokes the native compiler. Readers throw
+   *   listing failures and retain ownership of their returned array, which this
+   *   topology does not mutate.
+   */
   public constructor(
     private readonly options: WatchTopologyOptions,
     private readonly callbacks: WatchTopologyCallbacks,
+    private readonly openDirectoryWatch: typeof watchDirectory = watchDirectory,
+    private readonly openFileWatch: typeof fs.watch = fs.watch,
+    private readonly readDirectory: typeof fs.readdirSync = fs.readdirSync,
+    private readonly getCompilerInputs: typeof listCompilerInputs = listCompilerInputs,
   ) {}
 
-  /** Re-resolve compiler inputs and notify only when their membership changed. */
+  /**
+   * Re-resolve compiler inputs and notify when the resolved topology changes,
+   * including membership, output/configuration or analysis-mode changes. Errors
+   * propagate to the caller; native watcher registration failures are reported
+   * through onError while previous coverage remains live.
+   *
+   * @evidence contracts/common.md#principled-implementation The compiler-input operation defines membership and its native default reads the actual compiler list; new coverage is registered before stale coverage retires, and registration reconciliation compares against pre-registration baselines.
+   * @evidence contracts/common.md#clear-and-simple-design One refresh delegates compiler population resolution, watcher synchronization and notification classification to separate private owners.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Predicted outputs never subtract from compiler-reported inputs; failed registration cannot claim complete replacement coverage.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states notification gating, thrown errors and registration error ownership following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Compiler processes use explicit argv/env; native APIs own path grammar and backend differences. Lexical membership uses measured component case policy, keeping unknown names and symlink aliases distinct instead of folding all Windows paths.
+   * @evidence contracts/performance.md#efficient-algorithms Project/reference configuration discovery, output inference and supplied/native compiler listing precede file/key snapshot passes. Native path/case/ancestor work and newly admitted file hashing add text/byte costs; broad reconciliation stats tracked files and strongly reads metadata/owner movement, while named/gap events request strong reads. Windows directory pruning is pairwise, and extra/project watcher reconciliation adds its own scans and backend callback costs without a file-count or deadline cap.
+   * @evidence contracts/performance.md#reuse-equivalent-work Existing live watchers and unchanged fingerprints are reused by key; one fresh synchronous transaction shares parent case probes across membership, output and directory keys. One current root selection shares response inspection across referenced-project output queries; response observations are checked again after membership and never cached across refreshes. Registration microtasks coalesce gap work while actual compiler membership is refreshed rather than inferred from quiet notifications.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Current snapshots prune removed members and synchronization attempts obsolete handle closure, keeping old coverage after incomplete registration. Current/recovery populations and observations have no size cap; supplied close/error callbacks can throw and close does not await backend completion. State remains owner-held until released.
+   */
   public refresh(notify: boolean): void {
     this.refreshCompilerInputs(notify, false);
   }
@@ -142,12 +180,18 @@ export class WatchTopology {
     notify: boolean,
     skipUnobservedProjectInputWatchRoots: boolean,
   ): void {
-    const next = resolveWatchTopology(this.options, this.extraInputs);
+    this.beginLexicalTransaction();
+    const next = resolveWatchTopology(
+      this.options,
+      this.extraInputs,
+      this.lexicalIdentities,
+      this.getCompilerInputs,
+    );
     const compilerProgramMembershipChange =
       next.analysisOnly &&
-      mapsEqual(this.reloadFiles, next.reloadFiles) &&
-      mapsEqual(this.outputFiles, next.outputFiles) &&
-      mapsEqual(this.outputs, next.outputs)
+      WatchPaths.mapsEqual(this.reloadFiles, next.reloadFiles) &&
+      WatchPaths.mapsEqual(this.outputFiles, next.outputFiles) &&
+      WatchPaths.mapsEqual(this.outputs, next.outputs)
         ? compilerMembershipChange(this.files, next.files)
         : [];
     const projectInputProgramOverlap = projectInputCompilerMembershipChange(
@@ -162,11 +206,11 @@ export class WatchTopology {
         : undefined;
     const changed =
       this.analysisOnly !== next.analysisOnly ||
-      mapsEqual(this.files, next.files) === false ||
-      mapsEqual(this.directories, next.directories) === false ||
-      mapsEqual(this.outputFiles, next.outputFiles) === false ||
-      mapsEqual(this.outputs, next.outputs) === false ||
-      mapsEqual(this.reloadFiles, next.reloadFiles) === false;
+      WatchPaths.mapsEqual(this.files, next.files) === false ||
+      WatchPaths.mapsEqual(this.directories, next.directories) === false ||
+      WatchPaths.mapsEqual(this.outputFiles, next.outputFiles) === false ||
+      WatchPaths.mapsEqual(this.outputs, next.outputs) === false ||
+      WatchPaths.mapsEqual(this.reloadFiles, next.reloadFiles) === false;
     this.analysisOnly = next.analysisOnly;
     this.files = next.files;
     // Stamp the tracked set as it is resolved, so the first event that cannot
@@ -180,18 +224,16 @@ export class WatchTopology {
       // has a baseline would advance it past a change nobody reported, and the
       // next unnamed event would then read that change as no change at all.
       if (!this.compilerFileSnapshots.has(key)) {
-        this.compilerFileSnapshots.set(key, compilerFileSnapshot(file));
+        this.compilerFileSnapshots.set(
+          key,
+          compilerFileSnapshot(file, fingerprintProjectInputFile(file)),
+        );
       }
     }
     this.directories = next.directories;
     this.outputFiles = next.outputFiles;
     this.outputs = next.outputs;
     this.reloadFiles = next.reloadFiles;
-    for (const key of this.projectInputCompilerAcknowledgements.keys()) {
-      if (!next.files.has(key)) {
-        this.projectInputCompilerAcknowledgements.delete(key);
-      }
-    }
     const projectInputProgramReload =
       projectInputProgramOverlap.length === 0
         ? false
@@ -237,17 +279,17 @@ export class WatchTopology {
    * project watcher names the same creation. The rebuild scheduled here already
    * consumes the current project bytes, so publishing their strong fingerprints
    * keeps the later parent event from rediscovering the same population delta.
-   * A newly tracked compiler file also remembers that fingerprint until its
-   * first named content delivery; identical bytes are the delayed creation,
-   * while different bytes are a real later edit and remain observable even
-   * inside filesystem timestamp resolution.
+   * Compiler files keep their own content fingerprints at admission, so a
+   * delayed named event for the same bytes is quiet on every backend.
    */
   private acknowledgeProjectInputCompilerMembership(
     changed: readonly string[],
   ): boolean {
     const matches = this.collectProjectInputMatches();
-    const fingerprints = fingerprintProjectInputMatches(matches);
-    const identities = createProjectInputPathIdentityContext();
+    const fingerprints = fingerprintProjectInputMatches(
+      matches,
+      this.readDirectory,
+    );
     const changedInputs = projectInputChangedPaths({
       next: matches,
       nextFingerprints: fingerprints,
@@ -259,13 +301,19 @@ export class WatchTopology {
       changed,
       population.globs,
     );
-    const reload = projectInputReloadEventShouldNotify({
+    const reloadInput = {
       causedBy,
       changed: causedBy.length === 1 ? causedBy[0] : undefined,
       changedInputs,
       globs: population.globs,
       reloadDirectories: population.reloadDirectories,
       reloadFiles: population.reloadFiles ?? [],
+    };
+    const reload = projectInputReloadEventShouldNotify(reloadInput);
+    reportProjectInputDecision({
+      source: "compiler-membership",
+      ...reloadInput,
+      reload,
     });
     // The callback below consumes the complete population observed by this
     // scan. Crucially, reload classification runs against the old baseline
@@ -273,28 +321,58 @@ export class WatchTopology {
     // instead of disappearing behind the warm compiler-membership handoff.
     this.projectInputMatches = matches;
     this.projectInputFingerprints = fingerprints;
-    for (const location of changed) {
-      const compilerKey = pathKey(location);
-      if (!this.files.has(compilerKey)) continue;
-      const fingerprint = fingerprints.get(identities.resolve(location).key);
-      if (fingerprint !== undefined && fingerprint !== "") {
-        this.projectInputCompilerAcknowledgements.set(compilerKey, fingerprint);
-      }
-    }
     return reload;
   }
 
-  /** Add Go plugin source trees discovered by the real build lane. */
+  /**
+   * Add Go plugin source trees discovered by the real build lane. Existing
+   * input fingerprints retain their baseline; new inputs are captured before
+   * the caller builds them, so later notifications can compare that
+   * observation. This does not freeze the source tree or prove every transient
+   * edit was seen.
+   *
+   * @evidence contracts/common.md#principled-implementation Published plugin inputs define the source corpus, and retaining existing pre-build baselines keeps unreported edits visible.
+   * @evidence contracts/common.md#clear-and-simple-design Deduplication, baseline retention and compiler/watch reconciliation remain ordered phases.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual plugin source digest applies its owning source-selection and pruning policy; named plugins or fixture output do not replace observed input state.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains baseline timing and why existing inputs are not restamped following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and canonical backend registration govern source trees; lexical keys preserve declarations and unknown names, folding ASCII only under measured insensitive parents rather than an OS-derived rule.
+   * @evidence contracts/performance.md#efficient-algorithms Input/path keys deduplicate with text and native case/ancestor work; only newly admitted inputs compute initial source digests. Those reads scan the selected pruned corpus, then refresh(false) also pays project/compiler listing, directory traversal and watcher reconciliation; fixed publication count does not bound delegated bytes or backend work.
+   * @evidence contracts/performance.md#reuse-equivalent-work Unchanged ordered input sets return immediately; existing inputs reuse their recorded digest until actual notification processing establishes changed consumed state.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Publications replace input/digest populations and case-observation caches without a population cap; synchronization attempts obsolete watcher closure. Native/supplied closure has its own lifetime and can throw; owner close does not prove every backend has stopped or every retained snapshot byte was released.
+   */
   public setExtraInputs(inputs: readonly string[]): void {
-    const next = uniqueExistingPaths(inputs);
+    this.beginLexicalTransaction();
+    const next = uniqueExistingPaths(inputs, this.lexicalIdentities);
     if (arraysEqual(this.extraInputs, next)) return;
     this.extraInputs = next;
+    // The load reports its inputs before any build reads them, so the state
+    // recorded here precedes every read, and an edit after it moves the state.
+    // An input already tracked keeps its baseline: restamping it would absorb
+    // a change nobody reported.
+    const states = new Map<string, string>();
+    for (const input of next) {
+      const key = this.pathKey(input);
+      states.set(
+        key,
+        this.pluginInputStates.get(key) ?? pluginInputState(input),
+      );
+    }
+    this.pluginInputStates = states;
     this.refresh(false);
   }
 
   /**
    * Reconcile project-rule dependencies, retaining absent files and empty glob
    * populations as live topology.
+   *
+   * @evidence contracts/common.md#principled-implementation Both lexical declarations and current physical identities remain observable, including missing members and empty globs; republication can update aliased watcher ownership without requiring population movement.
+   * @evidence contracts/common.md#clear-and-simple-design Publication normalization, baseline population capture and root synchronization are separate stages, with one retained declaration-owner map.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing inputs are not dropped from observation, and an unavailable safe root is reported rather than widened over a system ancestor.
+   * @evidence contracts/common.md#meaningful-documentation Native prose and helper paragraphs explain absent populations, aliases, handoff reconciliation and root ceilings following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Transaction-owned native case observations and physical identities distinguish resolved aliases; unknown case routes both glob interpretations without merging keys, while canonical registration and separate link-entry observation preserve retargets.
+   * @evidence contracts/performance.md#efficient-algorithms Publication normalizes native identities and sorts distinct path lists, then compares snapshots and reconciles alias/watch roots. Changed publications enumerate deduplicated physical glob roots, test applicable patterns with pattern/path/native identity costs and fingerprint selected file bytes or sorted immediate directory entries. Parent/case probes, repeated declaration/root admission and backend work add costs beyond file-pattern visits; payloads and traversal depth are uncapped.
+   * @evidence contracts/performance.md#reuse-equivalent-work Equal normalized publications reuse content baselines but still reconcile lexical aliases; registration microtasks coalesce equivalent handoff work, and transaction indexes reuse identity and output-overlap decisions within one scan.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Publication prunes retired declaration-owner choices and replaces uncapped match/fingerprint populations. Watcher retirement invokes close without awaiting backend completion, and supplied errors can interrupt cleanup. Weak output-overlap keys do not retain old identity transactions; the current declaration snapshot can borrow caller arrays until replaced or the facade is released.
    */
   public setProjectInputs(inputs: ITtscProjectInputSnapshot): void {
     const next = normalizeProjectInputSnapshot(inputs);
@@ -320,11 +398,29 @@ export class WatchTopology {
     this.projectInputMatches = this.collectProjectInputMatches();
     this.projectInputFingerprints = fingerprintProjectInputMatches(
       this.projectInputMatches,
+      this.readDirectory,
     );
     this.syncProjectInputWatchers();
   }
 
-  /** Close every watcher so SIGINT/SIGTERM can drain the event loop. */
+  /**
+   * Invoke close on owned watchers so their backends can retire. Scheduled
+   * reconciliation callbacks observe the closed state and retire without
+   * creating replacement subscriptions. A thrown close propagates and
+   * interrupts remaining cleanup; this void method does not await
+   * native/backend shutdown or guarantee event-loop drain.
+   *
+   * @evidence contracts/common.md#principled-implementation Marking the owner closed before retiring subscriptions prevents queued reconciliations from reopening native handles.
+   * @evidence contracts/common.md#clear-and-simple-design One shutdown operation closes and clears each distinct watcher population through a shared helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown invokes actual owned subscription close methods rather than only suppressing output; errors propagate and no backend completion is fabricated.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain event-loop release and queued-work behavior following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Shared close methods retire both Node handles and macOS registry subscriptions without exposing native handle types.
+   * @evidence contracts/performance.md#efficient-algorithms Each successfully reached live map traverses its watcher references and invokes backend-owned close work before clearing. Completed maps make later traversals empty; delegated cleanup costs and a thrown callback are not bounded by reference count alone.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Shutdown decides no equivalence of compilation or fingerprint work.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources On successful completion all five watcher maps clear and the lexical transaction is replaced; queued tasks observe the closed guard. A thrown close can leave later maps retained, and backend closure is not joined. Snapshot/declaration/pending byte state remains until replaced or the facade is released.
+   */
   public close(): void {
     this.closed = true;
     closeWatchers(this.fileWatchers);
@@ -332,6 +428,19 @@ export class WatchTopology {
     closeWatchers(this.extraWatchers);
     closeWatchers(this.projectInputWatchers);
     closeWatchers(this.projectInputLinkWatchers);
+    this.beginLexicalTransaction();
+  }
+
+  /** Start fresh native case observations for one synchronous watch decision. */
+  private beginLexicalTransaction(): void {
+    this.lexicalIdentities = createProjectInputPathIdentityContext({
+      throwOnRealpathError: false,
+    });
+  }
+
+  /** Keep lexical alias ownership while sharing this decision's case probes. */
+  private pathKey(location: string): string {
+    return WatchPaths.pathKey(location, this.lexicalIdentities);
   }
 
   private syncFileWatchers(skipMissing = false): boolean {
@@ -348,21 +457,19 @@ export class WatchTopology {
       this.fileWatchers,
       files,
       (location) =>
-        fs.watch(
+        this.openFileWatch(
           watcherRegistrationPath(location),
           { persistent: true },
           () => {
+            this.beginLexicalTransaction();
             // A per-file watcher fires on any filesystem attention its target
             // receives, and it carries no filename to distinguish an edit from
             // a touch. It answers the same question the unnamed directory event
             // answers, so it answers it the same way: from the bytes.
-            const movement = this.compilerFileMovement(location);
+            const movement = this.compilerFileMovement(location, true);
             if (movement.owner) this.rearmFileWatchers([location], true);
-            if (!movement.content) return;
-            this.callbacks.onInputChange({
-              kind: this.classifyCompilerInput(location),
-              path: location,
-            });
+            if (!this.compilerMovementReports(location, movement)) return;
+            this.reportCompilerFileChange(location);
           },
         ),
       (location, error) => this.callbacks.onError(location, error),
@@ -373,24 +480,55 @@ export class WatchTopology {
     );
   }
 
-  /** Compare a tracked file's content and physical owner with its snapshot. */
-  private compilerFileMovement(location: string): CompilerFileMovement {
-    const key = pathKey(location);
+  /**
+   * Compare a tracked file with its last observed bytes and physical owner.
+   *
+   * A named event or observation gap reads the bytes even when time and size
+   * stayed still. A broad registration scan reads only a file whose metadata or
+   * owner moved, so an unrelated event does not read the whole Program.
+   */
+  private compilerFileMovement(
+    location: string,
+    strong = false,
+  ): CompilerFileMovement {
+    const key = this.pathKey(location);
     const previous = this.compilerFileSnapshots.get(key);
-    const next = compilerFileSnapshot(location);
-    this.compilerFileSnapshots.set(key, next);
+    const metadata = compilerFileSnapshot(location, "");
+    const read =
+      strong ||
+      previous === undefined ||
+      previous.content !== metadata.content ||
+      previous.owner !== metadata.owner;
+    const fingerprint = read
+      ? fingerprintProjectInputFile(location)
+      : (previous?.fingerprint ?? "");
+    this.compilerFileSnapshots.set(key, { ...metadata, fingerprint });
     return {
-      content: previous?.content !== next.content,
-      owner: previous?.owner !== next.owner,
+      content:
+        previous === undefined
+          ? fingerprint !== ""
+          : previous.fingerprint !== fingerprint,
+      owner: previous?.owner !== metadata.owner,
     };
   }
 
+  /** A config's physical replacement can change resolution with equal bytes. */
+  private compilerMovementReports(
+    location: string,
+    movement: CompilerFileMovement,
+  ): boolean {
+    return (
+      movement.content ||
+      (movement.owner && this.classifyCompilerInput(location) === "config")
+    );
+  }
+
   private syncDirectoryWatchers(): boolean {
     const previous = new Map(this.directoryWatchers);
     const desired = new Map(this.directories);
     for (const [key, location] of this.observedDirectories) {
       if (
-        isDirectory(location) === false ||
+        WatchPaths.isDirectory(location) === false ||
         this.isCompilerOutputDirectory(location) ||
         this.isProjectInputDirectory(location)
       ) {
@@ -404,7 +542,12 @@ export class WatchTopology {
         if (
           [...desired].some(
             ([candidateKey, candidate]) =>
-              candidateKey !== key && isPathWithin(candidate, location),
+              candidateKey !== key &&
+              WatchPaths.isPathWithin(
+                candidate,
+                location,
+                this.lexicalIdentities,
+              ),
           )
         ) {
           desired.delete(key);
@@ -415,23 +558,16 @@ export class WatchTopology {
       this.directoryWatchers,
       desired,
       (location) =>
-        fs.watch(
+        this.openDirectoryWatch(
           watcherRegistrationPath(location),
-          {
-            persistent: true,
-            recursive: process.platform === "win32",
-          },
-          (event, filename) => {
+          process.platform === "win32",
+          (event, filename, gap) => {
+            this.beginLexicalTransaction();
             const changed =
-              filename === null
-                ? undefined
-                : path.resolve(location, filename.toString());
+              filename === null ? undefined : path.resolve(location, filename);
             const pluginInput = changed ?? location;
             if (this.isPluginInput(pluginInput)) {
-              this.callbacks.onInputChange({
-                kind: "plugin",
-                path: pluginInput,
-              });
+              this.notePluginNotification(pluginInput);
               return;
             }
             const plan = planCompilerDirectoryWatchEvent({
@@ -439,6 +575,7 @@ export class WatchTopology {
               event,
               exists: fs.existsSync,
               location,
+              identities: this.lexicalIdentities,
               platform: process.platform,
               trackedFiles: this.files,
             });
@@ -446,12 +583,9 @@ export class WatchTopology {
             for (const file of this.compilerChangesToReport(
               plan.changes,
               changed,
-              event,
+              gap === true,
             )) {
-              this.callbacks.onInputChange({
-                kind: this.classifyCompilerInput(file),
-                path: file,
-              });
+              this.reportCompilerFileChange(file);
             }
             if (plan.refresh) this.refreshFromDirectory(location, changed);
           },
@@ -489,6 +623,7 @@ export class WatchTopology {
     queueMicrotask(() => {
       this.compilerPostRegistrationReconciliationScheduled = false;
       if (this.closed) return;
+      this.beginLexicalTransaction();
       const refreshCompilerMembership =
         this.compilerPostRegistrationMembershipRefresh;
       const skipUnobservedProjectInputWatchRoots =
@@ -500,19 +635,16 @@ export class WatchTopology {
       const rearm: string[] = [];
       for (const file of this.files.values()) {
         const movement = this.compilerFileMovement(file);
-        if (movement.content) changed.push(file);
+        if (this.compilerMovementReports(file, movement)) changed.push(file);
         if (movement.owner) rearm.push(file);
       }
       // A replacement can move the path to a new inode without changing its
-      // cheap content stamp or topology key. Rebind its physical owner without
-      // inventing a content notification. Missing entries remain covered by
-      // their parent directory and are retried when recreation is observed.
+      // bytes. Rebind an ordinary source without inventing a content change;
+      // report a config owner transition because it can change resolution.
+      // Missing entries remain covered by their parent directory.
       this.rearmFileWatchers(rearm, true);
       for (const file of changed) {
-        this.callbacks.onInputChange({
-          kind: this.classifyCompilerInput(file),
-          path: file,
-        });
+        this.reportCompilerFileChange(file);
       }
       if (!refreshCompilerMembership) return;
       try {
@@ -521,13 +653,14 @@ export class WatchTopology {
         // startup event cannot strand a newly included source.
         this.refreshCompilerInputs(true, skipUnobservedProjectInputWatchRoots);
       } catch (error) {
-        const reported = new Set(changed.map(pathKey));
+        const reported = new Set(changed.map((file) => this.pathKey(file)));
         const reconciledChange = changed.length === 1 ? changed[0]! : undefined;
         for (const reload of reloadInputsForFailedTopologyRefresh(
           this.reloadFiles.values(),
           reconciledChange,
+          this.lexicalIdentities,
         )) {
-          if (reported.has(pathKey(reload))) continue;
+          if (reported.has(this.pathKey(reload))) continue;
           this.callbacks.onInputChange({ kind: "config", path: reload });
         }
         this.callbacks.onError(
@@ -541,47 +674,55 @@ export class WatchTopology {
   }
 
   /**
-   * Narrow a plan's changes to the tracked files that actually moved.
+   * Narrow a plan's changes to tracked files whose bytes actually moved.
    *
-   * A backend that cannot name what changed forces the plan to nominate every
-   * tracked file under the watched directory, which is the only safe answer it
-   * can give from an event carrying no filename. macOS delivers such events for
-   * ordinary activity elsewhere in the project, so the compiler lane would wake
-   * for sources nobody touched. Only a content notification passes through: it
-   * is the one event that claims the bytes moved. A rename claims the directory
-   * entry was rewritten and an unnamed event claims nothing, so both are
-   * decided from the bytes, which is the question neither of them answered.
+   * A named event checks its file even when time and size stayed still. A gap
+   * can hide such a rewrite anywhere under the watched root, so every candidate
+   * gets a strong check. Ordinary broad scans still use metadata first.
    */
   private compilerChangesToReport(
     changes: readonly string[],
     changed: string | undefined,
-    event: string,
+    gap: boolean,
   ): string[] {
-    // A content notification is taken at its word: the backend is telling us
-    // these bytes changed, and second-guessing it would lose an edit that
-    // landed inside the clock's resolution. A rename says the directory entry
-    // was rewritten, which is a different claim — a file can be moved back, or
-    // replaced by an identical copy, without its content moving at all — and an
-    // event that cannot name anything makes no claim about content either.
-    // Those two are decided from the bytes, and the rearm they drive is
-    // unaffected, because rebinding is about the inode and not the content.
-    if (changed !== undefined && event !== "rename") {
-      return changes.filter((file) => {
-        const key = pathKey(file);
-        const acknowledged = this.projectInputCompilerAcknowledgements.get(key);
-        this.projectInputCompilerAcknowledgements.delete(key);
-        this.recordCompilerFileSnapshot(file);
-        return (
-          acknowledged === undefined ||
-          acknowledged !== fingerprintProjectInputFile(file)
-        );
-      });
-    }
-    return changes.filter((file) => this.compilerFileMovement(file).content);
+    return changes.filter((file) => {
+      const movement = this.compilerFileMovement(
+        file,
+        changed !== undefined || gap,
+      );
+      return this.compilerMovementReports(file, movement);
+    });
   }
 
-  private recordCompilerFileSnapshot(file: string): void {
-    this.compilerFileSnapshots.set(pathKey(file), compilerFileSnapshot(file));
+  /**
+   * Let a selected project input consume its compiler content notification.
+   * Both lanes watch a resolveJsonModule file, but its project fingerprint
+   * decides the resident update once whichever backend hears the edit first. A
+   * missing compiler member instead reconciles Program membership before a
+   * stale file-watch notification can schedule a second build.
+   */
+  private reportCompilerFileChange(location: string): void {
+    if (this.classifyCompilerInput(location) === "compiler") {
+      if (fs.existsSync(location)) {
+        if (this.projectInputMatches.size !== 0) {
+          const key = createProjectInputPathIdentityContext({
+            throwOnRealpathError: false,
+          }).resolve(location).key;
+          if (
+            this.projectInputMatches.has(key) &&
+            this.refreshProjectInputs(path.dirname(location), location)
+          )
+            return;
+        }
+      } else {
+        this.refreshFromDirectory(path.dirname(location), location);
+        if (!this.files.has(this.pathKey(location))) return;
+      }
+    }
+    this.callbacks.onInputChange({
+      kind: this.classifyCompilerInput(location),
+      path: location,
+    });
   }
 
   private rearmFileWatchers(
@@ -589,8 +730,10 @@ export class WatchTopology {
     skipMissing = false,
   ): void {
     for (const file of files) {
-      const key = pathKey(file);
-      this.fileWatchers.get(key)?.close();
+      const key = this.pathKey(file);
+      const watcher = this.fileWatchers.get(key);
+      if (watcher === undefined) continue;
+      watcher.close();
       this.fileWatchers.delete(key);
     }
     if (this.syncFileWatchers(skipMissing)) {
@@ -598,34 +741,73 @@ export class WatchTopology {
     }
   }
 
+  /**
+   * Watch every directory of every plugin input, and report what a directory
+   * that appeared below an input already watched holds by now.
+   *
+   * Each directory has a watcher of its own, and a directory created below a
+   * plugin module is heard through its parent's; its own watcher is added only
+   * here, when that notification is decided (`decidePluginNotifications`) or
+   * the topology refreshes. A file written into it in between reaches no
+   * watcher on a platform whose watcher reports a directory's direct entries
+   * alone, and a build may have read the directory before the file landed. So
+   * once its watcher is registered, each entry it holds is noted as a plugin
+   * notification, as `@ttsc/unplugin`'s observer announces a directory it
+   * starts watching, and reported when it moved what a build reads. The
+   * directories of an input new to this sync are not reported: the load reports
+   * its inputs before any build reads them.
+   */
   private syncExtraWatchers(): void {
     const directories = new Map<string, string>();
+    const appeared: string[] = [];
     for (const input of this.extraInputs) {
+      const watchedBefore = this.watchedExtraInputs.has(this.pathKey(input));
       for (const directory of collectInputDirectories(input)) {
-        directories.set(pathKey(directory), directory);
+        const key = this.pathKey(directory);
+        directories.set(key, directory);
+        if (watchedBefore && !this.extraWatchers.has(key)) {
+          appeared.push(directory);
+        }
       }
     }
     syncWatchers(
       this.extraWatchers,
       directories,
       (location) =>
-        fs.watch(
+        this.openDirectoryWatch(
           watcherRegistrationPath(location),
-          { persistent: true },
+          false,
           (_event, filename) => {
+            this.beginLexicalTransaction();
             const changed =
-              filename === null
-                ? undefined
-                : path.resolve(location, filename.toString());
-            this.callbacks.onInputChange({
-              kind: "plugin",
-              path: changed ?? location,
-            });
+              filename === null ? undefined : path.resolve(location, filename);
+            // The one decision every watcher that hears a plugin path shares;
+            // here it drops the entry of a directory the build passes over.
+            if (changed !== undefined && !this.isPluginInput(changed)) return;
+            this.notePluginNotification(changed ?? location);
           },
         ),
       (location, error) => this.callbacks.onError(location, error),
       () => this.closed === false,
     );
+    this.watchedExtraInputs = new Set(
+      this.extraInputs.map((input) => this.pathKey(input)),
+    );
+    for (const directory of appeared) {
+      // Only a directory now watched: one whose registration failed was
+      // reported through `onError`, and one gone meanwhile holds nothing.
+      if (!this.extraWatchers.has(this.pathKey(directory))) continue;
+      let entries: string[];
+      try {
+        entries = fs.readdirSync(directory);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        const entry = path.join(directory, name);
+        if (this.isPluginInput(entry)) this.notePluginNotification(entry);
+      }
+    }
   }
 
   private syncProjectInputWatchers(
@@ -715,14 +897,12 @@ export class WatchTopology {
       this.projectInputWatchers,
       active,
       (location) =>
-        fs.watch(
+        this.openDirectoryWatch(
           watcherRegistrationPath(location),
-          { persistent: true, recursive: true },
+          true,
           (_event, filename) => {
             const changed =
-              filename === null
-                ? undefined
-                : path.resolve(location, filename.toString());
+              filename === null ? undefined : path.resolve(location, filename);
             this.refreshProjectInputs(location, changed);
           },
         ),
@@ -785,7 +965,9 @@ export class WatchTopology {
         // still miss the retarget, because the watcher goes below the link.
         if (!isSymbolicLink(declared)) continue;
         if (this.isProjectInputCompilerOutput(declared, identities)) continue;
-        const parent = nearestExistingDirectory(path.dirname(declared));
+        const parent = WatchPaths.nearestExistingDirectory(
+          path.dirname(declared),
+        );
         if (parent === undefined) continue;
         desired.set(identities.resolve(parent).key, parent);
       }
@@ -794,14 +976,12 @@ export class WatchTopology {
       this.projectInputLinkWatchers,
       desired,
       (location) =>
-        fs.watch(
+        this.openDirectoryWatch(
           watcherRegistrationPath(location),
-          { persistent: true },
+          false,
           (_event, filename) => {
             const changed =
-              filename === null
-                ? undefined
-                : path.resolve(location, filename.toString());
+              filename === null ? undefined : path.resolve(location, filename);
             this.refreshProjectInputs(location, changed);
           },
         ),
@@ -1055,8 +1235,9 @@ export class WatchTopology {
   ): string | undefined {
     const key = projectInputDeclarationKey(kind, declaration);
     const retained = this.projectInputWatchRoots.get(key);
-    if (retained !== undefined && isDirectory(retained)) return retained;
-    const resolved = projectInputRecursiveWatchRoot(
+    if (retained !== undefined && WatchPaths.isDirectory(retained))
+      return retained;
+    const resolved = ProjectInputWatchRules.projectInputRecursiveWatchRoot(
       target,
       this.projectInputs.root,
     );
@@ -1068,7 +1249,8 @@ export class WatchTopology {
     location: string,
     changed?: string,
     skipUnobservedProjectInputWatchRoots = false,
-  ): void {
+  ): boolean {
+    this.beginLexicalTransaction();
     try {
       const previous = this.projectInputMatches;
       const identities = createProjectInputPathIdentityContext();
@@ -1093,7 +1275,7 @@ export class WatchTopology {
         (this.isProjectInputCompilerOutput(changed, identities) ||
           (directlyMatched === false && topologyMatched === false))
       ) {
-        return;
+        return false;
       }
       // Rearm before snapshotting. A watcher that has to be replaced stops
       // delivering the moment it is closed, so a scan taken first would become
@@ -1108,35 +1290,45 @@ export class WatchTopology {
         this.syncProjectInputWatchers();
       }
       const next = this.collectProjectInputMatches();
-      const membershipChanged = mapsEqual(previous, next) === false;
+      const membershipChanged = WatchPaths.mapsEqual(previous, next) === false;
       const nextFingerprints =
         changed === undefined ||
         membershipChanged ||
         directlyMatched ||
         topologyMatched
-          ? fingerprintProjectInputMatches(next)
+          ? fingerprintProjectInputMatches(next, this.readDirectory)
           : this.projectInputFingerprints;
       const contentChanged =
-        mapsEqual(this.projectInputFingerprints, nextFingerprints) === false;
+        WatchPaths.mapsEqual(
+          this.projectInputFingerprints,
+          nextFingerprints,
+        ) === false;
       const changedInputs = projectInputChangedPaths({
         next,
         nextFingerprints,
         previous,
         previousFingerprints: this.projectInputFingerprints,
       });
-      const reconciledChange =
-        changed ?? (changedInputs.length === 1 ? changedInputs[0] : undefined);
+      const reconciledChange = reconcileProjectInputChange({
+        changed,
+        changedInputs,
+        identities,
+        next,
+        previous,
+        reloadDirectories: population.reloadDirectories ?? [],
+      });
       // Both spellings classify the event. The normalized form names the file a
       // link pointed at when the snapshot was published, so after a retarget it
       // names the wrong one; only the declared form resolves to what the link
       // points at now, which is the selection this lane exists to protect.
-      const reload = projectInputReloadEventShouldNotify({
+      const reloadInput = {
         changed: reconciledChange,
         changedInputs,
         globs: population.globs,
         reloadDirectories: population.reloadDirectories ?? [],
         reloadFiles: population.reloadFiles ?? [],
-      });
+      };
+      const reload = projectInputReloadEventShouldNotify(reloadInput);
       const invalidate = projectInputMembershipInvalidatesProgram({
         changed: reconciledChange,
         changedInputs,
@@ -1154,7 +1346,7 @@ export class WatchTopology {
       if (invalidate) {
         this.refreshCompilerInputs(false, skipUnobservedProjectInputWatchRoots);
       }
-      if (
+      const notify =
         projectInputEventShouldNotify({
           contentChanged,
           directlyMatched,
@@ -1162,8 +1354,21 @@ export class WatchTopology {
         }) &&
         (reconciledChange === undefined ||
           this.isProjectInputCompilerOutput(reconciledChange, identities) ===
-            false)
-      ) {
+            false);
+      reportProjectInputDecision({
+        source: "project-input",
+        location,
+        namedChange: changed ?? null,
+        ...reloadInput,
+        directlyMatched,
+        topologyMatched,
+        membershipChanged,
+        contentChanged,
+        reload,
+        invalidate,
+        notify,
+      });
+      if (notify) {
         this.callbacks.onInputChange(
           reload
             ? { kind: "config", path: reconciledChange }
@@ -1174,6 +1379,7 @@ export class WatchTopology {
               },
         );
       }
+      return true;
     } catch (error) {
       // A rename can invalidate the old filesystem object before the
       // replacement is readable. Rebind ancestor ownership even when the
@@ -1181,6 +1387,7 @@ export class WatchTopology {
       // stranded without a watcher.
       this.syncProjectInputWatchers(skipUnobservedProjectInputWatchRoots);
       this.callbacks.onError(location, error);
+      return false;
     }
   }
 
@@ -1212,7 +1419,7 @@ export class WatchTopology {
     }
     for (const directory of this.projectInputDeclarations("reload-directory")) {
       if (
-        isDirectory(directory) &&
+        WatchPaths.isDirectory(directory) &&
         this.isProjectInputCompilerOutputDirectory(directory, identities) ===
           false
       ) {
@@ -1220,14 +1427,32 @@ export class WatchTopology {
         matches.set(identity.key, identity.path);
       }
     }
+    const globRoots = new Map<string, { root: string; patterns: string[] }>();
     for (const glob of this.projectInputDeclarations("glob")) {
       const root = literalGlobRoot(glob);
       if (
-        isDirectory(root) === false ||
+        WatchPaths.isDirectory(root) === false ||
         this.isProjectInputCompilerOutputDirectory(root, identities)
       ) {
         continue;
       }
+      const identity = identities.resolve(root);
+      const group = globRoots.get(identity.key) ?? {
+        root: identity.path,
+        patterns: [],
+      };
+      group.patterns.push(glob);
+      globRoots.set(identity.key, group);
+    }
+    // One native walk serves all patterns below a physical ancestor. Per-file
+    // matching still uses every declaration's own root and wildcard semantics.
+    for (const root of projectInputActiveWatchDirectories(
+      [...globRoots.values()].map((group) => group.root),
+      identities,
+    )) {
+      const patterns = [...globRoots.values()]
+        .filter((group) => identities.isWithin(root, group.root))
+        .flatMap((group) => group.patterns);
       const stack = [root];
       while (stack.length !== 0) {
         const current = stack.pop()!;
@@ -1247,7 +1472,9 @@ export class WatchTopology {
             stack.push(location);
           } else if (
             entry.isFile() &&
-            matchesProjectInputGlob(glob, location, identities)
+            patterns.some((glob) =>
+              matchesProjectInputGlob(glob, location, identities),
+            )
           ) {
             const identity = identities.resolve(location);
             matches.set(identity.key, identity.path);
@@ -1261,11 +1488,11 @@ export class WatchTopology {
   private refreshFromDirectory(location: string, changed?: string): void {
     if (
       changed !== undefined &&
-      isDirectory(changed) &&
+      WatchPaths.isDirectory(changed) &&
       this.isCompilerOutputDirectory(changed) === false &&
       this.isProjectInputDirectory(changed) === false
     ) {
-      this.observedDirectories.set(pathKey(changed), changed);
+      this.observedDirectories.set(this.pathKey(changed), changed);
     }
     try {
       this.refresh(true);
@@ -1273,6 +1500,7 @@ export class WatchTopology {
       for (const reload of reloadInputsForFailedTopologyRefresh(
         this.reloadFiles.values(),
         changed,
+        this.lexicalIdentities,
       )) {
         this.callbacks.onInputChange({ kind: "config", path: reload });
       }
@@ -1282,13 +1510,13 @@ export class WatchTopology {
 
   private isCompilerOutputDirectory(location: string): boolean {
     return [...this.outputs.values()].some((output) =>
-      isPathWithin(output, location),
+      WatchPaths.isPathWithin(output, location, this.lexicalIdentities),
     );
   }
 
   private isCompilerOutput(location: string): boolean {
     return (
-      this.outputFiles.has(pathKey(location)) ||
+      this.outputFiles.has(this.pathKey(location)) ||
       this.isCompilerOutputDirectory(location)
     );
   }
@@ -1370,41 +1598,166 @@ export class WatchTopology {
     location: string,
   ): "compiler" | "config" | "plugin" {
     if (this.isPluginInput(location)) return "plugin";
-    return this.reloadFiles.has(pathKey(location)) ? "config" : "compiler";
+    return this.reloadFiles.has(this.pathKey(location)) ? "config" : "compiler";
   }
 
-  private isPluginInput(location: string): boolean {
+  /**
+   * Note a notification at `location` against the plugin inputs it may have
+   * moved, to be decided once the delivery it came in has reached every
+   * listener (`decidePluginNotifications`).
+   *
+   * A watcher reports more than an edit. Windows reports a directory's entry as
+   * changed when only its metadata moved, such as its access time after a build
+   * enumerated it, and a notification taken at its word restarted the resident
+   * check host for a plugin whose sources nobody edited. An input is decided by
+   * what its build reads, which is every one of its source files, so the
+   * notifications of one delivery are decided together: an install or a
+   * checkout brings hundreds, and each input they name is read once. A location
+   * no input covers, such as a directory above one, names every input.
+   */
+  private notePluginNotification(location: string): void {
     const resolved = path.resolve(location);
-    return this.extraInputs.some(
-      (input) =>
-        pathKey(input) === pathKey(resolved) || isPathWithin(input, resolved),
+    const covering = this.extraInputs.filter((input) =>
+      pluginSourceCovers(input, resolved, "entry"),
     );
+    for (const input of covering.length === 0 ? this.extraInputs : covering) {
+      const key = this.pathKey(input);
+      const locations = this.pendingPluginNotifications.get(key) ?? new Set();
+      locations.add(location);
+      this.pendingPluginNotifications.set(key, locations);
+    }
+    if (this.pluginNotificationsScheduled) return;
+    this.pluginNotificationsScheduled = true;
+    // A watcher backend hands one delivery to its listeners within one turn
+    // of the event loop, so the check phase after that turn holds all of it.
+    setImmediate(() => this.decidePluginNotifications());
   }
-}
 
-export function reloadInputsForFailedTopologyRefresh(
-  reloadFiles: Iterable<string>,
-  changed?: string,
-): string[] {
-  const changedKey = changed === undefined ? undefined : pathKey(changed);
-  const reloads = new Map<string, string>();
-  for (const location of reloadFiles) {
+  /**
+   * Report every location noted for a plugin input whose state moved, once
+   * each, and record the state it moved to. A notification that moved no input
+   * is dropped.
+   *
+   * Whether a build must rerun and what must be watched are separate questions.
+   * A delivery can name a directory created below an input: while it is empty
+   * it moves nothing a build reads, yet it needs a watcher of its own before a
+   * file lands in it, or on a platform whose watcher reports a directory's
+   * direct entries alone that file reaches no watcher. So the watchers are
+   * synced first, and what a directory they start watching already holds is
+   * noted into this same decision (`syncExtraWatchers`).
+   */
+  private decidePluginNotifications(): void {
+    if (this.closed) {
+      this.pendingPluginNotifications = new Map();
+      this.pluginNotificationsScheduled = false;
+      return;
+    }
+    this.beginLexicalTransaction();
+    // Still scheduled while syncing, so what the sync notes joins this decision
+    // instead of scheduling another.
+    this.syncExtraWatchers();
+    this.pluginNotificationsScheduled = false;
+    const pending = this.pendingPluginNotifications;
+    this.pendingPluginNotifications = new Map();
+    const reported = new Set<string>();
+    for (const input of this.extraInputs) {
+      const key = this.pathKey(input);
+      const locations = pending.get(key);
+      if (locations === undefined) continue;
+      const state = pluginInputState(input);
+      if (this.pluginInputStates.get(key) === state) continue;
+      this.pluginInputStates.set(key, state);
+      for (const location of locations) {
+        if (reported.has(location)) continue;
+        reported.add(location);
+        this.callbacks.onInputChange({ kind: "plugin", path: location });
+      }
+    }
+  }
+
+  /**
+   * Whether a path is one a plugin build keys on: the plugin input itself, or a
+   * path below it outside every directory the build passes over
+   * (`pluginSourceCovers`). A write in a plugin module's `node_modules` or
+   * `.git` is not one, whatever watcher heard it.
+   *
+   * Nor is such a directory's own entry. Windows reports every write inside a
+   * directory as a change of that directory's entry to a watch on its parent,
+   * and nothing of a directory the build passes over, or below it, is a source.
+   * An entry of the same name that is a file is one the build reads.
+   */
+  private isPluginInput(location: string): boolean {
     const resolved = path.resolve(location);
-    const key = pathKey(resolved);
     if (
-      (changedKey !== undefined && key === changedKey) ||
-      fs.existsSync(resolved) === false
+      prunesPluginSourceDirectory(path.basename(resolved)) &&
+      WatchPaths.isDirectory(resolved)
     ) {
-      reloads.set(key, resolved);
+      return false;
     }
+    return this.extraInputs.some((input) =>
+      pluginSourceCovers(input, resolved, "entry"),
+    );
   }
-  return [...reloads.values()].sort();
 }
 
+type WatchTopologyOptions = Pick<
+  TtscBuildOptions,
+  | "binary"
+  | "compilerArgsCwd"
+  | "compilerProjectSelections"
+  | "emit"
+  | "env"
+  | "outDir"
+  | "passthrough"
+  | "projectRoot"
+  | "tsconfig"
+> & {
+  cwd: string;
+  files: readonly string[];
+  pinCompilerProject?: boolean;
+};
+
+type WatchTopologyCallbacks = {
+  onError(location: string, error: unknown): void;
+  onInputChange(change: WatchInputChange): void;
+  onProjectInputWatchUnavailable?(roots: readonly string[]): void;
+  onProjectInputWatchRoots?(roots: readonly string[]): void;
+  onTopologyChange(): void;
+};
+
+type ResolvedWatchTopology = {
+  analysisOnly: boolean;
+  directories: Map<string, string>;
+  files: Map<string, string>;
+  outputFiles: Map<string, string>;
+  outputs: Map<string, string>;
+  reloadFiles: Map<string, string>;
+};
+
+type CompilerFileSnapshot = {
+  content: string;
+  fingerprint: string;
+  owner: string;
+};
+
+type CompilerFileMovement = {
+  content: boolean;
+  owner: boolean;
+};
+
 function resolveWatchTopology(
   options: WatchTopologyOptions,
   extraInputs: readonly string[],
+  identities: ProjectInputPathIdentityContext,
+  getCompilerInputs: typeof listCompilerInputs,
 ): ResolvedWatchTopology {
+  const selection = CompilerProjectSelection.read(options);
+  if (selection.inspectionError !== undefined) throw selection.inspectionError;
+  options = {
+    ...options,
+    compilerArgsCwd: selection.compilerArgsCwd,
+    pinCompilerProject: selection.projectGuard.length !== 0,
+  };
   let analysisOnly = options.emit === false;
   const files = new Map<string, string>();
   const outputFiles = new Map<string, string>();
@@ -1412,15 +1765,14 @@ function resolveWatchTopology(
   const reloadFiles = new Map<string, string>();
   const roots: string[] = [];
   if (options.files.length !== 0) {
-    const project = readProjectConfig({
-      cwd: options.cwd,
-      projectRoot: options.projectRoot,
-      tsconfig: options.tsconfig,
-    });
+    const project = selection.project;
+    const inspected = watchCompilerOptions(selection, options);
     analysisOnly = watchTopologyAnalysisOnly(options, project);
+    addPaths(files, inspected.responseFiles, identities);
+    addPaths(reloadFiles, inspected.responseFiles, identities);
     roots.push(project.root);
-    addPaths(files, project.configPaths);
-    addPaths(reloadFiles, project.configPaths);
+    addPaths(files, project.configPaths, identities);
+    addPaths(reloadFiles, project.configPaths, identities);
     const positionalInputs = options.files.map((file) =>
       path.resolve(options.cwd, file),
     );
@@ -1428,41 +1780,59 @@ function resolveWatchTopology(
       positionalInputs.length === 1 &&
       (options.emit ?? project.compilerOptions.noEmit !== true)
     ) {
-      addPaths(outputFiles, [
-        resolveSingleFileOutput({
-          cliOutDir: options.outDir,
-          cwd: options.cwd,
-          file: positionalInputs[0]!,
-          passthrough: options.passthrough,
-          tsconfig: options.tsconfig,
-        }),
-      ]);
+      addPaths(
+        outputFiles,
+        [
+          resolveSingleFileOutput(
+            {
+              cliOutDir: options.outDir,
+              cwd: options.cwd,
+              file: positionalInputs[0]!,
+              passthrough: options.passthrough,
+              tsconfig: options.tsconfig,
+            },
+            project,
+          ),
+        ],
+        identities,
+      );
     }
-    addPaths(files, positionalInputs);
+    addPaths(files, positionalInputs, identities);
   } else {
-    const projects = readReferencedProjects(options);
-    if (projects[0] !== undefined) {
-      analysisOnly = watchTopologyAnalysisOnly(options, projects[0]);
-    }
+    const projects = readReferencedProjects(selection.project, identities);
     for (const project of projects) {
+      const inspected = watchCompilerOptions(selection, options);
+      if (project === projects[0]) {
+        analysisOnly = watchTopologyAnalysisOnly(inspected.options, project);
+      }
       roots.push(project.root);
-      addPaths(files, project.configPaths);
-      addPaths(reloadFiles, project.configPaths);
-      const compilerInputs = listCompilerInputs(project, options);
-      const compilerOutputs = resolveCompilerOutputs(project, options);
-      addPaths(outputFiles, compilerOutputs.files);
+      addPaths(files, project.configPaths, identities);
+      addPaths(reloadFiles, project.configPaths, identities);
+      addPaths(files, inspected.responseFiles, identities);
+      addPaths(reloadFiles, inspected.responseFiles, identities);
+      const compilerInputs = getCompilerInputs(project, options);
+      CompilerProjectSelection.assertCurrent(selection);
+      const compilerOutputs = resolveCompilerOutputs(project, inspected.options);
+      addPaths(outputFiles, compilerOutputs.files, identities);
       addPaths(
         outputFiles,
-        inferPerSourceCompilerOutputs(project, options, compilerInputs),
+        inferPerSourceCompilerOutputs(
+          project,
+          inspected.options,
+          compilerInputs,
+          identities,
+        ),
+        identities,
       );
-      addPaths(outputs, compilerOutputs.directories);
-      addPaths(files, compilerInputs);
+      addPaths(outputs, compilerOutputs.directories, identities);
+      addPaths(files, compilerInputs, identities);
     }
   }
-  addPaths(files, extraInputs);
+  CompilerProjectSelection.assertCurrent(selection);
+  addPaths(files, extraInputs, identities);
   return {
     analysisOnly,
-    directories: collectTopologyDirectories(files.values(), roots),
+    directories: collectTopologyDirectories(files.values(), roots, identities),
     files,
     outputFiles,
     outputs,
@@ -1470,32 +1840,51 @@ function resolveWatchTopology(
   };
 }
 
+/**
+ * Share the root selection's observed options across its referenced projects.
+ * The original request still reaches the compiler-input operation. Positional
+ * output placement remains the single-file launcher's own copy policy.
+ */
+function watchCompilerOptions(
+  selection: ReturnType<typeof CompilerProjectSelection.read>,
+  options: WatchTopologyOptions,
+): {
+  options: WatchTopologyOptions;
+  responseFiles: readonly string[];
+} {
+  return {
+    options: { ...options, passthrough: selection.inspectedArgs },
+    responseFiles: [...selection.observations.keys()],
+  };
+}
+
 function watchTopologyAnalysisOnly(
   options: WatchTopologyOptions,
   project: ITtscParsedProjectConfig,
 ): boolean {
-  if (options.emit !== undefined) return options.emit === false;
   const noEmit =
-    passthroughBooleanOption(options.passthrough, "--noEmit") ??
-    project.compilerOptions.noEmit === true;
+    passthroughBooleanOption(
+      readCompilerOptionValues(options.passthrough).values,
+      "--noEmit",
+    ) ??
+    (options.emit === undefined
+      ? project.compilerOptions.noEmit === true
+      : options.emit === false);
   return noEmit;
 }
 
 function readReferencedProjects(
-  options: WatchTopologyOptions,
+  root: ITtscParsedProjectConfig,
+  identities: ProjectInputPathIdentityContext,
 ): ITtscParsedProjectConfig[] {
-  const root = readProjectConfig({
-    cwd: options.cwd,
-    projectRoot: options.projectRoot,
-    tsconfig: options.tsconfig,
-  });
   const projects: ITtscParsedProjectConfig[] = [];
   const queue = [root];
   const seen = new Set<string>();
-  while (queue.length !== 0) {
-    const project = queue.shift()!;
-    if (seen.has(pathKey(project.path))) continue;
-    seen.add(pathKey(project.path));
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const project = queue[cursor]!;
+    const key = WatchPaths.pathKey(project.path, identities);
+    if (seen.has(key)) continue;
+    seen.add(key);
     projects.push(project);
     for (const reference of readProjectReferences(project.path)) {
       queue.push(
@@ -1550,9 +1939,10 @@ function listCompilerInputs(
       "--pretty",
       "false",
       ...(options.passthrough ?? []),
+      ...(options.pinCompilerProject === true ? ["-p", project.path] : []),
     ],
     {
-      cwd: project.root,
+      cwd: options.compilerArgsCwd ?? project.root,
       env: { ...process.env, ...options.env },
       encoding: "utf8",
     },
@@ -1609,6 +1999,7 @@ function inferPerSourceCompilerOutputs(
   project: ITtscParsedProjectConfig,
   options: WatchTopologyOptions,
   inputs: readonly string[],
+  identities: ProjectInputPathIdentityContext,
 ): string[] {
   const emit = effectiveCompilerEmit(project, options);
   const outputs = new Set<string>();
@@ -1626,7 +2017,7 @@ function inferPerSourceCompilerOutputs(
       adjacentWhenOutside: boolean,
     ): string | undefined => {
       if (directory === undefined) return stem;
-      if (!isPathWithin(sourceRoot, input)) {
+      if (!WatchPaths.isPathWithin(sourceRoot, input, identities)) {
         return adjacentWhenOutside ? stem : undefined;
       }
       return path.resolve(directory, path.relative(sourceRoot, stem));
@@ -1642,7 +2033,8 @@ function inferPerSourceCompilerOutputs(
       }
       continue;
     }
-    if (!isCompilerEmittableSourceExtension(extension)) continue;
+    if (!ProjectInputWatchRules.isCompilerEmittableSourceExtension(extension))
+      continue;
     if (
       emit.javascript &&
       (emit.outDir !== undefined ||
@@ -1686,19 +2078,6 @@ function inferPerSourceCompilerOutputs(
   return [...outputs];
 }
 
-function isCompilerEmittableSourceExtension(extension: string): boolean {
-  return [
-    ".cjs",
-    ".cts",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".mts",
-    ".ts",
-    ".tsx",
-  ].includes(extension);
-}
-
 function isJavaScriptSourceExtension(extension: string): boolean {
   return [".cjs", ".js", ".jsx", ".mjs"].includes(extension);
 }
@@ -1722,7 +2101,7 @@ function effectiveCompilerEmit(
   options: WatchTopologyOptions,
 ): EffectiveCompilerEmit {
   const compilerOptions = project.compilerOptions;
-  const passthrough = options.passthrough;
+  const passthrough = readCompilerOptionValues(options.passthrough).values;
   const noEmit =
     passthroughBooleanOption(passthrough, "--noEmit") ??
     (options.emit === false
@@ -1770,9 +2149,15 @@ function effectiveCompilerEmit(
     passthrough,
     "--tsBuildInfoFile",
   );
-  const jsx =
-    passthroughStringOption(passthrough, "--jsx") ?? compilerOptions.jsx;
-  const compilerCwd = project.root;
+  // Presence carries explicit null/empty enum resets. A configured JSX string
+  // follows JSON's lowercase-only contract, never the CLI whitespace trim.
+  const rawJsx = passthrough.has("jsx")
+    ? passthrough.get("jsx")
+    : typeof compilerOptions.jsx === "string"
+      ? normalizeCompilerEnumValue(compilerOptions.jsx, "json")
+      : undefined;
+  const jsx = typeof rawJsx === "string" ? rawJsx : undefined;
+  const compilerCwd = options.compilerArgsCwd ?? project.root;
   return {
     declaration,
     declarationDir:
@@ -1842,74 +2227,51 @@ function replaceOutputExtension(location: string, extension: string): string {
 }
 
 function passthroughBooleanOption(
-  tokens: readonly string[] | undefined,
+  values: ReadonlyMap<string, unknown>,
   name: string,
 ): boolean | undefined {
-  let value: boolean | undefined;
-  for (let index = 0; index < (tokens?.length ?? 0); index++) {
-    const token = tokens?.[index];
-    if (token === undefined) continue;
-    if (!passthroughOptionMatches(token, name)) continue;
-    const next = tokens?.[index + 1];
-    if (next === "true" || next === "false" || next === "null") {
-      value = next === "true";
-      index++;
-    } else {
-      value = true;
-    }
-  }
-  return value;
+  const value = values.get(name.slice(2));
+  return typeof value === "boolean"
+    ? value
+    : value === null
+      ? false
+      : undefined;
 }
 
 function passthroughPathOption(
-  tokens: readonly string[] | undefined,
+  values: ReadonlyMap<string, unknown>,
   name: string,
 ): string | null | undefined {
-  let value: string | null | undefined;
-  for (let index = 0; index < (tokens?.length ?? 0); index++) {
-    const token = tokens?.[index];
-    if (token === undefined) continue;
-    if (!passthroughOptionMatches(token, name)) continue;
-    if (index + 1 < (tokens?.length ?? 0)) {
-      const next = tokens?.[++index];
-      value = next === "null" ? null : next;
-    }
-  }
-  return value;
-}
-
-function passthroughStringOption(
-  tokens: readonly string[] | undefined,
-  name: string,
-): string | undefined {
-  return passthroughPathOption(tokens, name)?.toLowerCase() ?? undefined;
-}
-
-function passthroughOptionMatches(token: string, name: string): boolean {
-  if (!token.startsWith("-")) return false;
-  if (token.includes("=")) return false;
-  return resolveFlagSpec(token)?.name === resolveFlagSpec(name)?.name;
+  const value = values.get(name.slice(2));
+  return typeof value === "string" || value === null ? value : undefined;
 }
 
 function collectTopologyDirectories(
   files: Iterable<string>,
   roots: readonly string[],
+  identities: ProjectInputPathIdentityContext,
 ): Map<string, string> {
   const directories = new Map<string, string>();
   for (const root of roots) {
-    directories.set(pathKey(root), root);
+    directories.set(WatchPaths.pathKey(root, identities), root);
   }
   for (const file of files) {
     const directory = path.dirname(file);
-    const root = roots.find((candidate) => isPathWithin(candidate, directory));
+    const root = roots.find((candidate) =>
+      WatchPaths.isPathWithin(candidate, directory, identities),
+    );
     if (root === undefined) {
-      directories.set(pathKey(directory), directory);
+      directories.set(WatchPaths.pathKey(directory, identities), directory);
       continue;
     }
     let current = directory;
     while (true) {
-      directories.set(pathKey(current), current);
-      if (pathKey(current) === pathKey(root)) break;
+      directories.set(WatchPaths.pathKey(current, identities), current);
+      if (
+        WatchPaths.pathKey(current, identities) ===
+        WatchPaths.pathKey(root, identities)
+      )
+        break;
       const parent = path.dirname(current);
       if (parent === current) break;
       current = parent;
@@ -1918,27 +2280,16 @@ function collectTopologyDirectories(
   return directories;
 }
 
+/**
+ * Every directory of a plugin input a watch observes: the input and the
+ * directories below it, except those the plugin build passes over and all below
+ * them (`prunesPluginSourceDirectory`). The input is a plugin's whole Go
+ * module, which can be a repository with its own `node_modules` and `.git`;
+ * watching those would rebuild for every package install and commit without the
+ * build reading any of it.
+ */
 function collectInputDirectories(input: string): string[] {
-  if (isDirectory(input) === false) return [];
-  const directories: string[] = [];
-  const stack = [input];
-  while (stack.length !== 0) {
-    const current = stack.pop()!;
-    directories.push(current);
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(current, { withFileTypes: true });
-    } catch (error) {
-      if (isVanishedFilesystemEntry(error)) continue;
-      throw error;
-    }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        stack.push(path.join(current, entry.name));
-      }
-    }
-  }
-  return directories;
+  return collectPluginSourceDirectories(input);
 }
 
 function isVanishedFilesystemEntry(error: unknown): boolean {
@@ -1949,75 +2300,31 @@ function isVanishedFilesystemEntry(error: unknown): boolean {
   );
 }
 
-function isDirectory(location: string): boolean {
-  try {
-    return fs.statSync(location).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-type SynchronizedWatcher = {
-  close(): void;
-  on(event: "error", listener: (error: Error) => void): unknown;
-};
-
-export function syncWatchers<T extends SynchronizedWatcher>(
-  watchers: Map<string, T>,
-  desired: ReadonlyMap<string, string>,
-  create: (location: string, key: string) => T,
-  onError: (location: string, error: unknown) => void,
-  shouldContinue: () => boolean = () => true,
-): boolean {
-  let complete = true;
-  for (const [key, location] of desired) {
-    if (!shouldContinue()) {
-      complete = false;
-      break;
-    }
-    if (watchers.has(key)) continue;
-    try {
-      const watcher = create(location, key);
-      watcher.on("error", (error) => {
-        if (watchers.get(key) === watcher) {
-          watchers.delete(key);
-        }
-        watcher.close();
-        onError(location, error);
-      });
-      watchers.set(key, watcher);
-    } catch (error) {
-      complete = false;
-      onError(location, error);
-    }
-  }
-  if (!complete) return false;
-  for (const [key, watcher] of watchers) {
-    if (desired.has(key)) continue;
-    watcher.close();
-    watchers.delete(key);
-  }
-  return true;
-}
-
-function closeWatchers(watchers: Map<string, fs.FSWatcher>): void {
+function closeWatchers(watchers: Map<string, DirectoryWatcher>): void {
   for (const watcher of watchers.values()) watcher.close();
   watchers.clear();
 }
 
-function addPaths(target: Map<string, string>, paths: Iterable<string>): void {
+function addPaths(
+  target: Map<string, string>,
+  paths: Iterable<string>,
+  identities: ProjectInputPathIdentityContext,
+): void {
   for (const location of paths) {
     const resolved = path.resolve(location);
-    target.set(pathKey(resolved), resolved);
+    target.set(WatchPaths.pathKey(resolved, identities), resolved);
   }
 }
 
-function uniqueExistingPaths(paths: readonly string[]): string[] {
+function uniqueExistingPaths(
+  paths: readonly string[],
+  identities: ProjectInputPathIdentityContext,
+): string[] {
   const unique = new Map<string, string>();
   for (const location of paths) {
     if (location.length === 0) continue;
     const resolved = path.resolve(location);
-    unique.set(pathKey(resolved), resolved);
+    unique.set(WatchPaths.pathKey(resolved, identities), resolved);
   }
   return [...unique.values()];
 }
@@ -2072,24 +2379,6 @@ function projectInputSnapshotsEqual(
   );
 }
 
-export function literalGlobRoot(pattern: string): string {
-  const resolved = path.resolve(pattern);
-  const normalized = resolved.split("\\").join("/");
-  const wildcard = normalized.search(/[*?]/);
-  if (wildcard === -1) return path.dirname(resolved);
-  const separator = normalized.lastIndexOf("/", wildcard);
-  const prefix = separator < 0 ? "." : normalized.slice(0, separator);
-  const volumeRoot = path.parse(resolved).root;
-  const normalizedVolumeRoot = volumeRoot.split("\\").join("/");
-  if (
-    prefix.length === 0 ||
-    prefix === normalizedVolumeRoot.replace(/\/$/, "")
-  ) {
-    return volumeRoot;
-  }
-  return path.resolve(prefix);
-}
-
 function projectInputDeclarationKey(
   kind: "file" | "glob" | "reload" | "reload-directory",
   declaration: string,
@@ -2098,146 +2387,26 @@ function projectInputDeclarationKey(
 }
 
 /**
- * Chooses the one stable recursive watcher root owned by a project-input
- * declaration.
+ * Metadata, fingerprint, and physical-owner identities for a tracked file.
  *
- * Inputs inside the project share its physical root so directory replacement
- * cannot strand a child handle. External inputs use the nearest existing
- * ancestor of their declared parent, which is the explicit boundary for
- * observing a currently missing external tree without polling every file --
- * except that the boundary never rises to a directory holding the project,
- * since such a root outranks the project's own in the active merge and leaves
- * one handle over a shared system directory to carry everything. An external
- * declaration that can only be owned that way falls back to its own tree, and
- * is left unwatched when even that would contain the project.
+ * Modification time and size avoid a read on an ordinary broad scan. A strong
+ * event compares the fingerprint, so a timestamp collision cannot hide an edit
+ * and a metadata-only notification does not create a build. Device and inode
+ * answer whether a POSIX per-file watcher still owns the path.
  */
-export function projectInputWatchDirectories(
-  target: string,
-  projectRoot: string,
-): string[] {
-  const root = projectInputRecursiveWatchRoot(target, projectRoot);
-  return root === undefined ? [] : [root];
-}
-
-/**
- * Removes recursive roots already covered by an ancestor without rewriting the
- * declaration-specific roots retained by WatchTopology.
- */
-export function projectInputActiveWatchDirectories(
-  directories: Iterable<string>,
-  identities = createProjectInputPathIdentityContext(),
-): string[] {
-  const unique = new Map<string, string>();
-  for (const directory of directories) {
-    // Coverage is decided on physical identity so two spellings of one
-    // directory cannot both survive, but the surviving entry keeps the
-    // caller's spelling: this function selects roots, it does not rename them.
-    const identity = identities.resolve(directory);
-    if (!unique.has(identity.key)) unique.set(identity.key, directory);
-  }
-  return [...unique]
-    .filter(([key]) => {
-      let ancestor = path.dirname(key);
-      while (ancestor !== key) {
-        if (unique.has(ancestor)) return false;
-        const parent = path.dirname(ancestor);
-        if (parent === ancestor) break;
-        ancestor = parent;
-      }
-      return true;
-    })
-    .map(([, directory]) => directory);
-}
-
-export function projectInputAvailableWatchDirectory(
+function compilerFileSnapshot(
   location: string,
-  rejected: ReadonlySet<string>,
-  identities: ProjectInputPathIdentityContext = createProjectInputPathIdentityContext(),
-  projectRoot?: string,
-): string | undefined {
-  const resolvedProjectRoot =
-    projectRoot === undefined ? undefined : path.resolve(projectRoot);
-  let current = path.resolve(location);
-  while (true) {
-    const identity = identities.resolve(current);
-    // Escalation obeys the same ceiling root selection does. A watcher that
-    // failed once would otherwise be replaced by one over a directory holding
-    // the project, which outranks the project's own root in the active merge
-    // and re-opens, through the recovery path, the exact swallow that selection
-    // refuses to create. Giving up the failed root is the lesser loss.
-    if (
-      resolvedProjectRoot !== undefined &&
-      identity.key !== identities.resolve(resolvedProjectRoot).key &&
-      identities.isWithin(identity.path, resolvedProjectRoot)
-    ) {
-      return undefined;
-    }
-    if (!rejected.has(identity.key)) return identity.path;
-    const parent = path.dirname(current);
-    if (parent === current) return undefined;
-    const fallback = nearestExistingDirectory(parent);
-    if (fallback === undefined) return undefined;
-    current = fallback;
-  }
-}
-
-function projectInputRecursiveWatchRoot(
-  target: string,
-  projectRoot: string,
-  identities = createProjectInputPathIdentityContext(),
-): string | undefined {
-  const resolvedTarget = path.resolve(target);
-  const resolvedProjectRoot = path.resolve(projectRoot);
-  if (identities.isWithin(resolvedProjectRoot, resolvedTarget)) {
-    return nearestExistingDirectory(resolvedProjectRoot);
-  }
-  // An external anchor rises to the declared parent so a tree that does not
-  // exist yet is still observed, and so siblings under it share one handle. It
-  // may not rise past the project, though: a directory that contains the
-  // project swallows the project's own root when the two are merged, and every
-  // in-project declaration then rides one recursive handle over a shared system
-  // directory — a temp root, or the filesystem root itself — which delivers
-  // nothing. Prefer the declared parent, fall back to the target's own tree,
-  // and decline rather than widen past the project.
-  for (const candidate of [
-    nearestExistingDirectory(path.dirname(resolvedTarget)),
-    nearestExistingDirectory(resolvedTarget),
-  ]) {
-    if (candidate === undefined) continue;
-    // The project root cannot outrank itself in the merge, so it is the one
-    // container that is never a swallow — it is the owner the internal branch
-    // would have chosen anyway. A declaration reached through an in-project
-    // directory symlink lands here, and rejecting it would drop the hoist that
-    // keeps a replaced directory from stranding a child handle.
-    if (
-      identities.resolve(candidate).key !==
-        identities.resolve(resolvedProjectRoot).key &&
-      identities.isWithin(candidate, resolvedProjectRoot)
-    ) {
-      continue;
-    }
-    return candidate;
-  }
-  return undefined;
-}
-
-/**
- * Cheap content and physical-owner identities for a tracked file.
- *
- * Modification time and size answer "did the bytes move" without reading the
- * file. Device and inode answer whether a POSIX per-file watcher still owns the
- * path. Keeping the answers separate lets an identical atomic replacement
- * rebind its watcher without inventing a compiler notification.
- */
-function compilerFileSnapshot(location: string): CompilerFileSnapshot {
+  fingerprint: string,
+): CompilerFileSnapshot {
   try {
     const stats = fs.statSync(location);
     return {
       content: `${stats.mtimeMs}:${stats.size}`,
+      fingerprint,
       owner: `${stats.dev}:${stats.ino}`,
     };
   } catch {
-    return { content: "", owner: "" };
+    return { content: "", fingerprint: "", owner: "" };
   }
 }
 
@@ -2249,16 +2418,6 @@ function isSymbolicLink(location: string): boolean {
   }
 }
 
-function nearestExistingDirectory(location: string): string | undefined {
-  let current = path.resolve(location);
-  while (true) {
-    if (isDirectory(current)) return current;
-    const parent = path.dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}
-
 function matchesProjectInput(
   snapshot: ITtscProjectInputSnapshot,
   location: string,
@@ -2280,123 +2439,70 @@ function matchesProjectInput(
 }
 
 /**
- * Whether a replacement at this path leaves a recursive watcher bound to the
- * object that was replaced.
+ * Attribute a complete population scan to the changes it actually observed.
  *
- * Only one backend needs the answer. Node routes a recursive watch to its own
- * per-directory implementation when the platform is neither macOS nor Windows,
- * and that implementation keys its handles by path: the handle for a directory
- * renamed away stays bound to the object that left, and any child whose name
- * survives the swap is skipped as already known. The native subtree backends
- * both other platforms use follow the path, so retiring their watcher would buy
- * nothing and would open a window in which no events are delivered.
- *
- * The answer is deliberately narrower than the rescan rule, because
- * reinstalling a root costs one watch descriptor per entry beneath it, which an
- * install storm would pay thousands of times. A directory appearing inside a
- * glob root deserves a rescan but replaces nothing a root stands on, and a
- * reload directory anchors the directory that contains it rather than itself,
- * since its fingerprint is a digest of its own immediate entries and nothing
- * below it can reach the declared corpus.
+ * Observer attention can arrive late for bytes already admitted while another
+ * member has changed. Such a name must not consume that member's delta under
+ * the wrong path or select execution reload for unchanged selection bytes. A
+ * directory event remains a valid cause when it contains every changed member.
+ * Ancestor resolution-directory digests accompany those members rather than
+ * replace their identity; unrelated directory deltas remain separate. When only
+ * those digests changed, an untracked native name can still explain an
+ * immediate-entry change whose member was not selected, but not another
+ * directory's independent delta.
  */
-export function projectInputReplacementStrandsWatchers(
-  snapshot: ITtscProjectInputSnapshot,
-  location: string,
-  identities = createProjectInputPathIdentityContext(),
-  platform: NodeJS.Platform = process.platform,
-): boolean {
-  if (platform === "darwin" || platform === "win32") return false;
-  const changed = path.resolve(location);
-  if (!isDirectory(changed)) return false;
-  return projectInputAnchorsDeclaration(
-    snapshot,
-    path.dirname(changed),
-    identities,
-  );
-}
-
-function projectInputAnchorsDeclaration(
-  snapshot: ITtscProjectInputSnapshot,
-  directory: string,
-  identities: ProjectInputPathIdentityContext,
-): boolean {
-  return (
-    snapshot.files.some((file) => identities.isWithin(directory, file)) ||
-    (snapshot.reloadFiles ?? []).some((file) =>
-      identities.isWithin(directory, file),
-    ) ||
-    (snapshot.reloadDirectories ?? []).some(
-      (entry) =>
-        // A reload directory anchors the directory that contains it, never
-        // itself. Its own fingerprint is a digest of its immediate entries, so
-        // nothing below it can reach the corpus, and treating it as its own
-        // anchor would rearm for every entry created directly inside it —
-        // including `node_modules`, which contributors publish as one.
-        identities.isWithin(directory, entry) &&
-        identities.resolve(directory).key !== identities.resolve(entry).key,
-    ) ||
-    snapshot.globs.some((glob) =>
-      identities.isWithin(directory, literalGlobRoot(glob)),
-    )
+function reconcileProjectInputChange(input: {
+  changed?: string;
+  changedInputs: readonly string[];
+  identities: ProjectInputPathIdentityContext;
+  next: ReadonlyMap<string, string>;
+  previous: ReadonlyMap<string, string>;
+  reloadDirectories: readonly string[];
+}): string | undefined {
+  const directories = new Set(
+    input.reloadDirectories.map(
+      (location) => input.identities.resolve(location).key,
+    ),
   );
-}
-
-/**
- * Decide whether an event that named no declared input can still have moved
- * one.
- *
- * The admitted set is the only bound on how often a watch session re-reads and
- * re-hashes its declared corpus, and both directions cost: too narrow drops an
- * atomic replacement, too wide re-fingerprints on every entry an install
- * creates. Exported so that boundary is pinned directly instead of being
- * inferred from a rebuild that a silent rescan and a skipped rescan produce
- * identically.
- */
-export function projectInputTopologyMayAffect(
-  snapshot: ITtscProjectInputSnapshot,
-  location: string,
-  previous: ReadonlyMap<string, string>,
-  identities = createProjectInputPathIdentityContext(),
-): boolean {
-  const changed = path.resolve(location);
-  const anchors = (directory: string): boolean =>
-    projectInputAnchorsDeclaration(snapshot, directory, identities);
-  // An atomic replacement never names the declared file whose bytes it changed;
-  // it names the directory that was swapped, and that directory can be one the
-  // declaration does not contain — renaming `docs` away reports the arriving
-  // `docs-old`, not `docs`. So a directory event is admitted from where it
-  // happened rather than from what it contains: its own parent must already lie
-  // on the path to a declared input. A tree no declaration reaches, such as
-  // `node_modules` under an ordinary project, then costs nothing per created
-  // entry instead of a population rescan and a full content re-fingerprint. A
-  // glob whose literal root covers that tree still admits every directory
-  // beneath it through the branch below, because a directory appearing inside a
-  // glob root can hold matches; the declaration decides that reach, not this
-  // rule.
-  if (isDirectory(changed) && anchors(path.dirname(changed))) return true;
-  return (
-    anchors(changed) ||
-    (snapshot.reloadDirectories ?? []).some((directory) =>
-      identities.isWithin(directory, changed),
-    ) ||
-    snapshot.globs.some((glob) => {
-      const root = literalGlobRoot(glob);
-      if (identities.isWithin(changed, root)) return true;
-      if (identities.isWithin(root, changed) === false) return false;
-      if (isDirectory(changed)) return true;
-      return [...previous.values()].some((input) =>
-        identities.isWithin(changed, input),
-      );
-    })
+  const members = input.changedInputs.filter(
+    (location) => !directories.has(input.identities.resolve(location).key),
   );
-}
-
-export function projectInputEventShouldNotify(input: {
-  contentChanged: boolean;
-  directlyMatched: boolean;
-  membershipChanged: boolean;
-}): boolean {
-  return input.contentChanged || input.membershipChanged;
+  const memberAncestors = new Set<string>();
+  for (const member of members) {
+    let ancestor = path.dirname(input.identities.resolve(member).path);
+    while (true) {
+      const identity = input.identities.resolve(ancestor);
+      if (memberAncestors.has(identity.key)) break;
+      memberAncestors.add(identity.key);
+      const parent = path.dirname(identity.path);
+      if (parent === identity.path) break;
+      ancestor = parent;
+    }
+  }
+  const observed = input.changedInputs.filter((location) => {
+    const key = input.identities.resolve(location).key;
+    return !directories.has(key) || !memberAncestors.has(key);
+  });
+  const changed = input.changed;
+  if (changed !== undefined) {
+    const key = input.identities.resolve(changed).key;
+    if (
+      observed.every((location) =>
+        input.identities.isWithin(changed, location),
+      ) ||
+      (members.length === 0 &&
+        !input.previous.has(key) &&
+        !input.next.has(key) &&
+        observed.every(
+          (location) =>
+            input.identities.resolve(location).key ===
+            input.identities.resolve(path.dirname(changed)).key,
+        ))
+    ) {
+      return changed;
+    }
+  }
+  return observed.length === 1 ? observed[0] : undefined;
 }
 
 function projectInputChangedPaths(input: {
@@ -2425,171 +2531,6 @@ function projectInputChangedPaths(input: {
   return [...changed.values()];
 }
 
-/**
- * Classify an exact execution-selection input ahead of ordinary project data.
- *
- * `changedInputs` carries fingerprint or membership deltas, so a filename-less
- * event can still select the cold lane. A named exact event selects the cold
- * lane only after the surrounding change detector admits the event; unchanged
- * bytes remain quiet before this classifier is observed.
- */
-export function projectInputReloadEventShouldNotify(input: {
-  causedBy?: readonly string[];
-  changed?: string;
-  changedInputs: readonly string[];
-  reloadDirectories?: readonly string[];
-  reloadFiles: readonly string[];
-  globs?: readonly string[];
-}): boolean {
-  const identities = createProjectInputPathIdentityContext();
-  const reloadFiles = new Set(
-    input.reloadFiles.map((location) => identities.resolve(location).key),
-  );
-  const reloadDirectories = (input.reloadDirectories ?? []).map((location) =>
-    identities.resolve(location),
-  );
-  // Territory a declared glob is rooted at, judged against the resolution
-  // directory that would otherwise claim it. A project root is published as a
-  // resolution directory because the config lives there, so the directory a
-  // glob is rooted at reads as a new immediate entry the moment it appears --
-  // and appearing is what a declared population does. The data lane already
-  // reports it, with program invalidation when the membership moved, which is
-  // the cold-Program-same-process transition that belongs to data.
-  //
-  // Data can only carve out strictly below a resolution directory. A glob
-  // rooted on that directory, or above it -- `literalGlobRoot` answers with the
-  // volume root for a pattern with no literal prefix -- would otherwise exempt
-  // everything the directory exists to classify, and the selection lane would
-  // retire in silence. Its role predates any glob drawn around it.
-  //
-  // Only glob roots, either way. A declared file sitting directly in a
-  // resolution directory is still a selection surface: its own bytes are what a
-  // project rule reads to decide, once per execution.
-  const globRoots = (input.globs ?? []).map((glob) =>
-    identities.resolve(literalGlobRoot(glob)),
-  );
-  const exemptedFrom = (
-    directory: ProjectInputPathIdentity,
-    location: string,
-  ): boolean =>
-    globRoots.some(
-      (globRoot) =>
-        globRoot.key !== directory.key &&
-        identities.isWithin(directory.path, globRoot.path) &&
-        identities.isWithin(globRoot.path, location),
-    );
-  // A reload directory is a non-recursive surface: its digest covers its
-  // immediate entries' names, kinds, and link targets, so it moves only when the
-  // directory itself moves or when an entry it holds directly does. Matching the
-  // whole subtree instead makes a resolution ancestor -- the lint config graph
-  // publishes every node_modules level it searched, up to the filesystem root --
-  // read every edit beneath it as a selection change, which restarts the sidecar
-  // on each keystroke and ends warm reuse for any project inside one.
-  const holdsAsImmediateEntry = (location: string): boolean => {
-    const parent = identities.resolve(path.dirname(location)).key;
-    return reloadDirectories.some(
-      (directory) =>
-        directory.key === parent && exemptedFrom(directory, location) === false,
-    );
-  };
-  const namesDirectory = (location: string): boolean => {
-    const key = identities.resolve(location).key;
-    return reloadDirectories.some((directory) => directory.key === key);
-  };
-  // A digest delta on the directory itself is the only signal there is when the
-  // entry that appeared is not a declared match, so it cannot simply be dropped
-  // -- but it also cannot say what appeared. The event being classified in the
-  // same pass can: when it names data, the delta it caused is that data's, and
-  // when it names anything else, or nothing at all, the safe reading is that
-  // resolution moved. A missed reselection is a wrong answer; a spare restart is
-  // a slow one.
-  const explains = (directory: ProjectInputPathIdentity): boolean => {
-    const causes =
-      input.causedBy ?? (input.changed === undefined ? [] : [input.changed]);
-    // Only an immediate entry can move this directory's digest, so only an
-    // immediate entry can account for the delta. Asking whether the event was
-    // data somewhere else answers a different directory's question, and one
-    // exemption would then cancel every other directory's evidence.
-    return causes.some((location) => {
-      const parent = identities.resolve(path.dirname(location)).key;
-      return parent === directory.key && exemptedFrom(directory, location);
-    });
-  };
-  const isReloadDirectoryEvent = (location: string): boolean =>
-    namesDirectory(location) || holdsAsImmediateEntry(location);
-  const isReloadDirectoryDelta = (location: string): boolean => {
-    if (holdsAsImmediateEntry(location)) return true;
-    const key = identities.resolve(location).key;
-    return reloadDirectories.some(
-      (directory) => directory.key === key && explains(directory) === false,
-    );
-  };
-  return (
-    (input.changed !== undefined &&
-      (reloadFiles.has(identities.resolve(input.changed).key) ||
-        isReloadDirectoryEvent(input.changed))) ||
-    input.changedInputs.some(
-      (location) =>
-        reloadFiles.has(identities.resolve(location).key) ||
-        isReloadDirectoryDelta(location),
-    )
-  );
-}
-
-/**
- * Return whether a project-input population transition can reshape a Program.
- *
- * JSON is data to a ProjectRule but may simultaneously be a `resolveJsonModule`
- * source. TypeScript and JavaScript paths can likewise overlap a project-input
- * declaration. Their creation or deletion therefore requires a cold Program
- * inside the existing resident process. A filename-less event cannot identify
- * the changed member and is conservatively invalidating whenever the population
- * moved.
- */
-export function projectInputMembershipInvalidatesProgram(input: {
-  changed?: string;
-  changedInputs?: readonly string[];
-  contentChanged?: boolean;
-  next: ReadonlyMap<string, string>;
-  previous: ReadonlyMap<string, string>;
-}): boolean {
-  if (
-    input.contentChanged === true &&
-    (
-      input.changedInputs ??
-      (input.changed === undefined ? [] : [input.changed])
-    ).some(
-      (location) => path.basename(location).toLowerCase() === "package.json",
-    )
-  ) {
-    return true;
-  }
-  if (mapsEqual(input.previous, input.next)) return false;
-  if (input.changed === undefined) return true;
-  for (const [key, location] of input.previous) {
-    if (
-      input.next.has(key) === false &&
-      projectInputPathMayAffectProgram(location)
-    ) {
-      return true;
-    }
-  }
-  for (const [key, location] of input.next) {
-    if (
-      input.previous.has(key) === false &&
-      projectInputPathMayAffectProgram(location)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function projectInputPathMayAffectProgram(location: string): boolean {
-  const extension = path.extname(location).toLowerCase();
-  return extension === ".json" || isCompilerEmittableSourceExtension(extension);
-}
-
 function compilerMembershipChange(
   previous: ReadonlyMap<string, string>,
   next: ReadonlyMap<string, string>,
@@ -2608,10 +2549,11 @@ function projectInputCompilerMembershipChange(
   snapshot: ITtscProjectInputSnapshot,
   changed: readonly string[],
 ): string[] {
+  const identities = createProjectInputPathIdentityContext();
   return changed.filter(
     (location) =>
-      matchesProjectInput(snapshot, location) &&
-      projectInputPathMayAffectProgram(location),
+      matchesProjectInput(snapshot, location, identities) &&
+      ProjectInputWatchRules.projectInputPathMayAffectProgram(location),
   );
 }
 
@@ -2633,9 +2575,15 @@ function projectInputCompilerMembershipProjectChanges(
   const changes = new Map<string, string>();
   for (const location of locations) {
     const candidate = identities.resolve(location);
-    const root = roots
-      .filter((entry) => identities.isWithin(entry.path, candidate.path))
-      .sort((left, right) => right.path.length - left.path.length)[0];
+    let root: (typeof roots)[number] | undefined;
+    for (const entry of roots) {
+      if (
+        identities.isWithin(entry.path, candidate.path) &&
+        (root === undefined || entry.path.length > root.path.length)
+      ) {
+        root = entry;
+      }
+    }
     const change = root ?? candidate;
     changes.set(change.key, change.path);
   }
@@ -2644,13 +2592,14 @@ function projectInputCompilerMembershipProjectChanges(
 
 function fingerprintProjectInputMatches(
   matches: ReadonlyMap<string, string>,
+  readDirectory: typeof fs.readdirSync,
 ): Map<string, string> {
   const fingerprints = new Map<string, string>();
   for (const [key, location] of matches) {
     fingerprints.set(
       key,
-      isDirectory(location)
-        ? fingerprintProjectInputDirectory(location)
+      WatchPaths.isDirectory(location)
+        ? fingerprintProjectInputDirectory(location, readDirectory)
         : fingerprintProjectInputFile(location),
     );
   }
@@ -2668,10 +2617,12 @@ function fingerprintProjectInputFile(location: string): string {
   }
 }
 
-function fingerprintProjectInputDirectory(location: string): string {
+function fingerprintProjectInputDirectory(
+  location: string,
+  readDirectory: typeof fs.readdirSync,
+): string {
   try {
-    const entries = fs
-      .readdirSync(location, { withFileTypes: true })
+    const entries = readDirectory(location, { withFileTypes: true })
       .map((entry) => {
         const kind = entry.isDirectory()
           ? "directory"
@@ -2712,13 +2663,17 @@ function matchesProjectInputGlob(
   const candidateParts = path
     .relative(root.path, candidate.path)
     .split(path.sep);
-  return matchProjectInputGlobParts(
-    sensitive
-      ? patternParts
-      : patternParts.map((segment) => segment.toLowerCase()),
-    sensitive
-      ? candidateParts
-      : candidateParts.map((segment) => segment.toLowerCase()),
+  // Unknown capability is an observation-routing question, not an identity
+  // proof: admit either interpretation so an unproven case policy cannot hide
+  // a possible declared input. The resolver retains distinct physical keys.
+  return (
+    (sensitive !== false &&
+      matchProjectInputGlobParts(patternParts, candidateParts)) ||
+    (sensitive !== true &&
+      matchProjectInputGlobParts(
+        patternParts.map((segment) => segment.toLowerCase()),
+        candidateParts.map((segment) => segment.toLowerCase()),
+      ))
   );
 }
 
@@ -2767,14 +2722,6 @@ function matchProjectInputGlobSegment(
   return new RegExp(`${source}$`, "u").test(candidate);
 }
 
-function mapsEqual(
-  left: ReadonlyMap<string, string>,
-  right: ReadonlyMap<string, string>,
-): boolean {
-  if (left.size !== right.size) return false;
-  return [...left].every(([key, value]) => right.get(key) === value);
-}
-
 function arraysEqual(
   left: readonly string[],
   right: readonly string[],
@@ -2784,65 +2731,24 @@ function arraysEqual(
   );
 }
 
-function isPathWithin(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return (
-    relative === "" ||
-    (relative !== ".." &&
-      relative.startsWith(`..${path.sep}`) === false &&
-      !path.isAbsolute(relative))
-  );
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
 }
 
 /**
- * Plan one compiler-directory event without relying on backend timing.
- *
- * POSIX file watchers own ordinary content changes. A named rename re-arms the
- * replaced file; an unnamed event conservatively re-arms and reports every
- * surviving tracked input below the watch root. Windows has no per-file
- * watchers here, so both named and unnamed directory events report inputs.
+ * What a plugin build keys a plugin input on: the digest of the files its build
+ * reads from a source directory (`pluginSourceDigest`), or a file's bytes. An
+ * input that cannot be read has a state of its own, so the change that made it
+ * unreadable is reported and the build names the failure.
  */
-export function planCompilerDirectoryWatchEvent(input: {
-  changed?: string;
-  event: string;
-  exists(location: string): boolean;
-  location: string;
-  platform: NodeJS.Platform;
-  trackedFiles: ReadonlyMap<string, string>;
-}): CompilerDirectoryWatchEventPlan {
-  const candidates =
-    input.changed === undefined
-      ? [...input.trackedFiles.values()].filter(
-          (file) =>
-            input.exists(file) &&
-            isPathWithin(input.location, path.resolve(file)),
-        )
-      : input.trackedFiles.has(
-            pathKeyForPlatform(input.changed, input.platform),
-          ) && input.exists(input.changed)
-        ? [input.changed]
-        : [];
-  if (input.changed === undefined) {
-    return {
-      changes: candidates,
-      rearm: input.platform === "win32" ? [] : candidates,
-      refresh: true,
-    };
-  }
-  if (candidates.length === 0) {
-    return { changes: [], rearm: [], refresh: true };
-  }
-  if (input.platform === "win32") {
-    return { changes: candidates, rearm: [], refresh: false };
-  }
-  if (input.event === "rename") {
-    return { changes: candidates, rearm: candidates, refresh: false };
+function pluginInputState(input: string): string {
+  try {
+    return WatchPaths.isDirectory(input)
+      ? `directory:${pluginSourceDigest(input)}`
+      : `file:${fingerprintProjectInputFile(input)}`;
+  } catch (error) {
+    return `unreadable:${error instanceof Error ? error.message : String(error)}`;
   }
-  return { changes: [], rearm: [], refresh: false };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
 }
 
 /**
@@ -2873,14 +2779,13 @@ function watcherRegistrationPath(location: string): string {
   }
 }
 
-function pathKey(location: string): string {
-  return pathKeyForPlatform(location, process.platform);
-}
-
-function pathKeyForPlatform(
-  location: string,
-  platform: NodeJS.Platform,
-): string {
-  const resolved = path.resolve(location);
-  return platform === "win32" ? resolved.toLowerCase() : resolved;
+/**
+ * Report the actual decision inputs, without additional filesystem
+ * observations.
+ */
+function reportProjectInputDecision(decision: Record<string, unknown>): void {
+  if (!process.env.TTSC_WATCH_DEBUG_INPUTS) return;
+  process.stdout.write(
+    `[ttsc:debug] project-input decision ${JSON.stringify(decision)}\n`,
+  );
 }