@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/transform/inputs/graphInputObservationFailures.js

@@ -0,0 +1,75 @@
+'use strict';
+
+var compilerAccessibleEntries = require('./compilerAccessibleEntries.js');
+var compilerInputRealpathObservation = require('./compilerInputRealpathObservation.js');
+var compilerStatKind = require('./compilerStatKind.js');
+var graphInputReadHash = require('./graphInputReadHash.js');
+var nativeInputPredicateMatches = require('./nativeInputPredicateMatches.js');
+var sameHostInputRealpath = require('./sameHostInputRealpath.js');
+
+/**
+ * Replay the predicates recorded for one compiler-input spelling and collect
+ * every mismatch. Only recorded predicates are observed; one following stat is
+ * shared by kind, existence and read checks. Directory listings preserve sorted
+ * compiler entry names, while realpaths compare through filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Each present predicate compares its recorded result with compiler-compatible replay, preserving read failure, native kind, listing order and realpath identity as separate observations.
+ * @evidence contracts/common.md#clear-and-simple-design The collector owns mismatch names and delegates stat, text normalization and physical equivalence to their single-purpose observers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unrecorded predicates are not invented, and read or resolution failure is compared against recorded failure instead of replaced by a convenient cache match.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states full collection, absent-predicate behavior and shared observations, with separated acknowledgment tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay uses the supplied filesystem and identity context; accessible-entry joining selects that view's path dialect and realpath equality follows actual case capabilities.
+ * @evidence contracts/performance.md#efficient-algorithms One kind stat serves existence, kind and read checks; native listing/link/identity operations retain their path costs. Selected listings encode name bytes, sort E names by compared UTF-8 prefixes and serialize current/recorded names for equality; text decoding/hashing scans B read bytes. Temporary storage follows listing names/encodings/serialized text, read buffers and supplied identity observations; the returned failure list has the six compiler predicate names plus one name per supplied native predicate. Absent listing/read predicates perform neither operation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This collects one current replay; the generation owner decides whether an earlier replay remains valid across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Entry arrays and failure names are observation-local, with no persistent cache, descriptor or running task owned by the collector.
+ */
+function graphInputObservationFailures(file, observation, filesystem, identities) {
+    const failures = [];
+    for (const predicate of observation.nativePredicates ?? []) {
+        if (!nativeInputPredicateMatches.nativeInputPredicateMatches(file, predicate, filesystem, identities)) {
+            failures.push(`native-${predicate.kind}-changed`);
+        }
+    }
+    if (observation.accessibleEntries !== undefined) {
+        const current = compilerAccessibleEntries.compilerAccessibleEntries(file, filesystem);
+        if (JSON.stringify(current) !== JSON.stringify(observation.accessibleEntries)) {
+            failures.push("accessible-entries-changed");
+        }
+    }
+    const kind = observation.fileExists !== undefined ||
+        observation.directoryExists !== undefined ||
+        observation.stat !== undefined ||
+        observation.readFile !== undefined
+        ? compilerStatKind.compilerStatKind(file, filesystem)
+        : undefined;
+    if (observation.fileExists !== undefined &&
+        (kind === "file") !== observation.fileExists) {
+        failures.push("file-exists-changed");
+    }
+    if (observation.directoryExists !== undefined &&
+        (kind === "directory") !== observation.directoryExists) {
+        failures.push("directory-exists-changed");
+    }
+    if (observation.stat !== undefined && kind !== observation.stat) {
+        failures.push("stat-changed");
+    }
+    if (observation.readFile !== undefined) {
+        const currentHash = graphInputReadHash.graphInputReadHash(file, filesystem, kind);
+        if ((observation.readFile.ok && currentHash !== observation.readFile.hash) ||
+            (!observation.readFile.ok && currentHash !== null)) {
+            failures.push("read-file-changed");
+        }
+    }
+    if (observation.realpath !== undefined) {
+        const currentRealpath = compilerInputRealpathObservation.compilerInputRealpathObservation(file, filesystem);
+        if (observation.realpath.ok !== currentRealpath.ok ||
+            (observation.realpath.ok &&
+                currentRealpath.ok &&
+                !sameHostInputRealpath.sameHostInputRealpath(observation.realpath.path, currentRealpath.path, identities))) {
+            failures.push("realpath-changed");
+        }
+    }
+    return failures;
+}
+
+exports.graphInputObservationFailures = graphInputObservationFailures;
+//# sourceMappingURL=graphInputObservationFailures.js.map

