ttsc 0.30.4 → 0.31.1

package/lib/plugin/internal/source/inspectPluginBuildLock.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectPluginBuildLock = inspectPluginBuildLock;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceNativeRetirement_1 = require("../../../internal/SourceNativeRetirement");
+const isContendedCandidateRename_1 = require("../../../internal/isContendedCandidateRename");
+const PluginBuildLockOwner_1 = require("./PluginBuildLockOwner");
+const PluginBuildLockProtocol_1 = require("./PluginBuildLockProtocol");
+/**
+ * Classify the current state of a plugin build lock directory.
+ *
+ * Occupied v3 observations register this process as a fence holder and confirm
+ * the generation before returning. These records move into its tombstone and
+ * remain until the observer is provably gone. No heartbeat or timeout
+ * establishes that a live observer cannot act.
+ *
+ * An owner record whose generation is missing or mismatched remains active and
+ * inconclusive: another generation's absent PID cannot authorize this one.
+ * Unusable owner metadata also remains inconclusive regardless of age. Ordinary
+ * v3 publication includes the complete owner record; old legacy builders could
+ * continue after best-effort owner publication failed.
+ *
+ * Unknown or malformed native guards refuse same-key observations. Pending
+ * guards preserve active ownership even when the Node holder is absent, so
+ * bounded wait cannot turn PID or age into native reclamation authority.
+ *
+ * @evidence contracts/common.md#principled-implementation An observer is registered under a captured generation before owner classification; generation rechecks prevent a replacement from inheriting the captured fence, whose reserved retirement destination survives the builder's death.
+ * @evidence contracts/common.md#clear-and-simple-design Protocol selection, generation observation and legacy fence capture have separate helpers; the public result distinguishes absence from active and abandoned ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A replaced generation causes re-observation or a released handoff; ambiguous process errors are not interpreted as death, and observer age cannot replace liveness proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe observer registration, token retention and inconclusive owner metadata before the tags; private comments explain generation races and legacy record compatibility.
+ * @evidence contracts/portability.md#os-neutral-implementation Node filesystem and path APIs carry native access, while ESRCH-only local probing distinguishes absent processes from permission failure or remote identity.
+ * @evidence contracts/performance.md#efficient-algorithms Each observation scans native guards before direct generation paths; it does not scan generation directories; costs include native path resolution and protocol/generation/owner/fence JSON bytes, hostname checks and optional liveness probes. Publication adds candidate writes/rename/recursive cleanup. Failed v3 registration or changing legacy capture can re-enter the synchronous loop, which has no attempt or elapsed-time bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work A module's nonce shares one observer registration across polls of the same generation; liveness and current identity remain freshly observed because they can change between requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate records have finally cleanup that can fail, including after publication. Published records remain under the cooperating collector policy until observer absence is proven; distinct generations observed by live/unknown processes have no count or age bound here. Continued pathname churn may retain this synchronous observation without a deadline; it starts no asynchronous task.
+ */
+function inspectPluginBuildLock(lockDir) {
+    const protocolDir = PluginBuildLockProtocol_1.PluginBuildLockProtocol.pluginBuildLockProtocolDir(lockDir);
+    SourceNativeRetirement_1.SourceNativeRetirement.assertAvailable(protocolDir);
+    for (;;) {
+        if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockProtocolV3(protocolDir)) {
+            const current = inspectV3PluginBuildLock(protocolDir);
+            if (current.state !== "released") {
+                return current;
+            }
+        }
+        const legacy = captureLegacyPluginBuildLockFence(lockDir);
+        if (legacy !== null) {
+            return inspectLegacyPluginBuildLock(lockDir, legacy);
+        }
+        if (pluginBuildLockPathMissing(lockDir)) {
+            return { state: "released" };
+        }
+        // The path changed while its legacy fence was being captured. Re-observe
+        // the replacement rather than attaching the old state to a new owner.
+    }
+}
+// Each loaded module records one observer per generation. A random process
+// incarnation token keeps a reused PID or another worker's module separate.
+const PLUGIN_BUILD_LOCK_OBSERVER = node_crypto_1.default.randomBytes(16).toString("hex");
+function inspectV3PluginBuildLock(lockDir) {
+    const generationDir = node_path_1.default.join(lockDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_CURRENT_DIR);
+    const generation = readPluginBuildLockGeneration(generationDir);
+    if (generation === null) {
+        if (pluginBuildLockPathMissing(generationDir)) {
+            return { state: "released" };
+        }
+        throw new Error(`ttsc plugin build lock has no valid ${PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE}: ${generationDir}`);
+    }
+    if (!registerPluginBuildLockObserver(lockDir, generationDir, generation)) {
+        return { state: "released" };
+    }
+    const fence = { protocol: "v3", generation };
+    const owner = PluginBuildLockOwner_1.PluginBuildLockOwner.read(generationDir);
+    // Owner and generation are read through a mutable current pathname. A
+    // replacement must not inherit an earlier generation's liveness decision.
+    if (readPluginBuildLockGeneration(generationDir) !== generation) {
+        return { state: "released" };
+    }
+    if (owner !== null) {
+        const label = PluginBuildLockOwner_1.PluginBuildLockOwner.describe(owner);
+        if (owner.generation !== generation) {
+            return {
+                state: "active",
+                owner: `${label} with unconfirmed generation metadata`,
+                fence,
+            };
+        }
+        if (PluginBuildLockOwner_1.PluginBuildLockOwner.gone(owner)) {
+            if (SourceNativeRetirement_1.SourceNativeRetirement.isProtected(lockDir))
+                return {
+                    state: "active",
+                    owner: `${label} with native retirement pending`,
+                    fence,
+                };
+            return {
+                state: "abandoned",
+                reason: `${label} is no longer running`,
+                fence,
+            };
+        }
+        return {
+            state: "active",
+            owner: label,
+            fence,
+        };
+    }
+    // Normal v3 publication includes a complete owner record. Its absence or
+    // unreadability is inconclusive, not a creator window that age can expire.
+    return {
+        state: "active",
+        owner: `lock generation with unconfirmed ${PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+        fence,
+    };
+}
+/**
+ * Publish this process's fence ownership before returning an observation. A
+ * claim moves with current into its tombstone. Retirement prevents further
+ * claims from entering that old generation, so collection sees a closed set.
+ */
+function registerPluginBuildLockObserver(protocolDir, generationDir, generation) {
+    const observers = node_path_1.default.join(generationDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OBSERVERS_DIR);
+    const observer = node_path_1.default.join(observers, PLUGIN_BUILD_LOCK_OBSERVER);
+    try {
+        node_fs_1.default.mkdirSync(observers);
+    }
+    catch (error) {
+        if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error))
+            return false;
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    if (!node_fs_1.default.existsSync(observer)) {
+        const candidate = node_path_1.default.join(protocolDir, `observer-candidate-${PLUGIN_BUILD_LOCK_OBSERVER}-${generation}`);
+        node_fs_1.default.mkdirSync(candidate);
+        try {
+            node_fs_1.default.writeFileSync(node_path_1.default.join(candidate, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE), `${JSON.stringify({ hostname: node_os_1.default.hostname(), pid: process.pid })}\n`, { encoding: "utf8", flag: "wx" });
+            try {
+                node_fs_1.default.renameSync(candidate, observer);
+            }
+            catch (error) {
+                if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error))
+                    return false;
+                if (!PluginBuildLockProtocol_1.PluginBuildLockProtocol.isRenameDestinationOccupied(error, observer))
+                    throw error;
+            }
+        }
+        finally {
+            node_fs_1.default.rmSync(candidate, { force: true, recursive: true });
+        }
+    }
+    // A claim accidentally published into a successor cannot authorize the old
+    // fence. Its harmless extra record is collected when this process exits.
+    return readPluginBuildLockGeneration(generationDir) === generation;
+}
+function inspectLegacyPluginBuildLock(lockDir, legacy) {
+    const owner = PluginBuildLockOwner_1.PluginBuildLockOwner.read(lockDir);
+    if (owner !== null) {
+        const label = PluginBuildLockOwner_1.PluginBuildLockOwner.describe(owner);
+        if (PluginBuildLockOwner_1.PluginBuildLockOwner.gone(owner)) {
+            return {
+                state: "abandoned",
+                reason: `${label} is no longer running`,
+                fence: legacy.fence,
+            };
+        }
+        return {
+            state: "active",
+            owner: label,
+            fence: legacy.fence,
+        };
+    }
+    // Old builders treated owner publication as best effort and could continue
+    // working without that file. Directory age cannot prove their task ended.
+    return {
+        state: "active",
+        owner: `legacy lock with unconfirmed ${PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+        fence: legacy.fence,
+    };
+}
+function captureLegacyPluginBuildLockFence(lockDir) {
+    if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockProtocolV3(lockDir)) {
+        return null;
+    }
+    let legacyMtimeMs;
+    try {
+        legacyMtimeMs = node_fs_1.default.statSync(lockDir).mtimeMs;
+    }
+    catch (error) {
+        if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error))
+            return null;
+        throw error;
+    }
+    const fenceDir = node_path_1.default.join(lockDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR);
+    let captured = PluginBuildLockProtocol_1.PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+    if (captured === null) {
+        const generation = node_crypto_1.default.randomBytes(16).toString("hex");
+        // Keep candidates beside the legacy lock. Creating one inside `lockDir`
+        // would advance its mtime before a contender publishes the shared fence;
+        // a concurrent contender could then record an old lock as freshly created.
+        const candidateDir = `${lockDir}.legacy-candidate-${generation}`;
+        try {
+            node_fs_1.default.mkdirSync(candidateDir);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(candidateDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD), `${JSON.stringify({ generation, legacyMtimeMs })}\n`, "utf8");
+            try {
+                node_fs_1.default.renameSync(candidateDir, fenceDir);
+                captured = {
+                    fence: { protocol: "legacy", generation },
+                    legacyMtimeMs,
+                };
+            }
+            catch (error) {
+                if ((0, isContendedCandidateRename_1.isContendedCandidateRename)(error)) {
+                    captured =
+                        PluginBuildLockProtocol_1.PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+                    // The fence lives inside the legacy lock, so a fence another
+                    // process recorded and that is gone by now went with a lock that
+                    // was released or retired meanwhile.
+                    if (captured === null && !node_fs_1.default.existsSync(fenceDir))
+                        return null;
+                }
+                else if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error)) {
+                    return null;
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error)) {
+                return null;
+            }
+            throw error;
+        }
+        finally {
+            node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+        }
+    }
+    if (captured === null) {
+        throw new Error(`invalid legacy plugin build lock fence: ${fenceDir}`);
+    }
+    // A stale observer can resume after the legacy holder released or another
+    // process retired the path. Confirm both the legacy layout and token after
+    // publication; v3 ownership is kept in the orthogonal sibling directory.
+    const confirmed = PluginBuildLockProtocol_1.PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+    if (PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockProtocolV3(lockDir) ||
+        confirmed === null ||
+        confirmed.fence.generation !== captured.fence.generation) {
+        return null;
+    }
+    return captured;
+}
+function readPluginBuildLockGeneration(generationDir) {
+    try {
+        const generation = node_fs_1.default
+            .readFileSync(node_path_1.default.join(generationDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE), "utf8")
+            .trim();
+        return PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockGeneration(generation)
+            ? generation
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a path lookup proves absence. Permission and sharing failures are
+ * inconclusive, never evidence of a released or old abandoned generation.
+ */
+function pluginBuildLockPathMissing(lockDir) {
+    try {
+        node_fs_1.default.statSync(lockDir);
+        return false;
+    }
+    catch (error) {
+        return PluginBuildLockProtocol_1.PluginBuildLockProtocol.isMissingPathError(error);
+    }
+}
+//# sourceMappingURL=inspectPluginBuildLock.js.map

package/lib/plugin/internal/source/inspectPluginBuildLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspectPluginBuildLock.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/inspectPluginBuildLock.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/isPathWithin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Report whether `child` equals `parent` or is lexically nested beneath it.
+ *
+ * This does not resolve symlinks or establish physical containment.
+ *
+ * @evidence contracts/common.md#principled-implementation Empty relative paths establish equality; rejecting parent traversal and absolute relative results excludes ancestors, siblings and other native volumes.
+ * @evidence contracts/common.md#clear-and-simple-design One lexical predicate exposes containment without mixing physical realpath resolution into callers' already-resolved paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Parent traversal is checked by path components rather than an unsafe string-prefix exception for particular directories.
+ * @evidence contracts/common.md#meaningful-documentation The native comment distinguishes lexical nesting from symlink-safe physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.relative, separator and absolute-path rules cover volume and parent boundaries without inferring filesystem case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated native relative-path construction and prefix checks process supplied path text without enumerating directories. Node's Windows Unicode-folding fallback can allocate component arrays; relative inputs may also consult current-directory state during resolution. Temporary strings/arrays follow those delegated path lengths rather than a fixed allocation count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate compares supplied paths and stores no cross-request result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query retains no handle or state and performs no direct filesystem-entry inspection; any current-directory resolution belongs to the native path operation.
+ */
+export declare function isPathWithin(child: string, parent: string): boolean;

package/lib/plugin/internal/source/isPathWithin.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathWithin = isPathWithin;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Report whether `child` equals `parent` or is lexically nested beneath it.
+ *
+ * This does not resolve symlinks or establish physical containment.
+ *
+ * @evidence contracts/common.md#principled-implementation Empty relative paths establish equality; rejecting parent traversal and absolute relative results excludes ancestors, siblings and other native volumes.
+ * @evidence contracts/common.md#clear-and-simple-design One lexical predicate exposes containment without mixing physical realpath resolution into callers' already-resolved paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Parent traversal is checked by path components rather than an unsafe string-prefix exception for particular directories.
+ * @evidence contracts/common.md#meaningful-documentation The native comment distinguishes lexical nesting from symlink-safe physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.relative, separator and absolute-path rules cover volume and parent boundaries without inferring filesystem case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated native relative-path construction and prefix checks process supplied path text without enumerating directories. Node's Windows Unicode-folding fallback can allocate component arrays; relative inputs may also consult current-directory state during resolution. Temporary strings/arrays follow those delegated path lengths rather than a fixed allocation count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate compares supplied paths and stores no cross-request result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query retains no handle or state and performs no direct filesystem-entry inspection; any current-directory resolution belongs to the native path operation.
+ */
+function isPathWithin(child, parent) {
+    const rel = node_path_1.default.relative(parent, child);
+    return (rel === "" ||
+        (rel !== ".." && !rel.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(rel)));
+}
+//# sourceMappingURL=isPathWithin.js.map

package/lib/plugin/internal/source/isPathWithin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPathWithin.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/isPathWithin.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;GAcG;AACH,sBAA6B,KAAa,EAAE,MAAc;IACxD,MAAM,GAAG,GAAG,mBAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,CACL,GAAG,KAAK,EAAE;QACV,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,mBAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAC5E,CAAC;AACJ,CAAC"}

package/lib/plugin/internal/source/legacyGlobalCacheTargets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Machine-global cache directories created by pre-0.17 ttsc releases (XDG /
+ * AppData / Library / `~/.cache`). The current default no longer selects these
+ * machine-global roots, though an explicit override can select them. An
+ * upgraded machine can still hold a multi-GB orphaned cache here, so `ttsc
+ * clean` offers them for removal to reclaim that disk. Each entry is the whole
+ * `<userCacheRoot>/ttsc` directory (both its `plugins` and `go-build`), which
+ * was ttsc-owned in those releases. The cleanup transaction still validates
+ * present-day physical ownership and protected directories before deletion.
+ *
+ * The same holds for `<os.tmpdir()>/ttsc-orphan`, where releases that lowered
+ * orphan sources for every run without `TTSC_CACHE_DIR` and never collected
+ * them.
+ *
+ * @evidence contracts/common.md#principled-implementation The set enumerates historically authored ttsc cache locations, accepting environment cache bases only when absolute.
+ * @evidence contracts/common.md#clear-and-simple-design One migration query deduplicates the finite platform-specific candidates without deleting them.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform-specific paths represent actual prior layouts, not compensation for a disproven current-root assumption.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes historical roots from the current workspace policy and explains migration cleanup ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation os.homedir/tmpdir and native path.join provide host bases; explicit Windows/macOS historical layouts are isolated in this migration boundary and relative environment bases are rejected.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a fresh array; the Set is local to the call.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed candidate count is deduplicated through a call-local Set. Native home/tmp lookup, supplied environment-path text and joined result strings still contribute processing and temporary storage; no directory population is traversed here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The list is recomputed from the environment on each call and no cache is kept.
+ */
+export declare function legacyGlobalCacheTargets(): string[];

package/lib/plugin/internal/source/legacyGlobalCacheTargets.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.legacyGlobalCacheTargets = legacyGlobalCacheTargets;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+/**
+ * Machine-global cache directories created by pre-0.17 ttsc releases (XDG /
+ * AppData / Library / `~/.cache`). The current default no longer selects these
+ * machine-global roots, though an explicit override can select them. An
+ * upgraded machine can still hold a multi-GB orphaned cache here, so `ttsc
+ * clean` offers them for removal to reclaim that disk. Each entry is the whole
+ * `<userCacheRoot>/ttsc` directory (both its `plugins` and `go-build`), which
+ * was ttsc-owned in those releases. The cleanup transaction still validates
+ * present-day physical ownership and protected directories before deletion.
+ *
+ * The same holds for `<os.tmpdir()>/ttsc-orphan`, where releases that lowered
+ * orphan sources for every run without `TTSC_CACHE_DIR` and never collected
+ * them.
+ *
+ * @evidence contracts/common.md#principled-implementation The set enumerates historically authored ttsc cache locations, accepting environment cache bases only when absolute.
+ * @evidence contracts/common.md#clear-and-simple-design One migration query deduplicates the finite platform-specific candidates without deleting them.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform-specific paths represent actual prior layouts, not compensation for a disproven current-root assumption.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes historical roots from the current workspace policy and explains migration cleanup ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation os.homedir/tmpdir and native path.join provide host bases; explicit Windows/macOS historical layouts are isolated in this migration boundary and relative environment bases are rejected.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a fresh array; the Set is local to the call.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed candidate count is deduplicated through a call-local Set. Native home/tmp lookup, supplied environment-path text and joined result strings still contribute processing and temporary storage; no directory population is traversed here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The list is recomputed from the environment on each call and no cache is kept.
+ */
+function legacyGlobalCacheTargets() {
+    const roots = new Set();
+    const home = node_os_1.default.homedir();
+    const xdg = process.env.XDG_CACHE_HOME;
+    if (xdg && node_path_1.default.isAbsolute(xdg)) {
+        roots.add(node_path_1.default.join(xdg, SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+    }
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA;
+        if (local && node_path_1.default.isAbsolute(local)) {
+            roots.add(node_path_1.default.join(local, SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+        }
+        if (home) {
+            roots.add(node_path_1.default.join(home, "AppData", "Local", SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+        }
+    }
+    else if (process.platform === "darwin" && home) {
+        roots.add(node_path_1.default.join(home, "Library", "Caches", SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+    }
+    if (home) {
+        roots.add(node_path_1.default.join(home, ".cache", SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+    }
+    roots.add(node_path_1.default.join(node_os_1.default.tmpdir(), LEGACY_ORPHAN_CACHE_DIRNAME));
+    return [...roots];
+}
+/** The temporary-directory parent of the orphan cache in earlier releases. */
+const LEGACY_ORPHAN_CACHE_DIRNAME = "ttsc-orphan";
+//# sourceMappingURL=legacyGlobalCacheTargets.js.map

package/lib/plugin/internal/source/legacyGlobalCacheTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyGlobalCacheTargets.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/legacyGlobalCacheTargets.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IACE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,IAAI,GAAG,iBAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACvC,IAAI,GAAG,IAAI,mBAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,GAAG,CAAC,mBAAI,CAAC,IAAI,CAAC,GAAG,EAAE,+CAAsB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QACvC,IAAI,KAAK,IAAI,mBAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACpC,KAAK,CAAC,GAAG,CAAC,mBAAI,CAAC,IAAI,CAAC,KAAK,EAAE,+CAAsB,CAAC,kBAAkB,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;YACT,KAAK,CAAC,GAAG,CACP,mBAAI,CAAC,IAAI,CACP,IAAI,EACJ,SAAS,EACT,OAAO,EACP,+CAAsB,CAAC,kBAAkB,CAC1C,CACF,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,EAAE,CAAC;QACjD,KAAK,CAAC,GAAG,CACP,mBAAI,CAAC,IAAI,CACP,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,+CAAsB,CAAC,kBAAkB,CAC1C,CACF,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,GAAG,CACP,mBAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,+CAAsB,CAAC,kBAAkB,CAAC,CACrE,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,mBAAI,CAAC,IAAI,CAAC,iBAAE,CAAC,MAAM,EAAE,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,MAAM,2BAA2B,GAAG,aAAa,CAAC"}

package/lib/plugin/internal/source/pluginBuildEnvironment.d.ts

@@ -0,0 +1,31 @@
+import type { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+/**
+ * The digest of the environment a plugin build in `directory` is keyed on: the
+ * Go compiler the build resolves there, the Go build environment `go env`
+ * reports there, and the external toolchain environment
+ * (`hashPluginBuildEnvironment`).
+ *
+ * The compiler is resolved as the build resolves it (`resolveGoCompiler`, then
+ * the toolchain `directory` selects), so for a plugin's own module root this is
+ * the selected identity used by its binary key; it does not certify arbitrary
+ * unobserved tool/launcher inputs. A normal reading probes `go env` and walks
+ * GOROOT metadata. Witnessing a newly selected environment file can repeat the
+ * probe to observe it before reading. Compiler identity reuses a
+ * metadata-and-context memo; a changed SDK manifest rehashes all contributing
+ * content rather than only edited files.
+ *
+ * @param directory The directory a build runs `go` in.
+ * @param env The effective environment, `process.env` by default.
+ * @param witness Receives the paths the reading depends on and no variable
+ *   carries (`hashPluginBuildEnvironment`).
+ * @evidence contracts/common.md#principled-implementation The digest uses the same resolved compiler and environment serializer as the binary key, so reported toolchain state denotes the inputs actually used by the build.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler selection, executable resolution and hashing each stay with their owning helper; this function only composes one environment reading.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result comes from real Go/environment inputs, not a fixed compiler version or a caller-specific substitute.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation identifies the module-directory meaning, cost and witness output, with parameter descriptions and separated acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Executable identity is resolved before probing, and Node filesystem/process boundaries implement native spelling rather than assuming Windows or POSIX paths are interchangeable.
+ * @evidence contracts/performance.md#efficient-algorithms The wrapper resolves the compiler/tool under the supplied environment before delegating full environment hashing. Native resolution/probes, SDK metadata/name/path sorting and changed-manifest full content reads contribute cost; the final hash output is fixed-width but streamed identity/input text and full-file buffers are not. No independent duplicate source-directory digest scan is added here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is the fresh-reading boundary required by builds; processPluginBuildEnvironment owns reuse when a consumer permits it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Its digest and filesystem adapter are call-local; retained compiler/content memo ownership belongs to the hasher.
+ */
+export declare function pluginBuildEnvironment(directory: string, env?: NodeJS.ProcessEnv, witness?: PluginBuildEnvironmentWitness.Record): string;

package/lib/plugin/internal/source/pluginBuildEnvironment.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginBuildEnvironment = pluginBuildEnvironment;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const GoToolResolution_1 = require("./GoToolResolution");
+const hashPluginBuildEnvironment_1 = require("./hashPluginBuildEnvironment");
+const resolveGoCompiler_1 = require("./resolveGoCompiler");
+/**
+ * The digest of the environment a plugin build in `directory` is keyed on: the
+ * Go compiler the build resolves there, the Go build environment `go env`
+ * reports there, and the external toolchain environment
+ * (`hashPluginBuildEnvironment`).
+ *
+ * The compiler is resolved as the build resolves it (`resolveGoCompiler`, then
+ * the toolchain `directory` selects), so for a plugin's own module root this is
+ * the selected identity used by its binary key; it does not certify arbitrary
+ * unobserved tool/launcher inputs. A normal reading probes `go env` and walks
+ * GOROOT metadata. Witnessing a newly selected environment file can repeat the
+ * probe to observe it before reading. Compiler identity reuses a
+ * metadata-and-context memo; a changed SDK manifest rehashes all contributing
+ * content rather than only edited files.
+ *
+ * @param directory The directory a build runs `go` in.
+ * @param env The effective environment, `process.env` by default.
+ * @param witness Receives the paths the reading depends on and no variable
+ *   carries (`hashPluginBuildEnvironment`).
+ * @evidence contracts/common.md#principled-implementation The digest uses the same resolved compiler and environment serializer as the binary key, so reported toolchain state denotes the inputs actually used by the build.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler selection, executable resolution and hashing each stay with their owning helper; this function only composes one environment reading.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result comes from real Go/environment inputs, not a fixed compiler version or a caller-specific substitute.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation identifies the module-directory meaning, cost and witness output, with parameter descriptions and separated acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Executable identity is resolved before probing, and Node filesystem/process boundaries implement native spelling rather than assuming Windows or POSIX paths are interchangeable.
+ * @evidence contracts/performance.md#efficient-algorithms The wrapper resolves the compiler/tool under the supplied environment before delegating full environment hashing. Native resolution/probes, SDK metadata/name/path sorting and changed-manifest full content reads contribute cost; the final hash output is fixed-width but streamed identity/input text and full-file buffers are not. No independent duplicate source-directory digest scan is added here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is the fresh-reading boundary required by builds; processPluginBuildEnvironment owns reuse when a consumer permits it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Its digest and filesystem adapter are call-local; retained compiler/content memo ownership belongs to the hasher.
+ */
+function pluginBuildEnvironment(directory, env = process.env, witness) {
+    const goBinary = GoToolResolution_1.GoToolResolution.resolveGoToolForBuild((0, resolveGoCompiler_1.resolveGoCompiler)(env).binary, env, directory, witness);
+    const hash = node_crypto_1.default.createHash("sha256");
+    (0, hashPluginBuildEnvironment_1.hashPluginBuildEnvironment)(hash, goBinary, directory, env, { readFile: (location) => node_fs_1.default.readFileSync(location) }, witness);
+    return hash.digest("hex");
+}
+//# sourceMappingURL=pluginBuildEnvironment.js.map

package/lib/plugin/internal/source/pluginBuildEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginBuildEnvironment.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginBuildEnvironment.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AACjC,sDAAyB;AAEzB,yDAAsD;AAEtD,6EAA0E;AAC1E,2DAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,gCACE,SAAiB,EACjB,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,OAA8C;IAE9C,MAAM,QAAQ,GAAG,mCAAgB,CAAC,qBAAqB,CACrD,IAAA,qCAAiB,EAAC,GAAG,CAAC,CAAC,MAAM,EAC7B,GAAG,EACH,SAAS,EACT,OAAO,CACR,CAAC;IACF,MAAM,IAAI,GAAG,qBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAA,uDAA0B,EACxB,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,GAAG,EACH,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,iBAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,EACrD,OAAO,CACR,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}

package/lib/plugin/internal/source/pluginBuildEnvironmentWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/plugin/internal/source/pluginBuildEnvironmentWorker.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_worker_threads_1 = require("node:worker_threads");
+const serializeCompilerError_1 = require("../../../internal/serializeCompilerError");
+const pluginBuildEnvironment_1 = require("./pluginBuildEnvironment");
+/**
+ * Observe one requested native toolchain environment on the exclusive worker.
+ * Explicit environment values reach every Go/toolchain reader; no caller
+ * process globals are written. Only actual readings and pre-read witnesses
+ * cross the worker boundary, and failures retain their real error details.
+ */
+node_worker_threads_1.parentPort?.on("message", (request) => {
+    try {
+        const witness = new Map();
+        node_worker_threads_1.parentPort.postMessage({
+            environment: (0, pluginBuildEnvironment_1.pluginBuildEnvironment)(request.directory, request.env, witness),
+            witness,
+        });
+    }
+    catch (error) {
+        node_worker_threads_1.parentPort.postMessage({ thrown: (0, serializeCompilerError_1.serializeCompilerError)(error) });
+    }
+});
+//# sourceMappingURL=pluginBuildEnvironmentWorker.js.map

package/lib/plugin/internal/source/pluginBuildEnvironmentWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginBuildEnvironmentWorker.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginBuildEnvironmentWorker.ts"],"names":[],"mappings":";;AAAA,6DAAiD;AAEjD,qFAAkF;AAElF,qEAAkE;AAElE;;;;;GAKG;AACH,gCAAU,EAAE,EAAE,CACZ,SAAS,EACT,CAAC,OAAsD,EAAE,EAAE;IACzD,IAAI,CAAC;QACH,MAAM,OAAO,GAAyC,IAAI,GAAG,EAAE,CAAC;QAChE,gCAAW,CAAC,WAAW,CAAC;YACtB,WAAW,EAAE,IAAA,+CAAsB,EACjC,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,GAAG,EACX,OAAO,CACR;YACD,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gCAAW,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,IAAA,+CAAsB,EAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC,CACF,CAAC"}

package/lib/plugin/internal/source/pluginBuildVersions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-version labels used by plugin build keys (`computeCacheKey`) and
+ * persisted transform identities. These are metadata inputs, not a measurement
+ * of the executable actually selected for an invocation.
+ *
+ * Transform reuse also depends on inputs, plugin sources, build environment and
+ * the producer's declared proofs; these labels alone certify none of them. A
+ * consumer that keeps a transform's output beyond the process that produced it,
+ * as a persisted shared compile of `@ttsc/unplugin` is, names it by these
+ * versions with the rule the build applies instead of a copy of it: ttsc's own
+ * package version, and the version of the `typescript` package the project
+ * resolves, or `"unknown"` when resolution/read/parse fails or its version is
+ * absent. The host label falls back to `"0.0.0"` and is cached even after an
+ * unsuccessful first read. The host installation is assumed stable for the
+ * process lifetime; changing its manifest does not refresh that label.
+ *
+ * @param projectRoot The project base used to resolve
+ *   `typescript/package.json`.
+ * @evidence contracts/common.md#principled-implementation Package-version labels supply the same metadata tuple used by plugin keys; absent/unreadable metadata receives the documented unknown/default label rather than an executable identity certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Host-version and project-version readers are separate because one installation is stable within the process while project resolution varies per call.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Node package resolution determines the actual project dependency; no particular project or fixture version is embedded.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains persisted-output consumers, metadata fallbacks and the process-stable host premise without claiming that version labels establish executable or output equivalence.
+ * @evidence contracts/portability.md#os-neutral-implementation Node createRequire and path APIs locate package metadata using native module resolution without manual separator or case normalization.
+ * @evidence contracts/performance.md#efficient-algorithms Each call performs project package resolution and, when successful, reads/parses its manifest bytes; module search/path work and metadata size are not fixed by one logical manifest lookup. The host manifest is attempted only on the first invocation, including native path and JSON costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work All callers share the host installation's process-stable version; the project compiler version is resolved afresh so different project roots do not share a false identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This helper retains one host-version label for the process lifetime, whose text follows its manifest value rather than a fixed byte limit; the helper's retained label count is independent of project count. Native module-resolution caches belong to Node, and synchronous file reads leave no persistent descriptor here.
+ */
+export declare function pluginBuildVersions(projectRoot: string): {
+    tsgo: string;
+    ttsc: string;
+};