ttsc 0.30.3 → 0.31.0

package/src/launcher/internal/watch/literalGlobRoot.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+/**
+ * Select the literal directory prefix before a glob's first `*` or `?`.
+ *
+ * A pattern without any wildcard names one file, so its directory is returned.
+ * A wildcard in the first segment after the resolved volume root yields that
+ * root; a relative pattern includes its working-directory prefix first. Native
+ * resolution anchors relative patterns at the current working directory. Every
+ * backslash in the resolved spelling is interpreted as a glob separator; this
+ * is lexical glob syntax, not physical identity resolution or preservation of a
+ * literal POSIX backslash filename. The topology owner decides whether the
+ * selected directory exists and can be observed.
+ *
+ * @evidence contracts/common.md#principled-implementation The last separator before the first supported wildcard identifies the deepest literal directory that can contain every match.
+ * @evidence contracts/common.md#clear-and-simple-design Resolve, locate the wildcard boundary and preserve the volume root in one direct calculation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The root derives from the declared pattern instead of known project directory names.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain wildcard-free and root-level patterns following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native resolve/dirname/parse supply host drive, UNC and POSIX root syntax. Backslash-to-slash conversion expresses the supported glob separator interpretation, not proof that arbitrary physical filename spellings remain unchanged.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local normalized strings and split arrays are transient; the returned path transfers to the caller. No native descriptor, observer or historical query map is retained, and input text has no quota here.
+ * @evidence contracts/performance.md#efficient-algorithms Native path resolution, slash split/join, wildcard/separator scans and possible prefix resolution process supplied spelling plus the current-directory prefix for relative patterns. Temporary text/arrays scale with those lengths, without native stat or descendant enumeration; path length is not bounded by the one-path result.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This lexical selector owns no native observation producer or authority cache to coordinate. Relative results depend on the current working directory and host grammar, so an answer keyed only by the raw pattern would not establish reuse equivalence.
+ */
+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);
+}

package/src/launcher/internal/watch/planCompilerDirectoryWatchEvent.ts

@@ -0,0 +1,83 @@
+import path from "node:path";
+
+import type { ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import type { CompilerDirectoryWatchEventPlan } from "./CompilerDirectoryWatchEventPlan";
+
+/**
+ * Plan one compiler-directory event without relying on backend timing.
+ *
+ * A named content change of a tracked file is a candidate on every platform. On
+ * POSIX the file has a watcher of its own too, and either can miss what the
+ * other hears: on macOS a directory watch has heard a config edit its file
+ * watch never delivered. Both are decided from the bytes
+ * (`WatchTopology.compilerChangesToReport`), so the first to see the edit
+ * reports it once. A named rename selects the surviving file for rearming; an
+ * unnamed event conservatively selects every surviving tracked input below the
+ * watch root as a change candidate and for non-Windows rearming. The caller
+ * verifies actual content/owner movement before reporting; an event alone does
+ * not prove inode replacement. Windows has no per-file watchers here.
+ *
+ * Native case observations belong to `identities`, shared with the caller's
+ * reconciliation or created fresh here. An exact indexed member is preferred; a
+ * missing key conservatively routes eligible lexical aliases without merging
+ * stored members. `platform` controls rearming, not filesystem case policy.
+ *
+ * @evidence contracts/common.md#principled-implementation A named tracked survivor is a content candidate; absent localization requires conservative coverage and membership refresh, while POSIX inode replacement additionally rearms per-file watches.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate selection precedes independent refresh/rearm policy with no backend-timing simulation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual tracked membership and existence qualify candidates instead of treating every notification as an edit or guessing missing filenames.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain directory-only events, replacement and unnamed notifications following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform selects backend handle rearming only; lexical key and conservative fallback matching use native parent-directory case observations, retaining sensitive and unknown names as distinct stored inputs.
+ * @evidence contracts/performance.md#efficient-algorithms An indexed surviving hit avoids F-member traversal after delegated lexical key work. Other cases snapshot F borrowed values before filtering, so callbacks cannot change that traversal population; snapshot plus admitted arrays require O(F) references. Routing includes path/component/ancestor/case observations, key text and supplied existence callbacks; dimensions and native-query costs are uncapped. One transaction shares repeated case observations within the decision.
+ * @evidence contracts/performance.md#reuse-equivalent-work The supplied reconciliation context shares equivalent parent-directory capability observations across key construction and candidate classification; standalone decisions start fresh observations rather than historical case assumptions.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The planner borrows tracked membership and returns invocation-local candidates, retaining no watcher, historical event population or independent resident cache.
+ */
+export function planCompilerDirectoryWatchEvent(input: {
+  changed?: string;
+  event: string;
+  exists(location: string): boolean;
+  identities?: ProjectInputPathIdentityContext;
+  location: string;
+  platform: NodeJS.Platform;
+  trackedFiles: ReadonlyMap<string, string>;
+}): CompilerDirectoryWatchEventPlan {
+  const identities =
+    input.identities ??
+    createProjectInputPathIdentityContext({ throwOnRealpathError: false });
+  const tracked =
+    input.changed === undefined
+      ? undefined
+      : input.trackedFiles.get(identities.lexicalKey(input.changed));
+  const candidates =
+    input.changed === undefined
+      ? [...input.trackedFiles.values()].filter(
+          (file) =>
+            input.exists(file) &&
+            identities.lexicalIsWithin(input.location, path.resolve(file)),
+        )
+      : tracked !== undefined && input.exists(tracked)
+        ? [tracked]
+        : [...input.trackedFiles.values()].filter(
+            (file) =>
+              identities.lexicalMatches(file, input.changed!) &&
+              input.exists(file),
+          );
+  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 };
+  }
+  return { changes: candidates, rearm: [], refresh: false };
+}

