@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/filesystem/TtscTransformFilesystemOperations.d.ts

@@ -0,0 +1,219 @@
+import type fs from "node:fs";
+import type { FilesystemPathIdentityOperations } from "ttsc/path-identity";
+/**
+ * Cache-owned synchronous filesystem reads used by transform validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Capture and validation share one operation table, so evidence from different observed filesystems cannot be mixed implicitly.
+ * @evidence contracts/common.md#clear-and-simple-design Read, path-policy, and optional watch capabilities form one structural boundary; proof algorithms remain in their consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit capability injection avoids native monkeypatching and does not introduce a production branch that recognizes test inputs.
+ * @evidence contracts/common.md#meaningful-documentation Member comments distinguish ordinary versus bigint metadata, following versus link reads, and backend watch limitations.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral operations expose directory case and path-platform policy with native filesystem observations, without promising that one OS name determines every volume's capability.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscTransformFilesystemOperations only declares a shape; it has no
+ *   computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscTransformFilesystemOperations only declares a shape; it has no work
+ *   to reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscTransformFilesystemOperations only declares a shape; it has no handle
+ *   or retained state at runtime.
+ */
+export interface TtscTransformFilesystemOperations {
+    /**
+     * Optional native byte-preserving link text for contributor predicates.
+     *
+     * @evidence contracts/common.md#principled-implementation Raw native link text is retained independently of target bytes and metadata.
+     * @evidence contracts/common.md#clear-and-simple-design An optional native capability preserves existing structural filesystem adapters; missing support refuses the corresponding predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native bytes are not replaced with decoded text or an OS-default guess.
+     * @evidence contracts/common.md#meaningful-documentation The member comment identifies the byte-preserving query and contributor predicate consumer.
+     * @evidence contracts/portability.md#os-neutral-implementation The supplied native view owns link and filename bytes; consumers choose its declared path dialect.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Only an operation signature is declared; the implementing view owns query cost.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This signature provides no independent cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This signature owns no resource lifetime.
+     */
+    readlink?(location: string | Buffer): Buffer;
+    /**
+     * Optional byte-preserving native directory names for contributor predicates.
+     *
+     * @evidence contracts/common.md#principled-implementation Byte-preserving entry names retain directory fingerprint meaning on native byte-name filesystems.
+     * @evidence contracts/common.md#clear-and-simple-design An optional native capability preserves existing structural filesystem adapters; missing support refuses the corresponding predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native bytes are not replaced with decoded text or an OS-default guess.
+     * @evidence contracts/common.md#meaningful-documentation The member comment identifies the byte-preserving query and contributor predicate consumer.
+     * @evidence contracts/portability.md#os-neutral-implementation The supplied native view owns link and filename bytes; consumers choose its declared path dialect.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Only an operation signature is declared; the implementing view owns query cost.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This signature provides no independent cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This signature owns no resource lifetime.
+     */
+    readdirRaw?(location: string): fs.Dirent<Buffer>[];
+    /** Override the case policy when the observed filesystem is not the host. */
+    caseSensitive?: FilesystemPathIdentityOperations["caseSensitive"];
+    /**
+     * Test whether a validation or resolution candidate currently exists.
+     *
+     * @evidence contracts/common.md#principled-implementation Existence is a distinct observed predicate, not a substitute for file kind, readable content, or physical identity.
+     * @evidence contracts/common.md#clear-and-simple-design One boolean query exposes the capability needed by selection and missing-input proofs.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The view's actual observation supplies the answer rather than a filename exception or fabricated compiler proof.
+     * @evidence contracts/common.md#meaningful-documentation The native comment states the resolution and validation ownership of the candidate query.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral existence follows the supplied filesystem view instead of assuming native accessibility from path spelling.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of exists is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of exists is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of exists is declared here; the cost belongs to its
+     *   implementation.
+     */
+    exists(location: string): boolean;
+    /**
+     * Read link metadata without following a symbolic link.
+     *
+     * @evidence contracts/common.md#principled-implementation Nonfollowing metadata preserves link topology separately from the target's content and regular stat result.
+     * @evidence contracts/common.md#clear-and-simple-design BigIntStats carries device, identity, and nanosecond evidence in one native observation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Link metadata is not synthesized from target stat or inferred from a known path prefix.
+     * @evidence contracts/common.md#meaningful-documentation The native comment specifies the nonfollowing distinction and the return type identifies exact metadata precision.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral link evidence comes from the observing view's native device and metadata fields, including symlink and junction behavior.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of lstat is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of lstat is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of lstat is declared here; the cost belongs to its
+     *   implementation.
+     */
+    lstat(location: string): fs.BigIntStats;
+    /**
+     * Read bytes used by project, graph, and host-input fingerprints.
+     *
+     * @evidence contracts/common.md#principled-implementation Raw bytes supply content evidence independently of timestamps and of compiler text normalization.
+     * @evidence contracts/common.md#clear-and-simple-design A synchronous Buffer result exposes one read operation; each fingerprint owner chooses its required encoding and hash.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual bytes cannot be replaced by metadata or an expected transformed result solely to satisfy validation.
+     * @evidence contracts/common.md#meaningful-documentation The comment names the proof consumers and Buffer preserves the raw-byte contract.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral content reads use the supplied filesystem view without imposing line-ending conversion or path-case rewriting.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of readFile is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of readFile is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of readFile is declared here; the cost belongs to its
+     *   implementation.
+     */
+    readFile(location: string): Buffer;
+    /**
+     * Enumerate one project or missing-input proof directory.
+     *
+     * @evidence contracts/common.md#principled-implementation Dirent observations supply both names and kinds needed by program walks and directory predicates.
+     * @evidence contracts/common.md#clear-and-simple-design One directory read supplies the existing proof algorithms instead of exposing a second tree walker.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Enumeration does not silently remove names that happen to match known test or host directories.
+     * @evidence contracts/common.md#meaningful-documentation The comment identifies project and missing-input proof responsibilities; Dirent retains kind information.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral directory entries retain observed names and native kinds; case comparison follows the owning directory's policy in the consumer.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of readdir is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of readdir is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of readdir is declared here; the cost belongs to its
+     *   implementation.
+     */
+    readdir(location: string): fs.Dirent[];
+    /**
+     * Resolve one lexical path to its current physical target.
+     *
+     * @evidence contracts/common.md#principled-implementation Physical target resolution distinguishes changed link selection from unchanged lexical spelling and content.
+     * @evidence contracts/common.md#clear-and-simple-design One string observation exposes the resolver capability while equivalence and failure handling remain in proof consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Physical identity is observed rather than fabricated by removing link-like path components.
+     * @evidence contracts/common.md#meaningful-documentation The native comment distinguishes lexical input from the current physical target.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral resolution follows the actual filesystem's symlinks, junctions, and native aliases instead of a universal lowercase rule.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of realpath is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of realpath is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of realpath is declared here; the cost belongs to its
+     *   implementation.
+     */
+    realpath(location: string): string;
+    /**
+     * Read ordinary metadata for file-kind and missing-path checks.
+     *
+     * @evidence contracts/common.md#principled-implementation Ordinary following stats classify the observed target separately from lstat topology and exact content signatures.
+     * @evidence contracts/common.md#clear-and-simple-design The conventional Stats capability serves classification without demanding bigint arithmetic from every consumer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts File kind is not guessed from extension or substituted for evidence of readable bytes.
+     * @evidence contracts/common.md#meaningful-documentation The comment names the classification responsibility and distinguishes it from nanosecond statBigInt.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral kind checks follow native observations in the supplied view rather than assumed directory or link behavior.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of stat is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of stat is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of stat is declared here; the cost belongs to its
+     *   implementation.
+     */
+    stat(location: string): fs.Stats;
+    /**
+     * Read nanosecond metadata for stable file and directory signatures.
+     *
+     * @evidence contracts/common.md#principled-implementation Bigint metadata preserves reporting-device and exact stamp information required by signature separability proofs.
+     * @evidence contracts/common.md#clear-and-simple-design The precision-specific capability remains separate from ordinary classification stats.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native precision cannot be reconstructed from rounded millisecond values or a process-clock guess.
+     * @evidence contracts/common.md#meaningful-documentation The comment links nanosecond observations to file and directory signatures, explaining this separate method.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral signatures use the observed filesystem's device and bigint stamps, with clock-proof consumers handling granularity and cross-volume limits.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of statBigInt is declared here; the cost belongs to
+     *   its implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of statBigInt is declared here; the cost belongs to
+     *   its implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of statBigInt is declared here; the cost belongs to
+     *   its implementation.
+     */
+    statBigInt(location: string): fs.BigIntStats;
+    /** Override path parsing when the observed filesystem is not the host. */
+    platform?: NodeJS.Platform;
+    /**
+     * Open one directory's change notification, or throw when the observed
+     * filesystem cannot provide one.
+     *
+     * Left undefined, generations watch the host filesystem: in process on Linux,
+     * and through an isolated broker process on Windows and macOS. An embedder
+     * observing another filesystem supplies its own; a generation whose watch
+     * cannot be opened keeps validating from recorded state instead of losing its
+     * cache.
+     *
+     * Supplying one replaces the broker as well, so an embedder that wraps Node's
+     * own `fs.watch` gives up what the broker provides: on Windows, containing
+     * the native abort Node's fs-event backend can raise when a watched temporary
+     * tree is deleted, and on macOS, one FSEventStream per watch whose dropped
+     * events are reported rather than lost silently.
+     *
+     * @evidence contracts/common.md#principled-implementation The watch capability reports actual directory changes and failure; its absence or failure cannot certify silence as unchanged inputs.
+     * @evidence contracts/common.md#clear-and-simple-design One optional native operation exposes observation and a close handle, leaving broker selection and retained-generation proof in their owners.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Injected watches are explicit capabilities rather than patched fs methods, and errors require recorded-state validation instead of synthetic live coverage.
+     * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain absent overrides, failed watches, broker bypass, and the Windows/macOS capability lost when wrapping fs.watch directly.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral watching requires the observed filesystem's capability and accounts for backend-specific abort isolation and dropped-stream reporting rather than assuming recursive notifications are interchangeable.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of watch is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of watch is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of watch is declared here; the cost belongs to its
+     *   implementation.
+     */
+    watch?(directory: string, listener: (eventType: string, filename: string | null) => void, onError: () => void, recursive?: boolean): {
+        close: () => void;
+    };
+}

