@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/generation/transferCaptureClockReference.js

@@ -0,0 +1,36 @@
+'use strict';
+
+var TRANSFORM_CLOCK_REFERENCE_DIRECTORIES = require('../clock/TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.js');
+
+/**
+ * Publish the successfully cleaned capture's owned clock storage to its owner.
+ *
+ * Capture calls this only after local cleanup succeeds and a generation exists.
+ * An unavailable directory registers nothing. The association lets validation
+ * refresh the same owned probe and lets generation disposal detach and remove
+ * it; registration itself proves neither a clock stamp nor native acquisition.
+ *
+ * The caller transfers a fresh generation and its owned reference directory.
+ * This operation does not replace or dispose an earlier generation's storage.
+ *
+ * @evidence contracts/common.md#principled-implementation Associates available caller-owned reference storage with the exact returned generation, after capture's cleanup gate. Missing storage remains unavailable rather than receiving a fabricated path or timestamp.
+ * @evidence contracts/common.md#clear-and-simple-design One ownership publication connects capture to existing validation and disposal consumers; minting, proof qualification and storage removal remain their separate responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Performs the actual generation association used by production, without a test-only channel, injected compiler result or synthetic native release/acquisition receipt.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the successful-cleanup precondition, fresh ownership assumption, missing-directory behavior and limits of registration authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Publishes an opaque directory coordinate supplied by its native storage owner; no path grammar, case rule, filesystem operation or OS capability is interpreted here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One optional WeakMap assignment adds no scan, traversal or input processing strategy.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing validation consumers find this generation's same owned storage instead of inventing another probe location. They still mint and qualify fresh observations; sharing the directory grants no authority to reuse an old timestamp.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The weak generation association holds one directory spelling per transferred owner without extending that owner's reachability. disposeCachedTransform detaches the association and attempts native removal; garbage collection alone does not remove storage, and this publication neither acquires a handle nor certifies later release.
+ */
+function transferCaptureClockReference(
+/** Fresh returned generation whose local cleanup has completed successfully. */
+captured, 
+/** Owned reference storage, or unavailable storage leaving no association. */
+referenceDirectory) {
+    if (referenceDirectory !== undefined) {
+        TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.set(captured, referenceDirectory);
+    }
+}
+
+exports.transferCaptureClockReference = transferCaptureClockReference;
+//# sourceMappingURL=transferCaptureClockReference.js.map

package/lib/core/transform/generation/transferCaptureClockReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferCaptureClockReference.js","sources":["../../../../src/core/transform/generation/transferCaptureClockReference.ts"],"sourcesContent":[null],"names":["TRANSFORM_CLOCK_REFERENCE_DIRECTORIES"],"mappings":";;;;AAGA;;;;;;;;;;;;;;;;;;;AAmBG;SACa,6BAA6B;AAC3C;AACA,QAAoC;AAEpC;AACA,kBAAsC,EAAA;AAEtC,IAAA,IAAI,kBAAkB,KAAK,SAAS,EAAE;AACpC,QAAAA,2EAAqC,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACzE;AACF;;;;"}

package/lib/core/transform/generation/transferCaptureClockReference.mjs

@@ -0,0 +1,34 @@
+import { TRANSFORM_CLOCK_REFERENCE_DIRECTORIES } from '../clock/TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.mjs';
+
+/**
+ * Publish the successfully cleaned capture's owned clock storage to its owner.
+ *
+ * Capture calls this only after local cleanup succeeds and a generation exists.
+ * An unavailable directory registers nothing. The association lets validation
+ * refresh the same owned probe and lets generation disposal detach and remove
+ * it; registration itself proves neither a clock stamp nor native acquisition.
+ *
+ * The caller transfers a fresh generation and its owned reference directory.
+ * This operation does not replace or dispose an earlier generation's storage.
+ *
+ * @evidence contracts/common.md#principled-implementation Associates available caller-owned reference storage with the exact returned generation, after capture's cleanup gate. Missing storage remains unavailable rather than receiving a fabricated path or timestamp.
+ * @evidence contracts/common.md#clear-and-simple-design One ownership publication connects capture to existing validation and disposal consumers; minting, proof qualification and storage removal remain their separate responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Performs the actual generation association used by production, without a test-only channel, injected compiler result or synthetic native release/acquisition receipt.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the successful-cleanup precondition, fresh ownership assumption, missing-directory behavior and limits of registration authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Publishes an opaque directory coordinate supplied by its native storage owner; no path grammar, case rule, filesystem operation or OS capability is interpreted here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One optional WeakMap assignment adds no scan, traversal or input processing strategy.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing validation consumers find this generation's same owned storage instead of inventing another probe location. They still mint and qualify fresh observations; sharing the directory grants no authority to reuse an old timestamp.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The weak generation association holds one directory spelling per transferred owner without extending that owner's reachability. disposeCachedTransform detaches the association and attempts native removal; garbage collection alone does not remove storage, and this publication neither acquires a handle nor certifies later release.
+ */
+function transferCaptureClockReference(
+/** Fresh returned generation whose local cleanup has completed successfully. */
+captured, 
+/** Owned reference storage, or unavailable storage leaving no association. */
+referenceDirectory) {
+    if (referenceDirectory !== undefined) {
+        TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.set(captured, referenceDirectory);
+    }
+}
+
+export { transferCaptureClockReference };
+//# sourceMappingURL=transferCaptureClockReference.mjs.map