package/src/launcher/internal/watch/projectInputActiveWatchDirectories.ts

@@ -0,0 +1,47 @@
+import path from "node:path";
+
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+
+/**
+ * Removes recursive roots already covered by an ancestor without rewriting the
+ * declaration-specific roots retained by WatchTopology. Coverage here means
+ * identity-key ancestry used for root selection, not proof that a native
+ * watcher has been installed or delivers replacement events. All spellings and
+ * an explicitly supplied identity context must use the host's path grammar
+ * because ancestor walking uses native path.dirname.
+ *
+ * @evidence contracts/common.md#principled-implementation A physical root is redundant exactly when another selected root is its ancestor; returned spellings remain the caller's declarations.
+ * @evidence contracts/common.md#clear-and-simple-design One identity-keyed map separates deduplication and ancestor coverage from spelling preservation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Root pruning uses actual resolved identity rather than textual prefixes or guessed casing.
+ * @evidence contracts/common.md#meaningful-documentation Native prose and the identity-versus-spelling comment explain why selection does not rename declarations, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The transaction resolver supplies physical identity and case capability; native dirname walks the correct volume ancestry.
+ * @evidence contracts/performance.md#efficient-algorithms N input spellings require identity resolution before R distinct keys are retained. Each retained key walks native dirname ancestors and queries map membership rather than all root pairs; work includes key lengths and delegated ancestor/entry/case observations, not just R times depth. Temporary map/array and spelling storage grows with input/unique-key populations, without descendant enumeration or a quota here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One supplied transaction shares per-key native observations during input deduplication; ancestor comparisons then use already-resolved keys. Default calls create a fresh context. Reuse expires only when the caller releases the context, not automatically at reconciliation end, and is not an atomic filesystem snapshot.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selection owns no resident cache or native handle; returned roots transfer to the caller.
+ */
+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);
+}

package/src/launcher/internal/watch/projectInputAvailableWatchDirectory.ts

@@ -0,0 +1,56 @@
+import path from "node:path";
+
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import { WatchPaths } from "./WatchPaths";
+
+/**
+ * The directory to watch `location` through after some candidates failed.
+ *
+ * Starting at `location`, it escalates to the nearest existing parent while the
+ * candidate is in `rejected` (a directory whose watcher already errored). It
+ * refuses a candidate strictly containing `projectRoot`, returning `undefined`
+ * instead; equal project identity remains admissible. Losing the failed root is
+ * preferred to selecting the project from above. This selector installs no
+ * watcher and does not establish native event delivery.
+ *
+ * @evidence contracts/common.md#principled-implementation Rejected roots climb existing ancestors within the same project-containment ceiling as initial selection, preserving the distinction between unavailable coverage and unsafe broadening.
+ * @evidence contracts/common.md#clear-and-simple-design One ancestor loop combines rejection membership, existing-directory discovery and a shared identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recovery refuses strictly containing roots rather than treating any available ancestor as a safe candidate; project identity itself remains eligible.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain rejection, escalation and the undefined result following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native ancestry uses path.dirname and the transaction resolver compares actual physical identities rather than an OS-derived case rule.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The helper acquires no watcher or historical state. Borrowed rejection/context state remains caller-owned; a default context becomes reclaimable when invocation references are discarded, and the returned path transfers to the caller.
+ * @evidence contracts/performance.md#efficient-algorithms Rejected candidates climb native lexical ancestors; fallback directory searches perform stat admission, and identity/containment adds realpath, ancestor, entry and possible case-query work. Depth/path/key text and observation populations are uncapped; no descendant corpus is enumerated. The initial candidate is assumed selected by the caller rather than independently checked for directory kind here.
+ * @evidence contracts/performance.md#reuse-equivalent-work A supplied transaction shares repeated identity/case observations across candidate and project-ceiling queries; an omitted context starts invocation-local observations. Native fallback stat admission is fresh and not memoized by this helper.
+ */
+export function projectInputAvailableWatchDirectory(
+  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 = WatchPaths.nearestExistingDirectory(parent);
+    if (fallback === undefined) return undefined;
+    current = fallback;
+  }
+}

