ttsc 0.30.3 → 0.31.0

package/src/internal/pathIdentity/FilesystemPathIdentityContext.ts

@@ -0,0 +1,182 @@
+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/src/internal/pathIdentity/FilesystemPathIdentityOperations.ts

@@ -0,0 +1,106 @@
+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/src/internal/pathIdentity/ProjectInputPathIdentity.ts

@@ -0,0 +1,21 @@
+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/src/internal/pathIdentity/ProjectInputPathIdentityContext.ts

@@ -0,0 +1,21 @@
+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/src/internal/pathIdentity/ProjectInputPathIdentityOperations.ts

@@ -0,0 +1,22 @@
+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;