ttsc 0.30.3 → 0.31.0

package/lib/internal/pathIdentity/createFilesystemPathIdentityContext.js

@@ -0,0 +1,336 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFilesystemPathIdentityContext = createFilesystemPathIdentityContext;
+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 isFilesystemPathIdentityWithin_1 = require("./isFilesystemPathIdentityWithin");
+const resolveFilesystemPath_1 = require("./resolveFilesystemPath");
+/**
+ * Create one filesystem-identity resolver for a filesystem transaction.
+ *
+ * Successfully observed prefixes use their physical spelling. An unresolved
+ * suffix preserves spelling under sensitive or unknown policy; observed
+ * insensitivity permits ASCII case folding. In best-effort mode that suffix can
+ * include unreadable existing entries, so it is not proof of absence.
+ *
+ * Cached observations agree for the same queried key, not an atomic view of the
+ * whole filesystem. An unavailable read-only case probe reports unknown and
+ * preserves unresolved suffix spelling; only observed insensitivity permits
+ * folding.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful realpath observations establish physical prefixes; unresolved segments fold only under observed insensitivity, while sensitive or unknown ancestors preserve spelling. Best-effort unavailability does not establish absence or complete alias resolution, and unknown policy is not replaced with an OS-default equivalence assumption.
+ * @evidence contracts/common.md#clear-and-simple-design A transaction owns resolution and three memoized observation maps; native case probing, lexical normalization and key construction are separate helpers with one identity policy shared by all callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported injected operations replace no foreign methods; strict unexpected realpath failures propagate. Best-effort realpath is explicit, while unavailable case evidence remains unknown rather than a fabricated OS-default capability.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain missing-suffix semantics, per-key rather than atomic consistency and unknown case evidence; helpers document native probing premises, with separate tag paragraphs.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath, alternate-name observations and read-only Windows fsutil obtain actual case evidence; native path APIs separate Windows and POSIX syntax. OS names select syntax or probe mechanisms, never an unmeasured directory policy.
+ * @evidence contracts/performance.md#efficient-algorithms Construction allocates maps and closures without querying paths. Physical resolution visits missing ancestors and reverses the collected suffix once; lexical relations walk components. Default case probes enumerate uncapped immediate entries and inspect folded-name text, then stop at the first conclusive alternate-name observation. A rejected alternate is conclusive only when its original still exists; disappeared entries cannot establish sensitivity. Darwin can walk same-device ancestors, while Windows can synchronously launch directory and volume fsutil queries and parse returned bytes. Work includes visited path/name/output lengths and native metadata/process costs, not just depth or entry count.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each transaction memoizes resolved paths, realpath success or permitted-unavailable observations and case answers by their native keys; repeated questions reuse observations only within that unit of work, not across later filesystem generations. Best-effort cached unavailability is not an absence certificate.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Context-owned maps grow with queried paths and visited ancestors without internal eviction; reclamation requires the caller to release references to the context and its returned methods. Entry snapshots, decoded query text and synchronous fsutil results are transient rather than retained observers; no descriptor or child handle is held between completed observations. A Windows query supplies no explicit timeout, so active synchronous work has no deadline here. This boundary imposes no query-population quota or explicit dispose operation.
+ */
+function createFilesystemPathIdentityContext(operations = {}) {
+    const identities = new Map();
+    const realpaths = new Map();
+    const sensitivities = new Map();
+    const platform = operations.platform ?? process.platform;
+    const pathApi = platform === "win32" ? node_path_1.default.win32 : node_path_1.default.posix;
+    const throwOnRealpathError = operations.throwOnRealpathError ?? true;
+    const realpath = operations.realpath ?? physicalRealpath;
+    const lstat = operations.lstat ?? node_fs_1.default.lstatSync;
+    const readdir = operations.readdir ?? node_fs_1.default.readdirSync;
+    const caseSensitive = operations.caseSensitive ??
+        ((directory) => {
+            try {
+                return filesystemDirectoryIsCaseSensitive(directory, platform, {
+                    lstat,
+                    readdir,
+                    realpath,
+                });
+            }
+            catch {
+                // A failed capability observation is unknown. This does not suppress
+                // strict physical identity errors in the separate realpath resolver.
+                return undefined;
+            }
+        });
+    const resolve = (location) => {
+        const normalized = (0, resolveFilesystemPath_1.resolveFilesystemPath)(location, platform);
+        const cached = identities.get(normalized);
+        if (cached !== undefined)
+            return cached.identity;
+        let existing = normalized;
+        const missing = [];
+        while (true) {
+            const physical = cachedRealpath(realpaths, realpath, existing, platform, throwOnRealpathError);
+            if (physical !== undefined) {
+                missing.reverse();
+                const sensitive = missing.length === 0
+                    ? true
+                    : cachedCaseSensitivity(sensitivities, caseSensitive, physical);
+                const suffix = sensitive === false ? missing.map(foldAsciiCase) : missing;
+                const canonical = pathApi.resolve(physical, ...suffix);
+                const identity = {
+                    key: filesystemPathIdentityKey(canonical, platform),
+                    path: canonical,
+                };
+                identities.set(normalized, {
+                    ancestor: physical,
+                    identity,
+                });
+                return identity;
+            }
+            const parent = pathApi.dirname(existing);
+            if (parent === existing) {
+                const sensitive = cachedCaseSensitivity(sensitivities, caseSensitive, existing);
+                const identity = {
+                    key: filesystemPathIdentityKey(sensitive === false ? foldAsciiCase(normalized) : normalized, platform),
+                    path: normalized,
+                };
+                identities.set(normalized, {
+                    ancestor: normalized,
+                    identity,
+                });
+                return identity;
+            }
+            missing.push(pathApi.basename(existing));
+            existing = parent;
+        }
+    };
+    const directoryCaseSensitive = (directory) => {
+        const normalized = (0, resolveFilesystemPath_1.resolveFilesystemPath)(directory, platform);
+        resolve(normalized);
+        return cachedCaseSensitivity(sensitivities, caseSensitive, identities.get(normalized).ancestor);
+    };
+    const lexicalParts = (location) => {
+        const normalized = (0, resolveFilesystemPath_1.resolveFilesystemPath)(location, platform);
+        const root = pathApi.parse(normalized).root;
+        return {
+            root,
+            segments: normalized
+                .slice(root.length)
+                .split(pathApi.sep)
+                .filter(Boolean),
+        };
+    };
+    // These candidates guide observation routing, not equality or cache proof.
+    const lexicalRelation = (root, candidate, within) => {
+        const parent = lexicalParts(root);
+        const child = lexicalParts(candidate);
+        if (filesystemPathIdentityKey(parent.root, platform) !==
+            filesystemPathIdentityKey(child.root, platform) ||
+            (within
+                ? parent.segments.length > child.segments.length
+                : parent.segments.length !== child.segments.length))
+            return false;
+        let directory = parent.root;
+        for (let index = 0; index < parent.segments.length; index++) {
+            const expected = parent.segments[index];
+            const actual = child.segments[index];
+            if (expected !== actual) {
+                // Native Unicode case and normalization tables are not represented by
+                // the ASCII probe. Keep such spellings eligible rather than inventing
+                // a Unicode equivalence relation that could lose a watcher event.
+                if (/^[\x00-\x7f]*$/.test(expected) && /^[\x00-\x7f]*$/.test(actual)) {
+                    if (directoryCaseSensitive(directory) === true ||
+                        foldAsciiCase(expected) !== foldAsciiCase(actual))
+                        return false;
+                }
+            }
+            directory = pathApi.join(directory, expected);
+        }
+        return true;
+    };
+    return {
+        caseSensitive: directoryCaseSensitive,
+        isWithin: (root, candidate) => (0, isFilesystemPathIdentityWithin_1.isFilesystemPathIdentityWithin)(resolve(root).key, resolve(candidate).key, platform),
+        lexicalKey: (location) => {
+            const lexical = lexicalParts(location);
+            let parent = lexical.root;
+            const segments = lexical.segments.map((segment) => {
+                const key = directoryCaseSensitive(parent) === false
+                    ? foldAsciiCase(segment)
+                    : segment;
+                parent = pathApi.join(parent, segment);
+                return key;
+            });
+            return pathApi.join(filesystemPathIdentityKey(lexical.root, platform), ...segments);
+        },
+        lexicalMatches: (left, right) => lexicalRelation(left, right, false),
+        lexicalIsWithin: (root, candidate) => lexicalRelation(root, candidate, true),
+        resolve,
+    };
+}
+function cachedRealpath(cache, realpath, location, platform, throwOnRealpathError) {
+    const cached = cache.get(location);
+    if (cached !== undefined)
+        return cached.found ? cached.path : undefined;
+    try {
+        const physical = (0, resolveFilesystemPath_1.resolveFilesystemPath)(realpath(location), platform);
+        cache.set(location, { found: true, path: physical });
+        return physical;
+    }
+    catch (error) {
+        if (throwOnRealpathError && isMissingFilesystemEntry(error) === false) {
+            throw error;
+        }
+        cache.set(location, { found: false });
+        return undefined;
+    }
+}
+function cachedCaseSensitivity(cache, caseSensitive, directory) {
+    if (cache.has(directory))
+        return cache.get(directory);
+    const sensitive = caseSensitive(directory);
+    cache.set(directory, sensitive);
+    return sensitive;
+}
+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 filesystemPathIdentityKey(location, platform) {
+    if (platform !== "win32")
+        return location;
+    const root = node_path_1.default.win32.parse(location).root;
+    return `${root.toLowerCase()}${location.slice(root.length)}`;
+}
+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=createFilesystemPathIdentityContext.js.map

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

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