package/src/launcher/internal/watch/projectInputEventShouldNotify.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether a project-input event is worth a build cycle.
+ *
+ * Only a change of content or of membership notifies. Being matched by a
+ * declared glob is territory, not a change, so `directlyMatched` alone never
+ * triggers a rebuild.
+ *
+ * @evidence contracts/common.md#principled-implementation A content or membership delta establishes changed input; matching declared territory alone establishes neither.
+ * @evidence contracts/common.md#clear-and-simple-design One boolean disjunction keeps event admission separate from population classification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A matched path does not manufacture a content change or schedule fixture-specific work.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraph distinguishes change from territory following the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources projectInputEventShouldNotify acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms projectInputEventShouldNotify performs a fixed number of steps with no loop or recursion over caller data.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work projectInputEventShouldNotify computes one result per call, so there is no repeated work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation projectInputEventShouldNotify computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function projectInputEventShouldNotify(input: {
+  contentChanged: boolean;
+  directlyMatched: boolean;
+  membershipChanged: boolean;
+}): boolean {
+  return input.contentChanged || input.membershipChanged;
+}

package/src/launcher/internal/watch/projectInputMembershipInvalidatesProgram.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+
+import { ProjectInputWatchRules } from "./ProjectInputWatchRules";
+import { WatchPaths } from "./WatchPaths";
+
+/**
+ * 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.
+ *
+ * @evidence contracts/common.md#principled-implementation Added or removed emittable members and package.json content changes can alter compiler resolution; unlocalized population movement conservatively invalidates the resident Program.
+ * @evidence contracts/common.md#clear-and-simple-design Package selection changes, equal membership and changed compiler-capable members are separate ordered decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate inspects both populations instead of guessing the changed member from one named event.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain overlapping JSON/source populations and unnamed-event invalidation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native basename and extension APIs interpret paths; already canonical membership keys retain their producer's actual identity policy.
+ * @evidence contracts/performance.md#efficient-algorithms A content-change check can inspect C supplied changed-input spellings before map equality scans up to P borrowed entries. If membership differs and the event is named, removed/added checks can visit P previous and N next entries with short-circuiting. Indexed keys, value comparison, native basename/extname and lowercasing add uncapped spelling costs; no population array is reconstructed beyond an optional one-element fallback.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate classifies supplied snapshots without coordinating compilation reuse itself.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Both populations are borrowed and no historical state or native resource is retained.
+ */
+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 (WatchPaths.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 &&
+      ProjectInputWatchRules.projectInputPathMayAffectProgram(location)
+    ) {
+      return true;
+    }
+  }
+  for (const [key, location] of input.next) {
+    if (
+      input.previous.has(key) === false &&
+      ProjectInputWatchRules.projectInputPathMayAffectProgram(location)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/launcher/internal/watch/projectInputReloadEventShouldNotify.ts

@@ -0,0 +1,127 @@
+import path from "node:path";
+
+import { type ProjectInputPathIdentity } from "../../../internal/pathIdentity/ProjectInputPathIdentity";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import { literalGlobRoot } from "./literalGlobRoot";
+
+/**
+ * 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.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact selection files and immediate resolution-directory entries choose execution reload; a strictly nested declared glob can explain its own ancestor's membership delta without exempting unrelated selection changes.
+ * @evidence contracts/common.md#clear-and-simple-design Exact-file membership, immediate-entry membership and causal explanations have distinct helpers under one classification operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A data exemption must explain the same directory's observed delta, not cancel every reload because some unrelated data event occurred.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain caller admission, immediate-directory scope and strict glob exemptions with their reasons, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation One filesystem identity transaction resolves both declared aliases and changed native paths, using actual case and link identity.
+ * @evidence contracts/performance.md#efficient-algorithms Setup resolves F reload files, D reload directories and G literal glob roots into call-local collections. Named events and C deltas scan directory/glob predicates; an unexplained directory delta can additionally scan A supplied causes and G exemptions for matching directory entries. Duplicate declarations remain present. Costs include native identity/ancestor/case queries and path/key text, not only predicate counts; classification itself does not hash file contents and no population/text bound is imposed here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One transaction caches equivalent native identity/case resolutions for every helper in the same decision; a later event starts a fresh transaction so link retargets are observed.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Identity caches and predicate collections are local to one decision, without a resident historical cache or native handle.
+ */
+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 when a wildcard follows that resolved root directly -- 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),
+    )
+  );
+}

