@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/envelope/graphInputObservationCompatible.d.cts

@@ -0,0 +1,23 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Whether normalized predicates can describe one stable filesystem state.
+ *
+ * Nonempty directory entries establish directory presence, but empty entries
+ * and failed reads establish neither presence nor absence. Unqueried predicates
+ * remain unknown; this check compares recorded results without probing the
+ * host.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful reads require file-compatible predicates, nonempty listings require directory-compatible predicates, and explicit stat kinds rule out conflicting existence results; unknown and failed-read values are not treated as absence.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit contradiction checks compare one normalized record without combining schema parsing, host observation or legacy encoding in the same predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed reads and empty listings retain their weaker meaning rather than gaining synthetic existence facts to make a proof acceptable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-input premise and the weaker meaning of failed reads, empty lists and unqueried operations; paragraph/tag separation follows the documentation skill.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded predicate results in memory; it probes no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   No loop or traversal of its own; constant work apart from delegated
+ *   calls.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function graphInputObservationCompatible(observation: ITtscCompilerTransformation.IInputObservation): boolean;

package/lib/core/transform/envelope/graphInputObservationCompatible.d.mts

@@ -0,0 +1,23 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Whether normalized predicates can describe one stable filesystem state.
+ *
+ * Nonempty directory entries establish directory presence, but empty entries
+ * and failed reads establish neither presence nor absence. Unqueried predicates
+ * remain unknown; this check compares recorded results without probing the
+ * host.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful reads require file-compatible predicates, nonempty listings require directory-compatible predicates, and explicit stat kinds rule out conflicting existence results; unknown and failed-read values are not treated as absence.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit contradiction checks compare one normalized record without combining schema parsing, host observation or legacy encoding in the same predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed reads and empty listings retain their weaker meaning rather than gaining synthetic existence facts to make a proof acceptable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-input premise and the weaker meaning of failed reads, empty lists and unqueried operations; paragraph/tag separation follows the documentation skill.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded predicate results in memory; it probes no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   No loop or traversal of its own; constant work apart from delegated
+ *   calls.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function graphInputObservationCompatible(observation: ITtscCompilerTransformation.IInputObservation): boolean;

package/lib/core/transform/envelope/graphInputObservationCompatible.d.ts

@@ -0,0 +1,23 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Whether normalized predicates can describe one stable filesystem state.
+ *
+ * Nonempty directory entries establish directory presence, but empty entries
+ * and failed reads establish neither presence nor absence. Unqueried predicates
+ * remain unknown; this check compares recorded results without probing the
+ * host.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful reads require file-compatible predicates, nonempty listings require directory-compatible predicates, and explicit stat kinds rule out conflicting existence results; unknown and failed-read values are not treated as absence.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit contradiction checks compare one normalized record without combining schema parsing, host observation or legacy encoding in the same predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed reads and empty listings retain their weaker meaning rather than gaining synthetic existence facts to make a proof acceptable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-input premise and the weaker meaning of failed reads, empty lists and unqueried operations; paragraph/tag separation follows the documentation skill.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded predicate results in memory; it probes no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   No loop or traversal of its own; constant work apart from delegated
+ *   calls.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function graphInputObservationCompatible(observation: ITtscCompilerTransformation.IInputObservation): boolean;

package/lib/core/transform/envelope/graphInputObservationCompatible.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Whether normalized predicates can describe one stable filesystem state.
+ *
+ * Nonempty directory entries establish directory presence, but empty entries
+ * and failed reads establish neither presence nor absence. Unqueried predicates
+ * remain unknown; this check compares recorded results without probing the
+ * host.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful reads require file-compatible predicates, nonempty listings require directory-compatible predicates, and explicit stat kinds rule out conflicting existence results; unknown and failed-read values are not treated as absence.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit contradiction checks compare one normalized record without combining schema parsing, host observation or legacy encoding in the same predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed reads and empty listings retain their weaker meaning rather than gaining synthetic existence facts to make a proof acceptable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-input premise and the weaker meaning of failed reads, empty lists and unqueried operations; paragraph/tag separation follows the documentation skill.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded predicate results in memory; it probes no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   No loop or traversal of its own; constant work apart from delegated
+ *   calls.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function graphInputObservationCompatible(observation) {
+    const { accessibleEntries, directoryExists, fileExists, readFile, stat } = observation;
+    const hasAccessibleEntries = accessibleEntries !== undefined &&
+        (accessibleEntries.directories.length !== 0 ||
+            accessibleEntries.files.length !== 0);
+    if (hasAccessibleEntries &&
+        (fileExists === true ||
+            directoryExists === false ||
+            (stat !== undefined && stat !== "directory") ||
+            readFile?.ok === true)) {
+        return false;
+    }
+    if (fileExists === true && directoryExists === true)
+        return false;
+    if (stat === "directory" &&
+        (fileExists === true || directoryExists === false)) {
+        return false;
+    }
+    if (stat === "file" && (fileExists === false || directoryExists === true)) {
+        return false;
+    }
+    if (stat === "missing" && (fileExists === true || directoryExists === true)) {
+        return false;
+    }
+    if (readFile?.ok === true &&
+        (fileExists === false ||
+            directoryExists === true ||
+            (stat !== undefined && stat !== "file"))) {
+        return false;
+    }
+    return true;
+}
+
+exports.graphInputObservationCompatible = graphInputObservationCompatible;
+//# sourceMappingURL=graphInputObservationCompatible.js.map