package/lib/internal/pathIdentity/createProjectInputPathIdentityContext.d.ts

@@ -0,0 +1,28 @@
+import type { ProjectInputPathIdentityContext } from "./ProjectInputPathIdentityContext";
+import type { ProjectInputPathIdentityOperations } from "./ProjectInputPathIdentityOperations";
+/**
+ * Create the identity resolver used for project inputs.
+ *
+ * It is {@link createFilesystemPathIdentityContext} under the project-input
+ * name, kept as its own entry point so the watch, build, and LSP hosts that
+ * reason about project inputs read as such while sharing one implementation.
+ * Each call creates a new context; it does not reuse another transaction's
+ * observations. Creation allocates maps and closures without querying native
+ * paths. Later method calls perform the underlying resolver's native or
+ * injected observations, including a read-only Windows case query when
+ * selected. The caller chooses the observation lifetime by retaining or
+ * discarding the returned context; no explicit dispose operation or map
+ * eviction is supplied.
+ *
+ * @param operations Replaceable filesystem primitives; omitted members use the
+ *   host's own.
+ * @evidence contracts/common.md#principled-implementation Returning the filesystem context gives project consumers identical realpath, missing-suffix and case-policy decisions instead of a second identity relation.
+ * @evidence contracts/common.md#clear-and-simple-design This domain entry point delegates its entire policy and retains only a project-oriented name for watch, build and LSP callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Operations use the supported injection boundary; neither native methods nor foreign globals are patched to change identity.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the domain name, shared implementation and omitted-operation defaults, with tags visibly separate.
+ * @evidence contracts/portability.md#os-neutral-implementation The owning resolver uses actual native case evidence and path syntax; unavailable policy remains unknown and preserves identity spellings instead of assuming an OS-default filesystem capability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned context owns maps whose queried path/ancestor populations have no internal eviction bound; its lifetime and injected-operation references pass to the caller. Creation opens no native handle, and the alias adds no disposal or observation-freshness guarantee.
+ * @evidence contracts/performance.md#efficient-algorithms Construction delegates fixed map/closure allocation without path traversal. Actual context method calls incur the shared resolver's path/ancestor/entry/native-probe work; delegating does not make those later costs constant or impose a population cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each new context independently memoizes per-key observations within its caller-chosen transaction, including missing paths and unknown case answers. No context is shared across calls, and cached observations are not a fresh filesystem snapshot.
+ */
+export declare function createProjectInputPathIdentityContext(operations?: Partial<ProjectInputPathIdentityOperations>): ProjectInputPathIdentityContext;