package/src/launcher/internal/watch/projectInputReplacementStrandsWatchers.ts

@@ -0,0 +1,57 @@
+import path from "node:path";
+
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import { ProjectInputWatchRules } from "./ProjectInputWatchRules";
+import { WatchPaths } from "./WatchPaths";
+
+/**
+ * Select a directory attention that requests recursive watcher reinstallation.
+ *
+ * Node 22.15.0's `lib/fs.js` routes recursive watches to
+ * `lib/internal/fs/recursive_watch.js` outside macOS and Windows. That
+ * implementation records paths and skips an already registered path, motivating
+ * this policy's rearm selection on those hosts. The predicate returns false for
+ * macOS and Windows; that selection does not prove native subtree delivery
+ * after replacement or that those backends follow every replaced path.
+ *
+ * On the selected backend, the supplied path must currently stat as a directory
+ * and its parent must anchor at least one declared file, reload file, strict
+ * reload-directory descendant or literal glob root. This is an attention
+ * policy, not detection that an object was replaced. Restricting reinstallation
+ * avoids repeatedly rebuilding a recursive entry population on unrelated
+ * changes. Reload-directory membership alone anchors its parent rather than
+ * itself; another declaration can still anchor that same path. The topology
+ * caller owns retiring and synchronizing watchers before its next snapshot;
+ * this predicate starts or closes no watcher and does not certify the resulting
+ * coverage.
+ *
+ * @param identities Identity transaction; absence creates a native host
+ *   context.
+ * @param platform Backend selection only; paths still use the host's path API
+ *   and the supplied identity context, not this argument's foreign path
+ *   grammar.
+ * @evidence contracts/common.md#principled-implementation The supported selection policy requests rearming only outside macOS/Windows for an existing directory whose parent anchors a declaration; its boolean is not proof of replacement or native event delivery.
+ * @evidence contracts/common.md#clear-and-simple-design A backend capability branch precedes directory and declaration checks, separating rescan admission from handle reinstallation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Node's path-indexed registration supplies the rearm premise; actual directory/declaration observations select attention without test identities or an invented proof that native subtree backends always recover replacements.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain native versus per-directory backends and why indiscriminate reinstalling is costly, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform selection expresses Node's recursive watcher implementation boundary; filesystem identity and containment still come from the actual transaction resolver.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate starts or retains no watcher. A supplied identity context remains caller-owned; the default creates invocation-local observation maps without eviction, released only when their references are discarded.
+ * @evidence contracts/performance.md#efficient-algorithms Default context allocation occurs before the platform return. Selected hosts resolve/stat one changed path and short-circuit over files, reload declarations and glob roots; each containment query can perform delegated identity/path/native work. No declared corpus enumeration or watcher installation occurs in this predicate, and text/declaration/query populations are not capped here.
+ * @evidence contracts/performance.md#reuse-equivalent-work The topology caller supplies one identity transaction across attention and declaration checks, reusing per-key observations within that native state. Standalone default calls create fresh contexts; this predicate neither shares across transactions nor caches replacement verdicts.
+ */
+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 (!WatchPaths.isDirectory(changed)) return false;
+  return ProjectInputWatchRules.projectInputAnchorsDeclaration(
+    snapshot,
+    path.dirname(changed),
+    identities,
+  );
+}

package/src/launcher/internal/watch/projectInputTopologyMayAffect.ts

