@ttsc/unplugin 0.30.3 → 0.31.0

package/src/core/transform/cache/retainPassVerdict.ts

@@ -0,0 +1,58 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+
+import { TtscPassVerdictError } from "../errors/TtscPassVerdictError";
+import type { TtscTerminalGenerationError } from "../errors/TtscTerminalGenerationError";
+import { TERMINAL_TRANSFORM_GENERATIONS } from "./TERMINAL_TRANSFORM_GENERATIONS";
+import type { TtscCachedProjectTransform } from "./TtscCachedProjectTransform";
+import type { TtscTransformCache } from "./TtscTransformCache";
+
+/**
+ * Retain the verdict of a compile this pass already attempted, or return
+ * `undefined` when nothing may be retained.
+ *
+ * Only inside a delivery pass. A pass is the window in which every delivery is
+ * settled against the state the pass started from, so an attempt it already
+ * made is part of that state and the remaining modules replay it rather than
+ * each repeating a whole-project transform to reach the same answer. Outside a
+ * pass there is no such window, and a long-lived worker must keep retrying on
+ * its very next delivery so a transient host failure never becomes permanent.
+ *
+ * @evidence contracts/common.md#principled-implementation Retention requires a failed envelope, a declared epoch, and the same current promise; success with one missing output cannot become a generation-wide verdict.
+ * @evidence contracts/common.md#clear-and-simple-design One WeakMap stores the existing or newly wrapped verdict for that promise, keeping pass identity in the error instead of adding another cache-entry format.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The original failure remains observable and its retention cannot escape the declared pass or conceal a successful envelope's per-module absence.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains the pass's reuse rationale and why persistent workers outside a pass must retry transient failures.
+ * @evidence contracts/performance.md#efficient-algorithms Current-promise and epoch guards precede one weak lookup; only a new verdict formats a non-Error cause, with text-length scanning and any caller-defined String conversion. Remaining deliveries reuse the verdict without repeating that formatting or whole-project work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Remaining modules reuse the same observed failed attempt only in its pass; a successful envelope's missing output is never promoted to a reusable generation failure.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One verdict is weakly keyed by its generation promise, and the stored epoch limits replay authority to the owning pass.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ */
+export function retainPassVerdict(
+  cache: TtscTransformCache | undefined,
+  key: string,
+  generation: Promise<TtscCachedProjectTransform>,
+  epoch: number | undefined,
+  result: ITtscCompilerTransformation,
+  error: unknown,
+): TtscTerminalGenerationError | undefined {
+  // Only an envelope that failed outright is a statement about the generation.
+  // `selectTransformedSource` also throws for a file the compile simply has no
+  // output for, which is an ordinary condition for a module the bundle reaches
+  // but the tsconfig program does not contain, and which says nothing about the
+  // other modules. Retaining that would fail the whole pass, naming a file none
+  // of them asked about.
+  if (
+    result.type === "success" ||
+    epoch === undefined ||
+    cache?.get(key) !== generation
+  ) {
+    return undefined;
+  }
+  const existing = TERMINAL_TRANSFORM_GENERATIONS.get(generation);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const verdict = new TtscPassVerdictError(error, epoch);
+  TERMINAL_TRANSFORM_GENERATIONS.set(generation, verdict);
+  return verdict;
+}

package/src/core/transform/cache/selectCachedGenerationAction.ts

