ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordCacheFileUse = recordCacheFileUse;
+const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * Record a use of a single-file cache entry by setting its modification time,
+ * which `pruneCacheFileRoot` reads as its last use. A hit that cannot record it
+ * still answers: the entry may then age out a use early and be computed again.
+ *
+ * Pre-existing symbolic or multiply linked entries are left untouched so a
+ * restored alias is rejected by the initial lstat. The later path-based utimes
+ * is a separate operation, not an atomic inode-identity check against
+ * replacement.
+ *
+ * @evidence contracts/common.md#principled-implementation A successful cache hit advances the file's mtime used by age/LRU pruning; a failed refresh cannot invalidate an already obtained answer.
+ * @evidence contracts/common.md#clear-and-simple-design This helper changes only usage metadata and leaves answer validation to the reader and eviction to the collector.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual hit usage drives the timestamp, without recognized keys, expected answers or foreign API patches.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain failed-refresh consequences and pre-existing alias rejection without confusing usage metadata with answer validity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node utimes uses native file timestamp semantics; callers supply an owned cache entry and failures are tolerated rather than assuming a platform's open-file permissions.
+ * @evidence contracts/performance.md#efficient-algorithms An lstat admission probe precedes at most one timestamp update, avoiding answer-byte rewrites. Both are synchronous native path operations with path-text and filesystem costs, not a constant elapsed-time bound.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The owning reader validates equivalent answers; this helper merely records a completed hit.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Best-effort mtime updates influence the collector's age/LRU policy using the current wall clock; skipped/failed refreshes or clock changes do not guarantee postponement. This helper retains no handle and provides no storage-size bound.
+ */
+function recordCacheFileUse(file) {
+    try {
+        const stats = node_fs_1.default.lstatSync(file);
+        // A restored cache can contain aliases to an unrelated inode. Do not
+        // refresh their metadata merely because a reader obtained a valid answer.
+        if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1)
+            return;
+        const now = new Date();
+        node_fs_1.default.utimesSync(file, now, now);
+    }
+    catch {
+        // The entry was removed or cannot be touched; the answer stands.
+    }
+}
+//# sourceMappingURL=recordCacheFileUse.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recordCacheFileUse.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/recordCacheFileUse.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AAEzB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4BAAmC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,iBAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,qEAAqE;QACrE,0EAA0E;QAC1E,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,cAAc,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC;YAAE,OAAO;QAC3E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,iBAAE,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,33 @@
+import type { PluginBuildLockLease } from "./PluginBuildLockLease";
+/**
+ * Retire a held v3 generation during the holder's finally. False means the
+ * generation already retired or disappeared, or native closure remains unknown
+ * and the original cleanup callback was deferred; unexpected filesystem errors
+ * propagate to the caller's release reporting boundary. Ordinary synchronous
+ * contention retains its existing retries. Scoped cancellation uses the shared
+ * retirement helper's cleanup grace and reports a continuing refusal as
+ * ownership failure to the opted-in request owner.
+ *
+ * Scoped native boundaries additionally require qualified closure; unknown
+ * retirement retains the exact generation and defers this callback for
+ * recovery.
+ *
+ * Call only after the held payload callback has ended. Release records that
+ * completion in this exact retired generation, even if a waiter retired it
+ * first. A timeout or lease transfer alone does not satisfy this precondition.
+ * Unconfirmed metadata or failed publication leaves task completion unproven,
+ * so cache maintenance conservatively protects the payload while its owner may
+ * still act.
+ *
+ * @evidence contracts/common.md#principled-implementation The lease's generation selects its reserved tombstone; only a matching generation file, owner identity and completion nonce permit atomic completion publication after the actual payload callback ends.
+ * @evidence contracts/common.md#clear-and-simple-design Release delegates retirement and owns exact-generation completion publication; callers own actual callback completion, finally scheduling and error reporting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release renames the leased generation into retained history rather than recursively deleting a possibly replaced current directory.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain return/error behavior and the actual-task-end precondition, distinguishing completion publication from timeout or lease transfer before the tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path construction and the shared rename adapter preserve the same retirement meaning across Windows sharing refusals and POSIX contention.
+ * @evidence contracts/performance.md#efficient-algorithms Retirement checks guard metadata before direct completion paths, avoiding owner-population scans; costs include native path construction, owner JSON/hostname and generation bytes plus marker publication. Eligible Windows refusals repeat synchronous waits and sibling probes after a sampled sibling rename succeeds; ordinary work has no deadline, while scoped cancelled retries use the shared helper's one-second between-attempt grace. Native calls and yields are not hard bounded, and the probe does not establish the original refusal's cause.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Release is an effectful ownership transition, so a previous result cannot authorize a later call to skip its own atomic retirement attempt.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Qualified callback completion and certified scoped native closure permit payload eviction; unknown closure retains ownership without age expiry; pending marker files have finally-based removal that can fail. Ordinary retirement retries can block indefinitely; scoped cancelled cleanup stops retry admission after its shared grace and records actual refusal for the opted-in owner, without bounding native calls or yields. Best-effort probe cleanup may leave empty siblings. Cooperating collectors retain tombstones until recorded holder/observer absence; unconfirmed completion protects payloads while their owners may still act.
+ */
+export declare function releasePluginBuildLock(lockDir: string, lease: PluginBuildLockLease): boolean;

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

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releasePluginBuildLock = releasePluginBuildLock;
+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 PluginBuildLockOwner_1 = require("./PluginBuildLockOwner");
+const PluginBuildLockProtocol_1 = require("./PluginBuildLockProtocol");
+/**
+ * Retire a held v3 generation during the holder's finally. False means the
+ * generation already retired or disappeared, or native closure remains unknown
+ * and the original cleanup callback was deferred; unexpected filesystem errors
+ * propagate to the caller's release reporting boundary. Ordinary synchronous
+ * contention retains its existing retries. Scoped cancellation uses the shared
+ * retirement helper's cleanup grace and reports a continuing refusal as
+ * ownership failure to the opted-in request owner.
+ *
+ * Scoped native boundaries additionally require qualified closure; unknown
+ * retirement retains the exact generation and defers this callback for
+ * recovery.
+ *
+ * Call only after the held payload callback has ended. Release records that
+ * completion in this exact retired generation, even if a waiter retired it
+ * first. A timeout or lease transfer alone does not satisfy this precondition.
+ * Unconfirmed metadata or failed publication leaves task completion unproven,
+ * so cache maintenance conservatively protects the payload while its owner may
+ * still act.
+ *
+ * @evidence contracts/common.md#principled-implementation The lease's generation selects its reserved tombstone; only a matching generation file, owner identity and completion nonce permit atomic completion publication after the actual payload callback ends.
+ * @evidence contracts/common.md#clear-and-simple-design Release delegates retirement and owns exact-generation completion publication; callers own actual callback completion, finally scheduling and error reporting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release renames the leased generation into retained history rather than recursively deleting a possibly replaced current directory.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain return/error behavior and the actual-task-end precondition, distinguishing completion publication from timeout or lease transfer before the tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path construction and the shared rename adapter preserve the same retirement meaning across Windows sharing refusals and POSIX contention.
+ * @evidence contracts/performance.md#efficient-algorithms Retirement checks guard metadata before direct completion paths, avoiding owner-population scans; costs include native path construction, owner JSON/hostname and generation bytes plus marker publication. Eligible Windows refusals repeat synchronous waits and sibling probes after a sampled sibling rename succeeds; ordinary work has no deadline, while scoped cancelled retries use the shared helper's one-second between-attempt grace. Native calls and yields are not hard bounded, and the probe does not establish the original refusal's cause.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Release is an effectful ownership transition, so a previous result cannot authorize a later call to skip its own atomic retirement attempt.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Qualified callback completion and certified scoped native closure permit payload eviction; unknown closure retains ownership without age expiry; pending marker files have finally-based removal that can fail. Ordinary retirement retries can block indefinitely; scoped cancelled cleanup stops retry admission after its shared grace and records actual refusal for the opted-in owner, without bounding native calls or yields. Best-effort probe cleanup may leave empty siblings. Cooperating collectors retain tombstones until recorded holder/observer absence; unconfirmed completion protects payloads while their owners may still act.
+ */
+function releasePluginBuildLock(lockDir, lease) {
+    if (lease.protocol !== "v3")
+        return false;
+    if (!SourceNativeRetirement_1.SourceNativeRetirement.canRelease()) {
+        SourceNativeRetirement_1.SourceNativeRetirement.release(() => releasePluginBuildLock(lockDir, lease));
+        return false;
+    }
+    const protocolDir = PluginBuildLockProtocol_1.PluginBuildLockProtocol.pluginBuildLockProtocolDir(lockDir);
+    SourceNativeRetirement_1.SourceNativeRetirement.assertReleasable(protocolDir, lease.generation);
+    const retired = PluginBuildLockProtocol_1.PluginBuildLockProtocol.retireV3PluginBuildLock(protocolDir, lease.generation);
+    recordPluginBuildLockTaskCompletion(protocolDir, lease);
+    SourceNativeRetirement_1.SourceNativeRetirement.forget(protocolDir, lease.generation);
+    return retired;
+}
+/**
+ * Publish only into the qualified retired generation. This process remains
+ * alive throughout publication, so observer-aware collection cannot remove it.
+ */
+function recordPluginBuildLockTaskCompletion(protocolDir, lease) {
+    if (!PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockGeneration(lease.generation) ||
+        !PluginBuildLockProtocol_1.PluginBuildLockProtocol.isPluginBuildLockGeneration(lease.completionNonce)) {
+        return;
+    }
+    const generationDir = node_path_1.default.join(protocolDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_RETIRED_DIR, lease.generation);
+    const owner = PluginBuildLockOwner_1.PluginBuildLockOwner.read(generationDir);
+    if (owner === null ||
+        owner.generation !== lease.generation ||
+        owner.completionNonce !== lease.completionNonce ||
+        owner.pid !== process.pid ||
+        owner.hostname.toLowerCase() !== node_os_1.default.hostname().toLowerCase()) {
+        return;
+    }
+    try {
+        if (node_fs_1.default
+            .readFileSync(node_path_1.default.join(generationDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE), "utf8")
+            .trim() !== lease.generation) {
+            return;
+        }
+    }
+    catch {
+        return;
+    }
+    const marker = node_path_1.default.join(generationDir, PluginBuildLockProtocol_1.PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_COMPLETION_FILE);
+    const candidate = `${marker}.pending-${node_crypto_1.default.randomBytes(16).toString("hex")}`;
+    try {
+        node_fs_1.default.writeFileSync(candidate, `${lease.completionNonce}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+        node_fs_1.default.renameSync(candidate, marker);
+    }
+    finally {
+        node_fs_1.default.rmSync(candidate, { force: true });
+    }
+}
+//# sourceMappingURL=releasePluginBuildLock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"releasePluginBuildLock.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/releasePluginBuildLock.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AACjC,sDAAyB;AACzB,sDAAyB;AACzB,0DAA6B;AAE7B,qFAAkF;AAElF,iEAA8D;AAC9D,uEAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,gCACE,OAAe,EACf,KAA2B;IAE3B,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,CAAC,+CAAsB,CAAC,UAAU,EAAE,EAAE,CAAC;QACzC,+CAAsB,CAAC,OAAO,CAAC,GAAG,EAAE,CAClC,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,CACvC,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,WAAW,GACf,iDAAuB,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAC9D,+CAAsB,CAAC,gBAAgB,CAAC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,iDAAuB,CAAC,uBAAuB,CAC7D,WAAW,EACX,KAAK,CAAC,UAAU,CACjB,CAAC;IACF,mCAAmC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACxD,+CAAsB,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAS,mCAAmC,CAC1C,WAAmB,EACnB,KAA2B;IAE3B,IACE,CAAC,iDAAuB,CAAC,2BAA2B,CAAC,KAAK,CAAC,UAAU,CAAC;QACtE,CAAC,iDAAuB,CAAC,2BAA2B,CAAC,KAAK,CAAC,eAAe,CAAC,EAC3E,CAAC;QACD,OAAO;IACT,CAAC;IACD,MAAM,aAAa,GAAG,mBAAI,CAAC,IAAI,CAC7B,WAAW,EACX,iDAAuB,CAAC,6BAA6B,EACrD,KAAK,CAAC,UAAU,CACjB,CAAC;IACF,MAAM,KAAK,GAAG,2CAAoB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvD,IACE,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU;QACrC,KAAK,CAAC,eAAe,KAAK,KAAK,CAAC,eAAe;QAC/C,KAAK,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG;QACzB,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,iBAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,EAC5D,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,IACE,iBAAE;aACC,YAAY,CACX,mBAAI,CAAC,IAAI,CACP,aAAa,EACb,iDAAuB,CAAC,iCAAiC,CAC1D,EACD,MAAM,CACP;aACA,IAAI,EAAE,KAAK,KAAK,CAAC,UAAU,EAC9B,CAAC;YACD,OAAO;QACT,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,mBAAI,CAAC,IAAI,CACtB,aAAa,EACb,iDAAuB,CAAC,iCAAiC,CAC1D,CAAC;IACF,MAAM,SAAS,GAAG,GAAG,MAAM,YAAY,qBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAChF,IAAI,CAAC;QACH,iBAAE,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,eAAe,IAAI,EAAE;YACxD,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,iBAAE,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;YAAS,CAAC;QACT,iBAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,26 @@
+/**
+ * Return every directory `ttsc clean` should remove for `projectRoot`.
+ *
+ * Covers the resolved plugin-binary root, the single-file caches beside it
+ * (descriptor evaluations, capability answers, lowered orphan sources:
+ * `SourceBuildCacheLayout.CACHE_FILE_DIRNAMES`), a safely named nested
+ * `go-build/`, a ttsc-owned Go build cache that lives OUTSIDE that root
+ * (`TTSC_GO_CACHE_DIR`), and the two legacy project-local caches. A
+ * user-provided `GOCACHE` filters candidates whose reported identity keys
+ * overlap in either direction. This query does not pin those paths or certify
+ * unresolved case/alias relationships; the cleanup transaction validates the
+ * complete deletion set separately. Workspace discovery reads the filesystem;
+ * environment selection uses `env` so a programmatic caller can supply its
+ * effective environment.
+ *
+ * @evidence contracts/common.md#principled-implementation Candidate directories encode owned layout parts and dedicated Go provenance; reported identity-key overlap with external GOCACHE is excluded in either ancestor direction, without converting unresolved identity into a physical-ownership certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate enumeration is followed by one external-ownership filter; physical deletion and project-root protection remain the cleanup transaction's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Legacy paths are supported migration targets; external Go storage is protected by identity rather than guessed different spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state candidate ownership, filesystem discovery and injected environment semantics rather than claiming a pure query.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs construct candidates; environment lookup honors Windows case-insensitive names, and the shared identity context resolves aliases and actual directory case semantics for overlap protection.
+ * @evidence contracts/performance.md#efficient-algorithms The candidate count is fixed, but delegated default root discovery walks ancestors, reads manifest bytes and inspects layout entry populations. Path/environment text and native identity/case observations contribute cost; one call-local identity context shares repeated resolution across overlap checks without a constant-cost filesystem claim.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup candidate selection does not establish equivalence for computed build answers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The query returns candidates; the cleanup transaction owns deletion and no retained handle is acquired here.
+ */
+export declare function resolveCleanTargets(projectRoot: string, cacheDir?: string, env?: NodeJS.ProcessEnv): string[];

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

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCleanTargets = resolveCleanTargets;
+const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const createFilesystemPathIdentityContext_1 = require("../../../internal/pathIdentity/createFilesystemPathIdentityContext");
+const isFilesystemPathIdentityWithin_1 = require("../../../internal/pathIdentity/isFilesystemPathIdentityWithin");
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+const resolveSourceBuildCachePaths_1 = require("./resolveSourceBuildCachePaths");
+/**
+ * Return every directory `ttsc clean` should remove for `projectRoot`.
+ *
+ * Covers the resolved plugin-binary root, the single-file caches beside it
+ * (descriptor evaluations, capability answers, lowered orphan sources:
+ * `SourceBuildCacheLayout.CACHE_FILE_DIRNAMES`), a safely named nested
+ * `go-build/`, a ttsc-owned Go build cache that lives OUTSIDE that root
+ * (`TTSC_GO_CACHE_DIR`), and the two legacy project-local caches. A
+ * user-provided `GOCACHE` filters candidates whose reported identity keys
+ * overlap in either direction. This query does not pin those paths or certify
+ * unresolved case/alias relationships; the cleanup transaction validates the
+ * complete deletion set separately. Workspace discovery reads the filesystem;
+ * environment selection uses `env` so a programmatic caller can supply its
+ * effective environment.
+ *
+ * @evidence contracts/common.md#principled-implementation Candidate directories encode owned layout parts and dedicated Go provenance; reported identity-key overlap with external GOCACHE is excluded in either ancestor direction, without converting unresolved identity into a physical-ownership certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate enumeration is followed by one external-ownership filter; physical deletion and project-root protection remain the cleanup transaction's responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Legacy paths are supported migration targets; external Go storage is protected by identity rather than guessed different spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state candidate ownership, filesystem discovery and injected environment semantics rather than claiming a pure query.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs construct candidates; environment lookup honors Windows case-insensitive names, and the shared identity context resolves aliases and actual directory case semantics for overlap protection.
+ * @evidence contracts/performance.md#efficient-algorithms The candidate count is fixed, but delegated default root discovery walks ancestors, reads manifest bytes and inspects layout entry populations. Path/environment text and native identity/case observations contribute cost; one call-local identity context shares repeated resolution across overlap checks without a constant-cost filesystem claim.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup candidate selection does not establish equivalence for computed build answers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The query returns candidates; the cleanup transaction owns deletion and no retained handle is acquired here.
+ */
+function resolveCleanTargets(projectRoot, cacheDir, env = process.env) {
+    const paths = (0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(projectRoot, cacheDir, env);
+    // Remove ttsc-OWNED directories only, never the parent cache root.
+    const targets = [
+        paths.pluginRoot,
+        ...SourceBuildCacheLayout_1.SourceBuildCacheLayout.CACHE_FILE_DIRNAMES.map((name) => node_path_1.default.join(paths.root, name)),
+    ];
+    // ttsc's nested `<root>/go-build` is only safe to delete when we are certain
+    // the root belongs to ttsc: the default `node_modules/.cache/ttsc`, or a root
+    // the user explicitly named `ttsc`. Under a shared root (e.g.
+    // `TTSC_CACHE_DIR=~/.cache`) a bare `<root>/go-build` could be the user's
+    // machine-wide GOCACHE, so it must never be removed by name.
+    const isTtscOwnedRoot = (!cacheDir && !SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_CACHE_DIR")) ||
+        node_path_1.default.basename(paths.root) === SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME;
+    if (isTtscOwnedRoot) {
+        targets.push(node_path_1.default.join(paths.root, SourceBuildCacheLayout_1.SourceBuildCacheLayout.GO_BUILD_CACHE_DIRNAME));
+    }
+    // An explicit TTSC_GO_CACHE_DIR is a ttsc-dedicated external cache; a
+    // user-provided GOCACHE (source "GOCACHE") is never removed.
+    if (paths.goBuildRootSource === "TTSC_GO_CACHE_DIR") {
+        targets.push(paths.goBuildRoot);
+    }
+    targets.push(node_path_1.default.join(projectRoot, SourceBuildCacheLayout_1.SourceBuildCacheLayout.NODE_MODULES_DIRNAME, ".ttsc"));
+    targets.push(node_path_1.default.join(projectRoot, ".ttsc"));
+    const externalGoCache = SidecarEnvironment_1.SidecarEnvironment.read(env, "GOCACHE");
+    if (!externalGoCache)
+        return targets;
+    const identities = (0, createFilesystemPathIdentityContext_1.createFilesystemPathIdentityContext)();
+    const external = identities.resolve(externalGoCache);
+    return targets.filter((target) => {
+        const candidate = identities.resolve(target);
+        return (!(0, isFilesystemPathIdentityWithin_1.isFilesystemPathIdentityWithin)(candidate.key, external.key) &&
+            !(0, isFilesystemPathIdentityWithin_1.isFilesystemPathIdentityWithin)(external.key, candidate.key));
+    });
+}
+//# sourceMappingURL=resolveCleanTargets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCleanTargets.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/resolveCleanTargets.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,iGAA8F;AAC9F,4HAAyH;AACzH,kHAA+G;AAC/G,qEAAkE;AAClE,iFAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,6BACE,WAAmB,EACnB,QAAiB,EACjB,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,MAAM,KAAK,GAAG,IAAA,2DAA4B,EAAC,WAAW,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvE,mEAAmE;IACnE,MAAM,OAAO,GAAG;QACd,KAAK,CAAC,UAAU;QAChB,GAAG,+CAAsB,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACzD,mBAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAC5B;KACF,CAAC;IACF,6EAA6E;IAC7E,8EAA8E;IAC9E,8DAA8D;IAC9D,0EAA0E;IAC1E,6DAA6D;IAC7D,MAAM,eAAe,GACnB,CAAC,CAAC,QAAQ,IAAI,CAAC,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QAC9D,mBAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,+CAAsB,CAAC,kBAAkB,CAAC;IAC1E,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CACV,mBAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,+CAAsB,CAAC,sBAAsB,CAAC,CACrE,CAAC;IACJ,CAAC;IACD,sEAAsE;IACtE,6DAA6D;IAC7D,IAAI,KAAK,CAAC,iBAAiB,KAAK,mBAAmB,EAAE,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,CAAC,IAAI,CACV,mBAAI,CAAC,IAAI,CACP,WAAW,EACX,+CAAsB,CAAC,oBAAoB,EAC3C,OAAO,CACR,CACF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,mBAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAG,uCAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAChE,IAAI,CAAC,eAAe;QAAE,OAAO,OAAO,CAAC;IACrC,MAAM,UAAU,GAAG,IAAA,yEAAmC,GAAE,CAAC;IACzD,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QAC/B,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,CACL,CAAC,IAAA,+DAA8B,EAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC;YAC5D,CAAC,IAAA,+DAA8B,EAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,CAC7D,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * The initial Go executable candidate before build-facing lookup applies the
+ * module directory (`GoToolResolution.resolveGoToolForBuild`): TTSC_GO_BINARY
+ * when set, the toolchain bundled with ttsc's platform package or a local
+ * native build, `~/go-sdk`, and `go` on the path last.
+ *
+ * Both the build (`buildSourcePlugin`) and the environment a consumer proves
+ * the build's output against (`pluginBuildEnvironment`) resolve the compiler
+ * here. Nonexplicit layout candidates use resolution/existence checks, not
+ * content or executable-kind validation; later lookup/permission/probe owners
+ * handle that candidate. The bundled flag denotes selected install layout, not
+ * immutable physical ownership.
+ *
+ * @param env The build's effective environment.
+ * @returns The compiler, and whether it is the one ttsc bundles.
+ * @evidence contracts/common.md#principled-implementation Selection follows explicit override, packaged/local SDK layout, home SDK and bare-name fallback precedence. The bundled-layout flag chooses the downstream permission policy, without certifying candidate kind, execute access or immutable ownership here.
+ * @evidence contracts/common.md#clear-and-simple-design One resolver is shared by builds and environment proofs, with ordered early returns and executable resolution left to its separate owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Install layouts are product-defined fallbacks and the explicit environment belongs to the caller; no process global or foreign resolver is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation explains precedence, bundled provenance and the later module-directory toolchain boundary.
+ * @evidence contracts/portability.md#os-neutral-implementation Node module/path APIs select native platform packages and executable suffixes; home SDK lookup honors caller HOME/USERPROFILE then Node's native home directory, while explicit SDK and PATH remain supported fallbacks.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed candidate order has early returns but Node require resolution can search native module ancestors/manifests/paths. Native path/existence/home lookup and supplied text contribute cost; fixed candidate count is not a bounded filesystem-work claim and no SDK content traversal is performed here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current caller overrides and installation presence are resolved afresh; this selector owns no memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Candidate paths and require resolution are call-local and acquire no retained native handle.
+ */
+export declare function resolveGoCompiler(env?: NodeJS.ProcessEnv): {
+    binary: string;
+    bundled: boolean;
+};

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

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGoCompiler = resolveGoCompiler;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * The initial Go executable candidate before build-facing lookup applies the
+ * module directory (`GoToolResolution.resolveGoToolForBuild`): TTSC_GO_BINARY
+ * when set, the toolchain bundled with ttsc's platform package or a local
+ * native build, `~/go-sdk`, and `go` on the path last.
+ *
+ * Both the build (`buildSourcePlugin`) and the environment a consumer proves
+ * the build's output against (`pluginBuildEnvironment`) resolve the compiler
+ * here. Nonexplicit layout candidates use resolution/existence checks, not
+ * content or executable-kind validation; later lookup/permission/probe owners
+ * handle that candidate. The bundled flag denotes selected install layout, not
+ * immutable physical ownership.
+ *
+ * @param env The build's effective environment.
+ * @returns The compiler, and whether it is the one ttsc bundles.
+ * @evidence contracts/common.md#principled-implementation Selection follows explicit override, packaged/local SDK layout, home SDK and bare-name fallback precedence. The bundled-layout flag chooses the downstream permission policy, without certifying candidate kind, execute access or immutable ownership here.
+ * @evidence contracts/common.md#clear-and-simple-design One resolver is shared by builds and environment proofs, with ordered early returns and executable resolution left to its separate owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Install layouts are product-defined fallbacks and the explicit environment belongs to the caller; no process global or foreign resolver is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation explains precedence, bundled provenance and the later module-directory toolchain boundary.
+ * @evidence contracts/portability.md#os-neutral-implementation Node module/path APIs select native platform packages and executable suffixes; home SDK lookup honors caller HOME/USERPROFILE then Node's native home directory, while explicit SDK and PATH remain supported fallbacks.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed candidate order has early returns but Node require resolution can search native module ancestors/manifests/paths. Native path/existence/home lookup and supplied text contribute cost; fixed candidate count is not a bounded filesystem-work claim and no SDK content traversal is performed here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current caller overrides and installation presence are resolved afresh; this selector owns no memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Candidate paths and require resolution are call-local and acquire no retained native handle.
+ */
+function resolveGoCompiler(env = process.env) {
+    const explicit = env.TTSC_GO_BINARY;
+    if (explicit && explicit.length > 0) {
+        return { binary: explicit, bundled: false };
+    }
+    try {
+        return {
+            binary: (0, node_module_1.createRequire)(__filename).resolve(`@ttsc/${process.platform}-${process.arch}/bin/go/bin/${process.platform === "win32" ? "go.exe" : "go"}`),
+            bundled: true,
+        };
+    }
+    catch {
+        /* fall through */
+    }
+    const platformPackage = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", "..", `ttsc-${process.platform}-${process.arch}`, "bin", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
+    if (node_fs_1.default.existsSync(platformPackage)) {
+        return { binary: platformPackage, bundled: true };
+    }
+    const local = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", "..", "native", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
+    if (node_fs_1.default.existsSync(local))
+        return { binary: local, bundled: true };
+    const homeSdk = node_path_1.default.join(env.HOME || env.USERPROFILE || node_os_1.default.homedir(), "go-sdk", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
+    if (node_fs_1.default.existsSync(homeSdk))
+        return { binary: homeSdk, bundled: false };
+    return { binary: "go", bundled: false };
+}
+//# sourceMappingURL=resolveGoCompiler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveGoCompiler.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/resolveGoCompiler.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,6CAA4C;AAC5C,sDAAyB;AACzB,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2BAAkC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAIpE,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC;IACpC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC;QACH,OAAO;YACL,MAAM,EAAE,IAAA,2BAAa,EAAC,UAAU,CAAC,CAAC,OAAO,CACvC,SAAS,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,eAAe,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CACzG;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,MAAM,eAAe,GAAG,mBAAI,CAAC,OAAO,CAClC,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,EAC1C,KAAK,EACL,IAAI,EACJ,KAAK,EACL,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAC/C,CAAC;IACF,IAAI,iBAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,KAAK,GAAG,mBAAI,CAAC,OAAO,CACxB,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAC/C,CAAC;IACF,IAAI,iBAAE,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAElE,MAAM,OAAO,GAAG,mBAAI,CAAC,IAAI,CACvB,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,IAAI,iBAAE,CAAC,OAAO,EAAE,EAC3C,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAC/C,CAAC;IACF,IAAI,iBAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEvE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * Resolve the directory where compiled plugin binaries are cached.
+ *
+ * Delegates to {@link resolveSourceBuildCachePaths}; kept as a thin accessor for
+ * callers that only need the plugin-binary root. Triggers the opportunistic
+ * project-cache GC attempts as a side effect for the default location.
+ * Admission, protected entries and tolerated failures can defer reclamation;
+ * this accessor does not certify a storage ceiling or successful eviction.
+ *
+ * @evidence contracts/common.md#principled-implementation The binary root comes from the shared source layout and only ownership-admitted default caches are opportunistically pruned.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter delegates selection and maintenance before projecting pluginRoot.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Effective environment injection preserves host ownership without mutating process globals or substituting recognized projects.
+ * @evidence contracts/common.md#meaningful-documentation The native description states that this convenience query can perform maintenance; tags remain separate from prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform path and deletion boundaries remain with native-aware shared helpers.
+ * @evidence contracts/performance.md#efficient-algorithms Cost includes root discovery and admitted full maintenance passes, not merely constant projection.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This location/maintenance adapter does not validate binary content keys or coordinate completed or in-flight producers.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Default cache populations receive their collectors' opportunistic reclamation attempts, including protected/live entries and deletion failures that can leave growth unbounded. Collector coordination/history remain with those owners; explicit roots keep caller-controlled lifetime.
+ */
+export declare function resolvePluginCacheRoot(projectRoot: string, cacheDir?: string, env?: NodeJS.ProcessEnv): string;

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePluginCacheRoot = resolvePluginCacheRoot;
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+const resolveSourceBuildCachePaths_1 = require("./resolveSourceBuildCachePaths");
+/**
+ * Resolve the directory where compiled plugin binaries are cached.
+ *
+ * Delegates to {@link resolveSourceBuildCachePaths}; kept as a thin accessor for
+ * callers that only need the plugin-binary root. Triggers the opportunistic
+ * project-cache GC attempts as a side effect for the default location.
+ * Admission, protected entries and tolerated failures can defer reclamation;
+ * this accessor does not certify a storage ceiling or successful eviction.
+ *
+ * @evidence contracts/common.md#principled-implementation The binary root comes from the shared source layout and only ownership-admitted default caches are opportunistically pruned.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter delegates selection and maintenance before projecting pluginRoot.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Effective environment injection preserves host ownership without mutating process globals or substituting recognized projects.
+ * @evidence contracts/common.md#meaningful-documentation The native description states that this convenience query can perform maintenance; tags remain separate from prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform path and deletion boundaries remain with native-aware shared helpers.
+ * @evidence contracts/performance.md#efficient-algorithms Cost includes root discovery and admitted full maintenance passes, not merely constant projection.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This location/maintenance adapter does not validate binary content keys or coordinate completed or in-flight producers.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Default cache populations receive their collectors' opportunistic reclamation attempts, including protected/live entries and deletion failures that can leave growth unbounded. Collector coordination/history remain with those owners; explicit roots keep caller-controlled lifetime.
+ */
+function resolvePluginCacheRoot(projectRoot, cacheDir, env = process.env) {
+    const paths = (0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(projectRoot, cacheDir, env);
+    SourceBuildCacheLayout_1.SourceBuildCacheLayout.maybePruneSourceBuildCaches(paths, cacheDir, env);
+    return paths.pluginRoot;
+}
+//# sourceMappingURL=resolvePluginCacheRoot.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolvePluginCacheRoot.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/resolvePluginCacheRoot.ts"],"names":[],"mappings":";;;AAAA,qEAAkE;AAClE,iFAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gCACE,WAAmB,EACnB,QAAiB,EACjB,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,MAAM,KAAK,GAAG,IAAA,2DAA4B,EAAC,WAAW,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvE,+CAAsB,CAAC,2BAA2B,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzE,OAAO,KAAK,CAAC,UAAU,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * The Go module a plugin's `source` builds in: the package directory the source
+ * names, the module root above it, and the package's path inside the module.
+ *
+ * A `source` names a Go package directory or its `go.mod` file, and may sit
+ * anywhere below its module: the nearest `go.mod` within
+ * {@link GO_MOD_SEARCH_MAX_DEPTH} parents is the module root. The build copies
+ * and keys that whole root (`buildSourcePlugin`, `computeCacheKey`), so a
+ * sibling package or the module's own `go.mod` moves the binary as much as the
+ * package itself does. Everything that needs the module a plugin builds in, the
+ * build, the loader's validation, and the inputs a watch session observes,
+ * takes it from here, so the rule has one reading.
+ *
+ * @param source The source, absolute, which the caller has found to exist.
+ * @param pluginName The plugin's label in an error.
+ * @throws When the source is neither a directory nor a `go.mod` file, or no
+ *   `go.mod` lies within reach above it. Native stat failures also propagate.
+ *   Selection observes current file kinds and ancestry; it neither parses the
+ *   module contents nor pins that filesystem identity against later changes.
+ * @evidence contracts/common.md#principled-implementation The source must denote a package directory or go.mod; the bounded nearest-module search and relative package entry make copying/keying the entire owning module consistent with Go compilation.
+ * @evidence contracts/common.md#clear-and-simple-design Input classification and module discovery are visible in one small adapter; the nearest-manifest operation is shared with compiler code.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The three-parent reach is an explicit current source-plugin contract, with a descriptive failure rather than a guessed module or consumer-specific escape.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains whole-module identity, the documented reach limit and both failure classes; tags are separated from parameter prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source identity uses Node stat/dirname/relative; returned Go package entries convert host separators to slash spelling while preserving literal POSIX backslashes.
+ * @evidence contracts/performance.md#efficient-algorithms One source stat precedes at most three parent hops plus the starting-directory metadata probe. Native lookup and path-text resolve/join/relative/conversion costs remain part of this call; it performs no recursive repository or sibling-source scan.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current source type and nearest manifest must be observed afresh; this resolver owns no memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The resolver retains no file descriptor or historical directory state.
+ */
+export declare function resolvePluginGoModule(source: string, pluginName: string): {
+    entry: string;
+    moduleRoot: string;
+    packageDir: string;
+};

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

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePluginGoModule = resolvePluginGoModule;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const findNearestGoMod_1 = require("../../../compiler/internal/findNearestGoMod");
+/**
+ * The Go module a plugin's `source` builds in: the package directory the source
+ * names, the module root above it, and the package's path inside the module.
+ *
+ * A `source` names a Go package directory or its `go.mod` file, and may sit
+ * anywhere below its module: the nearest `go.mod` within
+ * {@link GO_MOD_SEARCH_MAX_DEPTH} parents is the module root. The build copies
+ * and keys that whole root (`buildSourcePlugin`, `computeCacheKey`), so a
+ * sibling package or the module's own `go.mod` moves the binary as much as the
+ * package itself does. Everything that needs the module a plugin builds in, the
+ * build, the loader's validation, and the inputs a watch session observes,
+ * takes it from here, so the rule has one reading.
+ *
+ * @param source The source, absolute, which the caller has found to exist.
+ * @param pluginName The plugin's label in an error.
+ * @throws When the source is neither a directory nor a `go.mod` file, or no
+ *   `go.mod` lies within reach above it. Native stat failures also propagate.
+ *   Selection observes current file kinds and ancestry; it neither parses the
+ *   module contents nor pins that filesystem identity against later changes.
+ * @evidence contracts/common.md#principled-implementation The source must denote a package directory or go.mod; the bounded nearest-module search and relative package entry make copying/keying the entire owning module consistent with Go compilation.
+ * @evidence contracts/common.md#clear-and-simple-design Input classification and module discovery are visible in one small adapter; the nearest-manifest operation is shared with compiler code.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The three-parent reach is an explicit current source-plugin contract, with a descriptive failure rather than a guessed module or consumer-specific escape.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains whole-module identity, the documented reach limit and both failure classes; tags are separated from parameter prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source identity uses Node stat/dirname/relative; returned Go package entries convert host separators to slash spelling while preserving literal POSIX backslashes.
+ * @evidence contracts/performance.md#efficient-algorithms One source stat precedes at most three parent hops plus the starting-directory metadata probe. Native lookup and path-text resolve/join/relative/conversion costs remain part of this call; it performs no recursive repository or sibling-source scan.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current source type and nearest manifest must be observed afresh; this resolver owns no memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The resolver retains no file descriptor or historical directory state.
+ */
+function resolvePluginGoModule(source, pluginName) {
+    const stat = node_fs_1.default.statSync(source);
+    const packageDir = stat.isFile() && node_path_1.default.basename(source) === "go.mod"
+        ? node_path_1.default.dirname(source)
+        : stat.isDirectory()
+            ? source
+            : null;
+    if (packageDir === null) {
+        throw new Error(`ttsc: plugin "${pluginName}" source must be a Go package directory or go.mod file: ${source}`);
+    }
+    const goMod = (0, findNearestGoMod_1.findNearestGoMod)(packageDir, GO_MOD_SEARCH_MAX_DEPTH);
+    if (goMod === null) {
+        throw new Error(`ttsc: plugin "${pluginName}" source must be inside a Go module with go.mod within ${GO_MOD_SEARCH_MAX_DEPTH} parent directories: ${source}`);
+    }
+    const moduleRoot = node_path_1.default.dirname(goMod);
+    const relative = node_path_1.default
+        .relative(moduleRoot, packageDir)
+        .replaceAll(node_path_1.default.sep, "/");
+    return {
+        entry: relative === "" ? "." : `./${relative}`,
+        moduleRoot,
+        packageDir,
+    };
+}
+/** How many parent directories above a plugin package `go.mod` may lie. */
+const GO_MOD_SEARCH_MAX_DEPTH = 3;
+//# sourceMappingURL=resolvePluginGoModule.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolvePluginGoModule.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/resolvePluginGoModule.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,kFAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,+BACE,MAAc,EACd,UAAkB;IAElB,MAAM,IAAI,GAAG,iBAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,UAAU,GACd,IAAI,CAAC,MAAM,EAAE,IAAI,mBAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,QAAQ;QACjD,CAAC,CAAC,mBAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACtB,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE;YAClB,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,IAAI,CAAC;IACb,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,2DAA2D,MAAM,EAAE,CAC/F,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,mCAAgB,EAAC,UAAU,EAAE,uBAAuB,CAAC,CAAC;IACpE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,0DAA0D,uBAAuB,wBAAwB,MAAM,EAAE,CAC7I,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,mBAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,mBAAI;SAClB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;SAChC,UAAU,CAAC,mBAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO;QACL,KAAK,EAAE,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE;QAC9C,UAAU;QACV,UAAU;KACX,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,uBAAuB,GAAG,CAAC,CAAC"}

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

@@ -0,0 +1,21 @@
+import type { ITtscSourceBuildCachePaths } from "./ITtscSourceBuildCachePaths";
+/**
+ * Resolve all source-plugin build cache directories for one invocation.
+ *
+ * `pluginRoot` stores compiled plugin binaries; `goBuildRoot` is the Go object
+ * cache passed as `GOCACHE` while ttsc builds those binaries. The default Go
+ * cache lives under `root`; `TTSC_GO_CACHE_DIR` is independently resolved,
+ * while external `GOCACHE` preserves its supplied value for Go to validate.
+ * Their selection provenance keeps the ownership policies distinct.
+ *
+ * @evidence contracts/common.md#principled-implementation Plugin and Go paths derive from one root while provenance preserves dedicated ttsc ownership versus external GOCACHE.
+ * @evidence contracts/common.md#clear-and-simple-design Root selection and Go override selection are separate helpers; the result carries paths with their ownership discriminant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Workspace markers and environment overrides are supported configuration inputs rather than project-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain each payload and independent Go ownership, separated from tags under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs anchor ttsc overrides; environment names use Windows case-insensitive lookup, and external GOCACHE preserves Go's supplied spelling and validation semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Default discovery walks ancestor directories, reading each inspected manifest's bytes and snapshotting entries at the node_modules/.cache/ttsc layout levels; those entry populations are not capped or recursively traversed. Path processing depends on visited text, while Windows override lookup scans current environment names. Explicit root selection skips ancestor discovery; Go provenance selection still observes its overrides.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Shared workspace placement permits producer caches to be shared, but this path query coordinates neither completed nor in-flight computations and establishes no answer equivalence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning paths and provenance acquires no retained cache entry or handle.
+ */
+export declare function resolveSourceBuildCachePaths(projectRoot: string, cacheDir?: string, env?: NodeJS.ProcessEnv): ITtscSourceBuildCachePaths;