package/lib/core/transform/envelope/graphInputObservationCompatible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputObservationCompatible.js","sources":["../../../../src/core/transform/envelope/graphInputObservationCompatible.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,+BAA+B,CAC7C,WAA0D,EAAA;AAE1D,IAAA,MAAM,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,GACtE,WAAW;AACb,IAAA,MAAM,oBAAoB,GACxB,iBAAiB,KAAK,SAAS;AAC/B,SAAC,iBAAiB,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;AACzC,YAAA,iBAAiB,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;AACzC,IAAA,IACE,oBAAoB;SACnB,UAAU,KAAK,IAAI;AAClB,YAAA,eAAe,KAAK,KAAK;AACzB,aAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,CAAC;AAC5C,YAAA,QAAQ,EAAE,EAAE,KAAK,IAAI,CAAC,EACxB;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI;AAAE,QAAA,OAAO,KAAK;IACjE,IACE,IAAI,KAAK,WAAW;SACnB,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,KAAK,CAAC,EAClD;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,IAAI,KAAK,MAAM,KAAK,UAAU,KAAK,KAAK,IAAI,eAAe,KAAK,IAAI,CAAC,EAAE;AACzE,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,IAAI,KAAK,SAAS,KAAK,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI,CAAC,EAAE;AAC3E,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IACE,QAAQ,EAAE,EAAE,KAAK,IAAI;SACpB,UAAU,KAAK,KAAK;AACnB,YAAA,eAAe,KAAK,IAAI;aACvB,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,EAC1C;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,IAAI;AACb;;;;"}

package/lib/core/transform/envelope/graphInputObservationCompatible.mjs