@@ -0,0 +1,58 @@
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import { isVolatileFile } from "../envelope/isVolatileFile";
+import { matchesCachedSource } from "../validation/matchesCachedSource";
+import type { TtscCachedProjectTransform } from "./TtscCachedProjectTransform";
+import type { TtscTransformCache } from "./TtscTransformCache";
+import { evictGeneration } from "./evictGeneration";
+
+/**
+ * Select the delivery action for an awaited project generation.
+ *
+ * The caller owns awaiting, Promise-ownership checks and required native
+ * notification settling. A volatile or mismatching generation is evicted by
+ * identity; if eviction exposed a sibling replacement, the caller retries it.
+ * Otherwise the caller must capture a new generation. A serving decision does
+ * not perform output selection or host notification, which remain with
+ * delivery.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual generation's volatility and recorded source proof decide serving; identity-guarded eviction then distinguishes a sibling's current replacement from an empty capture slot.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous operation selects serve/retry/capture and owns mismatch eviction, while its production caller owns awaiting, notification settling, native capture and output delivery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Decisions inspect the supplied actual generation and validators without fabricating a producer result, capability or success; no injectable compiler callback or test-only branch is introduced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the caller's awaited-Promise and settled-notification responsibilities and separates the decision from producer and delivery effects.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   First non-exception volatility lookup folds the native identity declaration;
+ *   later queries reuse its Set. Source validation may hash delivered/disk text,
+ *   build an output index, validate derived inputs or scan the complete recorded
+ *   snapshot according to its actual proof branch. Costs follow declaration
+ *   and input populations, path/source bytes and uncached native observations.
+ *   Eviction adds keyed access and delegated generation cleanup, not a compile.
+ * @evidence contracts/performance.md#reuse-equivalent-work A valid generation is served only under its source and dependency proof; a replacement retries the authoritative existing Promise instead of starting another capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Derived Sets/indexes, signatures and epoch state remain generation-owned.
+ *   Mismatch transfers only the current promise through identity-guarded
+ *   cleanup attempts, with their native failure and unresolved-compile limits.
+ *   This action selector acquires no independent handle or historical state.
+ * @evidence contracts/portability.md#os-neutral-implementation Generation derivation and source validation retain their actual filesystem identity and compiler policy; this coordinator adds no platform inference or path rewriting.
+ */
+export function selectCachedGenerationAction(props: {
+  cache: TtscTransformCache | undefined;
+  cached: TtscCachedProjectTransform;
+  epoch: number | undefined;
+  file: string;
+  generation: Promise<TtscCachedProjectTransform>;
+  key: string;
+  source: string;
+}): "serve" | "retry" | "capture" {
+  if (
+    !isVolatileFile(envelopeDerivation(props.cached), {
+      file: props.file,
+      projectRoot: props.cached.projectRoot,
+      result: props.cached.result,
+    }) &&
+    matchesCachedSource(props.cached, props.file, props.source, props.epoch)
+  ) {
+    return "serve";
+  }
+  evictGeneration(props.cache, props.key, props.generation);
+  return props.cache?.get(props.key) !== undefined ? "retry" : "capture";
+}

package/src/core/transform/cache/selectOrEvict.ts