@@ -0,0 +1,73 @@
+import path from "node:path";
+
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import { ProjectInputWatchRules } from "./ProjectInputWatchRules";
+import { WatchPaths } from "./WatchPaths";
+import { literalGlobRoot } from "./literalGlobRoot";
+
+/**
+ * Decide whether an event that named no declared input can still have moved
+ * one.
+ *
+ * The admitted set narrows which named events lead a watch session to re-read
+ * and re-hash 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.
+ *
+ * @evidence contracts/common.md#principled-implementation Declaration ancestry, reload territories and admitted glob trees decide whether an unnamed input may have moved, covering replacement events named after an arriving sibling.
+ * @evidence contracts/common.md#clear-and-simple-design A shared declaration-anchor predicate separates replacement ancestry from reload and glob admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Admission follows published declarations rather than hardcoded node_modules exclusion or unconditional whole-project rescanning.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain lost replacements and unnecessary corpus scans with their reasons, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path operations and transaction-owned physical containment qualify event paths and glob roots with actual case semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Up to two anchor checks visit file/reload/glob declarations before reload-directory and G glob branches; each glob can scan P borrowed previous members. Native directory stat and delegated identity/ancestor/case observations plus literal-root/path/key text are additional costs. Short-circuiting can stop earlier; populations/text are uncapped and this predicate does not read or hash corpus contents.
+ * @evidence contracts/performance.md#reuse-equivalent-work The caller can share one identity transaction with event matching and later classification; repeated resolutions within this decision use that transaction's cache.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No watcher, historical event population or resident cache is acquired by this admission predicate.
+ */
+export function projectInputTopologyMayAffect(
+  snapshot: ITtscProjectInputSnapshot,
+  location: string,
+  previous: ReadonlyMap<string, string>,
+  identities = createProjectInputPathIdentityContext(),
+): boolean {
+  const changed = path.resolve(location);
+  const anchors = (directory: string): boolean =>
+    ProjectInputWatchRules.projectInputAnchorsDeclaration(
+      snapshot,
+      directory,
+      identities,
+    );
+  // An atomic replacement can name an ancestor or arriving sibling rather than
+  // the declared file whose bytes moved. That directory can be one the
+  // declaration does not contain: renaming `docs` away can report 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, avoids corpus rescanning for each
+  // created entry while still paying this admission predicate cost. 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 (WatchPaths.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 (WatchPaths.isDirectory(changed)) return true;
+      for (const input of previous.values()) {
+        if (identities.isWithin(changed, input)) return true;
+      }
+      return false;
+    })
+  );
+}

package/src/launcher/internal/watch/projectInputWatchDirectories.ts

@@ -0,0 +1,33 @@
+import { ProjectInputWatchRules } from "./ProjectInputWatchRules";
+
+/**
+ * Return the selected zero-or-one recursive root for a project-input
+ * declaration.
+ *
+ * The shared selector uses the project's nearest existing ancestry for internal
+ * inputs. External inputs prefer the declared parent's existing ancestry, then
+ * the target's own, excluding strict ancestors of the project but admitting
+ * equal physical identity. An unavailable selected root becomes an empty list.
+ * This adapter neither installs a watch nor proves delivery after replacement;
+ * the topology caller owns observation and reporting of uncovered
+ * declarations.
+ *
+ * @evidence contracts/common.md#principled-implementation The shared selector preserves the internal-root and external strict-ancestor selection policy; an unavailable owner remains an empty result rather than proof of watch coverage.
+ * @evidence contracts/common.md#clear-and-simple-design One delegation converts the optional owner into the caller's zero-or-one root list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No second fallback broadens an absent safe owner into a system-wide watch.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish current root selection, equal versus strict ancestry and caller-owned native observation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The delegated selector owns native ancestry and actual physical containment instead of caller-side separator or OS-case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The adapter returns a caller-owned list of at most one spelling and starts no watcher or retained observer. The selector's default identity maps are invocation-local; their query population is not bounded by this small result.
+ * @evidence contracts/performance.md#efficient-algorithms The zero-or-one list conversion is fixed-width, but its delegated selector performs identity/path work and one internal or two external native ancestor-stat searches, including possible case queries. No descendant corpus is enumerated and declaration path depth/text is not capped here.
+ * @evidence contracts/performance.md#reuse-equivalent-work The delegated selector shares its new context's per-key observations within one selection. Each adapter invocation creates a fresh context, so repeated declarations may repeat native observations; this adapter coordinates no cross-invocation answer reuse or watcher ownership.
+ */
+export function projectInputWatchDirectories(
+  target: string,
+  projectRoot: string,
+): string[] {
+  const root = ProjectInputWatchRules.projectInputRecursiveWatchRoot(
+    target,
+    projectRoot,
+  );
+  return root === undefined ? [] : [root];
+}