@@ -0,0 +1,56 @@
+/**
+ * Whether normalized predicates can describe one stable filesystem state.
+ *
+ * Nonempty directory entries establish directory presence, but empty entries
+ * and failed reads establish neither presence nor absence. Unqueried predicates
+ * remain unknown; this check compares recorded results without probing the
+ * host.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful reads require file-compatible predicates, nonempty listings require directory-compatible predicates, and explicit stat kinds rule out conflicting existence results; unknown and failed-read values are not treated as absence.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit contradiction checks compare one normalized record without combining schema parsing, host observation or legacy encoding in the same predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed reads and empty listings retain their weaker meaning rather than gaining synthetic existence facts to make a proof acceptable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the normalized-input premise and the weaker meaning of failed reads, empty lists and unqueried operations; paragraph/tag separation follows the documentation skill.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded predicate results in memory; it probes no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   No loop or traversal of its own; constant work apart from delegated
+ *   calls.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function graphInputObservationCompatible(observation) {
+    const { accessibleEntries, directoryExists, fileExists, readFile, stat } = observation;
+    const hasAccessibleEntries = accessibleEntries !== undefined &&
+        (accessibleEntries.directories.length !== 0 ||
+            accessibleEntries.files.length !== 0);
+    if (hasAccessibleEntries &&
+        (fileExists === true ||
+            directoryExists === false ||
+            (stat !== undefined && stat !== "directory") ||
+            readFile?.ok === true)) {
+        return false;
+    }
+    if (fileExists === true && directoryExists === true)
+        return false;
+    if (stat === "directory" &&
+        (fileExists === true || directoryExists === false)) {
+        return false;
+    }
+    if (stat === "file" && (fileExists === false || directoryExists === true)) {
+        return false;
+    }
+    if (stat === "missing" && (fileExists === true || directoryExists === true)) {
+        return false;
+    }
+    if (readFile?.ok === true &&
+        (fileExists === false ||
+            directoryExists === true ||
+            (stat !== undefined && stat !== "file"))) {
+        return false;
+    }
+    return true;
+}
+
+export { graphInputObservationCompatible };
+//# sourceMappingURL=graphInputObservationCompatible.mjs.map

package/lib/core/transform/envelope/graphInputObservationCompatible.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphInputObservationCompatible.mjs","sources":["../../../../src/core/transform/envelope/graphInputObservationCompatible.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,+BAA+B,CAC7C,WAA0D,EAAA;AAE1D,IAAA,MAAM,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,GACtE,WAAW;AACb,IAAA,MAAM,oBAAoB,GACxB,iBAAiB,KAAK,SAAS;AAC/B,SAAC,iBAAiB,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;AACzC,YAAA,iBAAiB,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;AACzC,IAAA,IACE,oBAAoB;SACnB,UAAU,KAAK,IAAI;AAClB,YAAA,eAAe,KAAK,KAAK;AACzB,aAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,CAAC;AAC5C,YAAA,QAAQ,EAAE,EAAE,KAAK,IAAI,CAAC,EACxB;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI;AAAE,QAAA,OAAO,KAAK;IACjE,IACE,IAAI,KAAK,WAAW;SACnB,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,KAAK,CAAC,EAClD;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,IAAI,KAAK,MAAM,KAAK,UAAU,KAAK,KAAK,IAAI,eAAe,KAAK,IAAI,CAAC,EAAE;AACzE,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,IAAI,KAAK,SAAS,KAAK,UAAU,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI,CAAC,EAAE;AAC3E,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IACE,QAAQ,EAAE,EAAE,KAAK,IAAI;SACpB,UAAU,KAAK,KAAK;AACnB,YAAA,eAAe,KAAK,IAAI;aACvB,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,EAC1C;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,IAAI;AACb;;;;"}

package/lib/core/transform/envelope/hostSpelling.d.cts

@@ -0,0 +1,49 @@
+import type { TtscProjectSpellings } from "../filesystem/TtscProjectSpellings.cjs";
+/**
+ * How a host is handed the compiler's inputs for one delivery: spelled under
+ * the project as the host itself spelled the module it delivered.
+ *
+ * The compiler reports its inputs physically, after every link. A host names
+ * the project one of two ways, and says which by the module it hands over: one
+ * that resolves its modules through links, as webpack's resolver and Vite's do,
+ * delivers the physical path, and compares every dependency against physical
+ * paths of its own; one that keeps the path it was configured with, as
+ * Turbopack does, delivers that spelling, `/var/…` on macOS where the temporary
+ * directory links to `/private/var/…`, or a linked workspace anywhere, and
+ * refuses or duplicates a dependency spelled the other way. Handing the wrong
+ * spelling made Turbopack track no dependency at all and webpack watch every
+ * project directory twice. The adapter therefore speaks the spelling of the
+ * delivered module: an input below either spelling of the project root is
+ * returned under the one the module carries, and an input elsewhere keeps its
+ * own. A module under neither, which no host names by the project, takes the
+ * project's configured spelling. Containment uses native lexical path
+ * relations; physical identity was established when the roots were captured.
+ * The wrapper tsconfig written for the compiler takes the same function with
+ * the compiler's physical root as the delivered path, since the compiler is the
+ * other party the adapter spells paths for.
+ *
+ * @param project The project root as configured and as the filesystem resolves
+ *   it; equal where the root traverses no link, which makes the answer the
+ *   identity.
+ * @param delivered The module the host asked to transform, as it spelled it, or
+ *   the root the compiler spells.
+ * @returns The spelling function for this delivery's inputs.
+ * @evidence contracts/common.md#principled-implementation The delivered module selects which captured root spelling the host uses; rewriting only paths contained beneath the opposite root preserves project-relative suffixes and leaves external inputs unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Orientation is chosen once and a returned mapper applies that one native relative-path rule; the within helper shares the same containment predicate without consulting bundler-specific configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows two actual project root spellings and delivery context, not a named-consumer exception or patched resolver; paths outside the selected root are not coerced into the project.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/configured roots, delivery selection, external paths and compiler use, and parameter/return comments document the mapper's inputs with separated acknowledgments under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.relative, path.sep, path.isAbsolute and path.join handle native containment, parent escape and cross-volume paths; the function uses captured physical roots without hardcoding a platform's symlink or temporary-directory layout.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal roots return an identity mapper. Otherwise at most two lexical
+ *   comparisons choose orientation, then each mapped input uses one relative
+ *   path and optional join. Work scales with the involved path lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All inputs in one delivery reuse the chosen from/to orientation. The
+ *   supplied captured roots and delivered module establish that orientation;
+ *   a different delivery creates its own mapper rather than sharing stale choice.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned closure retains only its two root strings when mapping is
+ *   needed. The caller owns this fixed population until it releases the mapper;
+ *   no input history, filesystem descriptor or watcher is acquired.
+ */
+export declare function hostSpelling(project: TtscProjectSpellings, delivered: string): (input: string) => string;