@@ -0,0 +1,93 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+
+import type { TtscTransformedOutput } from "../envelope/TtscTransformedOutput";
+import { selectTransformedSource } from "../envelope/selectTransformedSource";
+import type { TtscCachedProjectTransform } from "./TtscCachedProjectTransform";
+import type { TtscTransformCache } from "./TtscTransformCache";
+import { evictGeneration } from "./evictGeneration";
+import { retainPassVerdict } from "./retainPassVerdict";
+
+/**
+ * Extract the transformed source, and decide what a throwing generation is.
+ *
+ * Envelope failure and per-module absence are distinct supported outcomes of
+ * {@link selectTransformedSource}. A host `"exception"` or a compiler
+ * `"failure"` means the compile produced nothing for anyone: inside a pass that
+ * verdict is retained and replayed, because evicting it made every remaining
+ * module repeat the whole-project transform instead of replaying that attempt
+ * (samchon/ttsc#1303), and outside a pass it keeps being evicted so a
+ * long-lived worker retries on its very next delivery exactly as before.
+ *
+ * A `"success"` envelope that has no output for the module asking is the other
+ * reason, and it is a fact about that one file: an ordinary condition for a
+ * module the bundle reaches and the tsconfig program does not contain. It is
+ * neither retained nor evicted. The error reaches the caller, and the
+ * generation stays available for other modules. Other extraction errors also
+ * propagate; eviction still depends on the envelope discriminator, not error
+ * text or an assumption that every thrown value is typed per-module absence.
+ *
+ * @evidence contracts/common.md#principled-implementation Compiler failure describes the whole generation, while absent output in a successful envelope describes only the requested module; retention and eviction respect that distinction.
+ * @evidence contracts/common.md#clear-and-simple-design The gate delegates source extraction and pass-verdict classification before choosing eviction, without duplicating envelope decoding.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing module neither fabricates output nor destroys a valid program generation to force a compensating compile.
+ * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain generation-wide failure, pass scope, and ordinary per-file absence so cleanup remains tied to the correct cause.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Extraction performs native source identity lookup; an output miss can build
+ *   an O(K) key/text index with delegated native resolution. Diagnostic failure
+ *   formatting scans rendered text, and missing-output reporting traverses
+ *   reachable config references/reads before constructing its path message.
+ *   Pass classification and guarded eviction add cache-key access and possible
+ *   generation cleanup; no compilation is started by this gate.
+ * @evidence contracts/performance.md#reuse-equivalent-work Valid output for other modules remains reusable after one absent module, and one failed generation verdict is reused inside its declared pass.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Failure outside retained pass scope transfers the current fulfilled
+ *   generation to guarded cleanup attempts; pending settlement and native
+ *   cleanup have their documented limits. Successful-envelope errors do not
+ *   evict its generation. The output index and retained terminal data belong
+ *   to their generation/promise, with key/text-dependent storage.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Source selection uses the generation's actual filesystem identity context
+ *   and config-reference addressing; cleanup invokes its native capabilities.
+ *   Original module/config spelling remains diagnostic context, distinct from
+ *   physical comparison keys, without OS-name case or alias assumptions.
+ */
+export function selectOrEvict(
+  /** Cache owning the selected promise, if any. */
+  cache: TtscTransformCache | undefined,
+  /** Opaque configuration address for guarded retention/eviction. */
+  key: string,
+  /** Awaited producer owner; sibling replacements must remain intact. */
+  generation: Promise<TtscCachedProjectTransform>,
+  /** Pass scope for a failed verdict, or undefined for persistent retry. */
+  epoch: number | undefined,
+  props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+    tsconfig: string;
+  },
+): TtscTransformedOutput {
+  try {
+    return selectTransformedSource(props);
+  } catch (error) {
+    const verdict = retainPassVerdict(
+      cache,
+      key,
+      generation,
+      epoch,
+      props.result,
+      error,
+    );
+    if (verdict !== undefined) {
+      throw verdict;
+    }
+    // A generation that compiled fine and simply has no output for the module
+    // asking is not a failed generation. Discarding it made every later module
+    // recompile the whole project to reach the same answer, which is the cost
+    // samchon/ttsc#1303 is about, for a bundle that merely reaches a file the
+    // tsconfig program does not contain.
+    if (props.result.type !== "success") {
+      evictGeneration(cache, key, generation);
+    }
+    throw error;
+  }
+}

package/src/core/transform/cache/sharedBuildTransformCache.ts

