ttsc 0.30.4 → 0.31.1

package/lib/internal/parseWindowsDirectoryCaseSensitivity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ * Inputs must be successful fsutil query responses. The opaque comparison
+ * assumes the volume-root response represents the ordinary disabled state;
+ * unrecognized or truncated framing returns no answer.
+ *
+ * @evidence contracts/common.md#principled-implementation Capturing the final status field of the complete native English message separates status authority from echoed path data. Other locales compare the successful response suffix with a known disabled volume-root response, under the query framing and root-state premises.
+ * @evidence contracts/common.md#clear-and-simple-design One complete-message recognition precedes one raw-byte fallback, avoiding a separate locale dictionary or unreliable console-code-page conversion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The native English message grammar supplies status framing without path-word exceptions or a locale dictionary. Absent baseline framing remains undefined, while the successful-query premise is explicit rather than applied to arbitrary output.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe locale handling, successful-query inputs and the disabled-root assumption, with the acknowledgment block separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows-specific query interpretation remains isolated; comparing native output bytes avoids assuming UTF-8 decoding preserves localized fsutil suffixes, while volume-root framing remains a stated boundary assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Decoded text, encoded root bytes and views of the supplied buffers are invocation-local; returning a boolean or undefined retains none of them and acquires no native handle or historical cache.
+ * @evidence contracts/performance.md#efficient-algorithms UTF-8 decoding and trailing-whitespace trimming precede one anchored native-message scan. The fallback encodes the root, searches the volume buffer for those bytes and compares one suffix view. Work and temporary storage depend on response/root lengths and byte-search implementation; inputs have no size cap here, and no locale dictionary or recursive lookup is built.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This byte interpreter owns no native-query producer or mutable directory observations to coordinate. The caller supplies current query bytes and any reusable disabled-root baseline; the parser adds no authority cache.
+ */
+export declare function parseWindowsDirectoryCaseSensitivity(directoryOutput: Buffer, volumeOutput: Buffer | undefined, volumeRoot: string): boolean | undefined;

package/lib/internal/parseWindowsDirectoryCaseSensitivity.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseWindowsDirectoryCaseSensitivity = parseWindowsDirectoryCaseSensitivity;
+/**
+ * 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.
+ *
+ * Inputs must be successful fsutil query responses. The opaque comparison
+ * assumes the volume-root response represents the ordinary disabled state;
+ * unrecognized or truncated framing returns no answer.
+ *
+ * @evidence contracts/common.md#principled-implementation Capturing the final status field of the complete native English message separates status authority from echoed path data. Other locales compare the successful response suffix with a known disabled volume-root response, under the query framing and root-state premises.
+ * @evidence contracts/common.md#clear-and-simple-design One complete-message recognition precedes one raw-byte fallback, avoiding a separate locale dictionary or unreliable console-code-page conversion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The native English message grammar supplies status framing without path-word exceptions or a locale dictionary. Absent baseline framing remains undefined, while the successful-query premise is explicit rather than applied to arbitrary output.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe locale handling, successful-query inputs and the disabled-root assumption, with the acknowledgment block separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows-specific query interpretation remains isolated; comparing native output bytes avoids assuming UTF-8 decoding preserves localized fsutil suffixes, while volume-root framing remains a stated boundary assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Decoded text, encoded root bytes and views of the supplied buffers are invocation-local; returning a boolean or undefined retains none of them and acquires no native handle or historical cache.
+ * @evidence contracts/performance.md#efficient-algorithms UTF-8 decoding and trailing-whitespace trimming precede one anchored native-message scan. The fallback encodes the root, searches the volume buffer for those bytes and compares one suffix view. Work and temporary storage depend on response/root lengths and byte-search implementation; inputs have no size cap here, and no locale dictionary or recursive lookup is built.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This byte interpreter owns no native-query producer or mutable directory observations to coordinate. The caller supplies current query bytes and any reusable disabled-root baseline; the parser adds no authority cache.
+ */
+function parseWindowsDirectoryCaseSensitivity(directoryOutput, volumeOutput, volumeRoot) {
+    const text = directoryOutput.toString("utf8");
+    const english = /^Case sensitive attribute on directory [^\r\n]+ is (enabled|disabled)\.$/iu.exec(text.trimEnd());
+    if (english !== null)
+        return english[1].toLowerCase() === "enabled";
+    if (volumeOutput === undefined)
+        return undefined;
+    const encodedRoot = Buffer.from(volumeRoot, "utf8");
+    const rootOffset = volumeOutput.lastIndexOf(encodedRoot);
+    if (rootOffset === -1)
+        return undefined;
+    const disabledSuffix = volumeOutput.subarray(rootOffset + encodedRoot.length);
+    if (disabledSuffix.length === 0 ||
+        directoryOutput.length < disabledSuffix.length) {
+        return undefined;
+    }
+    return !directoryOutput
+        .subarray(directoryOutput.length - disabledSuffix.length)
+        .equals(disabledSuffix);
+}
+//# sourceMappingURL=parseWindowsDirectoryCaseSensitivity.js.map