package/lib/core/transform/envelope/hostSpelling.d.mts

@@ -0,0 +1,49 @@
+import type { TtscProjectSpellings } from "../filesystem/TtscProjectSpellings.mjs";
+/**
+ * How a host is handed the compiler's inputs for one delivery: spelled under
+ * the project as the host itself spelled the module it delivered.
+ *
+ * The compiler reports its inputs physically, after every link. A host names
+ * the project one of two ways, and says which by the module it hands over: one
+ * that resolves its modules through links, as webpack's resolver and Vite's do,
+ * delivers the physical path, and compares every dependency against physical
+ * paths of its own; one that keeps the path it was configured with, as
+ * Turbopack does, delivers that spelling, `/var/…` on macOS where the temporary
+ * directory links to `/private/var/…`, or a linked workspace anywhere, and
+ * refuses or duplicates a dependency spelled the other way. Handing the wrong
+ * spelling made Turbopack track no dependency at all and webpack watch every
+ * project directory twice. The adapter therefore speaks the spelling of the
+ * delivered module: an input below either spelling of the project root is
+ * returned under the one the module carries, and an input elsewhere keeps its
+ * own. A module under neither, which no host names by the project, takes the
+ * project's configured spelling. Containment uses native lexical path
+ * relations; physical identity was established when the roots were captured.
+ * The wrapper tsconfig written for the compiler takes the same function with
+ * the compiler's physical root as the delivered path, since the compiler is the
+ * other party the adapter spells paths for.
+ *
+ * @param project The project root as configured and as the filesystem resolves
+ *   it; equal where the root traverses no link, which makes the answer the
+ *   identity.
+ * @param delivered The module the host asked to transform, as it spelled it, or
+ *   the root the compiler spells.
+ * @returns The spelling function for this delivery's inputs.
+ * @evidence contracts/common.md#principled-implementation The delivered module selects which captured root spelling the host uses; rewriting only paths contained beneath the opposite root preserves project-relative suffixes and leaves external inputs unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Orientation is chosen once and a returned mapper applies that one native relative-path rule; the within helper shares the same containment predicate without consulting bundler-specific configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows two actual project root spellings and delivery context, not a named-consumer exception or patched resolver; paths outside the selected root are not coerced into the project.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/configured roots, delivery selection, external paths and compiler use, and parameter/return comments document the mapper's inputs with separated acknowledgments under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.relative, path.sep, path.isAbsolute and path.join handle native containment, parent escape and cross-volume paths; the function uses captured physical roots without hardcoding a platform's symlink or temporary-directory layout.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal roots return an identity mapper. Otherwise at most two lexical
+ *   comparisons choose orientation, then each mapped input uses one relative
+ *   path and optional join. Work scales with the involved path lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All inputs in one delivery reuse the chosen from/to orientation. The
+ *   supplied captured roots and delivered module establish that orientation;
+ *   a different delivery creates its own mapper rather than sharing stale choice.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned closure retains only its two root strings when mapping is
+ *   needed. The caller owns this fixed population until it releases the mapper;
+ *   no input history, filesystem descriptor or watcher is acquired.
+ */
+export declare function hostSpelling(project: TtscProjectSpellings, delivered: string): (input: string) => string;

package/lib/core/transform/envelope/hostSpelling.d.ts