@@ -0,0 +1,65 @@
+import { SHARED_BUILD_TRANSFORM_CACHES } from "./SHARED_BUILD_TRANSFORM_CACHES";
+import type { TtscSharedBuildTransformCache } from "./TtscSharedBuildTransformCache";
+import { createTransformCacheLease } from "./createTransformCacheLease";
+import { createTtscTransformCache } from "./createTtscTransformCache";
+
+/**
+ * The process's build-scoped cache for one set of resolved options, created on
+ * first use (samchon/ttsc#1396).
+ *
+ * Final idle release resets the cache and removes this pair from the registry.
+ * A surviving adapter can acquire its pair again; it restores the registry
+ * entry only when no newer pair already owns that key.
+ *
+ * @param key A serialization preserving the resolved options' JSON order.
+ * @evidence contracts/common.md#principled-implementation Equal serialized options select the same process-local cache and lease, while generation validation still decides whether retained output may be served.
+ * @evidence contracts/common.md#clear-and-simple-design Lazy lookup creates one cache/lease pair per configuration rather than adding another compilation or filesystem snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A configuration match establishes sharing identity only; no target-name exception or synthetic successful output changes compile semantics.
+ * @evidence contracts/common.md#meaningful-documentation The comment identifies process scope and the stable options key required from callers.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Lookup and registry hooks use the supplied serialized key without scanning
+ *   other configurations; key access carries its text cost. A new key creates
+ *   one empty cache, fixed capability table and lease plus one initial idle
+ *   timer. Later final idle reclamation delegates N-entry reset and generation
+ *   resource cleanup to the lease rather than making that work constant.
+ * @evidence contracts/performance.md#reuse-equivalent-work Simultaneously requested configurations share one registered pair; final idle reclamation permits later fresh work, and a surviving adapter restores its pair only when another active pair does not already own that key.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Registry growth follows distinct configuration key text and retained pairs,
+ *   without a capacity limit. Initial/final idle callbacks reset unowned pairs
+ *   and remove matching registrations; active owners and event-loop delay can
+ *   extend retention. Surviving adapters keep their own pair, and old leases
+ *   cannot delete a newer registration. Lease timers/probes retain their
+ *   documented owners rather than being bounded by this registry's entry count.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   New pairs use the actual host-default filesystem capability table; sharing
+ *   does not manufacture another view or infer notification/case authority
+ *   from a process-wide key. Generation capture and validation still prove
+ *   native identities/inputs, and the lease owns native cleanup delegation.
+ */
+export function sharedBuildTransformCache(
+  key: string,
+): TtscSharedBuildTransformCache {
+  let entry = SHARED_BUILD_TRANSFORM_CACHES.get(key);
+  if (entry === undefined) {
+    const cache = createTtscTransformCache();
+    const owned: TtscSharedBuildTransformCache = {
+      cache,
+      lease: createTransformCacheLease(cache, {
+        acquire() {
+          if (!SHARED_BUILD_TRANSFORM_CACHES.has(key))
+            SHARED_BUILD_TRANSFORM_CACHES.set(key, owned);
+        },
+        idle() {
+          if (SHARED_BUILD_TRANSFORM_CACHES.get(key) === owned)
+            SHARED_BUILD_TRANSFORM_CACHES.delete(key);
+        },
+      }),
+    };
+    entry = owned;
+    SHARED_BUILD_TRANSFORM_CACHES.set(key, entry);
+    // A factory whose build never starts must not retain an unowned pair
+    // forever; the first real acquisition cancels this idle grace.
+    entry.lease.release();
+  }
+  return entry;
+}

package/src/core/transform/cache/transformCacheEpoch.ts

@@ -0,0 +1,21 @@
+import { TRANSFORM_CACHE_EPOCHS } from "./TRANSFORM_CACHE_EPOCHS";
+import type { TtscTransformCache } from "./TtscTransformCache";
+
+/**
+ * The pass a delivery belongs to, or `undefined` under persistent validation.
+ *
+ * @evidence contracts/common.md#principled-implementation The cache's declared epoch determines pass scope, and an absent cache or declaration yields persistent validation.
+ * @evidence contracts/common.md#clear-and-simple-design A read-only WeakMap lookup exposes the existing lifecycle state without advancing or inventing a pass.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined remains the absence of a pass, not a fabricated epoch authorizing narrow replay.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the returned pass identity and the meaning of undefined.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One WeakMap lookup.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A read of existing lifecycle state; there is no computation to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ */
+export function transformCacheEpoch(
+  cache: TtscTransformCache | undefined,
+): number | undefined {
+  return cache === undefined ? undefined : TRANSFORM_CACHE_EPOCHS.get(cache);
+}

package/src/core/transform/cache/transformCacheTrustsNotifications.ts