package/lib/internal/parseWindowsDirectoryCaseSensitivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseWindowsDirectoryCaseSensitivity.js","sourceRoot":"","sources":["../../src/internal/parseWindowsDirectoryCaseSensitivity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8CACE,eAAuB,EACvB,YAAgC,EAChC,UAAkB;IAElB,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,GACX,4EAA4E,CAAC,IAAI,CAC/E,IAAI,CAAC,OAAO,EAAE,CACf,CAAC;IACJ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC;IACrE,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEjD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,YAAY,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACzD,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,cAAc,GAAG,YAAY,CAAC,QAAQ,CAAC,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9E,IACE,cAAc,CAAC,MAAM,KAAK,CAAC;QAC3B,eAAe,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,EAC9C,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,eAAe;SACpB,QAAQ,CAAC,eAAe,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;SACxD,MAAM,CAAC,cAAc,CAAC,CAAC;AAC5B,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * One path answered by the filesystem, in two forms that answer different
+ * questions.
+ *
+ * `path` is the spelling to hand back to the filesystem or to a user: the
+ * observed physical prefix (reparse points and Windows 8.3 names expanded when
+ * resolved) followed by an unresolved suffix canonicalized according to the
+ * resolved ancestor's measured ASCII case policy. In strict resolution the
+ * suffix represents missing path structure; best-effort resolution can also
+ * retain unreadable existing entries. If no prefix resolves, the path remains
+ * lexically normalized. `key` is the spelling to compare under those
+ * observations; unresolved names are locations, not proof that an entry exists.
+ * Unknown case policy and unproved Unicode equivalence retain distinct keys, so
+ * key inequality cannot prove physical distinction.
+ *
+ * Produced by {@link FilesystemPathIdentityContext.resolve}.
+ *
+ * @evidence contracts/common.md#principled-implementation The pair separates comparison spelling from the path usable by native consumers. Resolved prefixes use native physical observations, and unresolved ASCII suffixes fold only under observed insensitivity; best-effort mode does not certify that every existing entry resolved. Unknown and Unicode variants may retain different keys without proof of distinct physical entries.
+ * @evidence contracts/common.md#clear-and-simple-design Two named fields expose the distinction without storing a second independently computed identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation records native resolution outcomes instead of fixture spellings or global case-folding assertions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain comparison versus returned spelling, missing-suffix canonicalization and member use; documented properties are separated and carry no acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Existing native aliases and Windows volume-root spelling are represented separately from missing-suffix case policy; unknown directory policy preserves exact spellings and cannot authorize treating case variants as equivalent.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type FilesystemPathIdentity = {
+    /**
+     * Comparison key under this transaction's filesystem observations. Windows
+     * volume roots use native root grammar. Unresolved ASCII letters fold only
+     * under measured insensitivity; unknown and non-ASCII variants can retain
+     * distinct keys even when a later native observation would establish an
+     * alias.
+     */
+    key: string;
+    /**
+     * Observed physical prefix followed by the unresolved suffix, or lexical
+     * spelling if no prefix resolved. Use it to open, watch, or print the
+     * location; best-effort output is not proof that every existing segment was
+     * resolved.
+     */
+    path: string;
+};

