@ttsc/unplugin 0.30.4 → 0.31.0

package/lib/core/transform/cache/beginTtscTransformBuild.d.ts

@@ -0,0 +1,35 @@
+import type { TtscTransformCache } from "./TtscTransformCache";
+/**
+ * Open a delivery pass that can share a retained generation's complete proof.
+ *
+ * The counter update is fixed work. The pass's first delivery still proves the
+ * recorded snapshot; later first deliveries reaching source comparison hash
+ * their text and may compare disk bytes before sharing that proof. Repeated
+ * module deliveries retain their existing validation path.
+ *
+ * This deliberately retains the cached generation. The pass boundary is a
+ * statement about _deliveries_ — each module is requested at most once inside
+ * it — not about whether the compiled program is still correct, which the
+ * generation's own recorded snapshot answers and which `matchesCachedSource`
+ * proves once at the pass's first delivery. Clearing here instead made a host
+ * whose `buildStart` repeats recompile the whole project on every rebuild even
+ * when no compiler input had changed (samchon/ttsc#1300). Use
+ * `resetTtscTransformCache` to actually discard a generation and its watchers.
+ *
+ * Hosts without a guaranteed pass boundary use persistent validation unless
+ * they have another immutable lifecycle. Bun runtime setup, for example,
+ * defines one process-scoped module-loading session.
+ *
+ * @evidence contracts/common.md#principled-implementation Advancing the delivery epoch opens a new proof window without discarding the compiled generation, whose first delivery must still prove its snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design One cache-owned counter declares the pass; validation and disposal remain separate operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A pass boundary does not fabricate freshness or clear valid work to hide an invalidation error.
+ * @evidence contracts/common.md#meaningful-documentation The paragraphs distinguish delivery epochs from generation validity and identify hosts that lack a guaranteed pass boundary.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The epoch is one number per cache in a WeakMap and is released with the cache; the generations' own resources are released by resetTtscTransformCache.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One counter increment.
+ * @evidence contracts/performance.md#reuse-equivalent-work Advancing the epoch instead of discarding the generation is what lets a repeating buildStart reuse its compile after the pass's first delivery proves it.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ */
+export declare function beginTtscTransformBuild(
+/** Cache whose next deliveries belong to a newly declared host pass. */
+cache: TtscTransformCache): void;

package/lib/core/transform/cache/beginTtscTransformBuild.js

@@ -0,0 +1,43 @@
+'use strict';
+
+var TRANSFORM_CACHE_EPOCHS = require('./TRANSFORM_CACHE_EPOCHS.js');
+
+/**
+ * Open a delivery pass that can share a retained generation's complete proof.
+ *
+ * The counter update is fixed work. The pass's first delivery still proves the
+ * recorded snapshot; later first deliveries reaching source comparison hash
+ * their text and may compare disk bytes before sharing that proof. Repeated
+ * module deliveries retain their existing validation path.
+ *
+ * This deliberately retains the cached generation. The pass boundary is a
+ * statement about _deliveries_ — each module is requested at most once inside
+ * it — not about whether the compiled program is still correct, which the
+ * generation's own recorded snapshot answers and which `matchesCachedSource`
+ * proves once at the pass's first delivery. Clearing here instead made a host
+ * whose `buildStart` repeats recompile the whole project on every rebuild even
+ * when no compiler input had changed (samchon/ttsc#1300). Use
+ * `resetTtscTransformCache` to actually discard a generation and its watchers.
+ *
+ * Hosts without a guaranteed pass boundary use persistent validation unless
+ * they have another immutable lifecycle. Bun runtime setup, for example,
+ * defines one process-scoped module-loading session.
+ *
+ * @evidence contracts/common.md#principled-implementation Advancing the delivery epoch opens a new proof window without discarding the compiled generation, whose first delivery must still prove its snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design One cache-owned counter declares the pass; validation and disposal remain separate operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A pass boundary does not fabricate freshness or clear valid work to hide an invalidation error.
+ * @evidence contracts/common.md#meaningful-documentation The paragraphs distinguish delivery epochs from generation validity and identify hosts that lack a guaranteed pass boundary.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The epoch is one number per cache in a WeakMap and is released with the cache; the generations' own resources are released by resetTtscTransformCache.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One counter increment.
+ * @evidence contracts/performance.md#reuse-equivalent-work Advancing the epoch instead of discarding the generation is what lets a repeating buildStart reuse its compile after the pass's first delivery proves it.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ */
+function beginTtscTransformBuild(
+/** Cache whose next deliveries belong to a newly declared host pass. */
+cache) {
+    TRANSFORM_CACHE_EPOCHS.TRANSFORM_CACHE_EPOCHS.set(cache, (TRANSFORM_CACHE_EPOCHS.TRANSFORM_CACHE_EPOCHS.get(cache) ?? 0) + 1);
+}
+
+exports.beginTtscTransformBuild = beginTtscTransformBuild;
+//# sourceMappingURL=beginTtscTransformBuild.js.map