@@ -0,0 +1,41 @@
+import { hostDeclaresPolling } from "../tracker/hostDeclaresPolling";
+import { TRANSFORM_CACHE_POLLING } from "./TRANSFORM_CACHE_POLLING";
+import type { TtscTransformCache } from "./TtscTransformCache";
+
+/**
+ * Whether polling policy permits a generation to acquire notification proof.
+ *
+ * Neither the host nor the process environment may have declared polling
+ * (samchon/ttsc#1395). Otherwise the generation opens no retained watcher and
+ * validates each delivery by metadata and content, the path a generation whose
+ * watcher failed already takes. True is permission, not unchanged-input
+ * evidence: coverage, directory identity, event classification and actual
+ * backend authority still qualify the generation's trackers.
+ *
+ * @evidence contracts/common.md#principled-implementation Notification trust requires a cache and no polling declaration from either the cache's host or process environment.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate combines the two policy owners; tracker capability and actual notification settlement remain separate proof requirements.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A false predicate selects real metadata/content proof rather than accepting silent watchers under polling.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains the two polling declarations and the recorded-state path used when trust is unavailable.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Absent caches and declared cache polling short-circuit before environment
+ *   parsing. Otherwise the host parser reads two named values and may lowercase
+ *   Chokidar text or convert and compare Watchpack numeric text; work and
+ *   temporary strings scale with the supplied declaration lengths.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Re-evaluated per delivery because a host or the environment can change its polling declaration; nothing is shared.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native notification admission follows the cache owner's polling declaration
+ *   and the existing host environment parser, not an OS or mount-name guess.
+ *   A positive policy result adds no capability or alias-free assumption;
+ *   actual tracker coverage and backend proof remain with their native owners.
+ */
+export function transformCacheTrustsNotifications(
+  /** Cache owning host polling policy, or absent when no tracker is retained. */
+  cache: TtscTransformCache | undefined,
+): boolean {
+  return (
+    cache !== undefined &&
+    !TRANSFORM_CACHE_POLLING.has(cache) &&
+    !hostDeclaresPolling()
+  );
+}

package/src/core/transform/cache/transformFilesystem.ts

@@ -0,0 +1,35 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { TRANSFORM_CACHE_FILESYSTEM } from "./TRANSFORM_CACHE_FILESYSTEM";
+import type { TtscTransformCache } from "./TtscTransformCache";
+
+/**
+ * Return the filesystem view a delivery through `cache` must use.
+ *
+ * A cache created by `createTtscTransformCache` carries the operations it was
+ * created with, which may observe a filesystem other than the host's. A
+ * delivery without a cache, or through a cache created elsewhere, uses the host
+ * filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation Deliveries use the cache's declared filesystem operations; absent or unregistered caches use the actual host defaults.
+ * @evidence contracts/common.md#clear-and-simple-design One capability lookup selects the view without copying snapshots or adding another filesystem abstraction.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit view selection avoids foreign-method monkeypatching and preserves the distinction between injected and native observations.
+ * @evidence contracts/common.md#meaningful-documentation The native prose states both ownership by cache construction and the exact fallback cases.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; the table is weakly keyed by the cache.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One WeakMap lookup.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The lookup returns the operation table the cache was created with; there is no computation to share.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Capture and validation receive the cache's supplied read, native identity,
+ *   case/platform and optional watch capabilities unchanged. Missing cache
+ *   registration uses the Node host defaults; this selector does not infer
+ *   volume policy from an OS name or fabricate observations for either view.
+ */
+export function transformFilesystem(
+  /** Cache registered with its observing view, or absent for native defaults. */
+  cache: TtscTransformCache | undefined,
+): TtscTransformFilesystemOperations {
+  return (
+    (cache === undefined ? undefined : TRANSFORM_CACHE_FILESYSTEM.get(cache)) ??
+    DEFAULT_FILESYSTEM_OPERATIONS
+  );
+}

package/src/core/transform/cache/withdrawGenerationNotifications.ts