package/lib/internal/pathIdentity/FilesystemPathIdentity.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FilesystemPathIdentity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemPathIdentity.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/FilesystemPathIdentity.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,176 @@
+import type { FilesystemPathIdentity } from "./FilesystemPathIdentity";
+/**
+ * A memoizing filesystem-identity resolver for one transaction.
+ *
+ * Create one with {@link createFilesystemPathIdentityContext} per unit of work
+ * (one build, one watch refresh, one runtime question) and ask it every
+ * question whose answers should reuse the same observations. Each queried key's
+ * realpath and case result is memoized, including missing-entry results and
+ * other unavailable observations admitted by best-effort error policy.
+ *
+ * This is not an atomic filesystem snapshot: previously unseen keys can be
+ * observed later, after the disk has changed. Begin a new context when the
+ * operation needs fresh observations rather than reusing earlier answers.
+ *
+ * Directory ASCII case capability is explicit: true means observed sensitivity,
+ * false means observed insensitivity and undefined means unknown. Unresolved
+ * suffixes fold ASCII letters only for false; an unknown policy preserves exact
+ * spelling without establishing that differently cased spellings denote
+ * different entries. Non-ASCII letters retain their spelling even under
+ * observed insensitivity, because an ASCII case probe does not establish native
+ * Unicode name equivalence.
+ *
+ * Physical resolve/isWithin operations and lexical routing operations answer
+ * different questions. Lexical keys preserve link and short-name components;
+ * lexical matching admits ASCII case candidates under insensitive or unknown
+ * policy and retains non-ASCII component pairs as candidates without asserting
+ * physical identity or cache freshness.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolution, tri-state case capability and containment share keyed observations; unknown policy preserves unresolved spelling instead of authorizing a merge, and the context makes no atomic guarantee across keys first observed at different times. Best-effort suffixes can include unreadable existing entries, not only missing names.
+ * @evidence contracts/common.md#clear-and-simple-design Six methods distinguish physical resolution/containment, native case capability and lexical key/candidate routing while sharing one probe context; callers need no parallel path-policy implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or permitted-unavailable observations remain memoized outcomes rather than guessed existence or absence; refreshed work needs a new context instead of layering retries over stale identity premises.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain generation-local observations, tri-state case policy, ASCII identity limits and physical versus lexical use; documented methods and acknowledgments follow the documentation skill's spacing guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath and observed directory capability govern observed physical prefixes; unavailable case probes remain unknown and only observed insensitivity permits unresolved-suffix ASCII folding. Best-effort output does not certify that every existing alias resolved. Lexical routing retains non-ASCII candidate pairs instead of inventing a native Unicode equivalence table.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type FilesystemPathIdentityContext = {
+    /**
+     * Whether ASCII names directly inside `directory` are compared
+     * case-sensitively, judged at its resolved ancestor where one is available.
+     *
+     * Returns true for observed sensitivity, false for observed insensitivity, or
+     * undefined when the native probes cannot establish the policy. Unknown does
+     * not authorize case-folded identity or a claim that a cache input is
+     * stable.
+     *
+     * @evidence contracts/common.md#principled-implementation True and false express observed native case policy at the resolved ancestor; undefined preserves insufficient evidence, so callers cannot treat a failed probe as either equivalence or proven distinction.
+     * @evidence contracts/common.md#clear-and-simple-design One tri-state query exposes both case judgment and inability to establish it without requiring a parallel provenance API or duplicated probing logic.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable measurement stays unknown rather than receiving an operating-system default or a preferred answer that makes a desired identity comparison succeed.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain ancestor selection, true/false/undefined and why unknown cannot certify case-folded identity or cache stability, with separated tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Directory-specific probes represent Windows per-directory and POSIX volume case behavior; undefined acknowledges unavailable capability instead of inferring it from an OS name.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources caseSensitive declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms caseSensitive declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work caseSensitive declares a signature only; the implementation owns any shared work.
+     */
+    caseSensitive(directory: string): boolean | undefined;
+    /**
+     * Whether `candidate` is `root` itself or lies beneath it, compared by
+     * identity key under the context's observations. Successfully resolved native
+     * aliases and observed ASCII case equivalence can share that key.
+     *
+     * Containment inherits the context's cached observations and case-policy
+     * limitations; it does not hold either directory open or refresh its
+     * identity. Best-effort output can retain unreadable existing aliases rather
+     * than prove that they resolved to one physical entry.
+     *
+     * With unknown policy, preserved missing-suffix spelling can leave real
+     * case-insensitive aliases separate; this result alone cannot prove complete
+     * watcher coverage or authorize cache reuse.
+     *
+     * @evidence contracts/common.md#principled-implementation Shared resolution and component-delimited keys define root-inclusive identity containment without lexical-prefix overmatch; unknown missing-suffix case policy can conservatively leave aliases separate, so this boolean is not a complete uncertainty proof.
+     * @evidence contracts/common.md#clear-and-simple-design The method combines the existing resolve and identity containment operations, keeping callers independent of key encoding details.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Aliases are handled by the shared resolver, not hardcoded directory names or string-prefix exceptions; stale observations are not secretly refreshed inside containment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents root inclusion, alias equivalence and inherited cache/case limits rather than claiming a held-directory guarantee; tags follow the documentation skill's separation rule.
+     * @evidence contracts/portability.md#os-neutral-implementation Containment uses native observed keys and volume-root grammar; unknown directory policy preserves unresolved spelling and best-effort failures can leave existing aliases unexpanded. Coverage and reuse owners must handle that uncertainty rather than assume OS-default folding or complete alias resolution.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isWithin declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms isWithin declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work isWithin declares a signature only; the implementation owns any shared work.
+     */
+    isWithin(root: string, candidate: string): boolean;
+    /**
+     * Whether a lexical path is a root-inclusive descendant candidate for
+     * routing.
+     *
+     * Native volume roots must agree and root components are compared against
+     * corresponding candidate components. For all-ASCII component pairs,
+     * sensitive parents require exact names and insensitive or unknown parents
+     * admit ASCII case matches. Pairs containing non-ASCII names remain
+     * candidates regardless of case capability, because native Unicode
+     * equivalence was not established. Link and short-name components are
+     * retained rather than physically merged.
+     *
+     * This is an observation-routing candidate relation, not physical containment
+     * proof. Non-ASCII admission deliberately overroutes observations rather than
+     * asserting a filesystem's Unicode equivalence or authorizing cache reuse.
+     *
+     * @evidence contracts/common.md#principled-implementation Native roots and component counts bound root-inclusive lexical descendants; ASCII pairs use exact or case-folded candidates by parent capability, while pairs containing non-ASCII remain possible matches because their native equivalence was not proved.
+     * @evidence contracts/common.md#clear-and-simple-design The lexical descendant operation shares component comparison with lexicalMatches and keeps physical containment in isWithin, preventing routing uncertainty from redefining identity keys.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown case evidence expands routing candidates rather than fabricating equality; link spellings remain intact and the relation cannot substitute for physical or generation proof.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain root inclusion, component/case rules, retained aliases, routing purpose and the Unicode/proof limit with separated method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native grammar separates volumes and components, actual parent probes govern ASCII case routing, and non-ASCII admission preserves possible native Unicode aliases without applying an invented OS-independent Unicode table.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lexicalIsWithin declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lexicalIsWithin declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lexicalIsWithin declares a signature only; the implementation owns any shared work.
+     */
+    lexicalIsWithin(root: string, candidate: string): boolean;
+    /**
+     * Build a lexical key without replacing link or short-name components.
+     *
+     * Normalization uses native path grammar. Each component folds ASCII letters
+     * only when its parent is observed insensitive; sensitive or unknown parents
+     * preserve exact spelling. Non-ASCII letters are not folded by this lexical
+     * key, and different keys do not prove distinct physical targets.
+     *
+     * @evidence contracts/common.md#principled-implementation Component-wise ASCII folding requires observed parent insensitivity, so the key retains uncertain names and lexical alias boundaries rather than merging them through unproved physical equivalence.
+     * @evidence contracts/common.md#clear-and-simple-design A named lexical key operation separates spelling-based indexing from resolve's physical identity while reusing the context's native parent-case observations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown capability preserves the name rather than inventing a default-insensitive answer; the key does not resolve away a symlink spelling merely to force it into an existing physical entry.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain component preservation, ASCII-only folding, parent policy and why key inequality is not physical distinction, with separate method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native roots and component separators come from the selected path grammar; directory probes authorize only the supported ASCII case canonicalization instead of universal lowercasing across host filesystems.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lexicalKey declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lexicalKey declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lexicalKey declares a signature only; the implementation owns any shared work.
+     */
+    lexicalKey(location: string): string;
+    /**
+     * Whether two lexical spellings are matching observation-routing candidates.
+     *
+     * Native roots and component counts must agree. Comparison walks the left
+     * spelling's parents: all-ASCII pairs require exact names under sensitive
+     * policy or admit ASCII case matches under insensitive or unknown policy. If
+     * either name contains non-ASCII characters, the pair remains a candidate
+     * without assuming a native Unicode equivalence table. Physical alias
+     * expansion is deliberately not applied to the compared components.
+     *
+     * A match is not file equality or a cache proof. Non-ASCII pairs deliberately
+     * overroute observations rather than treating uncertain Unicode names as
+     * equal.
+     *
+     * @evidence contracts/common.md#principled-implementation Equal native roots and component counts bound same-location lexical candidates; parent capability controls ASCII comparison, while non-ASCII pairs remain candidates without asserting physical equality or treating unknown as observed insensitivity.
+     * @evidence contracts/common.md#clear-and-simple-design The same component relation serves equality-shaped and descendant-shaped routing, while lexicalKey and physical resolve retain their separate indexing and identity responsibilities.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown policy admits an extra candidate comparison rather than certifying equality; no caller may use a true result as replacement evidence for unchanged files or generation validity.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain root/count requirements, left-parent capability, preserved aliases and the routing-versus-proof Unicode limit with separated method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native roots and directory probes control ASCII lexical routing across Windows and POSIX syntax; uncertain Unicode pairs remain candidates so JavaScript casing cannot suppress a possible native alias event.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lexicalMatches declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lexicalMatches declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lexicalMatches declares a signature only; the implementation owns any shared work.
+     */
+    lexicalMatches(left: string, right: string): boolean;
+    /**
+     * Resolve `location`, existing or not, to an observed path spelling and
+     * comparison key.
+     *
+     * Successfully observed ancestors are resolved natively. Unresolved suffix
+     * ASCII letters fold only for observed insensitivity, retaining exact case
+     * for sensitivity or unknown policy. Repeated normalized keys reuse the
+     * context's earlier observation; realpath error handling follows the
+     * creator's configured policy. Best-effort policy can preserve unreadable
+     * existing suffix entries; if no prefix resolves, the returned path stays
+     * lexically normalized.
+     *
+     * Non-ASCII letters in unresolved names preserve spelling because native
+     * Unicode case equivalence was not established by the ASCII capability
+     * probe.
+     *
+     * @evidence contracts/common.md#principled-implementation Physical ancestor resolution and ASCII-only folding under observed insensitivity avoid merging unknown or unproved Unicode suffixes; normalized queries reuse captured premises, while preserved spellings do not prove distinct physical entries.
+     * @evidence contracts/common.md#clear-and-simple-design One identity result groups path spelling and comparison key while native probing and memoization stay private to the creator.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses actual native observations and an explicit error policy; unresolved suffixes do not fabricate an existing entry or prove absence, and filesystem methods are not patched.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/key results, missing suffixes, memo reuse and error-policy ownership with separated method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native alias expansion and directory capability govern identity using selected path grammar; unknown policy preserves missing names and non-ASCII letters are never folded by the suffix canonicalizer, avoiding universal lowercasing or an OS default.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources resolve declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms resolve declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work resolve declares a signature only; the implementation owns any shared work.
+     */
+    resolve(location: string): FilesystemPathIdentity;
+};

