ttsc 0.31.4 → 0.32.0

package/lib/internal/TtsxNodeOptions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 declare namespace TtsxNodeOptions {
+    /** The channel carrying `[received, given]` as JSON. */
+    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.
+     */
+    function give(env: NodeJS.ProcessEnv, given: string): {
+        NODE_OPTIONS: string;
+        [RECORD]: string;
+    };
+    /**
+     * 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.
+     */
+    function received(env: NodeJS.ProcessEnv): string;
+    /**
+     * 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.
+     */
+    function forHelpers(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+}

package/lib/internal/TtsxNodeOptions.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtsxNodeOptions = void 0;
+const SidecarEnvironment_1 = require("../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.
+ */
+var TtsxNodeOptions;
+(function (TtsxNodeOptions) {
+    /** The channel carrying `[received, given]` as JSON. */
+    TtsxNodeOptions.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.
+     */
+    function give(env, given) {
+        return {
+            NODE_OPTIONS: given,
+            [TtsxNodeOptions.RECORD]: JSON.stringify([received(env), given]),
+        };
+    }
+    TtsxNodeOptions.give = give;
+    /**
+     * 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.
+     */
+    function received(env) {
+        const current = SidecarEnvironment_1.SidecarEnvironment.read(env, "NODE_OPTIONS") ?? "";
+        const record = readRecord(env);
+        return record !== undefined && record.given === current
+            ? record.received
+            : current;
+    }
+    TtsxNodeOptions.received = received;
+    /**
+     * 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.
+     */
+    function forHelpers(env) {
+        const record = readRecord(env);
+        const current = SidecarEnvironment_1.SidecarEnvironment.read(env, "NODE_OPTIONS") ?? "";
+        if (record === undefined || record.given !== current)
+            return env;
+        const helper = { ...env };
+        SidecarEnvironment_1.SidecarEnvironment.write(helper, "NODE_OPTIONS", record.received.trim() === "" ? undefined : record.received);
+        return helper;
+    }
+    TtsxNodeOptions.forHelpers = forHelpers;
+    function readRecord(env) {
+        const text = SidecarEnvironment_1.SidecarEnvironment.read(env, TtsxNodeOptions.RECORD);
+        if (text === undefined)
+            return undefined;
+        try {
+            const value = 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;
+        }
+    }
+})(TtsxNodeOptions || (exports.TtsxNodeOptions = TtsxNodeOptions = {}));
+//# sourceMappingURL=TtsxNodeOptions.js.map

package/lib/internal/TtsxNodeOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtsxNodeOptions.js","sourceRoot":"","sources":["../../src/internal/TtsxNodeOptions.ts"],"names":[],"mappings":";;;AAAA,2FAAwF;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,IAAiB,eAAe,CA6F/B;AA7FD,WAAiB,eAAe;IAC9B,wDAAwD;IAC3C,sBAAM,GAAG,0BAA0B,CAAC;IAEjD;;;;;;;;;;;;OAYG;IACH,SAAgB,IAAI,CAClB,GAAsB,EACtB,KAAa;QAEb,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,CAAC,sBAAM,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;SACjD,CAAC;IACJ,CAAC;IARe,gBAAA,IAAI,OAQnB,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,QAAQ,CAAC,GAAsB;QAC7C,MAAM,OAAO,GAAG,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QACnE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO;YACrD,CAAC,CAAC,MAAM,CAAC,QAAQ;YACjB,CAAC,CAAC,OAAO,CAAC;IACd,CAAC;IANe,gBAAA,QAAQ,WAMvB,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,UAAU,CAAC,GAAsB;QAC/C,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QACnE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO;YAAE,OAAO,GAAG,CAAC;QACjE,MAAM,MAAM,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC;QAC1B,uCAAkB,CAAC,KAAK,CACtB,MAAM,EACN,cAAc,EACd,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAC5D,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAXe,gBAAA,UAAU,aAWzB,CAAA;IAED,SAAS,UAAU,CACjB,GAAsB;QAEtB,MAAM,IAAI,GAAG,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,sBAAM,CAAC,CAAC;QAClD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBACzB,KAAK,CAAC,MAAM,KAAK,CAAC;gBAClB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAC5B,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAC5B,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE;gBACzC,CAAC,CAAC,SAAS,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC,EA7FgB,eAAe,aAAf,eAAe,GAAf,eAAe,QA6F/B"}

package/lib/internal/javascriptRuntimeCapabilities.js

@@ -12,6 +12,7 @@ const SidecarEnvironment_1 = require("../compiler/internal/sharedHost/SidecarEnv
 const PluginLoadAnswers_1 = require("../plugin/internal/source/PluginLoadAnswers");
 const E2ETrace_1 = require("./E2ETrace");
 const OwnedSynchronousProcess_1 = require("./OwnedSynchronousProcess");
+const TtsxNodeOptions_1 = require("./TtsxNodeOptions");
 const isSpawnSyncFdExhaustion_1 = require("./isSpawnSyncFdExhaustion");
 const runtimeExecutableIdentity_1 = require("./runtimeExecutableIdentity");
 const spawnSyncWithLowDescriptors_1 = require("./spawnSyncWithLowDescriptors");
@@ -42,7 +43,9 @@ const spawnSyncWithLowDescriptors_1 = require("./spawnSyncWithLowDescriptors");
  * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous probe owns child completion and fallback captures; finally attempts capture close/removal, whose helper suppresses cleanup failures, so native/file release is unconfirmed on failure. Capability entries retain absolute spellings and path/identity text with no eviction quota; failed identity validation can remove an entry. Returned capability copies transfer to callers.
  */
 function javascriptRuntimeCapabilities(runtime, env, cwd, identities) {
-    const effectiveEnv = SidecarEnvironment_1.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_1.TtsxNodeOptions.forHelpers(SidecarEnvironment_1.SidecarEnvironment.merge(process.env, env));
     const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
     const beforeIdentity = cacheKey === undefined
         ? undefined

package/lib/internal/javascriptRuntimeCapabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"javascriptRuntimeCapabilities.js","sourceRoot":"","sources":["../../src/internal/javascriptRuntimeCapabilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"javascriptRuntimeCapabilities.js","sourceRoot":"","sources":["../../src/internal/javascriptRuntimeCapabilities.ts"],"names":[],"mappings":"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"}

package/lib/internal/parseWindowsDirectoryCaseSensitivity.d.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/lib/internal/parseWindowsDirectoryCaseSensitivity.js

@@ -5,11 +5,11 @@ exports.parseWindowsDirectoryCaseSensitivity = parseWindowsDirectoryCaseSensitiv
  * 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/lib/internal/pathIdentity/createCaseSensitivityObservations.d.ts

@@ -0,0 +1,35 @@
+import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+/**
+ * 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 declare function createCaseSensitivityObservations(operations?: Partial<Pick<FilesystemPathIdentityOperations, "lstat" | "platform" | "readdir" | "realpath">>): (directory: string) => boolean | undefined;

package/lib/internal/pathIdentity/createCaseSensitivityObservations.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCaseSensitivityObservations = createCaseSensitivityObservations;
+const node_child_process_1 = __importDefault(require("node:child_process"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const E2ETrace_1 = require("../E2ETrace");
+const OwnedSynchronousProcess_1 = require("../OwnedSynchronousProcess");
+const parseWindowsDirectoryCaseSensitivity_1 = require("../parseWindowsDirectoryCaseSensitivity");
+const resolveFilesystemPath_1 = require("./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.
+ */
+function createCaseSensitivityObservations(operations = {}) {
+    const platform = operations.platform ?? process.platform;
+    const probes = {
+        lstat: operations.lstat ?? node_fs_1.default.lstatSync,
+        readdir: operations.readdir ?? node_fs_1.default.readdirSync,
+        realpath: operations.realpath ?? physicalRealpath,
+    };
+    const answers = new Map();
+    return (directory) => {
+        const key = (0, resolveFilesystemPath_1.resolveFilesystemPath)(directory, platform);
+        if (answers.has(key))
+            return answers.get(key);
+        let answer;
+        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) {
+    return node_fs_1.default.realpathSync.native?.(location) ?? node_fs_1.default.realpathSync(location);
+}
+function filesystemDirectoryIsCaseSensitive(directory, platform, operations) {
+    const pathApi = platform === "win32" ? node_path_1.default.win32 : node_path_1.default.posix;
+    let entries;
+    try {
+        entries = operations.readdir(directory);
+    }
+    catch {
+        return undefined;
+    }
+    const foldedNames = new Map();
+    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 = (0, resolveFilesystemPath_1.resolveFilesystemPath)(operations.realpath(pathApi.join(directory, name)), platform);
+            const alias = (0, resolveFilesystemPath_1.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 = (0, resolveFilesystemPath_1.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 = (0, resolveFilesystemPath_1.resolveFilesystemPath)(operations.realpath(current), platform);
+                    const alias = (0, resolveFilesystemPath_1.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) {
+    const result = queryWindowsDirectoryCaseSensitivityBytes(directory);
+    if (result === undefined)
+        return undefined;
+    const volumeRoot = node_path_1.default.win32.parse(directory).root;
+    const direct = (0, parseWindowsDirectoryCaseSensitivity_1.parseWindowsDirectoryCaseSensitivity)(result, undefined, volumeRoot);
+    if (direct !== undefined)
+        return direct;
+    const volume = queryWindowsDirectoryCaseSensitivityBytes(volumeRoot);
+    return (0, parseWindowsDirectoryCaseSensitivity_1.parseWindowsDirectoryCaseSensitivity)(result, volume, volumeRoot);
+}
+function queryWindowsDirectoryCaseSensitivityBytes(directory) {
+    const args = ["file", "queryCaseSensitiveInfo", directory];
+    const result = E2ETrace_1.E2ETrace.synchronous("fsutil.exe", args, {}, "path-case-probe", () => OwnedSynchronousProcess_1.OwnedSynchronousProcess.launch("fsutil.exe", args, {
+        windowsHide: true,
+    }) ?? node_child_process_1.default.spawnSync("fsutil.exe", args, { windowsHide: true }));
+    return result.error === undefined &&
+        result.status === 0 &&
+        Buffer.isBuffer(result.stdout)
+        ? result.stdout
+        : undefined;
+}
+function alternateCase(value) {
+    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) {
+    return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+function isMissingFilesystemEntry(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+//# sourceMappingURL=createCaseSensitivityObservations.js.map

package/lib/internal/pathIdentity/createCaseSensitivityObservations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCaseSensitivityObservations.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/createCaseSensitivityObservations.ts"],"names":[],"mappings":"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"}