package/lib/core/transform/inputs/graphInputObservationFailures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputObservationFailures.js","sources":["../../../../src/core/transform/inputs/graphInputObservationFailures.ts"],"sourcesContent":[null],"names":["nativeInputPredicateMatches","compilerAccessibleEntries","compilerStatKind","graphInputReadHash","compilerInputRealpathObservation","sameHostInputRealpath"],"mappings":";;;;;;;;;AAWA;;;;;;;;;;;;;;AAcG;AACG,SAAU,6BAA6B,CAC3C,IAAY,EACZ,WAA0D,EAC1D,UAA6C,EAC7C,UAAyC,EAAA;IAEzC,MAAM,QAAQ,GAAa,EAAE;IAC7B,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,gBAAgB,IAAI,EAAE,EAAE;AAC1D,QAAA,IAAI,CAACA,uDAA2B,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE;YACzE,QAAQ,CAAC,IAAI,CAAC,CAAA,OAAA,EAAU,SAAS,CAAC,IAAI,CAAA,QAAA,CAAU,CAAC;QACnD;IACF;AACA,IAAA,IAAI,WAAW,CAAC,iBAAiB,KAAK,SAAS,EAAE;QAC/C,MAAM,OAAO,GAAGC,mDAAyB,CAAC,IAAI,EAAE,UAAU,CAAC;AAC3D,QAAA,IACE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,iBAAiB,CAAC,EACzE;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC;QAC7C;IACF;AACA,IAAA,MAAM,IAAI,GACR,WAAW,CAAC,UAAU,KAAK,SAAS;QACpC,WAAW,CAAC,eAAe,KAAK,SAAS;QACzC,WAAW,CAAC,IAAI,KAAK,SAAS;QAC9B,WAAW,CAAC,QAAQ,KAAK;AACvB,UAAEC,iCAAgB,CAAC,IAAI,EAAE,UAAU;UACjC,SAAS;AACf,IAAA,IACE,WAAW,CAAC,UAAU,KAAK,SAAS;QACpC,CAAC,IAAI,KAAK,MAAM,MAAM,WAAW,CAAC,UAAU,EAC5C;AACA,QAAA,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC;IACtC;AACA,IAAA,IACE,WAAW,CAAC,eAAe,KAAK,SAAS;QACzC,CAAC,IAAI,KAAK,WAAW,MAAM,WAAW,CAAC,eAAe,EACtD;AACA,QAAA,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC;IAC3C;AACA,IAAA,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE;AAC/D,QAAA,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC;IAC/B;AACA,IAAA,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE;QACtC,MAAM,WAAW,GAAGC,qCAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC;AAC9D,QAAA,IACE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,IAAI,WAAW,KAAK,WAAW,CAAC,QAAQ,CAAC,IAAI;AACrE,aAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,IAAI,WAAW,KAAK,IAAI,CAAC,EAClD;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC;QACpC;IACF;AACA,IAAA,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE;QACtC,MAAM,eAAe,GAAGC,iEAAgC,CAAC,IAAI,EAAE,UAAU,CAAC;QAC1E,IACE,WAAW,CAAC,QAAQ,CAAC,EAAE,KAAK,eAAe,CAAC,EAAE;AAC9C,aAAC,WAAW,CAAC,QAAQ,CAAC,EAAE;AACtB,gBAAA,eAAe,CAAC,EAAE;AAClB,gBAAA,CAACC,2CAAqB,CACpB,WAAW,CAAC,QAAQ,CAAC,IAAI,EACzB,eAAe,CAAC,IAAI,EACpB,UAAU,CACX,CAAC,EACJ;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC;QACnC;IACF;AACA,IAAA,OAAO,QAAQ;AACjB;;;;"}

package/lib/core/transform/inputs/graphInputObservationFailures.mjs