package/lib/core/transform/cache/beginTtscTransformBuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beginTtscTransformBuild.js","sources":["../../../../src/core/transform/cache/beginTtscTransformBuild.ts"],"sourcesContent":[null],"names":["TRANSFORM_CACHE_EPOCHS"],"mappings":";;;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;SACa,uBAAuB;AACrC;AACA,KAAyB,EAAA;AAEzB,IAAAA,6CAAsB,CAAC,GAAG,CACxB,KAAK,EACL,CAACA,6CAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAC7C;AACH;;;;"}

package/lib/core/transform/cache/beginTtscTransformBuild.mjs

@@ -0,0 +1,41 @@
+import { TRANSFORM_CACHE_EPOCHS } from './TRANSFORM_CACHE_EPOCHS.mjs';
+
+/**
+ * Open a delivery pass that can share a retained generation's complete proof.
+ *
+ * The counter update is fixed work. The pass's first delivery still proves the
+ * recorded snapshot; later first deliveries reaching source comparison hash
+ * their text and may compare disk bytes before sharing that proof. Repeated
+ * module deliveries retain their existing validation path.
+ *
+ * This deliberately retains the cached generation. The pass boundary is a
+ * statement about _deliveries_ — each module is requested at most once inside
+ * it — not about whether the compiled program is still correct, which the
+ * generation's own recorded snapshot answers and which `matchesCachedSource`
+ * proves once at the pass's first delivery. Clearing here instead made a host
+ * whose `buildStart` repeats recompile the whole project on every rebuild even
+ * when no compiler input had changed (samchon/ttsc#1300). Use
+ * `resetTtscTransformCache` to actually discard a generation and its watchers.
+ *
+ * Hosts without a guaranteed pass boundary use persistent validation unless
+ * they have another immutable lifecycle. Bun runtime setup, for example,
+ * defines one process-scoped module-loading session.
+ *
+ * @evidence contracts/common.md#principled-implementation Advancing the delivery epoch opens a new proof window without discarding the compiled generation, whose first delivery must still prove its snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design One cache-owned counter declares the pass; validation and disposal remain separate operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A pass boundary does not fabricate freshness or clear valid work to hide an invalidation error.
+ * @evidence contracts/common.md#meaningful-documentation The paragraphs distinguish delivery epochs from generation validity and identify hosts that lack a guaranteed pass boundary.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The epoch is one number per cache in a WeakMap and is released with the cache; the generations' own resources are released by resetTtscTransformCache.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One counter increment.
+ * @evidence contracts/performance.md#reuse-equivalent-work Advancing the epoch instead of discarding the generation is what lets a repeating buildStart reuse its compile after the pass's first delivery proves it.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ */
+function beginTtscTransformBuild(
+/** Cache whose next deliveries belong to a newly declared host pass. */
+cache) {
+    TRANSFORM_CACHE_EPOCHS.set(cache, (TRANSFORM_CACHE_EPOCHS.get(cache) ?? 0) + 1);
+}
+
+export { beginTtscTransformBuild };
+//# sourceMappingURL=beginTtscTransformBuild.mjs.map

package/lib/core/transform/cache/beginTtscTransformBuild.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"beginTtscTransformBuild.mjs","sources":["../../../../src/core/transform/cache/beginTtscTransformBuild.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;SACa,uBAAuB;AACrC;AACA,KAAyB,EAAA;AAEzB,IAAA,sBAAsB,CAAC,GAAG,CACxB,KAAK,EACL,CAAC,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAC7C;AACH;;;;"}

package/lib/core/transform/cache/createTransformCacheKey.d.cts