package/lib/internal/pathIdentity/FilesystemPathIdentityContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FilesystemPathIdentityContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemPathIdentityContext.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/FilesystemPathIdentityContext.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+/**
+ * The filesystem primitives a {@link FilesystemPathIdentityContext} consults.
+ *
+ * Callers can supply a partial override to the creator and inherit host
+ * defaults for omitted primitives. Overrides must describe one consistent
+ * filesystem and match the selected platform's path grammar; combining foreign
+ * path grammar with unrelated host probes cannot establish a coherent
+ * identity.
+ *
+ * The case callback returns true or false only for established native policy;
+ * undefined explicitly reports an unavailable determination. The resolver uses
+ * established insensitivity for ASCII folding only; this callback supplies no
+ * native Unicode case or normalization table.
+ *
+ * @evidence contracts/common.md#principled-implementation Native realpath, tri-state directory case judgment and path grammar define identity premises; undefined preserves unestablished policy, optional stat/list primitives support the default probe, and explicit error policy distinguishes strict from best-effort resolution.
+ * @evidence contracts/common.md#clear-and-simple-design One dependency record groups the resolver's required decisions and optional native probe primitives; Partial overrides and default assembly belong to the creator rather than to each operation signature.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit injection replaces only this owned boundary, not foreign globals; a consistent filesystem/platform premise is required instead of accepting fabricated aliases or treating an OS name as measured directory policy.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain partial overrides, host defaults and coherent filesystem/path semantics; member descriptions state defaults and error-policy consequences with documentation-skill member and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform selects native path grammar, while realpath and directory capability probes establish identity; unknown case policy is explicit and does not inherit a platform default, and volume-root formatting remains a separate concern.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type FilesystemPathIdentityOperations = {
+    /**
+     * Whether ASCII names inside `directory` are compared case-sensitively. The
+     * resolver queries a resolved ancestor when interpreting unresolved suffixes
+     * or answering an explicit directory-policy query; if no existing prefix
+     * resolves, it can query the volume root. Return true for established
+     * sensitivity, false for established insensitivity or undefined if the policy
+     * cannot be established. Existing boolean-returning callbacks remain valid.
+     *
+     * @evidence contracts/common.md#principled-implementation Established directory policy supplies the unresolved-suffix ASCII equivalence premise, and undefined preserves inability to establish it; only false authorizes ASCII folding, independently of volume-root formatting and unproved Unicode equivalence. Best-effort resolution does not prove that such suffix entries are absent.
+     * @evidence contracts/common.md#clear-and-simple-design One callback reports sensitive, insensitive or unknown capability while accepting existing boolean implementations; the creator owns memoization and suffix handling rather than duplicating them in injected probes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Injected results must report actual established policy or unknown, not special-filename answers or OS defaults chosen to produce desired identity equality.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains directory scope, explicit-query use, all three result states and boolean callback compatibility, with separate method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation The callback represents native directory case capability, supporting case-sensitive Windows directories and case-insensitive POSIX volumes without deriving the answer solely from an operating-system name.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources caseSensitive declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms caseSensitive declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work caseSensitive declares a signature only; the implementation owns any shared work.
+     */
+    caseSensitive(directory: string): boolean | undefined;
+    /**
+     * Link-preserving stat the default case-sensitivity probe uses to test
+     * whether a name opens under its alternate case. Defaults to `fs.lstatSync`.
+     *
+     * @evidence contracts/common.md#principled-implementation Link-preserving metadata lets the default case probe test a candidate name without confusing that entry with a followed link target; native errors preserve whether the alternate spelling was absent or observation failed.
+     * @evidence contracts/common.md#clear-and-simple-design This optional primitive supports the default capability probe, with omitted-operation defaulting owned by the creator and case classification owned by that probe.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A supported callback supplies real stat results instead of mutating fs.lstatSync or returning a guessed affirmative answer for selected alternate names.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states link preservation, alternate-case purpose and the default implementation, with tags separated under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native link-preserving stat and either Stats representation retain filesystem metadata semantics; callers need no shell command or platform-specific filename heuristic at this boundary.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lstat declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lstat declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lstat declares a signature only; the implementation owns any shared work.
+     */
+    lstat?(location: string): fs.Stats | fs.BigIntStats;
+    /**
+     * Path semantics to apply. `win32` selects backslash separators, drive and
+     * UNC roots, and a case-folded volume key; anything else is POSIX.
+     */
+    platform: NodeJS.Platform;
+    /**
+     * Directory listing the default case-sensitivity probe reads. Defaults to
+     * `fs.readdirSync`.
+     *
+     * @evidence contracts/common.md#principled-implementation Listing actual immediate entry names gives the default case probe candidate spellings and distinct folded-name evidence; the operation returns names rather than resolving entries or asserting case policy itself.
+     * @evidence contracts/common.md#clear-and-simple-design An optional name-list primitive supplies only enumeration to the default probe; the creator owns defaults and the probe owns interpretation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Names must come from the actual directory rather than a fixed fixture list or patched global enumeration that makes a desired case decision appear supported.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies probe use and fs.readdirSync default; its separate method acknowledgment block follows the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native directory enumeration returns immediate names without a shell listing or hardcoded path separator; interpretation uses the selected filesystem's case behavior.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources readdir declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms readdir declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work readdir declares a signature only; the implementation owns any shared work.
+     */
+    readdir?(directory: string): string[];
+    /**
+     * Physical path of an existing entry. Defaults to `fs.realpathSync.native`,
+     * which, unlike the JavaScript implementation, also expands Windows 8.3 short
+     * names.
+     *
+     * @evidence contracts/common.md#principled-implementation Physical resolution identifies the existing prefix used to anchor unresolved suffixes; operation errors remain available to the creator's strict or best-effort policy rather than being silently converted by the signature.
+     * @evidence contracts/common.md#clear-and-simple-design One physical-path primitive delegates alias expansion to the filesystem and leaves memoization, missing ancestors and error classification with the creator.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native realpath results replace actual aliases instead of manually guessing a target or globally rewriting foreign filesystem behavior.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states existing-entry physical resolution and why the native default matters for Windows short names, with separated method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Physical resolution must honor native aliases, including Windows short names; path grammar and directory case interpretation remain separate capabilities instead of substitutes for realpath.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources realpath declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms realpath declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work realpath declares a signature only; the implementation owns any shared work.
+     */
+    realpath(location: string): string;
+    /**
+     * When `true` (the default), a realpath failure other than a missing entry
+     * propagates. When `false`, every failure is treated as an unavailable
+     * physical observation and resolution continues with the parent. This does
+     * not establish absence: existing inaccessible entries can become part of the
+     * unresolved suffix used by best-effort callers such as runtime hooks.
+     */
+    throwOnRealpathError: boolean;
+};