@@ -0,0 +1,73 @@
+import { compilerAccessibleEntries } from './compilerAccessibleEntries.mjs';
+import { compilerInputRealpathObservation } from './compilerInputRealpathObservation.mjs';
+import { compilerStatKind } from './compilerStatKind.mjs';
+import { graphInputReadHash } from './graphInputReadHash.mjs';
+import { nativeInputPredicateMatches } from './nativeInputPredicateMatches.mjs';
+import { sameHostInputRealpath } from './sameHostInputRealpath.mjs';
+
+/**
+ * Replay the predicates recorded for one compiler-input spelling and collect
+ * every mismatch. Only recorded predicates are observed; one following stat is
+ * shared by kind, existence and read checks. Directory listings preserve sorted
+ * compiler entry names, while realpaths compare through filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Each present predicate compares its recorded result with compiler-compatible replay, preserving read failure, native kind, listing order and realpath identity as separate observations.
+ * @evidence contracts/common.md#clear-and-simple-design The collector owns mismatch names and delegates stat, text normalization and physical equivalence to their single-purpose observers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unrecorded predicates are not invented, and read or resolution failure is compared against recorded failure instead of replaced by a convenient cache match.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states full collection, absent-predicate behavior and shared observations, with separated acknowledgment tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay uses the supplied filesystem and identity context; accessible-entry joining selects that view's path dialect and realpath equality follows actual case capabilities.
+ * @evidence contracts/performance.md#efficient-algorithms One kind stat serves existence, kind and read checks; native listing/link/identity operations retain their path costs. Selected listings encode name bytes, sort E names by compared UTF-8 prefixes and serialize current/recorded names for equality; text decoding/hashing scans B read bytes. Temporary storage follows listing names/encodings/serialized text, read buffers and supplied identity observations; the returned failure list has the six compiler predicate names plus one name per supplied native predicate. Absent listing/read predicates perform neither operation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This collects one current replay; the generation owner decides whether an earlier replay remains valid across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Entry arrays and failure names are observation-local, with no persistent cache, descriptor or running task owned by the collector.
+ */
+function graphInputObservationFailures(file, observation, filesystem, identities) {
+    const failures = [];
+    for (const predicate of observation.nativePredicates ?? []) {
+        if (!nativeInputPredicateMatches(file, predicate, filesystem, identities)) {
+            failures.push(`native-${predicate.kind}-changed`);
+        }
+    }
+    if (observation.accessibleEntries !== undefined) {
+        const current = compilerAccessibleEntries(file, filesystem);
+        if (JSON.stringify(current) !== JSON.stringify(observation.accessibleEntries)) {
+            failures.push("accessible-entries-changed");
+        }
+    }
+    const kind = observation.fileExists !== undefined ||
+        observation.directoryExists !== undefined ||
+        observation.stat !== undefined ||
+        observation.readFile !== undefined
+        ? compilerStatKind(file, filesystem)
+        : undefined;
+    if (observation.fileExists !== undefined &&
+        (kind === "file") !== observation.fileExists) {
+        failures.push("file-exists-changed");
+    }
+    if (observation.directoryExists !== undefined &&
+        (kind === "directory") !== observation.directoryExists) {
+        failures.push("directory-exists-changed");
+    }
+    if (observation.stat !== undefined && kind !== observation.stat) {
+        failures.push("stat-changed");
+    }
+    if (observation.readFile !== undefined) {
+        const currentHash = graphInputReadHash(file, filesystem, kind);
+        if ((observation.readFile.ok && currentHash !== observation.readFile.hash) ||
+            (!observation.readFile.ok && currentHash !== null)) {
+            failures.push("read-file-changed");
+        }
+    }
+    if (observation.realpath !== undefined) {
+        const currentRealpath = compilerInputRealpathObservation(file, filesystem);
+        if (observation.realpath.ok !== currentRealpath.ok ||
+            (observation.realpath.ok &&
+                currentRealpath.ok &&
+                !sameHostInputRealpath(observation.realpath.path, currentRealpath.path, identities))) {
+            failures.push("realpath-changed");
+        }
+    }
+    return failures;
+}
+
+export { graphInputObservationFailures };
+//# sourceMappingURL=graphInputObservationFailures.mjs.map