@@ -0,0 +1,43 @@
+import type { TtscCachedProjectTransform } from "./TtscCachedProjectTransform";
+
+/**
+ * Detach a generation's retained watchers and attempt their closure.
+ *
+ * Validation lets a retained watcher's silence stand in for re-reading inputs.
+ * When the host's watch policy stops justifying that, trackers are detached
+ * before their close attempts, and later validation takes the path a generation
+ * whose watchers never opened already takes: its recorded snapshot. The clock
+ * reference and the generation itself stay, so an unchanged project keeps its
+ * compile.
+ *
+ * @evidence contracts/common.md#principled-implementation Detaching all tracker fields before closure removes their authority immediately, so subsequent validation cannot rely on a tracker whose cleanup failed.
+ * @evidence contracts/common.md#clear-and-simple-design Withdrawal closes notification resources while preserving the generation and clock evidence needed by recorded-state validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Close failures cannot create freshness proof; every independent tracker is still attempted and retained output remains subject to snapshot validation.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains the authority transition, and the internal comment distinguishes cleanup failure from stale-output authorization.
+ * @evidence contracts/performance.md#efficient-algorithms Withdrawal checks at most three tracker fields and delegates each close's W retained-watch cleanup; it does not scan project files or start a compile. Fixed wrapper work does not make native closure duration constant.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation and clock evidence remain reusable under snapshot validation, so changed watch policy alone does not waste an equivalent compile.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources All tracker fields detach before independent close attempts; repeat withdrawal sees no retained handle. Failed closes can leave native resources without retaining freshness authority. Generation/clock ownership survives and this operation adds no retry task or history.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral policy changes close through the actual backend handles; unavailable notification authority requires recorded-state proof.
+ */
+export function withdrawGenerationNotifications(
+  /** Generation keeping its snapshot/clock while giving up notification owners. */
+  cached: TtscCachedProjectTransform,
+): void {
+  const trackers = [
+    cached.projectMutationTracker,
+    cached.hostInputMutationTracker,
+    cached.candidateMutationTracker,
+  ];
+  if (trackers.every((tracker) => tracker === undefined)) return;
+  cached.projectMutationTracker = undefined;
+  cached.hostInputMutationTracker = undefined;
+  cached.candidateMutationTracker = undefined;
+  for (const tracker of trackers) {
+    try {
+      tracker?.close();
+    } catch {
+      // The generation no longer reads the tracker, so a close failure leaves
+      // nothing it could serve stale.
+    }
+  }
+}

package/src/core/transform/cache/withdrawTtscTransformGenerations.ts

@@ -0,0 +1,42 @@
+import type { TtscTransformCache } from "./TtscTransformCache";
+import { disposeCachedTransform } from "./disposeCachedTransform";
+
+/**
+ * Withdraw every generation while preserving the host's current delivery pass.
+ *
+ * Volatile input observations disqualify reuse without ending a one-shot build.
+ * Clear membership immediately; fulfilled pending generations subsequently
+ * attempt owned tracker/probe cleanup. No compilation is cancelled here.
+ *
+ * @evidence contracts/common.md#principled-implementation Generation withdrawal clears only cached promises; the host's epoch stays authoritative until its actual terminal lifecycle boundary.
+ * @evidence contracts/common.md#clear-and-simple-design One operation shares generation disposal between volatile withdrawal and terminal reset without conflating their lifecycle authority.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete observation actually withdraws reusable entries; it does not invent a new pass or mark metadata that no owner consumes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish immediate membership withdrawal, scheduled resource cleanup and the retained delivery pass, without promising successful native release.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   An O(N) promise snapshot is followed by one N-entry reaction scheduling
+ *   pass and membership clear, without serially awaiting compilation. Fulfilled
+ *   reactions additionally delegate each generation's watcher/probe cleanup;
+ *   snapshots and reactions require temporary population-sized storage.
+ * @evidence contracts/performance.md#reuse-equivalent-work Terminal reset and volatile withdrawal share the same generation disposal operation; complete ordinary pass opening retains its existing reuse policy.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Membership is cleared before attaching reactions. Each fulfilled withdrawn
+ *   promise transfers its generation to the disposer; rejection is consumed.
+ *   Pending reactions have no cancellation/settlement deadline, and failed
+ *   native cleanup can leave underlying resources despite detached ownership.
+ *   The delivery epoch is deliberately retained by its separate owner.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Fulfilled generation cleanup uses its actual supplied native tracker and
+ *   clock-probe owners, without platform-name assumptions about close/removal
+ *   success. This coordinator keeps configuration keys opaque and preserves
+ *   the caller's lifecycle boundary separately from native cleanup.
+ */
+export function withdrawTtscTransformGenerations(
+  /** Cache whose generations are withdrawn while its delivery pass survives. */
+  cache: TtscTransformCache,
+): void {
+  const generations = [...cache.values()];
+  cache.clear();
+  for (const generation of generations) {
+    void generation.then(disposeCachedTransform, () => undefined);
+  }
+}