@@ -0,0 +1,49 @@
+import type { TtscProjectSpellings } from "../filesystem/TtscProjectSpellings";
+/**
+ * How a host is handed the compiler's inputs for one delivery: spelled under
+ * the project as the host itself spelled the module it delivered.
+ *
+ * The compiler reports its inputs physically, after every link. A host names
+ * the project one of two ways, and says which by the module it hands over: one
+ * that resolves its modules through links, as webpack's resolver and Vite's do,
+ * delivers the physical path, and compares every dependency against physical
+ * paths of its own; one that keeps the path it was configured with, as
+ * Turbopack does, delivers that spelling, `/var/…` on macOS where the temporary
+ * directory links to `/private/var/…`, or a linked workspace anywhere, and
+ * refuses or duplicates a dependency spelled the other way. Handing the wrong
+ * spelling made Turbopack track no dependency at all and webpack watch every
+ * project directory twice. The adapter therefore speaks the spelling of the
+ * delivered module: an input below either spelling of the project root is
+ * returned under the one the module carries, and an input elsewhere keeps its
+ * own. A module under neither, which no host names by the project, takes the
+ * project's configured spelling. Containment uses native lexical path
+ * relations; physical identity was established when the roots were captured.
+ * The wrapper tsconfig written for the compiler takes the same function with
+ * the compiler's physical root as the delivered path, since the compiler is the
+ * other party the adapter spells paths for.
+ *
+ * @param project The project root as configured and as the filesystem resolves
+ *   it; equal where the root traverses no link, which makes the answer the
+ *   identity.
+ * @param delivered The module the host asked to transform, as it spelled it, or
+ *   the root the compiler spells.
+ * @returns The spelling function for this delivery's inputs.
+ * @evidence contracts/common.md#principled-implementation The delivered module selects which captured root spelling the host uses; rewriting only paths contained beneath the opposite root preserves project-relative suffixes and leaves external inputs unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Orientation is chosen once and a returned mapper applies that one native relative-path rule; the within helper shares the same containment predicate without consulting bundler-specific configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows two actual project root spellings and delivery context, not a named-consumer exception or patched resolver; paths outside the selected root are not coerced into the project.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/configured roots, delivery selection, external paths and compiler use, and parameter/return comments document the mapper's inputs with separated acknowledgments under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.relative, path.sep, path.isAbsolute and path.join handle native containment, parent escape and cross-volume paths; the function uses captured physical roots without hardcoding a platform's symlink or temporary-directory layout.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal roots return an identity mapper. Otherwise at most two lexical
+ *   comparisons choose orientation, then each mapped input uses one relative
+ *   path and optional join. Work scales with the involved path lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All inputs in one delivery reuse the chosen from/to orientation. The
+ *   supplied captured roots and delivered module establish that orientation;
+ *   a different delivery creates its own mapper rather than sharing stale choice.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned closure retains only its two root strings when mapping is
+ *   needed. The caller owns this fixed population until it releases the mapper;
+ *   no input history, filesystem descriptor or watcher is acquired.
+ */
+export declare function hostSpelling(project: TtscProjectSpellings, delivered: string): (input: string) => string;

package/lib/core/transform/envelope/hostSpelling.js