package/lib/core/transform/inputs/graphInputObservationFailures.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputObservationFailures.mjs","sources":["../../../../src/core/transform/inputs/graphInputObservationFailures.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAWA;;;;;;;;;;;;;;AAcG;AACG,SAAU,6BAA6B,CAC3C,IAAY,EACZ,WAA0D,EAC1D,UAA6C,EAC7C,UAAyC,EAAA;IAEzC,MAAM,QAAQ,GAAa,EAAE;IAC7B,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,gBAAgB,IAAI,EAAE,EAAE;AAC1D,QAAA,IAAI,CAAC,2BAA2B,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE;YACzE,QAAQ,CAAC,IAAI,CAAC,CAAA,OAAA,EAAU,SAAS,CAAC,IAAI,CAAA,QAAA,CAAU,CAAC;QACnD;IACF;AACA,IAAA,IAAI,WAAW,CAAC,iBAAiB,KAAK,SAAS,EAAE;QAC/C,MAAM,OAAO,GAAG,yBAAyB,CAAC,IAAI,EAAE,UAAU,CAAC;AAC3D,QAAA,IACE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,iBAAiB,CAAC,EACzE;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC;QAC7C;IACF;AACA,IAAA,MAAM,IAAI,GACR,WAAW,CAAC,UAAU,KAAK,SAAS;QACpC,WAAW,CAAC,eAAe,KAAK,SAAS;QACzC,WAAW,CAAC,IAAI,KAAK,SAAS;QAC9B,WAAW,CAAC,QAAQ,KAAK;AACvB,UAAE,gBAAgB,CAAC,IAAI,EAAE,UAAU;UACjC,SAAS;AACf,IAAA,IACE,WAAW,CAAC,UAAU,KAAK,SAAS;QACpC,CAAC,IAAI,KAAK,MAAM,MAAM,WAAW,CAAC,UAAU,EAC5C;AACA,QAAA,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC;IACtC;AACA,IAAA,IACE,WAAW,CAAC,eAAe,KAAK,SAAS;QACzC,CAAC,IAAI,KAAK,WAAW,MAAM,WAAW,CAAC,eAAe,EACtD;AACA,QAAA,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC;IAC3C;AACA,IAAA,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE;AAC/D,QAAA,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC;IAC/B;AACA,IAAA,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE;QACtC,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC;AAC9D,QAAA,IACE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,IAAI,WAAW,KAAK,WAAW,CAAC,QAAQ,CAAC,IAAI;AACrE,aAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,IAAI,WAAW,KAAK,IAAI,CAAC,EAClD;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC;QACpC;IACF;AACA,IAAA,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE;QACtC,MAAM,eAAe,GAAG,gCAAgC,CAAC,IAAI,EAAE,UAAU,CAAC;QAC1E,IACE,WAAW,CAAC,QAAQ,CAAC,EAAE,KAAK,eAAe,CAAC,EAAE;AAC9C,aAAC,WAAW,CAAC,QAAQ,CAAC,EAAE;AACtB,gBAAA,eAAe,CAAC,EAAE;AAClB,gBAAA,CAAC,qBAAqB,CACpB,WAAW,CAAC,QAAQ,CAAC,IAAI,EACzB,eAAe,CAAC,IAAI,EACpB,UAAU,CACX,CAAC,EACJ;AACA,YAAA,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC;QACnC;IACF;AACA,IAAA,OAAO,QAAQ;AACjB;;;;"}

package/lib/core/transform/inputs/graphInputReadHash.d.cts

@@ -0,0 +1,17 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+export declare function graphInputReadHash(file: string, filesystem?: TtscTransformFilesystemOperations, observedKind?: "directory" | "file" | "missing"): string | null;

package/lib/core/transform/inputs/graphInputReadHash.d.mts

@@ -0,0 +1,17 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+export declare function graphInputReadHash(file: string, filesystem?: TtscTransformFilesystemOperations, observedKind?: "directory" | "file" | "missing"): string | null;

package/lib/core/transform/inputs/graphInputReadHash.d.ts

@@ -0,0 +1,17 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+export declare function graphInputReadHash(file: string, filesystem?: TtscTransformFilesystemOperations, observedKind?: "directory" | "file" | "missing"): string | null;

package/lib/core/transform/inputs/graphInputReadHash.js

@@ -0,0 +1,35 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var compilerInputTextHash = require('./compilerInputTextHash.js');
+var compilerStatKind = require('./compilerStatKind.js');
+
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+function graphInputReadHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS, observedKind) {
+    const kind = observedKind ?? compilerStatKind.compilerStatKind(file, filesystem);
+    try {
+        if (kind === "directory")
+            return null;
+        return compilerInputTextHash.compilerInputTextHash(filesystem.readFile(file));
+    }
+    catch {
+        return null;
+    }
+}
+
+exports.graphInputReadHash = graphInputReadHash;
+//# sourceMappingURL=graphInputReadHash.js.map