package/lib/internal/pathIdentity/FilesystemPathIdentityOperations.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FilesystemPathIdentityOperations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemPathIdentityOperations.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/FilesystemPathIdentityOperations.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentity } from "./FilesystemPathIdentity";
+/**
+ * The identity of one project input (a tsconfig, a source, a declared plugin
+ * input) as the watch and LSP hosts compare them.
+ *
+ * It is exactly a {@link FilesystemPathIdentity}. Project inputs carry no rule
+ * of their own; the alias keeps call sites that reason about project inputs
+ * readable while sharing the same representation. Equality conclusions still
+ * depend on the producing context's observations, platform and error policy.
+ *
+ * @evidence contracts/common.md#principled-implementation The exact type alias preserves both canonical comparison key and filesystem spelling without adding project-only distinctions that would change identity.
+ * @evidence contracts/common.md#clear-and-simple-design A domain alias improves caller vocabulary while the underlying representation and policy retain one owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The alias uses TypeScript's supported type identity and carries no runtime adaptation or consumer special case.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains which project inputs it names and why the representation is shared, separated from tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The aliased representation separates native comparison keys from returned path spellings; it does not introduce another OS or case-policy assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type ProjectInputPathIdentity = FilesystemPathIdentity;

package/lib/internal/pathIdentity/ProjectInputPathIdentity.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ProjectInputPathIdentity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectInputPathIdentity.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/ProjectInputPathIdentity.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentityContext } from "./FilesystemPathIdentityContext";
+/**
+ * A project-input identity resolver; an alias of
+ * {@link FilesystemPathIdentityContext}, so project inputs and every other path
+ * are compared by one rule.
+ *
+ * The inherited context memoizes per-key observations and is not an atomic
+ * filesystem snapshot. A new project-input operation needing fresh state must
+ * use a new context; the alias adds no freshness or case-policy guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation The alias preserves the filesystem context's resolution, case-policy and containment operations exactly, so project and other native consumers share the same relation.
+ * @evidence contracts/common.md#clear-and-simple-design The domain name adds no adapter state or policy; the underlying context owns caching and native decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A type alias neither patches foreign methods nor adds test-specific native behavior.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name the alias, shared identity rule and inherited non-atomic freshness limit, with separated acknowledgment tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared boundary exposes native case judgment and physical identity rather than deriving policy from the project domain or its filename.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type ProjectInputPathIdentityContext = FilesystemPathIdentityContext;

package/lib/internal/pathIdentity/ProjectInputPathIdentityContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ProjectInputPathIdentityContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectInputPathIdentityContext.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/ProjectInputPathIdentityContext.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+/**
+ * The replaceable filesystem primitives of a project-input identity context; an
+ * alias of {@link FilesystemPathIdentityOperations} for the same reason
+ * {@link ProjectInputPathIdentity} is one.
+ *
+ * Partial overrides, native defaults and strict versus best-effort error policy
+ * retain exactly the underlying resolver's meanings. This name adds no
+ * project-specific probing or dependency-validation guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation The alias preserves the complete filesystem primitive and policy shape, so project inputs use the same native identity premises as other consumers rather than a second equivalence relation.
+ * @evidence contracts/common.md#clear-and-simple-design A domain name is sufficient; no adapter, duplicate operations object or project-only defaults are introduced.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The alias adds no special project path handling or foreign mutation, and does not turn successful identity resolution into proof of unchanged input contents.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify the alias, inherited override/error semantics and absence of project-only validation, with separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Project operations inherit native alias resolution, path grammar and directory case capability from the shared boundary instead of applying an OS-based project naming rule.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type ProjectInputPathIdentityOperations = FilesystemPathIdentityOperations;

package/lib/internal/pathIdentity/ProjectInputPathIdentityOperations.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ProjectInputPathIdentityOperations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectInputPathIdentityOperations.js","sourceRoot":"","sources":["../../../src/internal/pathIdentity/ProjectInputPathIdentityOperations.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,25 @@
+import type { FilesystemPathIdentityContext } from "./FilesystemPathIdentityContext";
+import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+/**
+ * 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.
+ */
+export declare function createFilesystemPathIdentityContext(operations?: Partial<FilesystemPathIdentityOperations>): FilesystemPathIdentityContext;