ttsc 0.31.4 → 0.32.0

package/src/compiler/internal/runSingleFileEmit.ts

@@ -20,10 +20,11 @@ import { readEffectiveCompilerOptions } from "./readEffectiveCompilerOptions";
  * failure propagates on success and is aggregated with an earlier operation
  * failure rather than replacing it.
  *
- * A launcher-supplied selection shares its project and original compiler argument
- * cwd with public output planning. Response freshness is checked before native
- * work and publication; these sequential checks do not pin bytes atomically.
- * Callers without that record retain explicit config/nearest-file discovery.
+ * A launcher-supplied selection shares its project and original compiler
+ * argument cwd with public output planning. Response freshness is checked
+ * before native work and publication; these sequential checks do not pin bytes
+ * atomically. Callers without that record retain explicit config/nearest-file
+ * discovery.
  *
  * @returns The transformed JavaScript source text.
  * @throws When the build exits non-zero, proves no JavaScript for the requested
@@ -59,7 +60,8 @@ export function runSingleFileEmit(
     });
   const tsconfig = project.path;
   const compilerArgsCwd = selection?.compilerArgsCwd ?? project.root;
-  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
+  if (selection !== undefined)
+    CompilerProjectSelection.assertCurrent(selection);
   // The root tsgo lays the outputs against: a `--rootDir` forwarded on the
   // command line, which reaches it after the config; otherwise the declared
   // one, which `readProjectConfig` already absolutized; otherwise the project's
@@ -75,7 +77,8 @@ export function runSingleFileEmit(
     typeof effective === "string"
       ? path.resolve(compilerArgsCwd, effective)
       : project.root;
-  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
+  if (selection !== undefined)
+    CompilerProjectSelection.assertCurrent(selection);
   const outDir = createCanonicalTempDirectory("ttsc-single-file-");
   let failed = false;
   let failure: unknown;
@@ -119,7 +122,8 @@ export function runSingleFileEmit(
       );
     }
     const transformed = fs.readFileSync(emitted, "utf8");