package/lib/core/transform/generation/transferCaptureClockReference.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferCaptureClockReference.mjs","sources":["../../../../src/core/transform/generation/transferCaptureClockReference.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;AAmBG;SACa,6BAA6B;AAC3C;AACA,QAAoC;AAEpC;AACA,kBAAsC,EAAA;AAEtC,IAAA,IAAI,kBAAkB,KAAK,SAAS,EAAE;AACpC,QAAA,qCAAqC,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACzE;AACF;;;;"}

package/lib/core/transform/generation/transformProject.d.cts

@@ -0,0 +1,124 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.cjs";
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.cjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Compile one whole project generation, retrying within a bound while its proof
+ * is lost to a filesystem race.
+ *
+ * A capture whose snapshot could not be proven stable is disposed and attempted
+ * again. At the movement or absolute attempt cap, a coherent diagnostic verdict
+ * is returned; otherwise a terminal `TtscUnstableGenerationError` carries the
+ * failed environment, so later deliveries replay the verdict until that
+ * environment provably changes instead of each repeating a whole-project
+ * compile.
+ *
+ * The bound is for a project that keeps moving, so it counts the failures that
+ * say the project moved: every compile here that fails its proof, and every
+ * adoption whose own window moved. An attempt that adopted another worker's
+ * compile and could not prove it failed for one of two reasons
+ * (`TtscAdoptionVerdict`, samchon/ttsc#1479). When the publication itself
+ * failed its proof on this disk, the attempt says nothing about the project
+ * moving: the attempt after it refuses that publication and compiles the same
+ * state here, or claims the state the project moved to, and it does not spend
+ * the bound, which a pool would otherwise exhaust on publications while its
+ * project moved once, and end the delivery in an unstable verdict that
+ * compiling the state resolves. When the publication held and only this
+ * worker's window moved around it, the attempt is a moved window like any
+ * compile's here, and spends the bound; its retry claims whatever state it then
+ * reads, and adopts the same publication again when the project's content never
+ * changed. Refusing it, as every failed adoption once was, compiled on a
+ * Turbopack pool a state the pool had already compiled and proven, for an event
+ * that changed nothing. The attempts are capped at twice the bound all the
+ * same, so a project that keeps moving from one published state to the next
+ * ends too.
+ *
+ * A failed compile (a `failure` or `exception` envelope) needs no proven
+ * snapshot, since its verdict is its diagnostics, but it does need the project
+ * to have held still across it. One that read a source repaired while it ran
+ * reports a state already gone, and a host that takes its dependencies when the
+ * transform returns, as Turbopack does, records the repair as the baseline and
+ * never re-runs the module. It is compiled again, and when the project moves
+ * under the retry too, the retry's own failure is returned.
+ *
+ * A plugin-reported dependency path is certified only against a witness read
+ * before the compile (samchon/ttsc#1541), and a compile learns such paths only
+ * from its own envelope. An attempt whose one failure is a dependency path it
+ * reported for the first time is retried with that path witnessed. It says
+ * nothing about the project moving, so it does not spend the bound, and the cap
+ * of twice the bound still ends a project whose dependencies never settle. The
+ * compiler's case policy is learned the same way: a walk primed with another
+ * policy is taken again under the one the compile reported
+ * (samchon/ttsc#1545).
+ *
+ * A local success whose only lost premise is explicitly unavailable host
+ * observation may qualify for its initiating delivery. The delivery coordinator
+ * additionally requires an explicitly nonwatching host with cache-withdrawal
+ * capability. It remains incomplete and cannot authorize resident, shared or
+ * persistent caching. Actual changes, conflicts and unexplained missing proof
+ * retain the stabilization gate.
+ *
+ * Enabled private tracing records each computed disposition before its state is
+ * applied. It does not supply proof when capture throws or tracing fails.
+ *
+ * @evidence contracts/common.md#principled-implementation Each capture establishes config coherence and reusable success proof or a current diagnostic verdict; a local stable success with only explicit unavailable host observations instead transfers one fresh delivery without reuse authority, while mixed mutation, missing or conflicting proof retains retry admission.
+ * @evidence contracts/common.md#clear-and-simple-design The pure attempt policy selects acceptance and retry budgets; this loop owns mutable learned facts and resource handoff, capture owns proof construction, and the shared error builder owns terminal rendering and final disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retrying follows learned dependencies/case policy or refuted publication payload rather than an endless workaround chain; only lossless producer-authorized observation unavailability can permit a local fresh answer, and it never becomes a reusable success or excuses actual mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain movement versus absolute budgets, failed-compile diagnostics and learned facts; separated props state delivery, tracking and inherited witness meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Each capture delegates native filesystem and compiler behavior to injected host boundaries; reported compiler case policy is carried between attempts rather than guessed from OS names.
+ * @evidence contracts/performance.md#efficient-algorithms At most four captures bound retry count, not each capture's project/config/input bytes, native walks, compiler/plugin work, observer setup or session waiting time. Each rejected attempt copies the cumulative witnessed Set and scans its external dependencies into that copy; the next capture receives a separate array of its names; supplied spellings contribute hashing/text cost. Terminal rendering visits retained attempts/witnesses, and disposal delegates observer/probe cleanup rather than making those effects constant work. Enabled tracing serializes disposition scalars and path text through the existing bounded append sink; disabled tracing skips that payload construction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Learned dependency names and reported compiler case policy carry into the next capture, which takes new observations; previous witness bytes are not reused as fresh proof. The exact refuted publication payload is excluded on the next lookup; another payload under that same projected state still requires separate proof. This loop shares no cache entry itself; its caller owns generation/terminal Promise sharing and current-environment replay admission.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each nonterminal rejected capture is detached through the shared disposer before retry; terminal error construction does the same for the final failed capture, while diagnostic/success/fresh-only return transfers the generation to its caller. Cleanup failures do not certify native release. Up to four attempt aggregates remain, but their path/detail bytes and cumulative witnessed dependency names have no byte cap; the terminal error retains comparison data under cache-owner lifetime. Capture owns its own acquisition-failure cleanup and escaped errors.
+ */
+export declare function transformProject(props: {
+    /** Adapter aliases re-stated over inherited project paths for compilation. */
+    aliasPaths: Record<string, string[]>;
+    /** Compiler-option overlay, preserving the underlying config semantics. */
+    compilerOptions: Record<string, unknown>;
+    /** Native path of the module whose delivery initiated this capture. */
+    currentFile: string;
+    /** Delivered module text compared against the compiler's disk observation. */
+    currentSource: string;
+    /**
+     * Delivery pass this compile was started for; see
+     * {@link TtscCachedProjectTransform.deliveryEpoch}.
+     */
+    deliveryEpoch?: number;
+    /** Host filesystem boundary for project and external-input proof. */
+    filesystem: TtscTransformFilesystemOperations;
+    /** Native plugin descriptors supplied to the compiler. */
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /**
+     * Explicit common source root; omitted direct callers use the config
+     * directory.
+     */
+    projectRoot?: string;
+    /** Whether live membership observers may transfer to a retained generation. */
+    retainProjectMembership: boolean;
+    /**
+     * Whether the generation may keep watchers whose silence stands in for
+     * re-reading its inputs. False once the host or the environment declares
+     * polling (samchon/ttsc#1395); the generation then validates every delivery
+     * against its recorded state.
+     */
+    retainNotifications: boolean;
+    /**
+     * The pooled host session's shared compile store, when the cache shares its
+     * compiles (samchon/ttsc#1390).
+     */
+    session?: string;
+    /** Whether a pre-compile membership tracker should witness the capture window. */
+    trackProjectMembership: boolean;
+    /** Native project config selected for the whole-project transform. */
+    tsconfig: string;
+    /**
+     * Dependency-only paths the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_DEPENDENCY_WITNESSES`), to be witnessed before the
+     * compile; see {@link TtscCachedProjectTransform.externalDependencyInputs}.
+     */
+    witnessedDependencies?: readonly string[];
+    /**
+     * The case policy the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_CASE_POLICIES`, samchon/ttsc#1545).
+     */
+    useCaseSensitiveFileNames?: boolean;
+}): Promise<TtscCachedProjectTransform>;

package/lib/core/transform/generation/transformProject.d.mts

@@ -0,0 +1,124 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.mjs";
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.mjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Compile one whole project generation, retrying within a bound while its proof
+ * is lost to a filesystem race.
+ *
+ * A capture whose snapshot could not be proven stable is disposed and attempted
+ * again. At the movement or absolute attempt cap, a coherent diagnostic verdict
+ * is returned; otherwise a terminal `TtscUnstableGenerationError` carries the
+ * failed environment, so later deliveries replay the verdict until that
+ * environment provably changes instead of each repeating a whole-project
+ * compile.
+ *
+ * The bound is for a project that keeps moving, so it counts the failures that
+ * say the project moved: every compile here that fails its proof, and every
+ * adoption whose own window moved. An attempt that adopted another worker's
+ * compile and could not prove it failed for one of two reasons
+ * (`TtscAdoptionVerdict`, samchon/ttsc#1479). When the publication itself
+ * failed its proof on this disk, the attempt says nothing about the project
+ * moving: the attempt after it refuses that publication and compiles the same
+ * state here, or claims the state the project moved to, and it does not spend
+ * the bound, which a pool would otherwise exhaust on publications while its
+ * project moved once, and end the delivery in an unstable verdict that
+ * compiling the state resolves. When the publication held and only this
+ * worker's window moved around it, the attempt is a moved window like any
+ * compile's here, and spends the bound; its retry claims whatever state it then
+ * reads, and adopts the same publication again when the project's content never
+ * changed. Refusing it, as every failed adoption once was, compiled on a
+ * Turbopack pool a state the pool had already compiled and proven, for an event
+ * that changed nothing. The attempts are capped at twice the bound all the
+ * same, so a project that keeps moving from one published state to the next
+ * ends too.
+ *
+ * A failed compile (a `failure` or `exception` envelope) needs no proven
+ * snapshot, since its verdict is its diagnostics, but it does need the project
+ * to have held still across it. One that read a source repaired while it ran
+ * reports a state already gone, and a host that takes its dependencies when the
+ * transform returns, as Turbopack does, records the repair as the baseline and
+ * never re-runs the module. It is compiled again, and when the project moves
+ * under the retry too, the retry's own failure is returned.
+ *
+ * A plugin-reported dependency path is certified only against a witness read
+ * before the compile (samchon/ttsc#1541), and a compile learns such paths only
+ * from its own envelope. An attempt whose one failure is a dependency path it
+ * reported for the first time is retried with that path witnessed. It says
+ * nothing about the project moving, so it does not spend the bound, and the cap
+ * of twice the bound still ends a project whose dependencies never settle. The
+ * compiler's case policy is learned the same way: a walk primed with another
+ * policy is taken again under the one the compile reported
+ * (samchon/ttsc#1545).
+ *
+ * A local success whose only lost premise is explicitly unavailable host
+ * observation may qualify for its initiating delivery. The delivery coordinator
+ * additionally requires an explicitly nonwatching host with cache-withdrawal
+ * capability. It remains incomplete and cannot authorize resident, shared or
+ * persistent caching. Actual changes, conflicts and unexplained missing proof
+ * retain the stabilization gate.
+ *
+ * Enabled private tracing records each computed disposition before its state is
+ * applied. It does not supply proof when capture throws or tracing fails.
+ *
+ * @evidence contracts/common.md#principled-implementation Each capture establishes config coherence and reusable success proof or a current diagnostic verdict; a local stable success with only explicit unavailable host observations instead transfers one fresh delivery without reuse authority, while mixed mutation, missing or conflicting proof retains retry admission.
+ * @evidence contracts/common.md#clear-and-simple-design The pure attempt policy selects acceptance and retry budgets; this loop owns mutable learned facts and resource handoff, capture owns proof construction, and the shared error builder owns terminal rendering and final disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retrying follows learned dependencies/case policy or refuted publication payload rather than an endless workaround chain; only lossless producer-authorized observation unavailability can permit a local fresh answer, and it never becomes a reusable success or excuses actual mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain movement versus absolute budgets, failed-compile diagnostics and learned facts; separated props state delivery, tracking and inherited witness meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Each capture delegates native filesystem and compiler behavior to injected host boundaries; reported compiler case policy is carried between attempts rather than guessed from OS names.
+ * @evidence contracts/performance.md#efficient-algorithms At most four captures bound retry count, not each capture's project/config/input bytes, native walks, compiler/plugin work, observer setup or session waiting time. Each rejected attempt copies the cumulative witnessed Set and scans its external dependencies into that copy; the next capture receives a separate array of its names; supplied spellings contribute hashing/text cost. Terminal rendering visits retained attempts/witnesses, and disposal delegates observer/probe cleanup rather than making those effects constant work. Enabled tracing serializes disposition scalars and path text through the existing bounded append sink; disabled tracing skips that payload construction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Learned dependency names and reported compiler case policy carry into the next capture, which takes new observations; previous witness bytes are not reused as fresh proof. The exact refuted publication payload is excluded on the next lookup; another payload under that same projected state still requires separate proof. This loop shares no cache entry itself; its caller owns generation/terminal Promise sharing and current-environment replay admission.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each nonterminal rejected capture is detached through the shared disposer before retry; terminal error construction does the same for the final failed capture, while diagnostic/success/fresh-only return transfers the generation to its caller. Cleanup failures do not certify native release. Up to four attempt aggregates remain, but their path/detail bytes and cumulative witnessed dependency names have no byte cap; the terminal error retains comparison data under cache-owner lifetime. Capture owns its own acquisition-failure cleanup and escaped errors.
+ */
+export declare function transformProject(props: {
+    /** Adapter aliases re-stated over inherited project paths for compilation. */
+    aliasPaths: Record<string, string[]>;
+    /** Compiler-option overlay, preserving the underlying config semantics. */
+    compilerOptions: Record<string, unknown>;
+    /** Native path of the module whose delivery initiated this capture. */
+    currentFile: string;
+    /** Delivered module text compared against the compiler's disk observation. */
+    currentSource: string;
+    /**
+     * Delivery pass this compile was started for; see
+     * {@link TtscCachedProjectTransform.deliveryEpoch}.
+     */
+    deliveryEpoch?: number;
+    /** Host filesystem boundary for project and external-input proof. */
+    filesystem: TtscTransformFilesystemOperations;
+    /** Native plugin descriptors supplied to the compiler. */
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /**
+     * Explicit common source root; omitted direct callers use the config
+     * directory.
+     */
+    projectRoot?: string;
+    /** Whether live membership observers may transfer to a retained generation. */
+    retainProjectMembership: boolean;
+    /**
+     * Whether the generation may keep watchers whose silence stands in for
+     * re-reading its inputs. False once the host or the environment declares
+     * polling (samchon/ttsc#1395); the generation then validates every delivery
+     * against its recorded state.
+     */
+    retainNotifications: boolean;
+    /**
+     * The pooled host session's shared compile store, when the cache shares its
+     * compiles (samchon/ttsc#1390).
+     */
+    session?: string;
+    /** Whether a pre-compile membership tracker should witness the capture window. */
+    trackProjectMembership: boolean;
+    /** Native project config selected for the whole-project transform. */
+    tsconfig: string;
+    /**
+     * Dependency-only paths the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_DEPENDENCY_WITNESSES`), to be witnessed before the
+     * compile; see {@link TtscCachedProjectTransform.externalDependencyInputs}.
+     */
+    witnessedDependencies?: readonly string[];
+    /**
+     * The case policy the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_CASE_POLICIES`, samchon/ttsc#1545).
+     */
+    useCaseSensitiveFileNames?: boolean;
+}): Promise<TtscCachedProjectTransform>;

package/lib/core/transform/generation/transformProject.d.ts

@@ -0,0 +1,124 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions";
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Compile one whole project generation, retrying within a bound while its proof
+ * is lost to a filesystem race.
+ *
+ * A capture whose snapshot could not be proven stable is disposed and attempted
+ * again. At the movement or absolute attempt cap, a coherent diagnostic verdict
+ * is returned; otherwise a terminal `TtscUnstableGenerationError` carries the
+ * failed environment, so later deliveries replay the verdict until that
+ * environment provably changes instead of each repeating a whole-project
+ * compile.
+ *
+ * The bound is for a project that keeps moving, so it counts the failures that
+ * say the project moved: every compile here that fails its proof, and every
+ * adoption whose own window moved. An attempt that adopted another worker's
+ * compile and could not prove it failed for one of two reasons
+ * (`TtscAdoptionVerdict`, samchon/ttsc#1479). When the publication itself
+ * failed its proof on this disk, the attempt says nothing about the project
+ * moving: the attempt after it refuses that publication and compiles the same
+ * state here, or claims the state the project moved to, and it does not spend
+ * the bound, which a pool would otherwise exhaust on publications while its
+ * project moved once, and end the delivery in an unstable verdict that
+ * compiling the state resolves. When the publication held and only this
+ * worker's window moved around it, the attempt is a moved window like any
+ * compile's here, and spends the bound; its retry claims whatever state it then
+ * reads, and adopts the same publication again when the project's content never
+ * changed. Refusing it, as every failed adoption once was, compiled on a
+ * Turbopack pool a state the pool had already compiled and proven, for an event
+ * that changed nothing. The attempts are capped at twice the bound all the
+ * same, so a project that keeps moving from one published state to the next
+ * ends too.
+ *
+ * A failed compile (a `failure` or `exception` envelope) needs no proven
+ * snapshot, since its verdict is its diagnostics, but it does need the project
+ * to have held still across it. One that read a source repaired while it ran
+ * reports a state already gone, and a host that takes its dependencies when the
+ * transform returns, as Turbopack does, records the repair as the baseline and
+ * never re-runs the module. It is compiled again, and when the project moves
+ * under the retry too, the retry's own failure is returned.
+ *
+ * A plugin-reported dependency path is certified only against a witness read
+ * before the compile (samchon/ttsc#1541), and a compile learns such paths only
+ * from its own envelope. An attempt whose one failure is a dependency path it
+ * reported for the first time is retried with that path witnessed. It says
+ * nothing about the project moving, so it does not spend the bound, and the cap
+ * of twice the bound still ends a project whose dependencies never settle. The
+ * compiler's case policy is learned the same way: a walk primed with another
+ * policy is taken again under the one the compile reported
+ * (samchon/ttsc#1545).
+ *
+ * A local success whose only lost premise is explicitly unavailable host
+ * observation may qualify for its initiating delivery. The delivery coordinator
+ * additionally requires an explicitly nonwatching host with cache-withdrawal
+ * capability. It remains incomplete and cannot authorize resident, shared or
+ * persistent caching. Actual changes, conflicts and unexplained missing proof
+ * retain the stabilization gate.
+ *
+ * Enabled private tracing records each computed disposition before its state is
+ * applied. It does not supply proof when capture throws or tracing fails.
+ *
+ * @evidence contracts/common.md#principled-implementation Each capture establishes config coherence and reusable success proof or a current diagnostic verdict; a local stable success with only explicit unavailable host observations instead transfers one fresh delivery without reuse authority, while mixed mutation, missing or conflicting proof retains retry admission.
+ * @evidence contracts/common.md#clear-and-simple-design The pure attempt policy selects acceptance and retry budgets; this loop owns mutable learned facts and resource handoff, capture owns proof construction, and the shared error builder owns terminal rendering and final disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retrying follows learned dependencies/case policy or refuted publication payload rather than an endless workaround chain; only lossless producer-authorized observation unavailability can permit a local fresh answer, and it never becomes a reusable success or excuses actual mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain movement versus absolute budgets, failed-compile diagnostics and learned facts; separated props state delivery, tracking and inherited witness meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Each capture delegates native filesystem and compiler behavior to injected host boundaries; reported compiler case policy is carried between attempts rather than guessed from OS names.
+ * @evidence contracts/performance.md#efficient-algorithms At most four captures bound retry count, not each capture's project/config/input bytes, native walks, compiler/plugin work, observer setup or session waiting time. Each rejected attempt copies the cumulative witnessed Set and scans its external dependencies into that copy; the next capture receives a separate array of its names; supplied spellings contribute hashing/text cost. Terminal rendering visits retained attempts/witnesses, and disposal delegates observer/probe cleanup rather than making those effects constant work. Enabled tracing serializes disposition scalars and path text through the existing bounded append sink; disabled tracing skips that payload construction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Learned dependency names and reported compiler case policy carry into the next capture, which takes new observations; previous witness bytes are not reused as fresh proof. The exact refuted publication payload is excluded on the next lookup; another payload under that same projected state still requires separate proof. This loop shares no cache entry itself; its caller owns generation/terminal Promise sharing and current-environment replay admission.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each nonterminal rejected capture is detached through the shared disposer before retry; terminal error construction does the same for the final failed capture, while diagnostic/success/fresh-only return transfers the generation to its caller. Cleanup failures do not certify native release. Up to four attempt aggregates remain, but their path/detail bytes and cumulative witnessed dependency names have no byte cap; the terminal error retains comparison data under cache-owner lifetime. Capture owns its own acquisition-failure cleanup and escaped errors.
+ */
+export declare function transformProject(props: {
+    /** Adapter aliases re-stated over inherited project paths for compilation. */
+    aliasPaths: Record<string, string[]>;
+    /** Compiler-option overlay, preserving the underlying config semantics. */
+    compilerOptions: Record<string, unknown>;
+    /** Native path of the module whose delivery initiated this capture. */
+    currentFile: string;
+    /** Delivered module text compared against the compiler's disk observation. */
+    currentSource: string;
+    /**
+     * Delivery pass this compile was started for; see
+     * {@link TtscCachedProjectTransform.deliveryEpoch}.
+     */
+    deliveryEpoch?: number;
+    /** Host filesystem boundary for project and external-input proof. */
+    filesystem: TtscTransformFilesystemOperations;
+    /** Native plugin descriptors supplied to the compiler. */
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /**
+     * Explicit common source root; omitted direct callers use the config
+     * directory.
+     */
+    projectRoot?: string;
+    /** Whether live membership observers may transfer to a retained generation. */
+    retainProjectMembership: boolean;
+    /**
+     * Whether the generation may keep watchers whose silence stands in for
+     * re-reading its inputs. False once the host or the environment declares
+     * polling (samchon/ttsc#1395); the generation then validates every delivery
+     * against its recorded state.
+     */
+    retainNotifications: boolean;
+    /**
+     * The pooled host session's shared compile store, when the cache shares its
+     * compiles (samchon/ttsc#1390).
+     */
+    session?: string;
+    /** Whether a pre-compile membership tracker should witness the capture window. */
+    trackProjectMembership: boolean;
+    /** Native project config selected for the whole-project transform. */
+    tsconfig: string;
+    /**
+     * Dependency-only paths the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_DEPENDENCY_WITNESSES`), to be witnessed before the
+     * compile; see {@link TtscCachedProjectTransform.externalDependencyInputs}.
+     */
+    witnessedDependencies?: readonly string[];
+    /**
+     * The case policy the last generation of this cache key reported
+     * (`TRANSFORM_CACHE_CASE_POLICIES`, samchon/ttsc#1545).
+     */
+    useCaseSensitiveFileNames?: boolean;
+}): Promise<TtscCachedProjectTransform>;

package/lib/core/transform/generation/transformProject.js

@@ -0,0 +1,169 @@
+'use strict';
+
+var path = require('node:path');
+var traceInvocation = require('../../tracing/traceInvocation.js');
+var disposeCachedTransform = require('../cache/disposeCachedTransform.js');
+var TRANSFORM_ADOPTED_RESULTS = require('../session/TRANSFORM_ADOPTED_RESULTS.js');
+var TRANSFORM_FAILED_GENERATION_VALIDATIONS = require('./TRANSFORM_FAILED_GENERATION_VALIDATIONS.js');
+var TRANSFORM_GENERATION_FAILURES = require('./TRANSFORM_GENERATION_FAILURES.js');
+var captureTransformGeneration = require('./captureTransformGeneration.js');
+var carryTransformAttemptInputs = require('./carryTransformAttemptInputs.js');
+var createUnstableGenerationError = require('./createUnstableGenerationError.js');
+var selectTransformAttemptDisposition = require('./selectTransformAttemptDisposition.js');
+
+/**
+ * Compile one whole project generation, retrying within a bound while its proof
+ * is lost to a filesystem race.
+ *
+ * A capture whose snapshot could not be proven stable is disposed and attempted
+ * again. At the movement or absolute attempt cap, a coherent diagnostic verdict
+ * is returned; otherwise a terminal `TtscUnstableGenerationError` carries the
+ * failed environment, so later deliveries replay the verdict until that
+ * environment provably changes instead of each repeating a whole-project
+ * compile.
+ *
+ * The bound is for a project that keeps moving, so it counts the failures that
+ * say the project moved: every compile here that fails its proof, and every
+ * adoption whose own window moved. An attempt that adopted another worker's
+ * compile and could not prove it failed for one of two reasons
+ * (`TtscAdoptionVerdict`, samchon/ttsc#1479). When the publication itself
+ * failed its proof on this disk, the attempt says nothing about the project
+ * moving: the attempt after it refuses that publication and compiles the same
+ * state here, or claims the state the project moved to, and it does not spend
+ * the bound, which a pool would otherwise exhaust on publications while its
+ * project moved once, and end the delivery in an unstable verdict that
+ * compiling the state resolves. When the publication held and only this
+ * worker's window moved around it, the attempt is a moved window like any
+ * compile's here, and spends the bound; its retry claims whatever state it then
+ * reads, and adopts the same publication again when the project's content never
+ * changed. Refusing it, as every failed adoption once was, compiled on a
+ * Turbopack pool a state the pool had already compiled and proven, for an event
+ * that changed nothing. The attempts are capped at twice the bound all the
+ * same, so a project that keeps moving from one published state to the next
+ * ends too.
+ *
+ * A failed compile (a `failure` or `exception` envelope) needs no proven
+ * snapshot, since its verdict is its diagnostics, but it does need the project
+ * to have held still across it. One that read a source repaired while it ran
+ * reports a state already gone, and a host that takes its dependencies when the
+ * transform returns, as Turbopack does, records the repair as the baseline and
+ * never re-runs the module. It is compiled again, and when the project moves
+ * under the retry too, the retry's own failure is returned.
+ *
+ * A plugin-reported dependency path is certified only against a witness read
+ * before the compile (samchon/ttsc#1541), and a compile learns such paths only
+ * from its own envelope. An attempt whose one failure is a dependency path it
+ * reported for the first time is retried with that path witnessed. It says
+ * nothing about the project moving, so it does not spend the bound, and the cap
+ * of twice the bound still ends a project whose dependencies never settle. The
+ * compiler's case policy is learned the same way: a walk primed with another
+ * policy is taken again under the one the compile reported
+ * (samchon/ttsc#1545).
+ *
+ * A local success whose only lost premise is explicitly unavailable host
+ * observation may qualify for its initiating delivery. The delivery coordinator
+ * additionally requires an explicitly nonwatching host with cache-withdrawal
+ * capability. It remains incomplete and cannot authorize resident, shared or
+ * persistent caching. Actual changes, conflicts and unexplained missing proof
+ * retain the stabilization gate.
+ *
+ * Enabled private tracing records each computed disposition before its state is
+ * applied. It does not supply proof when capture throws or tracing fails.
+ *
+ * @evidence contracts/common.md#principled-implementation Each capture establishes config coherence and reusable success proof or a current diagnostic verdict; a local stable success with only explicit unavailable host observations instead transfers one fresh delivery without reuse authority, while mixed mutation, missing or conflicting proof retains retry admission.
+ * @evidence contracts/common.md#clear-and-simple-design The pure attempt policy selects acceptance and retry budgets; this loop owns mutable learned facts and resource handoff, capture owns proof construction, and the shared error builder owns terminal rendering and final disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retrying follows learned dependencies/case policy or refuted publication payload rather than an endless workaround chain; only lossless producer-authorized observation unavailability can permit a local fresh answer, and it never becomes a reusable success or excuses actual mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain movement versus absolute budgets, failed-compile diagnostics and learned facts; separated props state delivery, tracking and inherited witness meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Each capture delegates native filesystem and compiler behavior to injected host boundaries; reported compiler case policy is carried between attempts rather than guessed from OS names.
+ * @evidence contracts/performance.md#efficient-algorithms At most four captures bound retry count, not each capture's project/config/input bytes, native walks, compiler/plugin work, observer setup or session waiting time. Each rejected attempt copies the cumulative witnessed Set and scans its external dependencies into that copy; the next capture receives a separate array of its names; supplied spellings contribute hashing/text cost. Terminal rendering visits retained attempts/witnesses, and disposal delegates observer/probe cleanup rather than making those effects constant work. Enabled tracing serializes disposition scalars and path text through the existing bounded append sink; disabled tracing skips that payload construction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Learned dependency names and reported compiler case policy carry into the next capture, which takes new observations; previous witness bytes are not reused as fresh proof. The exact refuted publication payload is excluded on the next lookup; another payload under that same projected state still requires separate proof. This loop shares no cache entry itself; its caller owns generation/terminal Promise sharing and current-environment replay admission.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each nonterminal rejected capture is detached through the shared disposer before retry; terminal error construction does the same for the final failed capture, while diagnostic/success/fresh-only return transfers the generation to its caller. Cleanup failures do not certify native release. Up to four attempt aggregates remain, but their path/detail bytes and cumulative witnessed dependency names have no byte cap; the terminal error retains comparison data under cache-owner lifetime. Capture owns its own acquisition-failure cleanup and escaped errors.
+ */
+async function transformProject(props) {
+    const attemptTrace = traceInvocation.traceInvocation();
+    const attempts = [];
+    let rejected;
+    let moved = 0;
+    let witnessed = new Set(props.witnessedDependencies);
+    let useCaseSensitiveFileNames = props.useCaseSensitiveFileNames;
+    for (let attempt = 0;; attempt += 1) {
+        const cached = await captureTransformGeneration.captureTransformGeneration({
+            ...props,
+            rejected,
+            useCaseSensitiveFileNames,
+            witnessedDependencies: [...witnessed],
+        });
+        const disposition = selectTransformAttemptDisposition.selectTransformAttemptDisposition({
+            resultType: cached.result.type,
+            configStateComplete: cached.configStateComplete,
+            projectSnapshotComplete: cached.projectSnapshotComplete,
+            projectHeldStill: cached.projectHeldStill,
+            observationsComplete: cached.result.type === "failure"
+                ? cached.result.observationsComplete
+                : undefined,
+            hostInputProofFailureCount: cached.result.type === "failure"
+                ? Object.keys(cached.result.hostInputProofFailures ?? {}).length
+                : 0,
+            failures: TRANSFORM_GENERATION_FAILURES.TRANSFORM_GENERATION_FAILURES.get(cached.result),
+            adopted: TRANSFORM_ADOPTED_RESULTS.TRANSFORM_ADOPTED_RESULTS.get(cached.result),
+            attempt,
+            moved,
+            rejected,
+        });
+        attemptTrace?.("bridge-attempt-disposition", {
+            pid: process.pid,
+            cwd: cached.projectRoot,
+            data: {
+                tsconfig: props.tsconfig,
+                currentFile: props.currentFile,
+                temporaryTsconfig: cached.temporaryTsconfig,
+                scratchDirectory: cached.scratchDirectory,
+                attempt,
+                movedBefore: moved,
+                rejectedBefore: rejected ?? null,
+                kind: disposition.kind,
+                freshDeliveryOnly: disposition.freshDeliveryOnly,
+                movedAfter: "moved" in disposition ? disposition.moved : null,
+                rejectedAfter: "rejected" in disposition ? (disposition.rejected ?? null) : null,
+            },
+        });
+        if (disposition.freshDeliveryOnly) {
+            // Neither incomplete diagnostic observations nor a permitted local fresh
+            // success authorizes this generation's reuse beyond its current delivery.
+            cached.freshDeliveryOnly = true;
+        }
+        if (disposition.kind === "accepted" || disposition.kind === "fresh-only") {
+            return cached;
+        }
+        attempts.push(disposition.failures);
+        const nextInputs = carryTransformAttemptInputs.carryTransformAttemptInputs(witnessed, useCaseSensitiveFileNames, cached);
+        witnessed = nextInputs.witnessed;
+        useCaseSensitiveFileNames = nextInputs.useCaseSensitiveFileNames;
+        // A publication refuted here would be found again by a retry for the same
+        // state, which therefore compiles and replaces it. A retry whose project
+        // moved to another state claims that state's publication, and adopts it:
+        // refusing it too, measured on a Turbopack pool, compiled a state another
+        // worker had just published, while the next edit was already landing. An
+        // adoption whose own window moved refutes nothing, and is counted as the
+        // compile it stood in for.
+        rejected = disposition.rejected;
+        moved = disposition.moved;
+        // A failed compile the project moved under twice still names its own
+        // diagnostics, which say more than an unstable-generation error.
+        if (disposition.kind === "diagnostic") {
+            return cached;
+        }
+        if (disposition.kind === "terminal") {
+            const validation = TRANSFORM_FAILED_GENERATION_VALIDATIONS.TRANSFORM_FAILED_GENERATION_VALIDATIONS.get(cached.result);
+            if (validation === undefined) {
+                disposeCachedTransform.disposeCachedTransform(cached);
+                throw new Error("ttsc: failed transform generation has no retry validation baseline");
+            }
+            throw createUnstableGenerationError.createUnstableGenerationError(props.projectRoot ?? path.dirname(props.tsconfig), attempts, validation);
+        }
+        disposeCachedTransform.disposeCachedTransform(cached);
+    }
+}
+
+exports.transformProject = transformProject;
+//# sourceMappingURL=transformProject.js.map