@ttsc/unplugin 0.30.4 → 0.31.1

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

@@ -0,0 +1,222 @@
+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 through the native
+     * Linux helper, the native Windows completion-port helper, or the macOS
+     * FSEvents broker. 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 bypasses these native owners. Wrapping Node's `fs.watch`
+     * reintroduces Windows access-only notifications that invalidate unchanged
+     * inputs, and the native abort its fs-event backend can raise when a watched
+     * temporary tree is deleted. It also gives up explicit notification-loss
+     * reporting from the Linux helper and macOS's per-watch FSEventStream.
+     * Preserve mutation and loss reporting when implementing this capability;
+     * timestamps or identical current bytes cannot discard an actual A-B-A
+     * event.
+     *
+     * @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 default owners, failed watches, explicit override authority, access-only noise, native aborts and mutation/loss reporting that a direct fs.watch wrapper cannot supply.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral watching requires the observed filesystem's capability and accounts for native Windows mutation filtering and Linux/macOS loss 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/TtscTransformFilesystemOperations.d.ts

@@ -0,0 +1,222 @@
+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 through the native
+     * Linux helper, the native Windows completion-port helper, or the macOS
+     * FSEvents broker. 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 bypasses these native owners. Wrapping Node's `fs.watch`
+     * reintroduces Windows access-only notifications that invalidate unchanged
+     * inputs, and the native abort its fs-event backend can raise when a watched
+     * temporary tree is deleted. It also gives up explicit notification-loss
+     * reporting from the Linux helper and macOS's per-watch FSEventStream.
+     * Preserve mutation and loss reporting when implementing this capability;
+     * timestamps or identical current bytes cannot discard an actual A-B-A
+     * event.
+     *
+     * @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 default owners, failed watches, explicit override authority, access-only noise, native aborts and mutation/loss reporting that a direct fs.watch wrapper cannot supply.
+     * @evidence contracts/portability.md#os-neutral-implementation OS-neutral watching requires the observed filesystem's capability and accounts for native Windows mutation filtering and Linux/macOS loss 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;;;;"}