-    if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
+    if (selection !== undefined)
+      CompilerProjectSelection.assertCurrent(selection);
     if (options.out) {
       const target = path.isAbsolute(options.out)
         ? options.out

package/src/flags/ParseOptions.ts

@@ -29,8 +29,8 @@ export interface ParseOptions {
   readonly errorPrefix: string;
 
   /**
-   * Observe a validated launcher assignment at its compiler-frame position.
-   * The canonical schema name and parsed value retain alias/value semantics;
+   * Observe a validated launcher assignment at its compiler-frame position. The
+   * canonical schema name and parsed value retain alias/value semantics;
    * passthroughIndex counts compiler tokens already forwarded at this point.
    * Exceptions propagate from the caller's observer.
    *

package/src/internal/E2ETrace.ts

@@ -51,7 +51,9 @@ export namespace E2ETrace {
   export function runtimeCleanup(
     directory: string,
     runtimeCacheDir: string,
-    origin: "ttsx-runtime-cleanup" | "runtime-clean-selection" = "ttsx-runtime-cleanup",
+    origin:
+      | "ttsx-runtime-cleanup"
+      | "runtime-clean-selection" = "ttsx-runtime-cleanup",
   ):
     | ((
         phase: string,
@@ -62,6 +64,7 @@ export namespace E2ETrace {
           owner?: { hostname: string; pid: number };
           result: string;
           errorCode?: string;
+          state?: string;
         },
       ) => void)
     | undefined {
@@ -86,6 +89,7 @@ export namespace E2ETrace {
           owner?: { hostname: string; pid: number };
           result: string;
           errorCode?: string;
+          state?: string;
         },
       ): void => {
         try {

package/src/internal/OwnedNativeProcess.ts

@@ -42,8 +42,8 @@ export namespace OwnedNativeProcess {
    *
    * Enabled private tracing may receive a frozen scalar copy of an accepted
    * receipt through the existing retirement observer. The original helper has
-   * closed before that copy is made. It contains no command or environment
-   * data and cannot grant closure authority. Trace IO can change scheduling.
+   * closed before that copy is made. It contains no command or environment data
+   * and cannot grant closure authority. Trace IO can change scheduling.
    *
    * @evidence contracts/common.md#principled-implementation A private request carries exact command/options and a structurally checked native receipt is required after helper close; cancellation returns only after joined and empty-boundary proof.
    * @evidence contracts/common.md#clear-and-simple-design Control stdin is separate from target input, target output streams remain unchanged, and one finally owns listeners and private protocol storage.

package/src/internal/SourceNativeRetirement.ts

@@ -417,17 +417,18 @@ export namespace SourceNativeRetirement {
    * still exists. Cleanup can then remove that root without another realpath.
    * Only successful cleanup drops the exact captured registration; a failed
    * cleanup or a replacement registration remains owned. Unknown boundaries
-   * defer the same callback and identity through the original release protocol.
+   * defer the same callback and identity through the original release
+   * protocol.
    *
-   * The optional task failure distinguishes an earlier thrown undefined from
-   * no earlier failure. It is combined with a cleanup refusal, never rethrown
+   * The optional task failure distinguishes an earlier thrown undefined from no
+   * earlier failure. It is combined with a cleanup refusal, never rethrown
    * after successful cleanup or deferred recovery. Ordinary unscoped callers
    * perform cleanup without observing or inventing a registration.
    *
-   * Enabled private tracing observes the original callback's execution, not
-   * its deferral. Scalar own error properties are read without invoking
-   * getters; reflection or sink failures leave the original outcome intact.
-   * Synchronous trace writes can change scheduling and prove only that run.
+   * Enabled private tracing observes the original callback's execution, not its
+   * deferral. Scalar own error properties are read without invoking getters;
+   * reflection or sink failures leave the original outcome intact. Synchronous
+   * trace writes can change scheduling and prove only that run.
    *
    * @evidence contracts/common.md#principled-implementation Physical identity and the exact resource object are captured before destruction; only successful cleanup removes that identical registration from the original scope, while failure and replacement retain ownership.
    * @evidence contracts/common.md#clear-and-simple-design One operation combines destructive cleanup with registration release, using the existing release/recover protocol instead of making each caller order physical lookup around removal.
@@ -460,15 +461,31 @@ export namespace SourceNativeRetirement {
       OwnedSynchronousProcess.reportFailure(combined);
       throw combined;
     }
-    const resource = root === undefined ? undefined : scope!.resources.get(root);
+    const resource =
+      root === undefined ? undefined : scope!.resources.get(root);
     const observe = !process.env.TTSC_E2E_TRACE
       ? undefined
       : (phase: string, error?: unknown): void => {
           try {
-            const detail: Record<string, string | number | boolean | null | undefined> = {};
-            if (error !== null && (typeof error === "object" || typeof error === "function"))
-              for (const field of ["code", "errno", "syscall", "path", "dest"]) {
-                const descriptor = Object.getOwnPropertyDescriptor(error, field);
+            const detail: Record<
+              string,
+              string | number | boolean | null | undefined
+            > = {};
+            if (
+              error !== null &&
+              (typeof error === "object" || typeof error === "function")
+            )
+              for (const field of [
+                "code",
+                "errno",
+                "syscall",
+                "path",
+                "dest",
+              ]) {
+                const descriptor = Object.getOwnPropertyDescriptor(
+                  error,
+                  field,
+                );
                 const value: unknown = descriptor?.value;
                 if (typeof value === "string" || typeof value === "number")
                   detail[field] = value;
@@ -478,14 +495,20 @@ export namespace SourceNativeRetirement {
               resourceRoot: root ?? fenceRoot,
               ...detail,
             });
-            if (phase === "source-resource-cleanup-started" && scope !== undefined)
+            if (
+              phase === "source-resource-cleanup-started" &&
+              scope !== undefined
+            )
               for (const [boundary, state] of scope.boundaries)
-                E2ETrace.capabilityResolution("source-resource-cleanup-boundary", {
-                  taskToken: scope.taskToken,
-                  resourceRoot: root,
-                  boundary,
-                  retirement: state.state,
-                });
+                E2ETrace.capabilityResolution(
+                  "source-resource-cleanup-boundary",
+                  {
+                    taskToken: scope.taskToken,
+                    resourceRoot: root,
+                    boundary,
+                    retirement: state.state,
+                  },
+                );
           } catch {
             // Diagnostic reflection and IO cannot replace original cleanup.
           }

package/src/internal/TtsxNodeOptions.ts

@@ -0,0 +1,124 @@
+import { SidecarEnvironment } from "../compiler/internal/sharedHost/SidecarEnvironment";
+
+/**
+ * The `NODE_OPTIONS` a ttsx run received, beside the value it gave its program
+ * after appending its own preloads.
+ *
+ * Ttsx appends its runtime preloads (`register.js`, `runtimeOwnerPreload.js`,
+ * `runtimeHookPreload.js`) to the program's `NODE_OPTIONS`, so every process
+ * the program starts inherits the source loader. ttsc's own helper processes,
+ * the runtime capability probe and the plugin descriptor evaluator, are not the
+ * program's. They must neither run those preloads nor count them as a user's
+ * startup code: both helpers refuse their caches for any non-empty
+ * `NODE_OPTIONS`, so ttsx's own preloads re-probed Node and re-evaluated every
+ * descriptor on every plugin load of a run (samchon/ttsc#1740). A user's own
+ * `NODE_OPTIONS` still reaches the helpers and still disables both caches.
+ *
+ * The record travels to every descendant of the program, and a descendant may
+ * set its own `NODE_OPTIONS`. So the received value is restored only while
+ * `NODE_OPTIONS` is still exactly the value ttsx gave; any other value is the
+ * process's own and reaches its helpers unchanged.
+ *
+ * @evidence contracts/common.md#principled-implementation The received and given values are recorded together before the program starts, and the received value is restored only while the given one is still in force, so helpers see exactly the options their process was started with by its user.
+ * @evidence contracts/common.md#clear-and-simple-design One channel, one producer for launchers, one reader for nested launchers and one environment projection for helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No option string is parsed or filtered; values are carried and compared verbatim.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the preloads, the helpers, the cache refusals, the descendant case and the user case that stays conservative.
+ * @evidence contracts/portability.md#os-neutral-implementation Reads and writes go through SidecarEnvironment, which applies Windows' case-insensitive variable identity.
+ * @evidence contracts/performance.md#efficient-algorithms Each call reads at most two variables, decodes one short JSON pair and copies one environment.
+ * @evidence contracts/performance.md#reuse-equivalent-work Restoring the user's options is what lets the helpers' existing caches serve a ttsx run.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Nothing is retained; the returned environment belongs to the caller.
+ */
+export namespace TtsxNodeOptions {
+  /** The channel carrying `[received, given]` as JSON. */
+  export const RECORD = "TTSX_NODE_OPTIONS_RECORD";
+
+  /**
+   * The variables a ttsx run gives its program: `given` as `NODE_OPTIONS` and
+   * the record of what it received from `env`.
+   *
+   * @evidence contracts/common.md#principled-implementation The record pairs the value received before any preload with the exact value given, so later readers can tell whether ttsx's value is still in force.
+   * @evidence contracts/common.md#clear-and-simple-design One call returns both variables a launcher spreads into its child environment.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Both values are recorded verbatim; nothing is parsed or filtered.
+   * @evidence contracts/common.md#meaningful-documentation Native prose names both returned variables and where the received value comes from.
+   * @evidence contracts/portability.md#os-neutral-implementation The received value is read through `received`, which uses SidecarEnvironment's Windows-aware variable identity.
+   * @evidence contracts/performance.md#efficient-algorithms One read through `received` and one JSON encoding of two strings.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A launcher calls it once per child; there is no work to share.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned variables belong to the caller; nothing is retained.
+   */
+  export function give(
+    env: NodeJS.ProcessEnv,
+    given: string,
+  ): { NODE_OPTIONS: string; [RECORD]: string } {
+    return {
+      NODE_OPTIONS: given,
+      [RECORD]: JSON.stringify([received(env), given]),
+    };
+  }
+
+  /**
+   * The `NODE_OPTIONS` a process received from its user: an enclosing ttsx
+   * run's received value while its given value is still in force, else the
+   * process's own.
+   *
+   * @evidence contracts/common.md#principled-implementation The enclosing record answers only while its given value equals the current one; any other value is the process's own.
+   * @evidence contracts/common.md#clear-and-simple-design One comparison selects between the record and the current value.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A malformed record is ignored rather than repaired.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states both outcomes.
+   * @evidence contracts/portability.md#os-neutral-implementation Variables are read through SidecarEnvironment, which applies Windows' case-insensitive variable identity.
+   * @evidence contracts/performance.md#efficient-algorithms Two variable reads and one JSON decode of a short pair.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call answers from the given environment; there is nothing to share.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Nothing is retained.
+   */
+  export function received(env: NodeJS.ProcessEnv): string {
+    const current = SidecarEnvironment.read(env, "NODE_OPTIONS") ?? "";
+    const record = readRecord(env);
+    return record !== undefined && record.given === current
+      ? record.received
+      : current;
+  }
+
+  /**
+   * The environment for a ttsc helper process: `NODE_OPTIONS` restored to the
+   * received value while an enclosing ttsx run's given value is in force,
+   * unchanged anywhere else.
+   *
+   * @evidence contracts/common.md#principled-implementation Only ttsx's own appended preloads are withdrawn, and only while ttsx's value is in force; a user's or descendant's value reaches the helper.
+   * @evidence contracts/common.md#clear-and-simple-design One projection returns either the input environment or one copy with a single variable replaced.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No option string is edited; the received value replaces the given one whole.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states when the environment is changed and when it is returned unchanged.
+   * @evidence contracts/portability.md#os-neutral-implementation SidecarEnvironment reads and writes the variable under Windows' case-insensitive identity.
+   * @evidence contracts/performance.md#efficient-algorithms Two variable reads, one JSON decode and at most one environment copy.
+   * @evidence contracts/performance.md#reuse-equivalent-work Restoring the user's options lets the probe and descriptor caches serve a ttsx run.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned environment belongs to the caller; nothing is retained.
+   */
+  export function forHelpers(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+    const record = readRecord(env);
+    const current = SidecarEnvironment.read(env, "NODE_OPTIONS") ?? "";
+    if (record === undefined || record.given !== current) return env;
+    const helper = { ...env };
+    SidecarEnvironment.write(
+      helper,
+      "NODE_OPTIONS",
+      record.received.trim() === "" ? undefined : record.received,
+    );
+    return helper;
+  }
+
+  function readRecord(
+    env: NodeJS.ProcessEnv,
+  ): { given: string; received: string } | undefined {
+    const text = SidecarEnvironment.read(env, RECORD);
+    if (text === undefined) return undefined;
+    try {
+      const value: unknown = JSON.parse(text);
+      return Array.isArray(value) &&
+        value.length === 2 &&
+        typeof value[0] === "string" &&
+        typeof value[1] === "string"
+        ? { given: value[1], received: value[0] }
+        : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/internal/javascriptRuntimeCapabilities.ts

@@ -9,6 +9,7 @@ import { PluginLoadAnswers } from "../plugin/internal/source/PluginLoadAnswers";
 import { E2ETrace } from "./E2ETrace";
 import type { IJavaScriptRuntimeCapabilities } from "./IJavaScriptRuntimeCapabilities";
 import { OwnedSynchronousProcess } from "./OwnedSynchronousProcess";
+import { TtsxNodeOptions } from "./TtsxNodeOptions";
 import { isSpawnSyncFdExhaustion } from "./isSpawnSyncFdExhaustion";
 import { runtimeExecutableIdentity } from "./runtimeExecutableIdentity";
 import { spawnSyncWithLowDescriptors } from "./spawnSyncWithLowDescriptors";
@@ -45,7 +46,11 @@ export function javascriptRuntimeCapabilities(
   cwd: string,
   identities?: PluginContentIdentities.Store,
 ): IJavaScriptRuntimeCapabilities {
-  const effectiveEnv = SidecarEnvironment.merge(process.env, env);
+  // Inside a ttsx run this is the user's NODE_OPTIONS, not ttsx's preloads,
+  // which would refuse the cache and run in the probe (#1740).
+  const effectiveEnv = TtsxNodeOptions.forHelpers(
+    SidecarEnvironment.merge(process.env, env),
+  );
   const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
   const beforeIdentity =
     cacheKey === undefined

package/src/internal/parseWindowsDirectoryCaseSensitivity.ts

@@ -2,11 +2,11 @@
  * Interpret fsutil's case-sensitivity query without assuming a display
  * language.
  *
- * English messages identify the state in the final field of the complete
- * native message. The echoed directory path supplies no status evidence. For
- * every other locale, the volume-root query supplies the raw localized suffix
- * for the ordinary disabled state. A target with that suffix is insensitive;
- * a different successful message is the enabled state.
+ * English messages identify the state in the final field of the complete native
+ * message. The echoed directory path supplies no status evidence. For every
+ * other locale, the volume-root query supplies the raw localized suffix for the
+ * ordinary disabled state. A target with that suffix is insensitive; a
+ * different successful message is the enabled state.
  *
  * Inputs must be successful fsutil query responses. The opaque comparison
  * assumes the volume-root response represents the ordinary disabled state;

package/src/internal/pathIdentity/createCaseSensitivityObservations.ts

@@ -0,0 +1,242 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { E2ETrace } from "../E2ETrace";
+import { OwnedSynchronousProcess } from "../OwnedSynchronousProcess";
+import { parseWindowsDirectoryCaseSensitivity } from "../parseWindowsDirectoryCaseSensitivity";
+import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+import { resolveFilesystemPath } from "./resolveFilesystemPath";
+
+/**
+ * Create one unit of work's directory case-policy observations: a function that
+ * answers whether a directory's names are case-sensitive, asking the filesystem
+ * once per directory for as long as the unit keeps it.
+ *
+ * An identity context memoizes case answers for itself, but a unit of work that
+ * creates several contexts, such as one watch decision, asked each directory
+ * once per context. On Windows an inconclusive directory, one that is empty or
+ * whose names carry no ASCII case, costs an `fsutil` process per question, and
+ * one decision asked the same directory up to seventeen times
+ * (samchon/ttsc#1742). Contexts created with this function as their
+ * `caseSensitive` operation share its answers.
+ *
+ * The answers are observations of the moment they were asked, like a context's
+ * own. The unit's owner chooses their lifetime; a later unit creates new
+ * observations rather than reusing these. A directory's flag can change while
+ * it is empty, so an answer outliving its unit could be stale.
+ *
+ * Unavailable evidence is `undefined`: an unreadable directory, a failed query,
+ * or a platform without a read-only probe for an inconclusive directory. Only
+ * observed insensitivity permits ASCII folding.
+ *
+ * @param operations Replaceable filesystem primitives; omitted members use the
+ *   host's own.
+ * @evidence contracts/common.md#principled-implementation Alternate-name observations decide first; a rejected alternate is conclusive only while its original exists. Darwin walks same-device names for its volume-wide policy and Windows asks fsutil's read-only per-directory flag. Failed observation stays unknown.
+ * @evidence contracts/common.md#clear-and-simple-design One returned function owns the probe and its per-unit memo; identity resolution stays with the contexts that call it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No answer is inferred from the OS name, and no answer is carried beyond the unit that observed it.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain sharing, lifetime, the empty-directory hazard and unknown evidence, with tags separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath, lstat and readdir observe alternate names; darwin and win32 select their read-only volume or directory probes, and the platform's path dialect keys the memo.
+ * @evidence contracts/performance.md#efficient-algorithms A miss enumerates the directory's immediate entries and stops at the first conclusive alternate; darwin can walk same-device ancestors and Windows can launch directory and volume fsutil queries. A hit is one map lookup.
+ * @evidence contracts/performance.md#reuse-equivalent-work Every context of one unit shares each directory's answer, so a unit asks the filesystem once per directory instead of once per context.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The memo holds one entry per queried directory without eviction for the unit's lifetime; releasing the returned function releases it. Probes hold no handle after returning, and a Windows query has no explicit timeout.
+ */
+export function createCaseSensitivityObservations(
+  operations: Partial<
+    Pick<
+      FilesystemPathIdentityOperations,
+      "lstat" | "platform" | "readdir" | "realpath"
+    >
+  > = {},
+): (directory: string) => boolean | undefined {
+  const platform = operations.platform ?? process.platform;
+  const probes = {
+    lstat: operations.lstat ?? fs.lstatSync,
+    readdir: operations.readdir ?? fs.readdirSync,
+    realpath: operations.realpath ?? physicalRealpath,
+  };
+  const answers = new Map<string, boolean | undefined>();
+  return (directory) => {
+    const key = resolveFilesystemPath(directory, platform);
+    if (answers.has(key)) return answers.get(key);
+    let answer: boolean | undefined;
+    try {
+      answer = filesystemDirectoryIsCaseSensitive(key, platform, probes);
+    } catch {
+      // A failed capability observation is unknown. This does not suppress
+      // strict physical identity errors in a context's realpath resolver.
+      answer = undefined;
+    }
+    answers.set(key, answer);
+    return answer;
+  };
+}
+
+function physicalRealpath(location: string): string {
+  return fs.realpathSync.native?.(location) ?? fs.realpathSync(location);
+}
+
+function filesystemDirectoryIsCaseSensitive(
+  directory: string,
+  platform: NodeJS.Platform,
+  operations: {
+    lstat(location: string): fs.Stats | fs.BigIntStats;
+    readdir(directory: string): string[];
+    realpath(location: string): string;
+  },
+): boolean | undefined {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  let entries: string[];
+  try {
+    entries = operations.readdir(directory);
+  } catch {
+    return undefined;
+  }
+  const foldedNames = new Map<string, string>();
+  for (const name of entries) {
+    const folded = foldAsciiCase(name);
+    const previous = foldedNames.get(folded);
+    if (previous !== undefined && previous !== name) return true;
+    foldedNames.set(folded, name);
+  }
+  for (const name of entries) {
+    const alternate = alternateCase(name);
+    if (alternate === name) continue;
+    try {
+      operations.lstat(pathApi.join(directory, alternate));
+    } catch (error) {
+      if (isMissingFilesystemEntry(error)) {
+        // Enumeration is not an atomic snapshot. An absent alternate proves
+        // sensitivity only if the original spelling still names an entry.
+        try {
+          operations.lstat(pathApi.join(directory, name));
+          return true;
+        } catch (originalError) {
+          if (isMissingFilesystemEntry(originalError) === false)
+            throw originalError;
+        }
+        continue;
+      }
+      throw error;
+    }
+    try {
+      const actual = resolveFilesystemPath(
+        operations.realpath(pathApi.join(directory, name)),
+        platform,
+      );
+      const alias = resolveFilesystemPath(
+        operations.realpath(pathApi.join(directory, alternate)),
+        platform,
+      );
+      return actual !== alias;
+    } catch (error) {
+      if (isMissingFilesystemEntry(error) === false) throw error;
+    }
+  }
+  if (platform === "darwin") {
+    // APFS/HFS case semantics are volume-wide. An empty directory has no child
+    // name to probe, so ask the same read-only question of its existing name in
+    // the parent and walk upward until a name with ASCII case is available.
+    // This avoids a write probe while still distinguishing default APFS from a
+    // case-sensitive volume.
+    let current = resolveFilesystemPath(directory, platform);
+    while (true) {
+      const parent = pathApi.dirname(current);
+      if (parent === current) break;
+      // Names are interpreted by their parent; another mount is not evidence
+      // of the directory's own volume case policy.
+      if (operations.lstat(current).dev !== operations.lstat(parent).dev)
+        return undefined;
+      const name = pathApi.basename(current);
+      const alternate = alternateCase(name);
+      if (alternate !== name) {
+        try {
+          const actual = resolveFilesystemPath(
+            operations.realpath(current),
+            platform,
+          );
+          const alias = resolveFilesystemPath(
+            operations.realpath(pathApi.join(parent, alternate)),
+            platform,
+          );
+          return actual !== alias;
+        } catch (error) {
+          if (isMissingFilesystemEntry(error) === false) throw error;
+        }
+      }
+      current = parent;
+    }
+    return undefined;
+  }
+  if (platform !== "win32") return undefined;
+  // Node does not expose the Windows per-directory flag. Prefer fsutil's
+  // read-only answer; unavailable capability remains unknown.
+  const queried = queryWindowsDirectoryCaseSensitivity(directory);
+  if (queried !== undefined) return queried;
+  return undefined;
+}
+
+/**
+ * Read the per-directory flag without depending on fsutil's display language.
+ *
+ * English output is cheap to recognize directly. Other Windows locales write
+ * console-code-page bytes that Node cannot reliably decode, so their raw
+ * message is interpreted against the volume-root query.
+ */
+function queryWindowsDirectoryCaseSensitivity(
+  directory: string,
+): boolean | undefined {
+  const result = queryWindowsDirectoryCaseSensitivityBytes(directory);
+  if (result === undefined) return undefined;
+  const volumeRoot = path.win32.parse(directory).root;
+  const direct = parseWindowsDirectoryCaseSensitivity(
+    result,
+    undefined,
+    volumeRoot,
+  );
+  if (direct !== undefined) return direct;
+  const volume = queryWindowsDirectoryCaseSensitivityBytes(volumeRoot);
+  return parseWindowsDirectoryCaseSensitivity(result, volume, volumeRoot);
+}
+
+function queryWindowsDirectoryCaseSensitivityBytes(
+  directory: string,
+): Buffer | undefined {
+  const args = ["file", "queryCaseSensitiveInfo", directory];
+  const result = E2ETrace.synchronous(
+    "fsutil.exe",
+    args,
+    {},
+    "path-case-probe",
+    () =>
+      OwnedSynchronousProcess.launch("fsutil.exe", args, {
+        windowsHide: true,
+      }) ?? childProcess.spawnSync("fsutil.exe", args, { windowsHide: true }),
+  );
+  return result.error === undefined &&
+    result.status === 0 &&
+    Buffer.isBuffer(result.stdout)
+    ? result.stdout
+    : undefined;
+}
+
+function alternateCase(value: string): string {
+  return value.replace(/[A-Za-z]/g, (character) =>
+    character === character.toLowerCase()
+      ? character.toUpperCase()
+      : character.toLowerCase(),
+  );
+}
+
+/** ASCII folding is the case equivalence observed by the read-only probes. */
+function foldAsciiCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+function isMissingFilesystemEntry(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}