package/src/core/transform/clock/TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.ts

@@ -0,0 +1,7 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+
+/** Internal retained clock-probe ownership for published generations. */
+export const TRANSFORM_CLOCK_REFERENCE_DIRECTORIES = new WeakMap<
+  TtscCachedProjectTransform,
+  string
+>();

package/src/core/transform/clock/disposeFilesystemClockReference.ts

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Attempt removal of the known probe and its now-empty owned directory.
+ *
+ * @evidence contracts/common.md#principled-implementation Cleanup attempts the known probe then nonrecursive directory removal, preserving any foreign or concurrently added entry.
+ * @evidence contracts/common.md#clear-and-simple-design Two independent removal attempts target owned file/directory storage without a recursive cleanup policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failure cannot justify deleting unknown contents or leaving a rejected cleanup promise behind.
+ * @evidence contracts/common.md#meaningful-documentation The comment identifies the ownership limit, and internal comments explain independent attempts and nonrecursive preservation.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral cleanup uses native path joining and filesystem removal, tolerating missing or busy resources without hardcoded temporary roots.
+ * @evidence contracts/performance.md#efficient-algorithms Cleanup performs two native removal attempts with path-text joining cost, rather than scanning or recursively deleting a tree; syscall duration remains native filesystem work.
+ * @evidence contracts/performance.md#reuse-equivalent-work This is the shared disposal operation for retained generation and process clock probes, avoiding separate cleanup policies.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Both removal failures are consumed with no retained retry task. Only an empty directory may be removed; a busy probe, permissions or foreign contents can leave residual storage after ownership cleanup. Repeated attempts preserve the same nonrecursive boundary.
+ */
+export function disposeFilesystemClockReference(
+  /** Owned reference storage; unknown children must survive cleanup failure. */
+  referenceDirectory: string,
+): void {
+  try {
+    fs.rmSync(path.join(referenceDirectory, "clock-reference"), {
+      force: true,
+    });
+  } catch {
+    // The probe may already have disappeared; the directory removal below is
+    // still safe because it is deliberately non-recursive.
+  }
+  try {
+    fs.rmdirSync(referenceDirectory);
+  } catch {
+    // Eviction schedules cleanup without awaiting its Promise. A foreign entry
+    // or native removal failure can leave residual storage; never remove unknown
+    // contents to make a cleanup attempt appear successful.
+  }
+}

package/src/core/transform/clock/filesystemClockReferences.ts

