@ttsc/unplugin 0.30.4 → 0.31.0

package/lib/core/transform/session/TtscSharedCompilePublication.d.ts

@@ -0,0 +1,52 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * One whole-project compile a worker published to its session's store
+ * (samchon/ttsc#1390).
+ *
+ * The envelope names paths inside the publisher's own scratch directory, such
+ * as its generated tsconfig. An adopter keeps those paths so it excludes them
+ * from its inputs exactly as the publisher would, although they no longer
+ * exist.
+ *
+ * @evidence contracts/common.md#principled-implementation A publication carries compiler output plus the publisher's external-input hashes and physical identities, allowing an adopter to prove the original compile rather than its later reading alone.
+ * @evidence contracts/common.md#clear-and-simple-design The envelope and scratch-path context are retained together; the shape does not duplicate the compiler transformation schema.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The carrier alone certifies no reusable result. Publication producers omit
+ *   transient exceptions, store readers reject them, and adopters own proof.
+ * @evidence contracts/common.md#meaningful-documentation Member comments explain external-input proof and why vanished publisher scratch paths remain semantically relevant.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Carries the publisher's native external identity witnesses and scratch/config
+ *   spellings across workers. Adopters preserve those exclusions and validate
+ *   their current filesystem; vanished scratch paths are not live local handles.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscSharedCompilePublication only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscSharedCompilePublication only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscSharedCompilePublication only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscSharedCompilePublication {
+    /**
+     * Content hash of each external input the publisher recorded right after its
+     * compile, keyed by absolute path. A plugin-reported dependency outside the
+     * project carries no compile-time proof in the envelope, so an adopter must
+     * find exactly these states.
+     */
+    externalInputHashes: Record<string, string>;
+    /** Physical path of each external input, paired with the hashes. */
+    externalInputRealpaths: Record<string, string | null>;
+    /**
+     * The compile's envelope: a `success`, or a `failure` whose diagnostics are
+     * as much a function of the published state as an envelope is
+     * (samchon/ttsc#1458). Never an `exception`, which may come from a transient
+     * crash that every worker must be free to attempt again.
+     */
+    result: ITtscCompilerTransformation;
+    /** The publisher's compiler scratch directory. */
+    scratchDirectory: string;
+    /** The publisher's generated tsconfig, when the compile used one. */
+    temporaryTsconfig?: string;
+}

package/lib/core/transform/session/adoptedExternalInputMismatch.d.cts

@@ -0,0 +1,31 @@
+import type { TtscSharedCompilePublication } from "./TtscSharedCompilePublication.cjs";
+/**
+ * The first external input whose state differs from what the publisher of an
+ * adopted compile recorded, or `undefined` when both supplied maps agree
+ * (samchon/ttsc#1390).
+ *
+ * The project walk's state names the publication, and the compiler's own graph
+ * and host-input proofs carry compile-time state that any worker can check. A
+ * dependency a plugin reports outside the project has neither: the only
+ * evidence of what the compile read is the state the publisher recorded right
+ * after compiling. An adopter's later reading cannot replace that recorded
+ * state. This comparison requires equal own key sets and values for hashes and
+ * realpath observations. Equality alone does not establish completeness,
+ * compile-window stability or an unavailable physical identity; the
+ * capture/adoption owner checks those.
+ *
+ * @param publication The adopted publication.
+ * @param current This worker's external input snapshot of the same envelope.
+ * @evidence contracts/common.md#principled-implementation Both recorded and current key sets and values must agree for content and physical identity; a missing input on either side refutes adoption.
+ * @evidence contracts/common.md#clear-and-simple-design The same union-of-keys comparison handles the two proof dimensions and returns the first mismatched path without another snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An adopter's later reading is never treated as the publisher's compile-time state, and inherited object properties cannot masquerade as recorded inputs.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why external inputs need this separate proof and defines the first-mismatch result.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached dimension materializes both own-key arrays and their union before comparing values, so first mismatch does not avoid that dimension's key collection. Expected set work scales with key occurrences and their text; strict realpath comparison also depends on text length. Temporary arrays and the current union scale with that dimension's populations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation compares supplied records without caching or coordinating observations. The caller captures current state and separately decides adoption; map equality does not certify completeness or compile-window validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The comparison borrows both snapshots and retains only local key sets; publication storage and generation lifetime belong to their owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input names and realpath observations are compared exactly as captured, including null observations. No case, separator or alias normalization guesses equivalence; differently represented observations conservatively mismatch. Current completeness and usable physical identity remain capture-owner obligations.
+ */
+export declare function adoptedExternalInputMismatch(publication: TtscSharedCompilePublication, current: {
+    hashes: Readonly<Record<string, string>>;
+    realpaths: Readonly<Record<string, string | null>>;
+}): string | undefined;

package/lib/core/transform/session/adoptedExternalInputMismatch.d.mts

@@ -0,0 +1,31 @@
+import type { TtscSharedCompilePublication } from "./TtscSharedCompilePublication.mjs";
+/**
+ * The first external input whose state differs from what the publisher of an
+ * adopted compile recorded, or `undefined` when both supplied maps agree
+ * (samchon/ttsc#1390).
+ *
+ * The project walk's state names the publication, and the compiler's own graph
+ * and host-input proofs carry compile-time state that any worker can check. A
+ * dependency a plugin reports outside the project has neither: the only
+ * evidence of what the compile read is the state the publisher recorded right
+ * after compiling. An adopter's later reading cannot replace that recorded
+ * state. This comparison requires equal own key sets and values for hashes and
+ * realpath observations. Equality alone does not establish completeness,
+ * compile-window stability or an unavailable physical identity; the
+ * capture/adoption owner checks those.
+ *
+ * @param publication The adopted publication.
+ * @param current This worker's external input snapshot of the same envelope.
+ * @evidence contracts/common.md#principled-implementation Both recorded and current key sets and values must agree for content and physical identity; a missing input on either side refutes adoption.
+ * @evidence contracts/common.md#clear-and-simple-design The same union-of-keys comparison handles the two proof dimensions and returns the first mismatched path without another snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An adopter's later reading is never treated as the publisher's compile-time state, and inherited object properties cannot masquerade as recorded inputs.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why external inputs need this separate proof and defines the first-mismatch result.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached dimension materializes both own-key arrays and their union before comparing values, so first mismatch does not avoid that dimension's key collection. Expected set work scales with key occurrences and their text; strict realpath comparison also depends on text length. Temporary arrays and the current union scale with that dimension's populations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation compares supplied records without caching or coordinating observations. The caller captures current state and separately decides adoption; map equality does not certify completeness or compile-window validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The comparison borrows both snapshots and retains only local key sets; publication storage and generation lifetime belong to their owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input names and realpath observations are compared exactly as captured, including null observations. No case, separator or alias normalization guesses equivalence; differently represented observations conservatively mismatch. Current completeness and usable physical identity remain capture-owner obligations.
+ */
+export declare function adoptedExternalInputMismatch(publication: TtscSharedCompilePublication, current: {
+    hashes: Readonly<Record<string, string>>;
+    realpaths: Readonly<Record<string, string | null>>;
+}): string | undefined;

package/lib/core/transform/session/adoptedExternalInputMismatch.d.ts

@@ -0,0 +1,31 @@
+import type { TtscSharedCompilePublication } from "./TtscSharedCompilePublication";
+/**
+ * The first external input whose state differs from what the publisher of an
+ * adopted compile recorded, or `undefined` when both supplied maps agree
+ * (samchon/ttsc#1390).
+ *
+ * The project walk's state names the publication, and the compiler's own graph
+ * and host-input proofs carry compile-time state that any worker can check. A
+ * dependency a plugin reports outside the project has neither: the only
+ * evidence of what the compile read is the state the publisher recorded right
+ * after compiling. An adopter's later reading cannot replace that recorded
+ * state. This comparison requires equal own key sets and values for hashes and
+ * realpath observations. Equality alone does not establish completeness,
+ * compile-window stability or an unavailable physical identity; the
+ * capture/adoption owner checks those.
+ *
+ * @param publication The adopted publication.
+ * @param current This worker's external input snapshot of the same envelope.
+ * @evidence contracts/common.md#principled-implementation Both recorded and current key sets and values must agree for content and physical identity; a missing input on either side refutes adoption.
+ * @evidence contracts/common.md#clear-and-simple-design The same union-of-keys comparison handles the two proof dimensions and returns the first mismatched path without another snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An adopter's later reading is never treated as the publisher's compile-time state, and inherited object properties cannot masquerade as recorded inputs.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why external inputs need this separate proof and defines the first-mismatch result.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached dimension materializes both own-key arrays and their union before comparing values, so first mismatch does not avoid that dimension's key collection. Expected set work scales with key occurrences and their text; strict realpath comparison also depends on text length. Temporary arrays and the current union scale with that dimension's populations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation compares supplied records without caching or coordinating observations. The caller captures current state and separately decides adoption; map equality does not certify completeness or compile-window validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The comparison borrows both snapshots and retains only local key sets; publication storage and generation lifetime belong to their owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input names and realpath observations are compared exactly as captured, including null observations. No case, separator or alias normalization guesses equivalence; differently represented observations conservatively mismatch. Current completeness and usable physical identity remain capture-owner obligations.
+ */
+export declare function adoptedExternalInputMismatch(publication: TtscSharedCompilePublication, current: {
+    hashes: Readonly<Record<string, string>>;
+    realpaths: Readonly<Record<string, string | null>>;
+}): string | undefined;

package/lib/core/transform/session/adoptedExternalInputMismatch.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * The first external input whose state differs from what the publisher of an
+ * adopted compile recorded, or `undefined` when both supplied maps agree
+ * (samchon/ttsc#1390).
+ *
+ * The project walk's state names the publication, and the compiler's own graph
+ * and host-input proofs carry compile-time state that any worker can check. A
+ * dependency a plugin reports outside the project has neither: the only
+ * evidence of what the compile read is the state the publisher recorded right
+ * after compiling. An adopter's later reading cannot replace that recorded
+ * state. This comparison requires equal own key sets and values for hashes and
+ * realpath observations. Equality alone does not establish completeness,
+ * compile-window stability or an unavailable physical identity; the
+ * capture/adoption owner checks those.
+ *
+ * @param publication The adopted publication.
+ * @param current This worker's external input snapshot of the same envelope.
+ * @evidence contracts/common.md#principled-implementation Both recorded and current key sets and values must agree for content and physical identity; a missing input on either side refutes adoption.
+ * @evidence contracts/common.md#clear-and-simple-design The same union-of-keys comparison handles the two proof dimensions and returns the first mismatched path without another snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An adopter's later reading is never treated as the publisher's compile-time state, and inherited object properties cannot masquerade as recorded inputs.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why external inputs need this separate proof and defines the first-mismatch result.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached dimension materializes both own-key arrays and their union before comparing values, so first mismatch does not avoid that dimension's key collection. Expected set work scales with key occurrences and their text; strict realpath comparison also depends on text length. Temporary arrays and the current union scale with that dimension's populations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation compares supplied records without caching or coordinating observations. The caller captures current state and separately decides adoption; map equality does not certify completeness or compile-window validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The comparison borrows both snapshots and retains only local key sets; publication storage and generation lifetime belong to their owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input names and realpath observations are compared exactly as captured, including null observations. No case, separator or alias normalization guesses equivalence; differently represented observations conservatively mismatch. Current completeness and usable physical identity remain capture-owner obligations.
+ */
+function adoptedExternalInputMismatch(publication, current) {
+    for (const [recorded, adopted] of [
+        [publication.externalInputHashes, current.hashes],
+        [publication.externalInputRealpaths, current.realpaths],
+    ]) {
+        const paths = new Set([...Object.keys(recorded), ...Object.keys(adopted)]);
+        for (const input of paths) {
+            if (!Object.prototype.hasOwnProperty.call(recorded, input) ||
+                !Object.prototype.hasOwnProperty.call(adopted, input) ||
+                recorded[input] !== adopted[input]) {
+                return input;
+            }
+        }
+    }
+    return undefined;
+}
+
+exports.adoptedExternalInputMismatch = adoptedExternalInputMismatch;
+//# sourceMappingURL=adoptedExternalInputMismatch.js.map

package/lib/core/transform/session/adoptedExternalInputMismatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoptedExternalInputMismatch.js","sources":["../../../../src/core/transform/session/adoptedExternalInputMismatch.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACG,SAAU,4BAA4B,CAC1C,WAAyC,EACzC,OAGC,EAAA;AAED,IAAA,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI;AAChC,QAAA,CAAC,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC;AACjD,QAAA,CAAC,WAAW,CAAC,sBAAsB,EAAE,OAAO,CAAC,SAAS,CAAC;AAC/C,KAAA,EAAE;QACV,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1E,QAAA,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE;AACzB,YAAA,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;gBACtD,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC;gBACrD,QAAQ,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,EAClC;AACA,gBAAA,OAAO,KAAK;YACd;QACF;IACF;AACA,IAAA,OAAO,SAAS;AAClB;;;;"}

package/lib/core/transform/session/adoptedExternalInputMismatch.mjs

@@ -0,0 +1,45 @@
+/**
+ * The first external input whose state differs from what the publisher of an
+ * adopted compile recorded, or `undefined` when both supplied maps agree
+ * (samchon/ttsc#1390).
+ *
+ * The project walk's state names the publication, and the compiler's own graph
+ * and host-input proofs carry compile-time state that any worker can check. A
+ * dependency a plugin reports outside the project has neither: the only
+ * evidence of what the compile read is the state the publisher recorded right
+ * after compiling. An adopter's later reading cannot replace that recorded
+ * state. This comparison requires equal own key sets and values for hashes and
+ * realpath observations. Equality alone does not establish completeness,
+ * compile-window stability or an unavailable physical identity; the
+ * capture/adoption owner checks those.
+ *
+ * @param publication The adopted publication.
+ * @param current This worker's external input snapshot of the same envelope.
+ * @evidence contracts/common.md#principled-implementation Both recorded and current key sets and values must agree for content and physical identity; a missing input on either side refutes adoption.
+ * @evidence contracts/common.md#clear-and-simple-design The same union-of-keys comparison handles the two proof dimensions and returns the first mismatched path without another snapshot layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An adopter's later reading is never treated as the publisher's compile-time state, and inherited object properties cannot masquerade as recorded inputs.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why external inputs need this separate proof and defines the first-mismatch result.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached dimension materializes both own-key arrays and their union before comparing values, so first mismatch does not avoid that dimension's key collection. Expected set work scales with key occurrences and their text; strict realpath comparison also depends on text length. Temporary arrays and the current union scale with that dimension's populations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation compares supplied records without caching or coordinating observations. The caller captures current state and separately decides adoption; map equality does not certify completeness or compile-window validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The comparison borrows both snapshots and retains only local key sets; publication storage and generation lifetime belong to their owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input names and realpath observations are compared exactly as captured, including null observations. No case, separator or alias normalization guesses equivalence; differently represented observations conservatively mismatch. Current completeness and usable physical identity remain capture-owner obligations.
+ */
+function adoptedExternalInputMismatch(publication, current) {
+    for (const [recorded, adopted] of [
+        [publication.externalInputHashes, current.hashes],
+        [publication.externalInputRealpaths, current.realpaths],
+    ]) {
+        const paths = new Set([...Object.keys(recorded), ...Object.keys(adopted)]);
+        for (const input of paths) {
+            if (!Object.prototype.hasOwnProperty.call(recorded, input) ||
+                !Object.prototype.hasOwnProperty.call(adopted, input) ||
+                recorded[input] !== adopted[input]) {
+                return input;
+            }
+        }
+    }
+    return undefined;
+}
+
+export { adoptedExternalInputMismatch };
+//# sourceMappingURL=adoptedExternalInputMismatch.mjs.map

package/lib/core/transform/session/adoptedExternalInputMismatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoptedExternalInputMismatch.mjs","sources":["../../../../src/core/transform/session/adoptedExternalInputMismatch.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACG,SAAU,4BAA4B,CAC1C,WAAyC,EACzC,OAGC,EAAA;AAED,IAAA,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI;AAChC,QAAA,CAAC,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC;AACjD,QAAA,CAAC,WAAW,CAAC,sBAAsB,EAAE,OAAO,CAAC,SAAS,CAAC;AAC/C,KAAA,EAAE;QACV,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1E,QAAA,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE;AACzB,YAAA,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;gBACtD,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC;gBACrD,QAAQ,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,EAClC;AACA,gBAAA,OAAO,KAAK;YACd;QACF;IACF;AACA,IAAA,OAAO,SAAS;AAClB;;;;"}

package/lib/core/transform/session/claimSharedCompile.d.cts

@@ -0,0 +1,110 @@
+import type { TtscSharedCompileClaim } from "./TtscSharedCompileClaim.cjs";
+/**
+ * Ask the session store for the compile named `identity` and `state`: another
+ * worker's publication, or the lock to compile it here (samchon/ttsc#1390).
+ *
+ * `identity` encodes reported compile configuration and `state` a supplied
+ * project-input projection. Neither key alone certifies a publication. The
+ * first worker to need a pair takes its lock by creating a directory, which the
+ * filesystem makes atomic. The others wait without blocking the event loop, and
+ * adopt the publication the holder leaves behind. When the holder releases the
+ * lock without publishing, the next waiter takes the lock instead. A holder
+ * whose process has died, or whose heartbeat stopped, can lose the lock to a
+ * waiter. Waiting has no total deadline or cancellation; progress still depends
+ * on native operations and successful reclamation.
+ *
+ * The store outlives the processes that use it (samchon/ttsc#1483), so it
+ * best-effort prunes itself: an adoption marks its publication used, and each
+ * publication keeps the most recently used ones of its identity within the
+ * store's count and byte budgets, and removes locks and partial writes whose
+ * writer is gone. A publication larger than the byte budget stays in the
+ * compiling worker; it cannot be shared without making persistent storage
+ * unbounded.
+ *
+ * Sharing is only an optimization. An unreadable or unusable publication is
+ * ignored and a worker may claim its own compile. An escaping claim error
+ * answers `undefined`; publishing and cleanup failures are suppressed without
+ * certifying persistence. The caller retains local compilation. With `adopt:
+ * false` the caller has already found a publication wanting and compiles
+ * regardless, but still under the lock, so its compile replaces the publication
+ * for the waiters. A rejectedPublication excludes only that serialized payload:
+ * another worker's replacement under the same projected state remains eligible
+ * for independent adoption proof. The digest is computed from the already read
+ * UTF-8 publication, without another filesystem query.
+ *
+ * Its place in the adapter's invalidation model, and the units beside it, are
+ * mapped in the maintainer page
+ * `website/src/content/docs/development/reference/unplugin-invalidation.mdx`.
+ *
+ * @param store The session's shared compile store.
+ * @param identity Caller-provided hex configuration digest used in store names.
+ * @param state Caller-provided hex project-state digest used in store names.
+ * @param options.adopt Whether an existing publication may be adopted.
+ * @param options.rejectedPublication Digest of the exact previously refuted
+ *   payload; a replacement still requires the caller's full proof.
+ * @evidence contracts/common.md#principled-implementation
+ *   Filesystem directory creation coordinates independent workers, and owned
+ *   tokens distinguish a claim from another holder at the same pathname.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One identity/state claim selects adoption or compile ownership. Private
+ *   helpers separate lock coordination, publication, and bounded retention;
+ *   filesystem failure leaves the caller's local compile path available.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The optional store preserves a local compile path when sharing is
+ *   unavailable rather than changing compile semantics; it uses native APIs
+ *   without replacing foreign methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains why the store is optional, what identity and state name,
+ *   how waiting and abandonment differ, and why retained publications need
+ *   bounds. Purpose and reasons use separate native paragraphs under the
+ *   documentation skill; claim and publication interfaces retain their value
+ *   documentation.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node native paths and filesystem operations own store publication. The
+ *   implementation has a Windows replacement path because an open destination
+ *   may refuse rename; this does not make its ownership checks atomic. The
+ *   remaining pathname-check and replacement windows are recorded for
+ *   investigation rather than asserted OS-safe.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Each waiting iteration may reread and parse all publication bytes, inspect
+ *   envelope fields, probe lock metadata/token/process state and reclaim a
+ *   subtree. Backoff intervals are capped, not iteration count or total time.
+ *   Each valid read additionally hashes its serialized UTF-8 payload in O(bytes)
+ *   time for attempt-local refutation identity. This is not an input proof.
+ *   Publishing serializes the full payload before its UTF8 byte-budget check.
+ *   Pruning materializes all N store names, launches concurrent stats for J
+ *   JSON entries, sorts J last-use observations and scans names again for
+ *   abandoned state. Text comparisons, encoded bytes, native IO and removed
+ *   descendants contribute beyond entry counts; transient state includes full
+ *   publication text/value and O(N+J) lists/promises. Independent processes
+ *   share the inventory, so a process-local index cannot establish its contents.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The supplied identity/state pair coordinates in-flight ownership and
+ *   retained publication lookup. Shape checks reject unusable envelopes but
+ *   do not prove inputs; the producer and adopter supply separate stability,
+ *   completeness and current-state proofs. Caller adopt=false bypasses lookup
+ *   while retaining locking. Repeated claims still reread publication/lock
+ *   state; failed or oversized persistence leaves later workers compiling.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A publication over 256 MiB is not persisted. Each successful publication
+ *   best-effort prunes to four files per identity, 32 store-wide and 256 MiB of
+ *   publication bytes. Concurrent writes, failed removals or failed pruning
+ *   can leave limits exceeded until a later successful prune. Limits do not
+ *   bound live locks, partial-write bytes, waiting claims or concurrent IO.
+ *   A compile claim transfers its unref'd heartbeat and lock to the caller,
+ *   whose release clears the timer and best-effort removes an owned lock;
+ *   publishing alone does not release it. Later prunes reclaim abandoned locks
+ *   and departed-writer partial files. Owner checks followed by pathname IO
+ *   remain non-atomic, including asynchronous heartbeat touches.
+ */
+export declare function claimSharedCompile(store: string, identity: string, state: string, options: {
+    adopt: boolean;
+    rejectedPublication?: string;
+}): Promise<TtscSharedCompileClaim | undefined>;

package/lib/core/transform/session/claimSharedCompile.d.mts

@@ -0,0 +1,110 @@
+import type { TtscSharedCompileClaim } from "./TtscSharedCompileClaim.mjs";
+/**
+ * Ask the session store for the compile named `identity` and `state`: another
+ * worker's publication, or the lock to compile it here (samchon/ttsc#1390).
+ *
+ * `identity` encodes reported compile configuration and `state` a supplied
+ * project-input projection. Neither key alone certifies a publication. The
+ * first worker to need a pair takes its lock by creating a directory, which the
+ * filesystem makes atomic. The others wait without blocking the event loop, and
+ * adopt the publication the holder leaves behind. When the holder releases the
+ * lock without publishing, the next waiter takes the lock instead. A holder
+ * whose process has died, or whose heartbeat stopped, can lose the lock to a
+ * waiter. Waiting has no total deadline or cancellation; progress still depends
+ * on native operations and successful reclamation.
+ *
+ * The store outlives the processes that use it (samchon/ttsc#1483), so it
+ * best-effort prunes itself: an adoption marks its publication used, and each
+ * publication keeps the most recently used ones of its identity within the
+ * store's count and byte budgets, and removes locks and partial writes whose
+ * writer is gone. A publication larger than the byte budget stays in the
+ * compiling worker; it cannot be shared without making persistent storage
+ * unbounded.
+ *
+ * Sharing is only an optimization. An unreadable or unusable publication is
+ * ignored and a worker may claim its own compile. An escaping claim error
+ * answers `undefined`; publishing and cleanup failures are suppressed without
+ * certifying persistence. The caller retains local compilation. With `adopt:
+ * false` the caller has already found a publication wanting and compiles
+ * regardless, but still under the lock, so its compile replaces the publication
+ * for the waiters. A rejectedPublication excludes only that serialized payload:
+ * another worker's replacement under the same projected state remains eligible
+ * for independent adoption proof. The digest is computed from the already read
+ * UTF-8 publication, without another filesystem query.
+ *
+ * Its place in the adapter's invalidation model, and the units beside it, are
+ * mapped in the maintainer page
+ * `website/src/content/docs/development/reference/unplugin-invalidation.mdx`.
+ *
+ * @param store The session's shared compile store.
+ * @param identity Caller-provided hex configuration digest used in store names.
+ * @param state Caller-provided hex project-state digest used in store names.
+ * @param options.adopt Whether an existing publication may be adopted.
+ * @param options.rejectedPublication Digest of the exact previously refuted
+ *   payload; a replacement still requires the caller's full proof.
+ * @evidence contracts/common.md#principled-implementation
+ *   Filesystem directory creation coordinates independent workers, and owned
+ *   tokens distinguish a claim from another holder at the same pathname.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One identity/state claim selects adoption or compile ownership. Private
+ *   helpers separate lock coordination, publication, and bounded retention;
+ *   filesystem failure leaves the caller's local compile path available.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The optional store preserves a local compile path when sharing is
+ *   unavailable rather than changing compile semantics; it uses native APIs
+ *   without replacing foreign methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains why the store is optional, what identity and state name,
+ *   how waiting and abandonment differ, and why retained publications need
+ *   bounds. Purpose and reasons use separate native paragraphs under the
+ *   documentation skill; claim and publication interfaces retain their value
+ *   documentation.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node native paths and filesystem operations own store publication. The
+ *   implementation has a Windows replacement path because an open destination
+ *   may refuse rename; this does not make its ownership checks atomic. The
+ *   remaining pathname-check and replacement windows are recorded for
+ *   investigation rather than asserted OS-safe.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Each waiting iteration may reread and parse all publication bytes, inspect
+ *   envelope fields, probe lock metadata/token/process state and reclaim a
+ *   subtree. Backoff intervals are capped, not iteration count or total time.
+ *   Each valid read additionally hashes its serialized UTF-8 payload in O(bytes)
+ *   time for attempt-local refutation identity. This is not an input proof.
+ *   Publishing serializes the full payload before its UTF8 byte-budget check.
+ *   Pruning materializes all N store names, launches concurrent stats for J
+ *   JSON entries, sorts J last-use observations and scans names again for
+ *   abandoned state. Text comparisons, encoded bytes, native IO and removed
+ *   descendants contribute beyond entry counts; transient state includes full
+ *   publication text/value and O(N+J) lists/promises. Independent processes
+ *   share the inventory, so a process-local index cannot establish its contents.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The supplied identity/state pair coordinates in-flight ownership and
+ *   retained publication lookup. Shape checks reject unusable envelopes but
+ *   do not prove inputs; the producer and adopter supply separate stability,
+ *   completeness and current-state proofs. Caller adopt=false bypasses lookup
+ *   while retaining locking. Repeated claims still reread publication/lock
+ *   state; failed or oversized persistence leaves later workers compiling.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A publication over 256 MiB is not persisted. Each successful publication
+ *   best-effort prunes to four files per identity, 32 store-wide and 256 MiB of
+ *   publication bytes. Concurrent writes, failed removals or failed pruning
+ *   can leave limits exceeded until a later successful prune. Limits do not
+ *   bound live locks, partial-write bytes, waiting claims or concurrent IO.
+ *   A compile claim transfers its unref'd heartbeat and lock to the caller,
+ *   whose release clears the timer and best-effort removes an owned lock;
+ *   publishing alone does not release it. Later prunes reclaim abandoned locks
+ *   and departed-writer partial files. Owner checks followed by pathname IO
+ *   remain non-atomic, including asynchronous heartbeat touches.
+ */
+export declare function claimSharedCompile(store: string, identity: string, state: string, options: {
+    adopt: boolean;
+    rejectedPublication?: string;
+}): Promise<TtscSharedCompileClaim | undefined>;

package/lib/core/transform/session/claimSharedCompile.d.ts

@@ -0,0 +1,110 @@
+import type { TtscSharedCompileClaim } from "./TtscSharedCompileClaim";
+/**
+ * Ask the session store for the compile named `identity` and `state`: another
+ * worker's publication, or the lock to compile it here (samchon/ttsc#1390).
+ *
+ * `identity` encodes reported compile configuration and `state` a supplied
+ * project-input projection. Neither key alone certifies a publication. The
+ * first worker to need a pair takes its lock by creating a directory, which the
+ * filesystem makes atomic. The others wait without blocking the event loop, and
+ * adopt the publication the holder leaves behind. When the holder releases the
+ * lock without publishing, the next waiter takes the lock instead. A holder
+ * whose process has died, or whose heartbeat stopped, can lose the lock to a
+ * waiter. Waiting has no total deadline or cancellation; progress still depends
+ * on native operations and successful reclamation.
+ *
+ * The store outlives the processes that use it (samchon/ttsc#1483), so it
+ * best-effort prunes itself: an adoption marks its publication used, and each
+ * publication keeps the most recently used ones of its identity within the
+ * store's count and byte budgets, and removes locks and partial writes whose
+ * writer is gone. A publication larger than the byte budget stays in the
+ * compiling worker; it cannot be shared without making persistent storage
+ * unbounded.
+ *
+ * Sharing is only an optimization. An unreadable or unusable publication is
+ * ignored and a worker may claim its own compile. An escaping claim error
+ * answers `undefined`; publishing and cleanup failures are suppressed without
+ * certifying persistence. The caller retains local compilation. With `adopt:
+ * false` the caller has already found a publication wanting and compiles
+ * regardless, but still under the lock, so its compile replaces the publication
+ * for the waiters. A rejectedPublication excludes only that serialized payload:
+ * another worker's replacement under the same projected state remains eligible
+ * for independent adoption proof. The digest is computed from the already read
+ * UTF-8 publication, without another filesystem query.
+ *
+ * Its place in the adapter's invalidation model, and the units beside it, are
+ * mapped in the maintainer page
+ * `website/src/content/docs/development/reference/unplugin-invalidation.mdx`.
+ *
+ * @param store The session's shared compile store.
+ * @param identity Caller-provided hex configuration digest used in store names.
+ * @param state Caller-provided hex project-state digest used in store names.
+ * @param options.adopt Whether an existing publication may be adopted.
+ * @param options.rejectedPublication Digest of the exact previously refuted
+ *   payload; a replacement still requires the caller's full proof.
+ * @evidence contracts/common.md#principled-implementation
+ *   Filesystem directory creation coordinates independent workers, and owned
+ *   tokens distinguish a claim from another holder at the same pathname.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One identity/state claim selects adoption or compile ownership. Private
+ *   helpers separate lock coordination, publication, and bounded retention;
+ *   filesystem failure leaves the caller's local compile path available.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The optional store preserves a local compile path when sharing is
+ *   unavailable rather than changing compile semantics; it uses native APIs
+ *   without replacing foreign methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains why the store is optional, what identity and state name,
+ *   how waiting and abandonment differ, and why retained publications need
+ *   bounds. Purpose and reasons use separate native paragraphs under the
+ *   documentation skill; claim and publication interfaces retain their value
+ *   documentation.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node native paths and filesystem operations own store publication. The
+ *   implementation has a Windows replacement path because an open destination
+ *   may refuse rename; this does not make its ownership checks atomic. The
+ *   remaining pathname-check and replacement windows are recorded for
+ *   investigation rather than asserted OS-safe.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Each waiting iteration may reread and parse all publication bytes, inspect
+ *   envelope fields, probe lock metadata/token/process state and reclaim a
+ *   subtree. Backoff intervals are capped, not iteration count or total time.
+ *   Each valid read additionally hashes its serialized UTF-8 payload in O(bytes)
+ *   time for attempt-local refutation identity. This is not an input proof.
+ *   Publishing serializes the full payload before its UTF8 byte-budget check.
+ *   Pruning materializes all N store names, launches concurrent stats for J
+ *   JSON entries, sorts J last-use observations and scans names again for
+ *   abandoned state. Text comparisons, encoded bytes, native IO and removed
+ *   descendants contribute beyond entry counts; transient state includes full
+ *   publication text/value and O(N+J) lists/promises. Independent processes
+ *   share the inventory, so a process-local index cannot establish its contents.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The supplied identity/state pair coordinates in-flight ownership and
+ *   retained publication lookup. Shape checks reject unusable envelopes but
+ *   do not prove inputs; the producer and adopter supply separate stability,
+ *   completeness and current-state proofs. Caller adopt=false bypasses lookup
+ *   while retaining locking. Repeated claims still reread publication/lock
+ *   state; failed or oversized persistence leaves later workers compiling.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A publication over 256 MiB is not persisted. Each successful publication
+ *   best-effort prunes to four files per identity, 32 store-wide and 256 MiB of
+ *   publication bytes. Concurrent writes, failed removals or failed pruning
+ *   can leave limits exceeded until a later successful prune. Limits do not
+ *   bound live locks, partial-write bytes, waiting claims or concurrent IO.
+ *   A compile claim transfers its unref'd heartbeat and lock to the caller,
+ *   whose release clears the timer and best-effort removes an owned lock;
+ *   publishing alone does not release it. Later prunes reclaim abandoned locks
+ *   and departed-writer partial files. Owner checks followed by pathname IO
+ *   remain non-atomic, including asynchronous heartbeat touches.
+ */
+export declare function claimSharedCompile(store: string, identity: string, state: string, options: {
+    adopt: boolean;
+    rejectedPublication?: string;
+}): Promise<TtscSharedCompileClaim | undefined>;