@@ -0,0 +1,44 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.cjs";
+/**
+ * Build the key one project generation is cached under.
+ *
+ * The declared compile configuration is represented by: the selected tsconfig's
+ * filesystem identity, common source-root identity, compiler overlay, plugin
+ * list, and translated aliases. Two adapter configurations that have different
+ * supported JSON representations therefore receive different keys; native
+ * spellings resolving to one config identity may share a key. A key does not
+ * encode current filesystem content or prove freshness. Compiler overlays,
+ * plugin payloads and alias mappings retain their JSON declaration order: tied
+ * compiler path patterns and arbitrary plugin payloads can observe it. Only the
+ * host-owned outer manifest is serialized with sorted keys.
+ *
+ * @evidence contracts/common.md#principled-implementation Native config and source-root identities plus actual JSON representations of compiler overlays, plugin payloads and alias mappings distinguish requested compiles, retaining declaration order that path-pattern ties or plugins can observe.
+ * @evidence contracts/common.md#clear-and-simple-design Existing path identity and stable JSON encoding define the key; filesystem state remains the generation validator's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equivalent configuration spelling is normalized without dropping semantically relevant plugin order or pretending a matching key proves current inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name every key dimension and distinguish host-owned canonical manifest order from semantically observable external configuration order.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three payload serializations preserve supported JSON order; the outer
+ *   five-field manifest sorts only its fixed keys and serializes their text
+ *   again, with escaping/output space proportional to the payload text.
+ *   One path-identity transaction for config and root observes uncached native
+ *   aliases, ancestors and directory case policy; that work is not constant
+ *   or bounded by option size alone. The caller builds this key per delivery.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supported JSON configuration representation plus native config/root identities
+ *   selects a shared generation within the cache. Declaration order remains
+ *   observable; equal keys do not replace recorded-input validation. This
+ *   function retains no serialized payload or native observation across calls.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The config and root components use the actual host path-identity resolver's native
+ *   alias and directory case observations instead of lowercasing by OS. It is
+ *   a comparison address, not a replacement for the spelling passed to reads.
+ */
+export declare function createTransformCacheKey(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /** Common source root; omission defaults to the config directory. */
+    projectRoot?: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/cache/createTransformCacheKey.d.mts

@@ -0,0 +1,44 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.mjs";
+/**
+ * Build the key one project generation is cached under.
+ *
+ * The declared compile configuration is represented by: the selected tsconfig's
+ * filesystem identity, common source-root identity, compiler overlay, plugin
+ * list, and translated aliases. Two adapter configurations that have different
+ * supported JSON representations therefore receive different keys; native
+ * spellings resolving to one config identity may share a key. A key does not
+ * encode current filesystem content or prove freshness. Compiler overlays,
+ * plugin payloads and alias mappings retain their JSON declaration order: tied
+ * compiler path patterns and arbitrary plugin payloads can observe it. Only the
+ * host-owned outer manifest is serialized with sorted keys.
+ *
+ * @evidence contracts/common.md#principled-implementation Native config and source-root identities plus actual JSON representations of compiler overlays, plugin payloads and alias mappings distinguish requested compiles, retaining declaration order that path-pattern ties or plugins can observe.
+ * @evidence contracts/common.md#clear-and-simple-design Existing path identity and stable JSON encoding define the key; filesystem state remains the generation validator's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equivalent configuration spelling is normalized without dropping semantically relevant plugin order or pretending a matching key proves current inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name every key dimension and distinguish host-owned canonical manifest order from semantically observable external configuration order.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three payload serializations preserve supported JSON order; the outer
+ *   five-field manifest sorts only its fixed keys and serializes their text
+ *   again, with escaping/output space proportional to the payload text.
+ *   One path-identity transaction for config and root observes uncached native
+ *   aliases, ancestors and directory case policy; that work is not constant
+ *   or bounded by option size alone. The caller builds this key per delivery.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supported JSON configuration representation plus native config/root identities
+ *   selects a shared generation within the cache. Declaration order remains
+ *   observable; equal keys do not replace recorded-input validation. This
+ *   function retains no serialized payload or native observation across calls.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The config and root components use the actual host path-identity resolver's native
+ *   alias and directory case observations instead of lowercasing by OS. It is
+ *   a comparison address, not a replacement for the spelling passed to reads.
+ */
+export declare function createTransformCacheKey(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /** Common source root; omission defaults to the config directory. */
+    projectRoot?: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/cache/createTransformCacheKey.d.ts

@@ -0,0 +1,44 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions";
+/**
+ * Build the key one project generation is cached under.
+ *
+ * The declared compile configuration is represented by: the selected tsconfig's
+ * filesystem identity, common source-root identity, compiler overlay, plugin
+ * list, and translated aliases. Two adapter configurations that have different
+ * supported JSON representations therefore receive different keys; native
+ * spellings resolving to one config identity may share a key. A key does not
+ * encode current filesystem content or prove freshness. Compiler overlays,
+ * plugin payloads and alias mappings retain their JSON declaration order: tied
+ * compiler path patterns and arbitrary plugin payloads can observe it. Only the
+ * host-owned outer manifest is serialized with sorted keys.
+ *
+ * @evidence contracts/common.md#principled-implementation Native config and source-root identities plus actual JSON representations of compiler overlays, plugin payloads and alias mappings distinguish requested compiles, retaining declaration order that path-pattern ties or plugins can observe.
+ * @evidence contracts/common.md#clear-and-simple-design Existing path identity and stable JSON encoding define the key; filesystem state remains the generation validator's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equivalent configuration spelling is normalized without dropping semantically relevant plugin order or pretending a matching key proves current inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name every key dimension and distinguish host-owned canonical manifest order from semantically observable external configuration order.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three payload serializations preserve supported JSON order; the outer
+ *   five-field manifest sorts only its fixed keys and serializes their text
+ *   again, with escaping/output space proportional to the payload text.
+ *   One path-identity transaction for config and root observes uncached native
+ *   aliases, ancestors and directory case policy; that work is not constant
+ *   or bounded by option size alone. The caller builds this key per delivery.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supported JSON configuration representation plus native config/root identities
+ *   selects a shared generation within the cache. Declaration order remains
+ *   observable; equal keys do not replace recorded-input validation. This
+ *   function retains no serialized payload or native observation across calls.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The config and root components use the actual host path-identity resolver's native
+ *   alias and directory case observations instead of lowercasing by OS. It is
+ *   a comparison address, not a replacement for the spelling passed to reads.
+ */
+export declare function createTransformCacheKey(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    /** Common source root; omission defaults to the config directory. */
+    projectRoot?: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/cache/createTransformCacheKey.js

@@ -0,0 +1,55 @@
+'use strict';
+
+var path = require('node:path');
+var createHostPathIdentityContext = require('../filesystem/createHostPathIdentityContext.js');
+var pathIdentityKey = require('../filesystem/pathIdentityKey.js');
+var stableStringify = require('../utils/stableStringify.js');
+
+/**
+ * Build the key one project generation is cached under.
+ *
+ * The declared compile configuration is represented by: the selected tsconfig's
+ * filesystem identity, common source-root identity, compiler overlay, plugin
+ * list, and translated aliases. Two adapter configurations that have different
+ * supported JSON representations therefore receive different keys; native
+ * spellings resolving to one config identity may share a key. A key does not
+ * encode current filesystem content or prove freshness. Compiler overlays,
+ * plugin payloads and alias mappings retain their JSON declaration order: tied
+ * compiler path patterns and arbitrary plugin payloads can observe it. Only the
+ * host-owned outer manifest is serialized with sorted keys.
+ *
+ * @evidence contracts/common.md#principled-implementation Native config and source-root identities plus actual JSON representations of compiler overlays, plugin payloads and alias mappings distinguish requested compiles, retaining declaration order that path-pattern ties or plugins can observe.
+ * @evidence contracts/common.md#clear-and-simple-design Existing path identity and stable JSON encoding define the key; filesystem state remains the generation validator's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equivalent configuration spelling is normalized without dropping semantically relevant plugin order or pretending a matching key proves current inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name every key dimension and distinguish host-owned canonical manifest order from semantically observable external configuration order.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three payload serializations preserve supported JSON order; the outer
+ *   five-field manifest sorts only its fixed keys and serializes their text
+ *   again, with escaping/output space proportional to the payload text.
+ *   One path-identity transaction for config and root observes uncached native
+ *   aliases, ancestors and directory case policy; that work is not constant
+ *   or bounded by option size alone. The caller builds this key per delivery.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supported JSON configuration representation plus native config/root identities
+ *   selects a shared generation within the cache. Declaration order remains
+ *   observable; equal keys do not replace recorded-input validation. This
+ *   function retains no serialized payload or native observation across calls.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The config and root components use the actual host path-identity resolver's native
+ *   alias and directory case observations instead of lowercasing by OS. It is
+ *   a comparison address, not a replacement for the spelling passed to reads.
+ */
+function createTransformCacheKey(props) {
+    const identities = createHostPathIdentityContext.createHostPathIdentityContext();
+    return stableStringify.stableStringify({
+        aliasPaths: JSON.stringify(props.aliasPaths),
+        compilerOptions: JSON.stringify(props.compilerOptions),
+        plugins: JSON.stringify(props.plugins),
+        projectRoot: pathIdentityKey.pathIdentityKey(props.projectRoot ?? path.dirname(props.tsconfig), identities),
+        tsconfig: pathIdentityKey.pathIdentityKey(props.tsconfig, identities),
+    });
+}
+
+exports.createTransformCacheKey = createTransformCacheKey;
+//# sourceMappingURL=createTransformCacheKey.js.map

package/lib/core/transform/cache/createTransformCacheKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTransformCacheKey.js","sources":["../../../../src/core/transform/cache/createTransformCacheKey.ts"],"sourcesContent":[null],"names":["createHostPathIdentityContext","stableStringify","pathIdentityKey"],"mappings":";;;;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCG;AACG,SAAU,uBAAuB,CAAC,KAOvC,EAAA;AACC,IAAA,MAAM,UAAU,GAAGA,2DAA6B,EAAE;AAClD,IAAA,OAAOC,+BAAe,CAAC;QACrB,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC;QAC5C,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC;QACtD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC;AACtC,QAAA,WAAW,EAAEC,+BAAe,CAC1B,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EACjD,UAAU,CACX;QACD,QAAQ,EAAEA,+BAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC;AACtD,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/cache/createTransformCacheKey.mjs

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { createHostPathIdentityContext } from '../filesystem/createHostPathIdentityContext.mjs';
+import { pathIdentityKey } from '../filesystem/pathIdentityKey.mjs';
+import { stableStringify } from '../utils/stableStringify.mjs';
+
+/**
+ * Build the key one project generation is cached under.
+ *
+ * The declared compile configuration is represented by: the selected tsconfig's
+ * filesystem identity, common source-root identity, compiler overlay, plugin
+ * list, and translated aliases. Two adapter configurations that have different
+ * supported JSON representations therefore receive different keys; native
+ * spellings resolving to one config identity may share a key. A key does not
+ * encode current filesystem content or prove freshness. Compiler overlays,
+ * plugin payloads and alias mappings retain their JSON declaration order: tied
+ * compiler path patterns and arbitrary plugin payloads can observe it. Only the
+ * host-owned outer manifest is serialized with sorted keys.
+ *
+ * @evidence contracts/common.md#principled-implementation Native config and source-root identities plus actual JSON representations of compiler overlays, plugin payloads and alias mappings distinguish requested compiles, retaining declaration order that path-pattern ties or plugins can observe.
+ * @evidence contracts/common.md#clear-and-simple-design Existing path identity and stable JSON encoding define the key; filesystem state remains the generation validator's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equivalent configuration spelling is normalized without dropping semantically relevant plugin order or pretending a matching key proves current inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs name every key dimension and distinguish host-owned canonical manifest order from semantically observable external configuration order.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a string and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Three payload serializations preserve supported JSON order; the outer
+ *   five-field manifest sorts only its fixed keys and serializes their text
+ *   again, with escaping/output space proportional to the payload text.
+ *   One path-identity transaction for config and root observes uncached native
+ *   aliases, ancestors and directory case policy; that work is not constant
+ *   or bounded by option size alone. The caller builds this key per delivery.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Supported JSON configuration representation plus native config/root identities
+ *   selects a shared generation within the cache. Declaration order remains
+ *   observable; equal keys do not replace recorded-input validation. This
+ *   function retains no serialized payload or native observation across calls.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The config and root components use the actual host path-identity resolver's native
+ *   alias and directory case observations instead of lowercasing by OS. It is
+ *   a comparison address, not a replacement for the spelling passed to reads.
+ */
+function createTransformCacheKey(props) {
+    const identities = createHostPathIdentityContext();
+    return stableStringify({
+        aliasPaths: JSON.stringify(props.aliasPaths),
+        compilerOptions: JSON.stringify(props.compilerOptions),
+        plugins: JSON.stringify(props.plugins),
+        projectRoot: pathIdentityKey(props.projectRoot ?? path.dirname(props.tsconfig), identities),
+        tsconfig: pathIdentityKey(props.tsconfig, identities),
+    });
+}
+
+export { createTransformCacheKey };
+//# sourceMappingURL=createTransformCacheKey.mjs.map

package/lib/core/transform/cache/createTransformCacheKey.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTransformCacheKey.mjs","sources":["../../../../src/core/transform/cache/createTransformCacheKey.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCG;AACG,SAAU,uBAAuB,CAAC,KAOvC,EAAA;AACC,IAAA,MAAM,UAAU,GAAG,6BAA6B,EAAE;AAClD,IAAA,OAAO,eAAe,CAAC;QACrB,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC;QAC5C,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC;QACtD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC;AACtC,QAAA,WAAW,EAAE,eAAe,CAC1B,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EACjD,UAAU,CACX;QACD,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC;AACtD,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/cache/createTransformCacheLease.d.cts

@@ -0,0 +1,49 @@
+import type { TtscTransformCache } from "./TtscTransformCache.cjs";
+import type { TtscTransformCacheLease } from "./TtscTransformCacheLease.cjs";
+/**
+ * Tie a build-scoped cache's lifetime to the sessions that use it, rather than
+ * to one session (samchon/ttsc#1396).
+ *
+ * A multi-environment `vite build`, and Next's client, server, and edge
+ * compilers, each ran a session of their own over the same program, and each
+ * one discarded the generation at its end, so the next compiled the whole
+ * project again. The cache can retain generation data and clock probes;
+ * generation capture decides whether notification handles are retained. When
+ * the last session releases it, the lease keeps it for a short grace. A session
+ * acquired within that grace opens its own delivery pass, and the pass's first
+ * delivery proves the kept generation against the filesystem. The grace
+ * callback resets a cache still unowned when it runs; event-loop scheduling is
+ * not a wall-clock cleanup deadline. Optional registry hooks observe
+ * acquisition and final idle reclamation; they do not change the generation's
+ * validation or the lease's owner count.
+ *
+ * @evidence contracts/common.md#principled-implementation Active-session counting prevents premature reset, and final release schedules a grace timer whose callback rechecks ownership before resetting the generation.
+ * @evidence contracts/common.md#clear-and-simple-design One counter and one pending timer represent active ownership and the between-session grace; reacquisition cancels that timer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The measured grace controls reuse cost only; it cannot replace the new pass's filesystem proof or manufacture a valid generation.
+ * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain repeated-host compile cost, retained generation/probe responsibility and proof required by a reacquiring session, without promising a timer execution deadline.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Acquisition/release update one counter and pending timer without scanning
+ *   entries. Registry hooks add their caller-owned work. Final idle callback
+ *   resets N cached promises, with O(N) snapshot/cleanup scheduling and delegated
+ *   generation watcher/probe disposal as fulfilled promises settle.
+ * @evidence contracts/performance.md#reuse-equivalent-work Adjacent compiler sessions share the cache through teardown gaps; a new pass still proves input equivalence before serving output.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   One pending timer captures the cache/registry, is cancelled on reacquisition
+ *   and is unreferenced so it does not keep the process alive. Final idle reset
+ *   clears membership and schedules fulfilled generation cleanup; unresolved
+ *   compiles still have no lease cancellation deadline. Cache entries/bytes
+ *   are not capacity-bounded here, and callback delay can extend retention.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The standard Node timer controls ownership grace, while generation disposal
+ *   closes supplied native notification capabilities and owned clock probes.
+ *   Scheduling adds no filesystem or OS-name reliability assumption, and the
+ *   lease does not reinterpret the generation's actual observing view.
+ */
+export declare function createTransformCacheLease(
+/** Cache retained across sessions and reset by final idle reclamation. */
+cache: TtscTransformCache, 
+/** Optional registration hooks; their failures/work remain caller-owned. */
+registry?: {
+    acquire(): void;
+    idle(): void;
+}): TtscTransformCacheLease;

package/lib/core/transform/cache/createTransformCacheLease.d.mts

@@ -0,0 +1,49 @@
+import type { TtscTransformCache } from "./TtscTransformCache.mjs";
+import type { TtscTransformCacheLease } from "./TtscTransformCacheLease.mjs";
+/**
+ * Tie a build-scoped cache's lifetime to the sessions that use it, rather than
+ * to one session (samchon/ttsc#1396).
+ *
+ * A multi-environment `vite build`, and Next's client, server, and edge
+ * compilers, each ran a session of their own over the same program, and each
+ * one discarded the generation at its end, so the next compiled the whole
+ * project again. The cache can retain generation data and clock probes;
+ * generation capture decides whether notification handles are retained. When
+ * the last session releases it, the lease keeps it for a short grace. A session
+ * acquired within that grace opens its own delivery pass, and the pass's first
+ * delivery proves the kept generation against the filesystem. The grace
+ * callback resets a cache still unowned when it runs; event-loop scheduling is
+ * not a wall-clock cleanup deadline. Optional registry hooks observe
+ * acquisition and final idle reclamation; they do not change the generation's
+ * validation or the lease's owner count.
+ *
+ * @evidence contracts/common.md#principled-implementation Active-session counting prevents premature reset, and final release schedules a grace timer whose callback rechecks ownership before resetting the generation.
+ * @evidence contracts/common.md#clear-and-simple-design One counter and one pending timer represent active ownership and the between-session grace; reacquisition cancels that timer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The measured grace controls reuse cost only; it cannot replace the new pass's filesystem proof or manufacture a valid generation.
+ * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain repeated-host compile cost, retained generation/probe responsibility and proof required by a reacquiring session, without promising a timer execution deadline.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Acquisition/release update one counter and pending timer without scanning
+ *   entries. Registry hooks add their caller-owned work. Final idle callback
+ *   resets N cached promises, with O(N) snapshot/cleanup scheduling and delegated
+ *   generation watcher/probe disposal as fulfilled promises settle.
+ * @evidence contracts/performance.md#reuse-equivalent-work Adjacent compiler sessions share the cache through teardown gaps; a new pass still proves input equivalence before serving output.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   One pending timer captures the cache/registry, is cancelled on reacquisition
+ *   and is unreferenced so it does not keep the process alive. Final idle reset
+ *   clears membership and schedules fulfilled generation cleanup; unresolved
+ *   compiles still have no lease cancellation deadline. Cache entries/bytes
+ *   are not capacity-bounded here, and callback delay can extend retention.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The standard Node timer controls ownership grace, while generation disposal
+ *   closes supplied native notification capabilities and owned clock probes.
+ *   Scheduling adds no filesystem or OS-name reliability assumption, and the
+ *   lease does not reinterpret the generation's actual observing view.
+ */
+export declare function createTransformCacheLease(
+/** Cache retained across sessions and reset by final idle reclamation. */
+cache: TtscTransformCache, 
+/** Optional registration hooks; their failures/work remain caller-owned. */
+registry?: {
+    acquire(): void;
+    idle(): void;
+}): TtscTransformCacheLease;

package/lib/core/transform/cache/createTransformCacheLease.d.ts

@@ -0,0 +1,49 @@
+import type { TtscTransformCache } from "./TtscTransformCache";
+import type { TtscTransformCacheLease } from "./TtscTransformCacheLease";
+/**
+ * Tie a build-scoped cache's lifetime to the sessions that use it, rather than
+ * to one session (samchon/ttsc#1396).
+ *
+ * A multi-environment `vite build`, and Next's client, server, and edge
+ * compilers, each ran a session of their own over the same program, and each
+ * one discarded the generation at its end, so the next compiled the whole
+ * project again. The cache can retain generation data and clock probes;
+ * generation capture decides whether notification handles are retained. When
+ * the last session releases it, the lease keeps it for a short grace. A session
+ * acquired within that grace opens its own delivery pass, and the pass's first
+ * delivery proves the kept generation against the filesystem. The grace
+ * callback resets a cache still unowned when it runs; event-loop scheduling is
+ * not a wall-clock cleanup deadline. Optional registry hooks observe
+ * acquisition and final idle reclamation; they do not change the generation's
+ * validation or the lease's owner count.
+ *
+ * @evidence contracts/common.md#principled-implementation Active-session counting prevents premature reset, and final release schedules a grace timer whose callback rechecks ownership before resetting the generation.
+ * @evidence contracts/common.md#clear-and-simple-design One counter and one pending timer represent active ownership and the between-session grace; reacquisition cancels that timer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The measured grace controls reuse cost only; it cannot replace the new pass's filesystem proof or manufacture a valid generation.
+ * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain repeated-host compile cost, retained generation/probe responsibility and proof required by a reacquiring session, without promising a timer execution deadline.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Acquisition/release update one counter and pending timer without scanning
+ *   entries. Registry hooks add their caller-owned work. Final idle callback
+ *   resets N cached promises, with O(N) snapshot/cleanup scheduling and delegated
+ *   generation watcher/probe disposal as fulfilled promises settle.
+ * @evidence contracts/performance.md#reuse-equivalent-work Adjacent compiler sessions share the cache through teardown gaps; a new pass still proves input equivalence before serving output.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   One pending timer captures the cache/registry, is cancelled on reacquisition
+ *   and is unreferenced so it does not keep the process alive. Final idle reset
+ *   clears membership and schedules fulfilled generation cleanup; unresolved
+ *   compiles still have no lease cancellation deadline. Cache entries/bytes
+ *   are not capacity-bounded here, and callback delay can extend retention.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The standard Node timer controls ownership grace, while generation disposal
+ *   closes supplied native notification capabilities and owned clock probes.
+ *   Scheduling adds no filesystem or OS-name reliability assumption, and the
+ *   lease does not reinterpret the generation's actual observing view.
+ */
+export declare function createTransformCacheLease(
+/** Cache retained across sessions and reset by final idle reclamation. */
+cache: TtscTransformCache, 
+/** Optional registration hooks; their failures/work remain caller-owned. */
+registry?: {
+    acquire(): void;
+    idle(): void;
+}): TtscTransformCacheLease;

package/lib/core/transform/cache/createTransformCacheLease.js

@@ -0,0 +1,88 @@
+'use strict';
+
+var resetTtscTransformCache = require('./resetTtscTransformCache.js');
+
+/**
+ * How long a build-scoped generation outlives its last session
+ * (samchon/ttsc#1396).
+ *
+ * Measured with `next build --webpack`, the next compiler applied its plugins
+ * 456 ms after the previous one shut down, and Vite builds an app's
+ * environments back to back. The grace only decides whether the next session
+ * reuses the generation; that session proves it against the filesystem before
+ * serving a module, so the value affects cost, never correctness.
+ */
+const RELEASE_GRACE_MS = 2_000;
+/**
+ * Tie a build-scoped cache's lifetime to the sessions that use it, rather than
+ * to one session (samchon/ttsc#1396).
+ *
+ * A multi-environment `vite build`, and Next's client, server, and edge
+ * compilers, each ran a session of their own over the same program, and each
+ * one discarded the generation at its end, so the next compiled the whole
+ * project again. The cache can retain generation data and clock probes;
+ * generation capture decides whether notification handles are retained. When
+ * the last session releases it, the lease keeps it for a short grace. A session
+ * acquired within that grace opens its own delivery pass, and the pass's first
+ * delivery proves the kept generation against the filesystem. The grace
+ * callback resets a cache still unowned when it runs; event-loop scheduling is
+ * not a wall-clock cleanup deadline. Optional registry hooks observe
+ * acquisition and final idle reclamation; they do not change the generation's
+ * validation or the lease's owner count.
+ *
+ * @evidence contracts/common.md#principled-implementation Active-session counting prevents premature reset, and final release schedules a grace timer whose callback rechecks ownership before resetting the generation.
+ * @evidence contracts/common.md#clear-and-simple-design One counter and one pending timer represent active ownership and the between-session grace; reacquisition cancels that timer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The measured grace controls reuse cost only; it cannot replace the new pass's filesystem proof or manufacture a valid generation.
+ * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain repeated-host compile cost, retained generation/probe responsibility and proof required by a reacquiring session, without promising a timer execution deadline.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Acquisition/release update one counter and pending timer without scanning
+ *   entries. Registry hooks add their caller-owned work. Final idle callback
+ *   resets N cached promises, with O(N) snapshot/cleanup scheduling and delegated
+ *   generation watcher/probe disposal as fulfilled promises settle.
+ * @evidence contracts/performance.md#reuse-equivalent-work Adjacent compiler sessions share the cache through teardown gaps; a new pass still proves input equivalence before serving output.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   One pending timer captures the cache/registry, is cancelled on reacquisition
+ *   and is unreferenced so it does not keep the process alive. Final idle reset
+ *   clears membership and schedules fulfilled generation cleanup; unresolved
+ *   compiles still have no lease cancellation deadline. Cache entries/bytes
+ *   are not capacity-bounded here, and callback delay can extend retention.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The standard Node timer controls ownership grace, while generation disposal
+ *   closes supplied native notification capabilities and owned clock probes.
+ *   Scheduling adds no filesystem or OS-name reliability assumption, and the
+ *   lease does not reinterpret the generation's actual observing view.
+ */
+function createTransformCacheLease(
+/** Cache retained across sessions and reset by final idle reclamation. */
+cache, 
+/** Optional registration hooks; their failures/work remain caller-owned. */
+registry) {
+    let owners = 0;
+    let pending;
+    return {
+        acquire() {
+            registry?.acquire();
+            owners += 1;
+            if (pending !== undefined) {
+                clearTimeout(pending);
+                pending = undefined;
+            }
+        },
+        release() {
+            owners = Math.max(0, owners - 1);
+            if (owners !== 0 || pending !== undefined)
+                return;
+            pending = setTimeout(() => {
+                pending = undefined;
+                if (owners === 0) {
+                    resetTtscTransformCache.resetTtscTransformCache(cache);
+                    registry?.idle();
+                }
+            }, RELEASE_GRACE_MS);
+            pending.unref();
+        },
+    };
+}
+
+exports.createTransformCacheLease = createTransformCacheLease;
+//# sourceMappingURL=createTransformCacheLease.js.map