package/lib/internal/pathIdentity/createProjectInputPathIdentityContext.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectInputPathIdentityContext = createProjectInputPathIdentityContext;
+const createFilesystemPathIdentityContext_1 = require("./createFilesystemPathIdentityContext");
+/**
+ * Create the identity resolver used for project inputs.
+ *
+ * It is {@link createFilesystemPathIdentityContext} under the project-input
+ * name, kept as its own entry point so the watch, build, and LSP hosts that
+ * reason about project inputs read as such while sharing one implementation.
+ * Each call creates a new context; it does not reuse another transaction's
+ * observations. Creation allocates maps and closures without querying native
+ * paths. Later method calls perform the underlying resolver's native or
+ * injected observations, including a read-only Windows case query when
+ * selected. The caller chooses the observation lifetime by retaining or
+ * discarding the returned context; no explicit dispose operation or map
+ * eviction is supplied.
+ *
+ * @param operations Replaceable filesystem primitives; omitted members use the
+ *   host's own.
+ * @evidence contracts/common.md#principled-implementation Returning the filesystem context gives project consumers identical realpath, missing-suffix and case-policy decisions instead of a second identity relation.
+ * @evidence contracts/common.md#clear-and-simple-design This domain entry point delegates its entire policy and retains only a project-oriented name for watch, build and LSP callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Operations use the supported injection boundary; neither native methods nor foreign globals are patched to change identity.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the domain name, shared implementation and omitted-operation defaults, with tags visibly separate.
+ * @evidence contracts/portability.md#os-neutral-implementation The owning resolver uses actual native case evidence and path syntax; unavailable policy remains unknown and preserves identity spellings instead of assuming an OS-default filesystem capability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned context owns maps whose queried path/ancestor populations have no internal eviction bound; its lifetime and injected-operation references pass to the caller. Creation opens no native handle, and the alias adds no disposal or observation-freshness guarantee.
+ * @evidence contracts/performance.md#efficient-algorithms Construction delegates fixed map/closure allocation without path traversal. Actual context method calls incur the shared resolver's path/ancestor/entry/native-probe work; delegating does not make those later costs constant or impose a population cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each new context independently memoizes per-key observations within its caller-chosen transaction, including missing paths and unknown case answers. No context is shared across calls, and cached observations are not a fresh filesystem snapshot.
+ */
+function createProjectInputPathIdentityContext(operations = {}) {
+    return (0, createFilesystemPathIdentityContext_1.createFilesystemPathIdentityContext)(operations);
+}
+//# sourceMappingURL=createProjectInputPathIdentityContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createProjectInputPathIdentityContext.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/createProjectInputPathIdentityContext.ts"],"names":[],"mappings":";;;AAEA,+FAA4F;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+CACE,UAAU,GAAgD,EAAE;IAE5D,OAAO,IAAA,yEAAmC,EAAC,UAAU,CAAC,CAAC;AACzD,CAAC"}