package/lib/core/transform/filesystem/createHostPathIdentityContext.d.cts

@@ -0,0 +1,31 @@
+import { type FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "./TtscTransformFilesystemOperations.cjs";
+/**
+ * Create the path-identity resolver for one filesystem view.
+ *
+ * Identity decides when two spellings name one file: case folding on
+ * case-insensitive volumes, and physical targets behind links. It must be
+ * answered by the same operations that capture and validate a generation, so
+ * the resolver is built from them. Failed realpath observations try the nearest
+ * resolvable ancestor and preserve uncertain missing suffix spelling. If no
+ * ancestor can be resolved, lexical spelling is retained instead of throwing.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity resolution uses the same lstat, listings, realpath, platform, and directory-case view as generation capture and validation, keeping equivalence within one observed filesystem.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter supplies the shared resolver's existing capability interface rather than implementing another realpath or case-folding algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed realpath retains the unresolved suffix under an observed ancestor, or lexical spelling when no ancestor resolves, rather than fabricating an existing target; no foreign filesystem methods are replaced.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains filesystem-view consistency and conservative failure semantics before the operation table wiring.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral identity follows actual directory case capability and native aliases through the supplied view, without assuming all Windows directories insensitive or all POSIX volumes sensitive.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Creating the transaction allocates its three empty observation maps;
+ *   later resolution visits missing ancestors and case-probe listings. The
+ *   adapter maps one requested listing to names without an additional native read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned context memoizes path, realpath and case observations for
+ *   repeated questions within one filesystem transaction. Callers must create
+ *   a new context when later filesystem changes can invalidate those observations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Ownership of the context and its maps transfers to the caller. Retained
+ *   entries grow with queried paths and ancestors and have no internal eviction;
+ *   ending the caller's transaction releases them, without retained descriptors.
+ */
+export declare function createHostPathIdentityContext(filesystem?: TtscTransformFilesystemOperations): FilesystemPathIdentityContext;

package/lib/core/transform/filesystem/createHostPathIdentityContext.d.mts

@@ -0,0 +1,31 @@
+import { type FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "./TtscTransformFilesystemOperations.mjs";
+/**
+ * Create the path-identity resolver for one filesystem view.
+ *
+ * Identity decides when two spellings name one file: case folding on
+ * case-insensitive volumes, and physical targets behind links. It must be
+ * answered by the same operations that capture and validate a generation, so
+ * the resolver is built from them. Failed realpath observations try the nearest
+ * resolvable ancestor and preserve uncertain missing suffix spelling. If no
+ * ancestor can be resolved, lexical spelling is retained instead of throwing.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity resolution uses the same lstat, listings, realpath, platform, and directory-case view as generation capture and validation, keeping equivalence within one observed filesystem.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter supplies the shared resolver's existing capability interface rather than implementing another realpath or case-folding algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed realpath retains the unresolved suffix under an observed ancestor, or lexical spelling when no ancestor resolves, rather than fabricating an existing target; no foreign filesystem methods are replaced.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains filesystem-view consistency and conservative failure semantics before the operation table wiring.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral identity follows actual directory case capability and native aliases through the supplied view, without assuming all Windows directories insensitive or all POSIX volumes sensitive.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Creating the transaction allocates its three empty observation maps;
+ *   later resolution visits missing ancestors and case-probe listings. The
+ *   adapter maps one requested listing to names without an additional native read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned context memoizes path, realpath and case observations for
+ *   repeated questions within one filesystem transaction. Callers must create
+ *   a new context when later filesystem changes can invalidate those observations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Ownership of the context and its maps transfers to the caller. Retained
+ *   entries grow with queried paths and ancestors and have no internal eviction;
+ *   ending the caller's transaction releases them, without retained descriptors.
+ */
+export declare function createHostPathIdentityContext(filesystem?: TtscTransformFilesystemOperations): FilesystemPathIdentityContext;

package/lib/core/transform/filesystem/createHostPathIdentityContext.d.ts

@@ -0,0 +1,31 @@
+import { type FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "./TtscTransformFilesystemOperations";
+/**
+ * Create the path-identity resolver for one filesystem view.
+ *
+ * Identity decides when two spellings name one file: case folding on
+ * case-insensitive volumes, and physical targets behind links. It must be
+ * answered by the same operations that capture and validate a generation, so
+ * the resolver is built from them. Failed realpath observations try the nearest
+ * resolvable ancestor and preserve uncertain missing suffix spelling. If no
+ * ancestor can be resolved, lexical spelling is retained instead of throwing.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity resolution uses the same lstat, listings, realpath, platform, and directory-case view as generation capture and validation, keeping equivalence within one observed filesystem.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter supplies the shared resolver's existing capability interface rather than implementing another realpath or case-folding algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed realpath retains the unresolved suffix under an observed ancestor, or lexical spelling when no ancestor resolves, rather than fabricating an existing target; no foreign filesystem methods are replaced.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains filesystem-view consistency and conservative failure semantics before the operation table wiring.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral identity follows actual directory case capability and native aliases through the supplied view, without assuming all Windows directories insensitive or all POSIX volumes sensitive.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Creating the transaction allocates its three empty observation maps;
+ *   later resolution visits missing ancestors and case-probe listings. The
+ *   adapter maps one requested listing to names without an additional native read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned context memoizes path, realpath and case observations for
+ *   repeated questions within one filesystem transaction. Callers must create
+ *   a new context when later filesystem changes can invalidate those observations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Ownership of the context and its maps transfers to the caller. Retained
+ *   entries grow with queried paths and ancestors and have no internal eviction;
+ *   ending the caller's transaction releases them, without retained descriptors.
+ */
+export declare function createHostPathIdentityContext(filesystem?: TtscTransformFilesystemOperations): FilesystemPathIdentityContext;

package/lib/core/transform/filesystem/createHostPathIdentityContext.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var pathIdentity = require('ttsc/path-identity');
+var DEFAULT_FILESYSTEM_OPERATIONS = require('./DEFAULT_FILESYSTEM_OPERATIONS.js');
+
+/**
+ * Create the path-identity resolver for one filesystem view.
+ *
+ * Identity decides when two spellings name one file: case folding on
+ * case-insensitive volumes, and physical targets behind links. It must be
+ * answered by the same operations that capture and validate a generation, so
+ * the resolver is built from them. Failed realpath observations try the nearest
+ * resolvable ancestor and preserve uncertain missing suffix spelling. If no
+ * ancestor can be resolved, lexical spelling is retained instead of throwing.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity resolution uses the same lstat, listings, realpath, platform, and directory-case view as generation capture and validation, keeping equivalence within one observed filesystem.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter supplies the shared resolver's existing capability interface rather than implementing another realpath or case-folding algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed realpath retains the unresolved suffix under an observed ancestor, or lexical spelling when no ancestor resolves, rather than fabricating an existing target; no foreign filesystem methods are replaced.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains filesystem-view consistency and conservative failure semantics before the operation table wiring.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral identity follows actual directory case capability and native aliases through the supplied view, without assuming all Windows directories insensitive or all POSIX volumes sensitive.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Creating the transaction allocates its three empty observation maps;
+ *   later resolution visits missing ancestors and case-probe listings. The
+ *   adapter maps one requested listing to names without an additional native read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned context memoizes path, realpath and case observations for
+ *   repeated questions within one filesystem transaction. Callers must create
+ *   a new context when later filesystem changes can invalidate those observations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Ownership of the context and its maps transfers to the caller. Retained
+ *   entries grow with queried paths and ancestors and have no internal eviction;
+ *   ending the caller's transaction releases them, without retained descriptors.
+ */
+function createHostPathIdentityContext(filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    return pathIdentity.createFilesystemPathIdentityContext({
+        caseSensitive: filesystem.caseSensitive,
+        lstat: filesystem.lstat,
+        platform: filesystem.platform,
+        readdir: (directory) => filesystem.readdir(directory).map((entry) => entry.name),
+        realpath: filesystem.realpath,
+        throwOnRealpathError: false,
+    });
+}
+
+exports.createHostPathIdentityContext = createHostPathIdentityContext;
+//# sourceMappingURL=createHostPathIdentityContext.js.map

package/lib/core/transform/filesystem/createHostPathIdentityContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHostPathIdentityContext.js","sources":["../../../../src/core/transform/filesystem/createHostPathIdentityContext.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","createFilesystemPathIdentityContext"],"mappings":";;;;;AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,6BAA6B,CAC3C,UAAA,GAAgDA,2DAA6B,EAAA;AAE7E,IAAA,OAAOC,gDAAmC,CAAC;QACzC,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,OAAO,EAAE,CAAC,SAAS,KACjB,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC;QAC1D,QAAQ,EAAE,UAAU,CAAC,QAAQ;AAC7B,QAAA,oBAAoB,EAAE,KAAK;AAC5B,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/filesystem/createHostPathIdentityContext.mjs

@@ -0,0 +1,44 @@
+import { createFilesystemPathIdentityContext } from 'ttsc/path-identity';
+import { DEFAULT_FILESYSTEM_OPERATIONS } from './DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+
+/**
+ * Create the path-identity resolver for one filesystem view.
+ *
+ * Identity decides when two spellings name one file: case folding on
+ * case-insensitive volumes, and physical targets behind links. It must be
+ * answered by the same operations that capture and validate a generation, so
+ * the resolver is built from them. Failed realpath observations try the nearest
+ * resolvable ancestor and preserve uncertain missing suffix spelling. If no
+ * ancestor can be resolved, lexical spelling is retained instead of throwing.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity resolution uses the same lstat, listings, realpath, platform, and directory-case view as generation capture and validation, keeping equivalence within one observed filesystem.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter supplies the shared resolver's existing capability interface rather than implementing another realpath or case-folding algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed realpath retains the unresolved suffix under an observed ancestor, or lexical spelling when no ancestor resolves, rather than fabricating an existing target; no foreign filesystem methods are replaced.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains filesystem-view consistency and conservative failure semantics before the operation table wiring.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral identity follows actual directory case capability and native aliases through the supplied view, without assuming all Windows directories insensitive or all POSIX volumes sensitive.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Creating the transaction allocates its three empty observation maps;
+ *   later resolution visits missing ancestors and case-probe listings. The
+ *   adapter maps one requested listing to names without an additional native read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned context memoizes path, realpath and case observations for
+ *   repeated questions within one filesystem transaction. Callers must create
+ *   a new context when later filesystem changes can invalidate those observations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Ownership of the context and its maps transfers to the caller. Retained
+ *   entries grow with queried paths and ancestors and have no internal eviction;
+ *   ending the caller's transaction releases them, without retained descriptors.
+ */
+function createHostPathIdentityContext(filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    return createFilesystemPathIdentityContext({
+        caseSensitive: filesystem.caseSensitive,
+        lstat: filesystem.lstat,
+        platform: filesystem.platform,
+        readdir: (directory) => filesystem.readdir(directory).map((entry) => entry.name),
+        realpath: filesystem.realpath,
+        throwOnRealpathError: false,
+    });
+}
+
+export { createHostPathIdentityContext };
+//# sourceMappingURL=createHostPathIdentityContext.mjs.map

package/lib/core/transform/filesystem/createHostPathIdentityContext.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHostPathIdentityContext.mjs","sources":["../../../../src/core/transform/filesystem/createHostPathIdentityContext.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,6BAA6B,CAC3C,UAAA,GAAgD,6BAA6B,EAAA;AAE7E,IAAA,OAAO,mCAAmC,CAAC;QACzC,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,OAAO,EAAE,CAAC,SAAS,KACjB,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC;QAC1D,QAAQ,EAAE,UAAU,CAAC,QAAQ;AAC7B,QAAA,oBAAoB,EAAE,KAAK;AAC5B,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/filesystem/normalizeHostInputName.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Fold ASCII letters for a directory watch's coarse name filter.
+ *
+ * Non-ASCII spelling is preserved so the consumer can recognize uncertainty.
+ * Case policy alone does not define native normalization or Windows short-name
+ * aliases; this value cannot prove that a different native spelling is absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Sensitive policy preserves spelling; insensitive policy folds only ASCII letters. Non-ASCII remains visible to consumers that withdraw uncertain lexical filters, while native stat owns existence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One explicit policy parameter controls entry normalization without rereading directory capability or resolving a whole path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The coarse filter does not substitute JavaScript Unicode folding or guessed short-name syntax for actual native equivalence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ASCII-only scope and why preserved non-ASCII spelling still requires an uncertainty decision.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller's measured case policy selects coarse ASCII folding; normalization and alternate native names remain separate capabilities that this helper cannot infer.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sensitive input returns directly; insensitive replacement scans the name
+ *   once with fixed one-character ASCII matches and output bounded by its length.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This stateless spelling projection does not coordinate request validity;
+ *   the watch-location owner stores its projected names for the subscription.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizeHostInputName(name: string, caseSensitive: boolean): string;

package/lib/core/transform/filesystem/normalizeHostInputName.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Fold ASCII letters for a directory watch's coarse name filter.
+ *
+ * Non-ASCII spelling is preserved so the consumer can recognize uncertainty.
+ * Case policy alone does not define native normalization or Windows short-name
+ * aliases; this value cannot prove that a different native spelling is absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Sensitive policy preserves spelling; insensitive policy folds only ASCII letters. Non-ASCII remains visible to consumers that withdraw uncertain lexical filters, while native stat owns existence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One explicit policy parameter controls entry normalization without rereading directory capability or resolving a whole path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The coarse filter does not substitute JavaScript Unicode folding or guessed short-name syntax for actual native equivalence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ASCII-only scope and why preserved non-ASCII spelling still requires an uncertainty decision.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller's measured case policy selects coarse ASCII folding; normalization and alternate native names remain separate capabilities that this helper cannot infer.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sensitive input returns directly; insensitive replacement scans the name
+ *   once with fixed one-character ASCII matches and output bounded by its length.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This stateless spelling projection does not coordinate request validity;
+ *   the watch-location owner stores its projected names for the subscription.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizeHostInputName(name: string, caseSensitive: boolean): string;

package/lib/core/transform/filesystem/normalizeHostInputName.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Fold ASCII letters for a directory watch's coarse name filter.
+ *
+ * Non-ASCII spelling is preserved so the consumer can recognize uncertainty.
+ * Case policy alone does not define native normalization or Windows short-name
+ * aliases; this value cannot prove that a different native spelling is absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Sensitive policy preserves spelling; insensitive policy folds only ASCII letters. Non-ASCII remains visible to consumers that withdraw uncertain lexical filters, while native stat owns existence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One explicit policy parameter controls entry normalization without rereading directory capability or resolving a whole path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The coarse filter does not substitute JavaScript Unicode folding or guessed short-name syntax for actual native equivalence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ASCII-only scope and why preserved non-ASCII spelling still requires an uncertainty decision.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller's measured case policy selects coarse ASCII folding; normalization and alternate native names remain separate capabilities that this helper cannot infer.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sensitive input returns directly; insensitive replacement scans the name
+ *   once with fixed one-character ASCII matches and output bounded by its length.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This stateless spelling projection does not coordinate request validity;
+ *   the watch-location owner stores its projected names for the subscription.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizeHostInputName(name: string, caseSensitive: boolean): string;

package/lib/core/transform/filesystem/normalizeHostInputName.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Fold ASCII letters for a directory watch's coarse name filter.
+ *
+ * Non-ASCII spelling is preserved so the consumer can recognize uncertainty.
+ * Case policy alone does not define native normalization or Windows short-name
+ * aliases; this value cannot prove that a different native spelling is absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Sensitive policy preserves spelling; insensitive policy folds only ASCII letters. Non-ASCII remains visible to consumers that withdraw uncertain lexical filters, while native stat owns existence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One explicit policy parameter controls entry normalization without rereading directory capability or resolving a whole path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The coarse filter does not substitute JavaScript Unicode folding or guessed short-name syntax for actual native equivalence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ASCII-only scope and why preserved non-ASCII spelling still requires an uncertainty decision.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller's measured case policy selects coarse ASCII folding; normalization and alternate native names remain separate capabilities that this helper cannot infer.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sensitive input returns directly; insensitive replacement scans the name
+ *   once with fixed one-character ASCII matches and output bounded by its length.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This stateless spelling projection does not coordinate request validity;
+ *   the watch-location owner stores its projected names for the subscription.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function normalizeHostInputName(name, caseSensitive) {
+    return caseSensitive
+        ? name
+        : name.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
+
+exports.normalizeHostInputName = normalizeHostInputName;
+//# sourceMappingURL=normalizeHostInputName.js.map

package/lib/core/transform/filesystem/normalizeHostInputName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeHostInputName.js","sources":["../../../../src/core/transform/filesystem/normalizeHostInputName.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,sBAAsB,CACpC,IAAY,EACZ,aAAsB,EAAA;AAEtB,IAAA,OAAO;AACL,UAAE;AACF,UAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC;AAC9D;;;;"}

package/lib/core/transform/filesystem/normalizeHostInputName.mjs

@@ -0,0 +1,29 @@
+/**
+ * Fold ASCII letters for a directory watch's coarse name filter.
+ *
+ * Non-ASCII spelling is preserved so the consumer can recognize uncertainty.
+ * Case policy alone does not define native normalization or Windows short-name
+ * aliases; this value cannot prove that a different native spelling is absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Sensitive policy preserves spelling; insensitive policy folds only ASCII letters. Non-ASCII remains visible to consumers that withdraw uncertain lexical filters, while native stat owns existence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One explicit policy parameter controls entry normalization without rereading directory capability or resolving a whole path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The coarse filter does not substitute JavaScript Unicode folding or guessed short-name syntax for actual native equivalence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ASCII-only scope and why preserved non-ASCII spelling still requires an uncertainty decision.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller's measured case policy selects coarse ASCII folding; normalization and alternate native names remain separate capabilities that this helper cannot infer.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sensitive input returns directly; insensitive replacement scans the name
+ *   once with fixed one-character ASCII matches and output bounded by its length.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This stateless spelling projection does not coordinate request validity;
+ *   the watch-location owner stores its projected names for the subscription.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function normalizeHostInputName(name, caseSensitive) {
+    return caseSensitive
+        ? name
+        : name.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
+
+export { normalizeHostInputName };
+//# sourceMappingURL=normalizeHostInputName.mjs.map

package/lib/core/transform/filesystem/normalizeHostInputName.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeHostInputName.mjs","sources":["../../../../src/core/transform/filesystem/normalizeHostInputName.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,sBAAsB,CACpC,IAAY,EACZ,aAAsB,EAAA;AAEtB,IAAA,OAAO;AACL,UAAE;AACF,UAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC;AAC9D;;;;"}

package/lib/core/transform/filesystem/normalizePath.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Convert Windows separators to forward slashes.
+ *
+ * Project keys, alias targets, and generated tsconfig paths all use one
+ * separator spelling. This conversion does not establish filesystem identity or
+ * make paths from different native filesystems equivalent.
+ *
+ * @evidence contracts/common.md#principled-implementation The helper converts path separators into the forward-slash representation consumed by project keys and generated compiler paths, without changing case or resolving identity.
+ * @evidence contracts/common.md#clear-and-simple-design One separator conversion owns protocol spelling while native path resolution and physical equivalence remain separate operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Separator normalization does not pretend to prove containment, physical identity, or compiler-input freshness.
+ * @evidence contracts/common.md#meaningful-documentation The native comment names the normalized representation's consumers and distinguishes it from filesystem identity.
+ * @evidence contracts/portability.md#os-neutral-implementation The slash conversion serves project keys, alias targets and compiler configuration values; a spelling handed to a filesystem or a bundler is never rewritten, and identity comes from the filesystem identity context.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One fixed replacement scans the supplied path spelling in linear time
+ *   and creates at most a same-length result; it performs no filesystem walk.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizePath(file: string): string;

package/lib/core/transform/filesystem/normalizePath.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Convert Windows separators to forward slashes.
+ *
+ * Project keys, alias targets, and generated tsconfig paths all use one
+ * separator spelling. This conversion does not establish filesystem identity or
+ * make paths from different native filesystems equivalent.
+ *
+ * @evidence contracts/common.md#principled-implementation The helper converts path separators into the forward-slash representation consumed by project keys and generated compiler paths, without changing case or resolving identity.
+ * @evidence contracts/common.md#clear-and-simple-design One separator conversion owns protocol spelling while native path resolution and physical equivalence remain separate operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Separator normalization does not pretend to prove containment, physical identity, or compiler-input freshness.
+ * @evidence contracts/common.md#meaningful-documentation The native comment names the normalized representation's consumers and distinguishes it from filesystem identity.
+ * @evidence contracts/portability.md#os-neutral-implementation The slash conversion serves project keys, alias targets and compiler configuration values; a spelling handed to a filesystem or a bundler is never rewritten, and identity comes from the filesystem identity context.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One fixed replacement scans the supplied path spelling in linear time
+ *   and creates at most a same-length result; it performs no filesystem walk.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizePath(file: string): string;