package/lib/core/transform/inputs/graphInputReadHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputReadHash.js","sources":["../../../../src/core/transform/inputs/graphInputReadHash.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","compilerStatKind","compilerInputTextHash"],"mappings":";;;;;;AAKA;;;;;;;;;;;;;;AAcG;AACG,SAAU,kBAAkB,CAChC,IAAY,EACZ,UAAA,GAAgDA,2DAA6B,EAC7E,YAA+C,EAAA;IAE/C,MAAM,IAAI,GAAG,YAAY,IAAIC,iCAAgB,CAAC,IAAI,EAAE,UAAU,CAAC;AAC/D,IAAA,IAAI;QACF,IAAI,IAAI,KAAK,WAAW;AAAE,YAAA,OAAO,IAAI;QACrC,OAAOC,2CAAqB,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;;;;"}

package/lib/core/transform/inputs/graphInputReadHash.mjs

@@ -0,0 +1,33 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { compilerInputTextHash } from './compilerInputTextHash.mjs';
+import { compilerStatKind } from './compilerStatKind.mjs';
+
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+function graphInputReadHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS, observedKind) {
+    const kind = observedKind ?? compilerStatKind(file, filesystem);
+    try {
+        if (kind === "directory")
+            return null;
+        return compilerInputTextHash(filesystem.readFile(file));
+    }
+    catch {
+        return null;
+    }
+}
+
+export { graphInputReadHash };
+//# sourceMappingURL=graphInputReadHash.mjs.map

package/lib/core/transform/inputs/graphInputReadHash.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputReadHash.mjs","sources":["../../../../src/core/transform/inputs/graphInputReadHash.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;;;;;;;AAcG;AACG,SAAU,kBAAkB,CAChC,IAAY,EACZ,UAAA,GAAgD,6BAA6B,EAC7E,YAA+C,EAAA;IAE/C,MAAM,IAAI,GAAG,YAAY,IAAI,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC;AAC/D,IAAA,IAAI;QACF,IAAI,IAAI,KAAK,WAAW;AAAE,YAAA,OAAO,IAAI;QACrC,OAAO,qBAAqB,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;;;;"}

package/lib/core/transform/inputs/graphInputStateHash.d.cts