@@ -0,0 +1,81 @@
+'use strict';
+
+var path = require('node:path');
+
+/**
+ * How a host is handed the compiler's inputs for one delivery: spelled under
+ * the project as the host itself spelled the module it delivered.
+ *
+ * The compiler reports its inputs physically, after every link. A host names
+ * the project one of two ways, and says which by the module it hands over: one
+ * that resolves its modules through links, as webpack's resolver and Vite's do,
+ * delivers the physical path, and compares every dependency against physical
+ * paths of its own; one that keeps the path it was configured with, as
+ * Turbopack does, delivers that spelling, `/var/…` on macOS where the temporary
+ * directory links to `/private/var/…`, or a linked workspace anywhere, and
+ * refuses or duplicates a dependency spelled the other way. Handing the wrong
+ * spelling made Turbopack track no dependency at all and webpack watch every
+ * project directory twice. The adapter therefore speaks the spelling of the
+ * delivered module: an input below either spelling of the project root is
+ * returned under the one the module carries, and an input elsewhere keeps its
+ * own. A module under neither, which no host names by the project, takes the
+ * project's configured spelling. Containment uses native lexical path
+ * relations; physical identity was established when the roots were captured.
+ * The wrapper tsconfig written for the compiler takes the same function with
+ * the compiler's physical root as the delivered path, since the compiler is the
+ * other party the adapter spells paths for.
+ *
+ * @param project The project root as configured and as the filesystem resolves
+ *   it; equal where the root traverses no link, which makes the answer the
+ *   identity.
+ * @param delivered The module the host asked to transform, as it spelled it, or
+ *   the root the compiler spells.
+ * @returns The spelling function for this delivery's inputs.
+ * @evidence contracts/common.md#principled-implementation The delivered module selects which captured root spelling the host uses; rewriting only paths contained beneath the opposite root preserves project-relative suffixes and leaves external inputs unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Orientation is chosen once and a returned mapper applies that one native relative-path rule; the within helper shares the same containment predicate without consulting bundler-specific configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows two actual project root spellings and delivery context, not a named-consumer exception or patched resolver; paths outside the selected root are not coerced into the project.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/configured roots, delivery selection, external paths and compiler use, and parameter/return comments document the mapper's inputs with separated acknowledgments under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.relative, path.sep, path.isAbsolute and path.join handle native containment, parent escape and cross-volume paths; the function uses captured physical roots without hardcoding a platform's symlink or temporary-directory layout.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal roots return an identity mapper. Otherwise at most two lexical
+ *   comparisons choose orientation, then each mapped input uses one relative
+ *   path and optional join. Work scales with the involved path lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All inputs in one delivery reuse the chosen from/to orientation. The
+ *   supplied captured roots and delivered module establish that orientation;
+ *   a different delivery creates its own mapper rather than sharing stale choice.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned closure retains only its two root strings when mapping is
+ *   needed. The caller owns this fixed population until it releases the mapper;
+ *   no input history, filesystem descriptor or watcher is acquired.
+ */
+function hostSpelling(project, delivered) {
+    if (project.physical === project.spelling)
+        return (input) => input;
+    const host = !within(delivered, project.spelling) && within(delivered, project.physical)
+        ? { from: project.spelling, to: project.physical }
+        : { from: project.physical, to: project.spelling };
+    return (input) => {
+        const relative = path.relative(host.from, input);
+        return relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)
+            ? input
+            : path.join(host.to, relative);
+    };
+}
+/**
+ * Test native lexical containment, including the root itself.
+ *
+ * Parent-relative escapes and cross-volume absolute relatives are outside; this
+ * check does not resolve symlinks or establish physical file identity.
+ */
+function within(file, root) {
+    const relative = path.relative(root, file);
+    return (relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+
+exports.hostSpelling = hostSpelling;
+//# sourceMappingURL=hostSpelling.js.map

package/lib/core/transform/envelope/hostSpelling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSpelling.js","sources":["../../../../src/core/transform/envelope/hostSpelling.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CG;AACG,SAAU,YAAY,CAC1B,OAA6B,EAC7B,SAAiB,EAAA;AAEjB,IAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;AAAE,QAAA,OAAO,CAAC,KAAK,KAAK,KAAK;AAClE,IAAA,MAAM,IAAI,GACR,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ;AACxE,UAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ;AAChD,UAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE;IACtD,OAAO,CAAC,KAAK,KAAI;AACf,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAChD,OAAO,QAAQ,KAAK,IAAI;YACtB,QAAQ,CAAC,UAAU,CAAC,CAAA,EAAA,EAAK,IAAI,CAAC,GAAG,EAAE,CAAC;AACpC,YAAA,IAAI,CAAC,UAAU,CAAC,QAAQ;AACxB,cAAE;cACA,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC;AAClC,IAAA,CAAC;AACH;AAEA;;;;;AAKG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY,EAAA;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAC1C,QACE,QAAQ,KAAK,IAAI;QACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,CAAA,CAAE,CAAC;AACrC,QAAA,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;AAE9B;;;;"}

package/lib/core/transform/envelope/hostSpelling.mjs

@@ -0,0 +1,79 @@
+import path from 'node:path';
+
+/**
+ * How a host is handed the compiler's inputs for one delivery: spelled under
+ * the project as the host itself spelled the module it delivered.
+ *
+ * The compiler reports its inputs physically, after every link. A host names
+ * the project one of two ways, and says which by the module it hands over: one
+ * that resolves its modules through links, as webpack's resolver and Vite's do,
+ * delivers the physical path, and compares every dependency against physical
+ * paths of its own; one that keeps the path it was configured with, as
+ * Turbopack does, delivers that spelling, `/var/…` on macOS where the temporary
+ * directory links to `/private/var/…`, or a linked workspace anywhere, and
+ * refuses or duplicates a dependency spelled the other way. Handing the wrong
+ * spelling made Turbopack track no dependency at all and webpack watch every
+ * project directory twice. The adapter therefore speaks the spelling of the
+ * delivered module: an input below either spelling of the project root is
+ * returned under the one the module carries, and an input elsewhere keeps its
+ * own. A module under neither, which no host names by the project, takes the
+ * project's configured spelling. Containment uses native lexical path
+ * relations; physical identity was established when the roots were captured.
+ * The wrapper tsconfig written for the compiler takes the same function with
+ * the compiler's physical root as the delivered path, since the compiler is the
+ * other party the adapter spells paths for.
+ *
+ * @param project The project root as configured and as the filesystem resolves
+ *   it; equal where the root traverses no link, which makes the answer the
+ *   identity.
+ * @param delivered The module the host asked to transform, as it spelled it, or
+ *   the root the compiler spells.
+ * @returns The spelling function for this delivery's inputs.
+ * @evidence contracts/common.md#principled-implementation The delivered module selects which captured root spelling the host uses; rewriting only paths contained beneath the opposite root preserves project-relative suffixes and leaves external inputs unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Orientation is chosen once and a returned mapper applies that one native relative-path rule; the within helper shares the same containment predicate without consulting bundler-specific configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping follows two actual project root spellings and delivery context, not a named-consumer exception or patched resolver; paths outside the selected root are not coerced into the project.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain physical/configured roots, delivery selection, external paths and compiler use, and parameter/return comments document the mapper's inputs with separated acknowledgments under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.relative, path.sep, path.isAbsolute and path.join handle native containment, parent escape and cross-volume paths; the function uses captured physical roots without hardcoding a platform's symlink or temporary-directory layout.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal roots return an identity mapper. Otherwise at most two lexical
+ *   comparisons choose orientation, then each mapped input uses one relative
+ *   path and optional join. Work scales with the involved path lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All inputs in one delivery reuse the chosen from/to orientation. The
+ *   supplied captured roots and delivered module establish that orientation;
+ *   a different delivery creates its own mapper rather than sharing stale choice.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned closure retains only its two root strings when mapping is
+ *   needed. The caller owns this fixed population until it releases the mapper;
+ *   no input history, filesystem descriptor or watcher is acquired.
+ */
+function hostSpelling(project, delivered) {
+    if (project.physical === project.spelling)
+        return (input) => input;
+    const host = !within(delivered, project.spelling) && within(delivered, project.physical)
+        ? { from: project.spelling, to: project.physical }
+        : { from: project.physical, to: project.spelling };
+    return (input) => {
+        const relative = path.relative(host.from, input);
+        return relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)
+            ? input
+            : path.join(host.to, relative);
+    };
+}
+/**
+ * Test native lexical containment, including the root itself.
+ *
+ * Parent-relative escapes and cross-volume absolute relatives are outside; this
+ * check does not resolve symlinks or establish physical file identity.
+ */
+function within(file, root) {
+    const relative = path.relative(root, file);
+    return (relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+
+export { hostSpelling };
+//# sourceMappingURL=hostSpelling.mjs.map

package/lib/core/transform/envelope/hostSpelling.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSpelling.mjs","sources":["../../../../src/core/transform/envelope/hostSpelling.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CG;AACG,SAAU,YAAY,CAC1B,OAA6B,EAC7B,SAAiB,EAAA;AAEjB,IAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;AAAE,QAAA,OAAO,CAAC,KAAK,KAAK,KAAK;AAClE,IAAA,MAAM,IAAI,GACR,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ;AACxE,UAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ;AAChD,UAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE;IACtD,OAAO,CAAC,KAAK,KAAI;AACf,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAChD,OAAO,QAAQ,KAAK,IAAI;YACtB,QAAQ,CAAC,UAAU,CAAC,CAAA,EAAA,EAAK,IAAI,CAAC,GAAG,EAAE,CAAC;AACpC,YAAA,IAAI,CAAC,UAAU,CAAC,QAAQ;AACxB,cAAE;cACA,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC;AAClC,IAAA,CAAC;AACH;AAEA;;;;;AAKG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY,EAAA;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAC1C,QACE,QAAQ,KAAK,IAAI;QACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,CAAA,CAAE,CAAC;AACrC,QAAA,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;AAE9B;;;;"}

package/lib/core/transform/envelope/isVolatileFile.d.cts

@@ -0,0 +1,22 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+/**
+ * Report whether the plugin declared `file` volatile: its output depends on
+ * non-file inputs (environment, time, network), so neither the project
+ * transform cache nor a bundler's persistent cache may replay it. Reads the
+ * per-envelope identity set instead of rescanning the member list.
+ *
+ * @evidence contracts/common.md#principled-implementation Volatility is explicit producer membership by file identity, not an inference from output contents; an exception result supplies no declaration for this predicate.
+ * @evidence contracts/common.md#clear-and-simple-design The predicate reads the declaration while cache and bundler owners enforce their respective replay restrictions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported non-file dependencies are honestly represented by volatility rather than replaced by fixture hashes or a promise that file inputs prove them stable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains non-file inputs and both replay consequences, along with per-envelope set reuse; separated tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Declaration and queried file share the envelope's native filesystem identity context, so relative/absolute aliases and filesystem case behavior are not hand-normalized.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The set retains only declared physical identities on weakly owned generation state and opens no watcher or file handle; its lifetime ends with that state.
+ * @evidence contracts/performance.md#efficient-algorithms One linear declaration fold builds a set; subsequent module queries use keyed membership and memoized path identity instead of repeated whole-list scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work The memoized set is valid for the immutable declaration, project root and identity context of one envelope generation; unrelated result objects cannot share it.
+ */
+export declare function isVolatileFile(state: TtscEnvelopeDerivation, props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+}): boolean;

package/lib/core/transform/envelope/isVolatileFile.d.mts

@@ -0,0 +1,22 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+/**
+ * Report whether the plugin declared `file` volatile: its output depends on
+ * non-file inputs (environment, time, network), so neither the project
+ * transform cache nor a bundler's persistent cache may replay it. Reads the
+ * per-envelope identity set instead of rescanning the member list.
+ *
+ * @evidence contracts/common.md#principled-implementation Volatility is explicit producer membership by file identity, not an inference from output contents; an exception result supplies no declaration for this predicate.
+ * @evidence contracts/common.md#clear-and-simple-design The predicate reads the declaration while cache and bundler owners enforce their respective replay restrictions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported non-file dependencies are honestly represented by volatility rather than replaced by fixture hashes or a promise that file inputs prove them stable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains non-file inputs and both replay consequences, along with per-envelope set reuse; separated tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Declaration and queried file share the envelope's native filesystem identity context, so relative/absolute aliases and filesystem case behavior are not hand-normalized.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The set retains only declared physical identities on weakly owned generation state and opens no watcher or file handle; its lifetime ends with that state.
+ * @evidence contracts/performance.md#efficient-algorithms One linear declaration fold builds a set; subsequent module queries use keyed membership and memoized path identity instead of repeated whole-list scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work The memoized set is valid for the immutable declaration, project root and identity context of one envelope generation; unrelated result objects cannot share it.
+ */
+export declare function isVolatileFile(state: TtscEnvelopeDerivation, props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+}): boolean;

package/lib/core/transform/envelope/isVolatileFile.d.ts

@@ -0,0 +1,22 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation";
+/**
+ * Report whether the plugin declared `file` volatile: its output depends on
+ * non-file inputs (environment, time, network), so neither the project
+ * transform cache nor a bundler's persistent cache may replay it. Reads the
+ * per-envelope identity set instead of rescanning the member list.
+ *
+ * @evidence contracts/common.md#principled-implementation Volatility is explicit producer membership by file identity, not an inference from output contents; an exception result supplies no declaration for this predicate.
+ * @evidence contracts/common.md#clear-and-simple-design The predicate reads the declaration while cache and bundler owners enforce their respective replay restrictions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported non-file dependencies are honestly represented by volatility rather than replaced by fixture hashes or a promise that file inputs prove them stable.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains non-file inputs and both replay consequences, along with per-envelope set reuse; separated tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Declaration and queried file share the envelope's native filesystem identity context, so relative/absolute aliases and filesystem case behavior are not hand-normalized.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The set retains only declared physical identities on weakly owned generation state and opens no watcher or file handle; its lifetime ends with that state.
+ * @evidence contracts/performance.md#efficient-algorithms One linear declaration fold builds a set; subsequent module queries use keyed membership and memoized path identity instead of repeated whole-list scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work The memoized set is valid for the immutable declaration, project root and identity context of one envelope generation; unrelated result objects cannot share it.
+ */
+export declare function isVolatileFile(state: TtscEnvelopeDerivation, props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+}): boolean;