@@ -0,0 +1,90 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * The current stamp an adapter-owned probe has minted, keyed by the operations
+ * object that observes it and, inside, by reporting device.
+ *
+ * A filesystem stamps a write once per clock tick, so two same-length writes
+ * inside one tick are indistinguishable by metadata alone. A signature may
+ * therefore stand for content only while a later write is guaranteed to move
+ * it, and that guarantee needs a reference instant the observed filesystem
+ * itself produced: once some stamp on the same device is strictly newer than an
+ * input's modification stamp, that input's tick is provably over, so any later
+ * write must mint a newer stamp and move the signature. This adapts git's
+ * racily-clean index rule: both sides of the comparison come from the same
+ * reporting device, and the newer side is a write the adapter itself made.
+ *
+ * A timestamp merely observed on another input cannot advance the reference.
+ * Tools may assign modification times, and a filesystem clock can move
+ * backwards independently of the process clock. Neither a passive historical
+ * maximum nor `Date.now()` proves what stamp a write would mint now. The probe
+ * is therefore rewritten immediately before every proof that may reuse a
+ * content signature, and its previous reference is cleared before the write. A
+ * failed refresh or a different reporting device declines the optimization and
+ * retains the content comparison (samchon/ttsc#1344). A generation's capture
+ * and deliveries rewrite the probe it retains
+ * (`refreshFilesystemClockReference`); a proof that holds no generation, a
+ * failed generation's replay, a record's proof at a build start, and the
+ * observer's proof of a plugin source, mints in one probe directory the process
+ * keeps below this user's state root (`refreshProcessClockReference`). Once
+ * that directory exists, a mint rewrites the probe in place and adds or removes
+ * no entry in a directory another observer reads.
+ *
+ * Proofs share one reference per operations object and may interleave across an
+ * await. That is sound because separability is decided when an input's metadata
+ * is taken before its read (`inputMetadataEvidence`): whatever reference is
+ * current then was minted before that read, whichever proof minted it.
+ *
+ * The probe lives in an adapter-owned temporary directory outside the project.
+ * That directory may be on another volume, such as `C:` when a project lives on
+ * `D:`. Such a split-volume generation safely keeps reading content because no
+ * same-device reference exists; it never substitutes a process-clock guess or
+ * writes a probe into the user's project.
+ */
+const FILESYSTEM_CLOCK_REFERENCES = new WeakMap<
+  TtscTransformFilesystemOperations,
+  Map<bigint, bigint>
+>();
+
+/**
+ * Return one observed filesystem's current clock references, creating the empty
+ * map on first use.
+ *
+ * Each entry maps a reporting device to the modification stamp the adapter's
+ * probe last minted there. `refreshFilesystemClockReference` replaces the map's
+ * contents before a validation, and `stampSeparable` reads it: an input whose
+ * stamp is strictly older than its device's reference can be trusted by
+ * signature. A device with no entry proves nothing, so its inputs keep being
+ * compared by content. The map is held per operations object; a distinct view
+ * object gets an independent table. The view owner must keep observations
+ * coherent when its backing state or methods change: object identity alone does
+ * not establish equivalent filesystem evidence.
+ *
+ * @evidence contracts/common.md#principled-implementation Device-keyed references are partitioned by observing operation object; refresh and metadata owners must maintain that view's coherence before its table can qualify a signature. Table identity alone proves no observation equivalence.
+ * @evidence contracts/common.md#clear-and-simple-design One WeakMap owns reference tables by operation identity; refresh and separability consumers retain their own write and comparison responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The table contains minted filesystem stamps, never a passive historical maximum or guessed process time that would hide same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain racy-clean metadata, fresh writes, device identity, cross-volume behavior, and proof interleaving before describing the lookup.
+ * @evidence contracts/performance.md#efficient-algorithms Operation-table and device maps provide constant-time reference selection rather than rescanning inputs to infer a clock.
+ * @evidence contracts/performance.md#reuse-equivalent-work All proofs using the same operations object share its current device reference; replacement of that object creates independent evidence.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Weak association does not retain the operations object. Current writers
+ *   clear old entries and record at most one minted device stamp per refresh;
+ *   the returned Map can also be retained by its borrower. No native handle,
+ *   clock history or running task is acquired by table selection.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The table carries the observing view's bigint device/time representation;
+ *   actual probe reads and stamp comparison remain with their native owners.
+ *   A different view receives independent storage, without assuming equal OS
+ *   names or device labels establish cross-view clock equivalence.
+ */
+export function filesystemClockReferences(
+  /** Coherent observing view partitioning native device/time authority. */
+  filesystem: TtscTransformFilesystemOperations,
+): Map<bigint, bigint> {
+  let references = FILESYSTEM_CLOCK_REFERENCES.get(filesystem);
+  if (references === undefined) {
+    references = new Map();
+    FILESYSTEM_CLOCK_REFERENCES.set(filesystem, references);
+  }
+  return references;
+}