@@ -0,0 +1,16 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+export declare function graphInputStateHash(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/graphInputStateHash.d.mts

@@ -0,0 +1,16 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+export declare function graphInputStateHash(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/graphInputStateHash.d.ts

@@ -0,0 +1,16 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+export declare function graphInputStateHash(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/graphInputStateHash.js

@@ -0,0 +1,31 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var hashText = require('../utils/hashText.js');
+var compilerStatKind = require('./compilerStatKind.js');
+var graphInputReadHash = require('./graphInputReadHash.js');
+
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+function graphInputStateHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    const kind = compilerStatKind.compilerStatKind(file, filesystem);
+    const readHash = graphInputReadHash.graphInputReadHash(file, filesystem, kind);
+    if (readHash !== null)
+        return readHash;
+    return kind === "directory" ? hashText.hashText("ttsc:host-input:directory\0") : null;
+}
+
+exports.graphInputStateHash = graphInputStateHash;
+//# sourceMappingURL=graphInputStateHash.js.map

package/lib/core/transform/inputs/graphInputStateHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputStateHash.js","sources":["../../../../src/core/transform/inputs/graphInputStateHash.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","compilerStatKind","graphInputReadHash","hashText"],"mappings":";;;;;;;AAMA;;;;;;;;;;;;;AAaG;SACa,mBAAmB,CACjC,IAAY,EACZ,aAAgDA,2DAA6B,EAAA;IAE7E,MAAM,IAAI,GAAGC,iCAAgB,CAAC,IAAI,EAAE,UAAU,CAAC;IAC/C,MAAM,QAAQ,GAAGC,qCAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC;IAC3D,IAAI,QAAQ,KAAK,IAAI;AAAE,QAAA,OAAO,QAAQ;AACtC,IAAA,OAAO,IAAI,KAAK,WAAW,GAAGC,iBAAQ,CAAC,6BAA6B,CAAC,GAAG,IAAI;AAC9E;;;;"}

package/lib/core/transform/inputs/graphInputStateHash.mjs

@@ -0,0 +1,29 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { hashText } from '../utils/hashText.mjs';
+import { compilerStatKind } from './compilerStatKind.mjs';
+import { graphInputReadHash } from './graphInputReadHash.mjs';
+
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+function graphInputStateHash(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const kind = compilerStatKind(file, filesystem);
+    const readHash = graphInputReadHash(file, filesystem, kind);
+    if (readHash !== null)
+        return readHash;
+    return kind === "directory" ? hashText("ttsc:host-input:directory\0") : null;
+}
+
+export { graphInputStateHash };
+//# sourceMappingURL=graphInputStateHash.mjs.map

package/lib/core/transform/inputs/graphInputStateHash.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputStateHash.mjs","sources":["../../../../src/core/transform/inputs/graphInputStateHash.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAMA;;;;;;;;;;;;;AAaG;SACa,mBAAmB,CACjC,IAAY,EACZ,aAAgD,6BAA6B,EAAA;IAE7E,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC;IAC/C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC;IAC3D,IAAI,QAAQ,KAAK,IAAI;AAAE,QAAA,OAAO,QAAQ;AACtC,IAAA,OAAO,IAAI,KAAK,WAAW,GAAG,QAAQ,CAAC,6BAA6B,CAAC,GAAG,IAAI;AAC9E;;;;"}

package/lib/core/transform/inputs/hostInputRealpath.d.cts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+export declare function hostInputRealpath(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/hostInputRealpath.d.mts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+export declare function hostInputRealpath(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/hostInputRealpath.d.ts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+export declare function hostInputRealpath(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;

package/lib/core/transform/inputs/hostInputRealpath.js

@@ -0,0 +1,33 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+function hostInputRealpath(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        return filesystem.realpath(file);
+    }
+    catch {
+        return null;
+    }
+}
+
+exports.hostInputRealpath = hostInputRealpath;
+//# sourceMappingURL=hostInputRealpath.js.map

package/lib/core/transform/inputs/hostInputRealpath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostInputRealpath.js","sources":["../../../../src/core/transform/inputs/hostInputRealpath.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS"],"mappings":";;;;AAGA;;;;;;;;;;;;;;;;;AAiBG;SACa,iBAAiB,CAC/B,IAAY,EACZ,aAAgDA,2DAA6B,EAAA;AAE7E,IAAA,IAAI;AACF,QAAA,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;IAClC;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;;;;"}

package/lib/core/transform/inputs/hostInputRealpath.mjs

@@ -0,0 +1,31 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+function hostInputRealpath(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        return filesystem.realpath(file);
+    }
+    catch {
+        return null;
+    }
+}
+
+export { hostInputRealpath };
+//# sourceMappingURL=hostInputRealpath.mjs.map

package/lib/core/transform/inputs/hostInputRealpath.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostInputRealpath.mjs","sources":["../../../../src/core/transform/inputs/hostInputRealpath.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;AAiBG;SACa,iBAAiB,CAC/B,IAAY,EACZ,aAAgD,6BAA6B,EAAA;AAE7E,IAAA,IAAI;AACF,QAAA,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;IAClC;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;;;;"}

package/lib/core/transform/inputs/hostInputStateHash.d.cts

@@ -0,0 +1,16 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Hash host-input raw bytes. If reading fails, an observed directory receives
+ * the shared directory marker and any other state returns null. Unlike graph
+ * reads, successful host bytes retain their BOM and original encoding.
+ *
+ * @evidence contracts/common.md#principled-implementation Byte hashing preserves the host-input contract independently of compiler text normalization, with following stat used only to classify a failed read.
+ * @evidence contracts/common.md#clear-and-simple-design The read-first path and directory fallback produce one optional fingerprint without mixing graph decoding into host state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual bytes determine successful hashes; the directory marker is a contract-defined kind value and unreadable files do not gain guessed contents.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes raw bytes, graph normalization and null fallback, with a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral content comes from the supplied read capability with no line-ending or byte-order rewrite; following stat determines native directory fallback.
+ * @evidence contracts/performance.md#efficient-algorithms Successful reads require one O(B) byte hash and no stat; only failed reads request metadata, retaining a call-local Buffer proportional to file size.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each invocation observes current bytes; generation owners establish when a saved host hash can replace this read.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No cache, open descriptor or asynchronous task is retained by this synchronous fingerprint helper.
+ */
+export declare function hostInputStateHash(file: string, filesystem?: TtscTransformFilesystemOperations): string | null;