package/lib/internal/pathIdentity/isFilesystemPathIdentityWithin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether `candidate` equals `root` or lies beneath it, compared lexically.
+ *
+ * Both arguments must already be identity keys (see
+ * {@link FilesystemPathIdentity.key}). The function performs no filesystem
+ * access and no case folding. A root that already ends in a separator (a volume
+ * root such as `C:\` or `/`) is used as is, so every path on that volume is
+ * inside it.
+ *
+ * @param platform Separator semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Equality includes the root itself and a separator-delimited prefix includes only descendants; inputs must already carry canonical identity keys so sibling names and case policy are not guessed here.
+ * @evidence contracts/common.md#clear-and-simple-design One equality check and one boundary prefix check keep this lexical predicate separate from the resolver that proves keys.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The volume-root separator rule is path syntax required by containment, not an expected-result exception or a casing workaround.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents the canonical-key premise, no filesystem access and volume-root behavior, which callers need to avoid treating raw paths as identities.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit platform separators preserve drive, UNC and POSIX root boundaries; existing keys supply native case policy rather than whole-path lowercasing here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The lexical boolean query owns no native handle, persistent observation map or output artifact; a temporary separator-suffixed root is invocation-local.
+ * @evidence contracts/performance.md#efficient-algorithms Equality and one separator-delimited prefix comparison inspect string contents; a non-root suffix construction can copy the root spelling. Work and temporary text depend on key lengths, without filesystem observation, component walking or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate compares already-produced identity keys and owns no expensive producer, shared native observations or mutable authority whose equivalent work needs coordination. Key construction and its reuse belong to the supplying context.
+ */
+export declare function isFilesystemPathIdentityWithin(root: string, candidate: string, platform?: NodeJS.Platform): boolean;

package/lib/internal/pathIdentity/isFilesystemPathIdentityWithin.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFilesystemPathIdentityWithin = isFilesystemPathIdentityWithin;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Whether `candidate` equals `root` or lies beneath it, compared lexically.
+ *
+ * Both arguments must already be identity keys (see
+ * {@link FilesystemPathIdentity.key}). The function performs no filesystem
+ * access and no case folding. A root that already ends in a separator (a volume
+ * root such as `C:\` or `/`) is used as is, so every path on that volume is
+ * inside it.
+ *
+ * @param platform Separator semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Equality includes the root itself and a separator-delimited prefix includes only descendants; inputs must already carry canonical identity keys so sibling names and case policy are not guessed here.
+ * @evidence contracts/common.md#clear-and-simple-design One equality check and one boundary prefix check keep this lexical predicate separate from the resolver that proves keys.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The volume-root separator rule is path syntax required by containment, not an expected-result exception or a casing workaround.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents the canonical-key premise, no filesystem access and volume-root behavior, which callers need to avoid treating raw paths as identities.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit platform separators preserve drive, UNC and POSIX root boundaries; existing keys supply native case policy rather than whole-path lowercasing here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The lexical boolean query owns no native handle, persistent observation map or output artifact; a temporary separator-suffixed root is invocation-local.
+ * @evidence contracts/performance.md#efficient-algorithms Equality and one separator-delimited prefix comparison inspect string contents; a non-root suffix construction can copy the root spelling. Work and temporary text depend on key lengths, without filesystem observation, component walking or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate compares already-produced identity keys and owns no expensive producer, shared native observations or mutable authority whose equivalent work needs coordination. Key construction and its reuse belong to the supplying context.
+ */
+function isFilesystemPathIdentityWithin(root, candidate, platform = process.platform) {
+    if (candidate === root)
+        return true;
+    const separator = platform === "win32" ? node_path_1.default.win32.sep : node_path_1.default.posix.sep;
+    return candidate.startsWith(root.endsWith(separator) ? root : `${root}${separator}`);
+}
+//# sourceMappingURL=isFilesystemPathIdentityWithin.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"isFilesystemPathIdentityWithin.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/isFilesystemPathIdentityWithin.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCACE,IAAY,EACZ,SAAiB,EACjB,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAE5C,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,SAAS,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC,GAAG,CAAC;IACzE,OAAO,SAAS,CAAC,UAAU,CACzB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,CACxD,CAAC;AACJ,CAAC"}

package/lib/internal/pathIdentity/isProjectInputPathIdentityWithin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether one project-input identity key contains another, using the host
+ * platform's separator; the project-input name of
+ * {@link isFilesystemPathIdentityWithin}.
+ *
+ * @evidence contracts/common.md#principled-implementation Delegation preserves canonical-key equality and separator-boundary containment for project inputs with the same premises as filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design The project-facing name introduces no independent containment policy; the filesystem predicate remains the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No project-specific path exception or foreign mutation bypasses the canonical-key predicate.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the identity-key inputs and shared owner, without suggesting raw lexical paths have been physically resolved.
+ * @evidence contracts/portability.md#os-neutral-implementation The host separator is obtained by the shared predicate while case and alias equivalence must already be encoded in its input keys.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The delegated lexical query owns no native handle, persistent cache or created artifact; this domain adapter adds no retained state.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation performs the shared equality and separator-prefix comparisons, with string work and temporary suffix text dependent on input key lengths. This adapter adds no native lookup or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The adapter receives precomputed identity keys and introduces no producer or mutable observations to share. Identity construction and transaction reuse remain with the caller's context, rather than a second cache here.
+ */
+export declare function isProjectInputPathIdentityWithin(root: string, candidate: string): boolean;

package/lib/internal/pathIdentity/isProjectInputPathIdentityWithin.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProjectInputPathIdentityWithin = isProjectInputPathIdentityWithin;
+const isFilesystemPathIdentityWithin_1 = require("./isFilesystemPathIdentityWithin");
+/**
+ * Whether one project-input identity key contains another, using the host
+ * platform's separator; the project-input name of
+ * {@link isFilesystemPathIdentityWithin}.
+ *
+ * @evidence contracts/common.md#principled-implementation Delegation preserves canonical-key equality and separator-boundary containment for project inputs with the same premises as filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design The project-facing name introduces no independent containment policy; the filesystem predicate remains the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No project-specific path exception or foreign mutation bypasses the canonical-key predicate.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the identity-key inputs and shared owner, without suggesting raw lexical paths have been physically resolved.
+ * @evidence contracts/portability.md#os-neutral-implementation The host separator is obtained by the shared predicate while case and alias equivalence must already be encoded in its input keys.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The delegated lexical query owns no native handle, persistent cache or created artifact; this domain adapter adds no retained state.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation performs the shared equality and separator-prefix comparisons, with string work and temporary suffix text dependent on input key lengths. This adapter adds no native lookup or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The adapter receives precomputed identity keys and introduces no producer or mutable observations to share. Identity construction and transaction reuse remain with the caller's context, rather than a second cache here.
+ */
+function isProjectInputPathIdentityWithin(root, candidate) {
+    return (0, isFilesystemPathIdentityWithin_1.isFilesystemPathIdentityWithin)(root, candidate);
+}
+//# sourceMappingURL=isProjectInputPathIdentityWithin.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"isProjectInputPathIdentityWithin.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/isProjectInputPathIdentityWithin.ts"],"names":[],"mappings":";;;AAAA,qFAAkF;AAElF;;;;;;;;;;;;;GAaG;AACH,0CACE,IAAY,EACZ,SAAiB;IAEjB,OAAO,IAAA,+DAA8B,EAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACzD,CAAC"}

package/lib/internal/pathIdentity/resolveFilesystemPath.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Normalize a path lexically, without touching the filesystem.
+ *
+ * On Windows, forward slashes become backslashes and the extended-length
+ * prefixes a native API can return (`\\?\C:\...` and `\\?\UNC\server\share`)
+ * are removed, so one location spelled by Node, by `fs.realpathSync.native`,
+ * and by a user compares equal before any identity is taken. POSIX paths are
+ * only resolved. Relative spellings also depend on the selected path API's
+ * current-directory resolution; `platform` chooses path syntax, not an
+ * independent filesystem.
+ *
+ * @param platform Path semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Native path resolution removes only recognized drive and UNC extended-length aliases; it normalizes lexical spelling without pretending to establish filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One Windows normalization branch precedes the selected path API, keeping lexical syntax separate from physical realpath and case-policy decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recognized Windows path prefixes are native syntax, not consumer exceptions; no filesystem method or global state is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains lexical scope, supported extended prefixes and the platform argument, separately from the acknowledgments.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32 or posix path semantics handle native separators and Windows extended drive/UNC representations without assuming casing establishes physical identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local and returned strings scale with supplied and resolved path text, but this lexical operation owns no independent historical population, handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms Windows separator replacement and lowercase-prefix inspection traverse path text and allocate local strings; selected path.resolve performs lexical segment/current-directory resolution. A fixed expression count is not constant work, and no native filesystem identity query or directory enumeration occurs here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This lexical normalizer coordinates no work across requests and retains no cache; relative results depend on current-directory resolution as well as the explicit arguments.
+ */
+export declare function resolveFilesystemPath(location: string, platform?: NodeJS.Platform): string;

package/lib/internal/pathIdentity/resolveFilesystemPath.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFilesystemPath = resolveFilesystemPath;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Normalize a path lexically, without touching the filesystem.
+ *
+ * On Windows, forward slashes become backslashes and the extended-length
+ * prefixes a native API can return (`\\?\C:\...` and `\\?\UNC\server\share`)
+ * are removed, so one location spelled by Node, by `fs.realpathSync.native`,
+ * and by a user compares equal before any identity is taken. POSIX paths are
+ * only resolved. Relative spellings also depend on the selected path API's
+ * current-directory resolution; `platform` chooses path syntax, not an
+ * independent filesystem.
+ *
+ * @param platform Path semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Native path resolution removes only recognized drive and UNC extended-length aliases; it normalizes lexical spelling without pretending to establish filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One Windows normalization branch precedes the selected path API, keeping lexical syntax separate from physical realpath and case-policy decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recognized Windows path prefixes are native syntax, not consumer exceptions; no filesystem method or global state is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains lexical scope, supported extended prefixes and the platform argument, separately from the acknowledgments.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32 or posix path semantics handle native separators and Windows extended drive/UNC representations without assuming casing establishes physical identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local and returned strings scale with supplied and resolved path text, but this lexical operation owns no independent historical population, handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms Windows separator replacement and lowercase-prefix inspection traverse path text and allocate local strings; selected path.resolve performs lexical segment/current-directory resolution. A fixed expression count is not constant work, and no native filesystem identity query or directory enumeration occurs here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This lexical normalizer coordinates no work across requests and retains no cache; relative results depend on current-directory resolution as well as the explicit arguments.
+ */
+function resolveFilesystemPath(location, platform = process.platform) {
+    const pathApi = platform === "win32" ? node_path_1.default.win32 : node_path_1.default.posix;
+    if (platform !== "win32") {
+        return pathApi.resolve(location);
+    }
+    const normalized = location.replaceAll("/", "\\");
+    if (normalized.toLowerCase().startsWith("\\\\?\\unc\\")) {
+        return pathApi.resolve(`\\\\${normalized.slice(8)}`);
+    }
+    if (normalized.startsWith("\\\\?\\") &&
+        /^[A-Za-z]:\\/.test(normalized.slice(4))) {
+        return pathApi.resolve(normalized.slice(4));
+    }
+    return pathApi.resolve(normalized);
+}
+//# sourceMappingURL=resolveFilesystemPath.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveFilesystemPath.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/resolveFilesystemPath.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+BACE,QAAgB,EAChB,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAE5C,MAAM,OAAO,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAI,CAAC,KAAK,CAAC;IAC/D,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,UAAU,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACxD,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IACE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC;QAChC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EACxC,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AACrC,CAAC"}