ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginSourceState.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginSourceState.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AAEjC,qEAAkE;AAClE,6DAA0D;AAC1D,mFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,2BACE,SAAiB,EACjB,OAAO,GAIH,EAAE;IAEN,OAAO,qBAAM;SACV,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CACL,UAAU,OAAO,CAAC,YAAY,IAAI,IAAA,uCAAkB,EAAC,SAAS,CAAC,IAAI;QACjE,eACE,OAAO,CAAC,WAAW;YACnB,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS;gBACxB,CAAC,CAAC,IAAA,6DAA6B,EAAC,SAAS,CAAC;gBAC1C,CAAC,CAAC,IAAA,+CAAsB,EAAC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CACpD,IAAI,CACP;SACA,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * Whether one plugin source directory still holds the state a transform
+ * reported for it (`pluginSourceState`), under this process's environment.
+ *
+ * The sources are read now, unless the caller hands over their digest
+ * (`pluginSourceDigest`) from a reading it can vouch for still holding, as a
+ * consumer that re-proves a source on every delivery does once the metadata of
+ * every file the digest reads (`collectPluginSourceFiles`) is unchanged. The
+ * environment is this process's reading (`processPluginBuildEnvironment`),
+ * which is read again whenever the Go tool, its environment file, or the C
+ * toolchain it names moved, and read again before a state that does not match
+ * is refuted. A compile keys its binaries on a fresh read, so a state it
+ * reported after a change gets one comparison with a refreshed environment.
+ * That retry does not guarantee equality for a changing or differently keyed
+ * environment, and a supplied source digest remains the caller's premise.
+ *
+ * @param directory The source directory, as the envelope names it.
+ * @param state The state the envelope reported.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller holds one it can vouch for.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation Equality uses shared state composition and one real environment refresh after mismatch. This allows changed observations to be reconsidered without certifying the second comparison must match; supplied digest validity and native witness premises remain with their owners.
+ * @evidence contracts/common.md#clear-and-simple-design One source reading is passed through both attempts and only the environment owner performs the refresh.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Refresh corrects a genuinely changed environment reading rather than adding exceptions for particular digest values or consumers.
+ * @evidence contracts/common.md#meaningful-documentation The prose states source-digest provenance, environment invalidation and the reason a mismatching state gets a fresh comparison.
+ * @evidence contracts/portability.md#os-neutral-implementation Source reads and Go/environment witnesses use the same native boundary implementations as builds, rather than comparing OS names or guessed installation paths.
+ * @evidence contracts/performance.md#efficient-algorithms At most one source digest computation is requested and reused by both comparisons; supplied strings bypass it. Native enumeration/file bytes, full environment identity/witness checks, optional tool/SDK refresh and digest-string hashing contribute work; mismatch repeats environment resolution once rather than bounding total cost by comparison count.
+ * @evidence contracts/performance.md#reuse-equivalent-work A caller's proven source digest and the process owner's still-valid environment are reused; a mismatch forces the owning environment refresh before returning false.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The proof owns no retained source buffer, process or watcher; its caller owns any saved source digest.
+ */
+export declare function pluginSourceStateHolds(directory: string, state: string, options?: {
+    sourceDigest?: string;
+}): boolean;

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceStateHolds = pluginSourceStateHolds;
+const pluginSourceDigest_1 = require("./pluginSourceDigest");
+const pluginSourceState_1 = require("./pluginSourceState");
+const processPluginBuildEnvironment_1 = require("./processPluginBuildEnvironment");
+/**
+ * Whether one plugin source directory still holds the state a transform
+ * reported for it (`pluginSourceState`), under this process's environment.
+ *
+ * The sources are read now, unless the caller hands over their digest
+ * (`pluginSourceDigest`) from a reading it can vouch for still holding, as a
+ * consumer that re-proves a source on every delivery does once the metadata of
+ * every file the digest reads (`collectPluginSourceFiles`) is unchanged. The
+ * environment is this process's reading (`processPluginBuildEnvironment`),
+ * which is read again whenever the Go tool, its environment file, or the C
+ * toolchain it names moved, and read again before a state that does not match
+ * is refuted. A compile keys its binaries on a fresh read, so a state it
+ * reported after a change gets one comparison with a refreshed environment.
+ * That retry does not guarantee equality for a changing or differently keyed
+ * environment, and a supplied source digest remains the caller's premise.
+ *
+ * @param directory The source directory, as the envelope names it.
+ * @param state The state the envelope reported.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller holds one it can vouch for.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation Equality uses shared state composition and one real environment refresh after mismatch. This allows changed observations to be reconsidered without certifying the second comparison must match; supplied digest validity and native witness premises remain with their owners.
+ * @evidence contracts/common.md#clear-and-simple-design One source reading is passed through both attempts and only the environment owner performs the refresh.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Refresh corrects a genuinely changed environment reading rather than adding exceptions for particular digest values or consumers.
+ * @evidence contracts/common.md#meaningful-documentation The prose states source-digest provenance, environment invalidation and the reason a mismatching state gets a fresh comparison.
+ * @evidence contracts/portability.md#os-neutral-implementation Source reads and Go/environment witnesses use the same native boundary implementations as builds, rather than comparing OS names or guessed installation paths.
+ * @evidence contracts/performance.md#efficient-algorithms At most one source digest computation is requested and reused by both comparisons; supplied strings bypass it. Native enumeration/file bytes, full environment identity/witness checks, optional tool/SDK refresh and digest-string hashing contribute work; mismatch repeats environment resolution once rather than bounding total cost by comparison count.
+ * @evidence contracts/performance.md#reuse-equivalent-work A caller's proven source digest and the process owner's still-valid environment are reused; a mismatch forces the owning environment refresh before returning false.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The proof owns no retained source buffer, process or watcher; its caller owns any saved source digest.
+ */
+function pluginSourceStateHolds(directory, state, options = {}) {
+    const sourceDigest = options.sourceDigest ?? (0, pluginSourceDigest_1.pluginSourceDigest)(directory);
+    if ((0, pluginSourceState_1.pluginSourceState)(directory, { sourceDigest }) === state)
+        return true;
+    (0, processPluginBuildEnvironment_1.processPluginBuildEnvironment)(directory, true);
+    return (0, pluginSourceState_1.pluginSourceState)(directory, { sourceDigest }) === state;
+}
+//# sourceMappingURL=pluginSourceStateHolds.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginSourceStateHolds.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/pluginSourceStateHolds.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAC1D,2DAAwD;AACxD,mFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,gCACE,SAAiB,EACjB,KAAa,EACb,OAAO,GAA8B,EAAE;IAEvC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAA,uCAAkB,EAAC,SAAS,CAAC,CAAC;IAC3E,IAAI,IAAA,qCAAiB,EAAC,SAAS,EAAE,EAAE,YAAY,EAAE,CAAC,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAA,6DAA6B,EAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/C,OAAO,IAAA,qCAAiB,EAAC,SAAS,EAAE,EAAE,YAAY,EAAE,CAAC,KAAK,KAAK,CAAC;AAClE,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * The environment a plugin build in `directory` is keyed on under this
+ * process's variables (`pluginBuildEnvironment`), read once per process and
+ * directory while what it depended on holds, unless `refresh` asks for it
+ * again.
+ *
+ * Reading it probes `go env` and walks GOROOT metadata. A changed compiler
+ * metadata/context memo also runs `go version` and reads the binary, and a
+ * changed SDK manifest rehashes all contributing content. A consumer that
+ * proves a plugin source's state for every adoption, record, or delivery would
+ * pay that work again without reuse. The read is therefore kept under the
+ * variables it was taken with, all of them, so a changed variable reads it
+ * again, and with the metadata of every path it depended on that no variable
+ * carries (`PluginBuildEnvironmentWitness`): the Go tool, the Go environment
+ * file `go env -w` writes, the executables the C toolchain commands name, and
+ * GOROOT. A kept read is reused only while each of them holds its metadata, so
+ * a distinguishable metadata change triggers a new reading at use. This is the
+ * witness's declared distinguishability premise, not detection of every
+ * possible metadata-restored change. The build itself never reads through here:
+ * it keys each binary on a fresh read.
+ *
+ * @param directory The directory a build runs `go` in.
+ * @param refresh Whether to read the environment again rather than reuse it.
+ * @evidence contracts/common.md#principled-implementation Variable serialization is sorted and length-delimited; reuse additionally requires unchanged pre-read metadata for every external dependency, including all contributing GOROOT directories and files, under the witness's documented metadata-distinguishability premise.
+ * @evidence contracts/common.md#clear-and-simple-design One process-local map owns environment memoization; fresh construction and witness validation remain separate operations shared with build verification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Refresh performs the real environment read rather than assuming that a stable compiler path or quiet source tree implies a stable toolchain.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why environment probing is retained, its variable/path invalidation, and why builds still read fresh; descriptive prose and tags are separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Native environment and filesystem identity are delegated to the shared platform-aware probe and metadata witness rather than inferred from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms The delegated owner serializes/hashes variable names/values after text-sensitive sorting and validates witnessed native paths. A qualified hit avoids cold tool/content preparation but not native lookup/path/link/text costs. Misses/refresh delegate actual Go/toolchain/SDK readings; V/P counts alone do not bound all bytes or native work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Directory and all effective variables identify a candidate reading; the complete external-path witness must hold, otherwise the environment is read and its record replaced.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources PluginBuildEnvironmentReadings owns the process-shared map and asynchronous worker/request lifetimes, not this forwarding call. Existing keys are replaced, but distinct directory/variable combinations retain historical witnesses without an eviction bound; consumers and the owner govern that retention.
+ */
+export declare function processPluginBuildEnvironment(directory: string, refresh?: boolean): string;

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

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processPluginBuildEnvironment = processPluginBuildEnvironment;
+const PluginBuildEnvironmentReadings_1 = require("./PluginBuildEnvironmentReadings");
+/**
+ * The environment a plugin build in `directory` is keyed on under this
+ * process's variables (`pluginBuildEnvironment`), read once per process and
+ * directory while what it depended on holds, unless `refresh` asks for it
+ * again.
+ *
+ * Reading it probes `go env` and walks GOROOT metadata. A changed compiler
+ * metadata/context memo also runs `go version` and reads the binary, and a
+ * changed SDK manifest rehashes all contributing content. A consumer that
+ * proves a plugin source's state for every adoption, record, or delivery would
+ * pay that work again without reuse. The read is therefore kept under the
+ * variables it was taken with, all of them, so a changed variable reads it
+ * again, and with the metadata of every path it depended on that no variable
+ * carries (`PluginBuildEnvironmentWitness`): the Go tool, the Go environment
+ * file `go env -w` writes, the executables the C toolchain commands name, and
+ * GOROOT. A kept read is reused only while each of them holds its metadata, so
+ * a distinguishable metadata change triggers a new reading at use. This is the
+ * witness's declared distinguishability premise, not detection of every
+ * possible metadata-restored change. The build itself never reads through here:
+ * it keys each binary on a fresh read.
+ *
+ * @param directory The directory a build runs `go` in.
+ * @param refresh Whether to read the environment again rather than reuse it.
+ * @evidence contracts/common.md#principled-implementation Variable serialization is sorted and length-delimited; reuse additionally requires unchanged pre-read metadata for every external dependency, including all contributing GOROOT directories and files, under the witness's documented metadata-distinguishability premise.
+ * @evidence contracts/common.md#clear-and-simple-design One process-local map owns environment memoization; fresh construction and witness validation remain separate operations shared with build verification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Refresh performs the real environment read rather than assuming that a stable compiler path or quiet source tree implies a stable toolchain.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why environment probing is retained, its variable/path invalidation, and why builds still read fresh; descriptive prose and tags are separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Native environment and filesystem identity are delegated to the shared platform-aware probe and metadata witness rather than inferred from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms The delegated owner serializes/hashes variable names/values after text-sensitive sorting and validates witnessed native paths. A qualified hit avoids cold tool/content preparation but not native lookup/path/link/text costs. Misses/refresh delegate actual Go/toolchain/SDK readings; V/P counts alone do not bound all bytes or native work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Directory and all effective variables identify a candidate reading; the complete external-path witness must hold, otherwise the environment is read and its record replaced.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources PluginBuildEnvironmentReadings owns the process-shared map and asynchronous worker/request lifetimes, not this forwarding call. Existing keys are replaced, but distinct directory/variable combinations retain historical witnesses without an eviction bound; consumers and the owner govern that retention.
+ */
+function processPluginBuildEnvironment(directory, refresh = false) {
+    return PluginBuildEnvironmentReadings_1.PluginBuildEnvironmentReadings.read(directory, refresh);
+}
+//# sourceMappingURL=processPluginBuildEnvironment.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"processPluginBuildEnvironment.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/processPluginBuildEnvironment.ts"],"names":[],"mappings":";;;AAAA,qFAAkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,uCACE,SAAiB,EACjB,OAAO,GAAG,KAAK;IAEf,OAAO,+DAA8B,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC"}

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

@@ -0,0 +1,34 @@
+import type { IPluginCachePruneOptions } from "./IPluginCachePruneOptions";
+/**
+ * Opportunistically bound a part of the cache root whose entries are single
+ * files: the descriptor evaluations under `descriptors/`, the capability
+ * answers under `capabilities/`, and the lowered orphan sources under
+ * `ttsx-orphan/`.
+ *
+ * The policy is the plugin cache's (`CachePrunePolicy`). An entry's last use is
+ * its modification time: a write sets it, and every hit records a use by
+ * setting it again (`recordCacheFileUse`), improving its recent-use priority
+ * under the collection policy rather than pinning it indefinitely. A writer
+ * publishes an entry by renaming a finished staging file over it, so removing
+ * an entry can only make a reader miss and compute the answer again, never read
+ * a partial one; a staging file a crashed writer left behind is an entry nobody
+ * uses, and ages out like one.
+ *
+ * A part absent or nonordinary at admission is left alone. A pass that gets
+ * beyond the interval gate attempts marker publication after eviction; physical
+ * path validation does not retain a directory handle against concurrent root
+ * replacement. Failures are swallowed, since a collection must never fail the
+ * launch that triggered it.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordinary-root validation selects physical spelling for the pass, subject to that path retaining its identity during later lookups. Age and oldest-first size eviction operate on atomically published answer files, whose deletion means a cache miss rather than a partial answer; no directory handle freezes the root against concurrent replacement.
+ * @evidence contracts/common.md#clear-and-simple-design Admission, age eviction, fresh accounting and size eviction are separate phases, followed by one retry marker publication.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout-independent file metadata drives reclamation; failures are tolerated because cache availability is optional, not hidden to fabricate a computed answer.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain payloads, hit-touch metadata, atomic publication and failure behavior under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation lstat rejects aliased root leaves at admission, and later paths use the observed physical root instead of the original ancestor alias. Native per-file removal handles sharing restrictions without shell assumptions; physical spelling is not an ongoing object-identity pin.
+ * @evidence contracts/performance.md#efficient-algorithms Two metadata scans and optional numeric timestamp sorting cost O(entries log entries), with temporary metadata and filename/path text scaling with admitted entries. Root validation and native metadata operations add path work, and interval-marker reading/encoding costs its text bytes; cached answer payload bytes are not read.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Answer equivalence is established by owning readers and producer keys, not eviction.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Thirty-day age and 2 GiB-triggered LRU target historical state; all entries used within the protection window and failed deletions can exceed the budget until later retry.
+ */
+export declare function pruneCacheFileRoot(root: string, options?: Omit<IPluginCachePruneOptions, "protectedEntries">): void;

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

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneCacheFileRoot = pruneCacheFileRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const CachePrunePolicy_1 = require("./CachePrunePolicy");
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+/**
+ * Opportunistically bound a part of the cache root whose entries are single
+ * files: the descriptor evaluations under `descriptors/`, the capability
+ * answers under `capabilities/`, and the lowered orphan sources under
+ * `ttsx-orphan/`.
+ *
+ * The policy is the plugin cache's (`CachePrunePolicy`). An entry's last use is
+ * its modification time: a write sets it, and every hit records a use by
+ * setting it again (`recordCacheFileUse`), improving its recent-use priority
+ * under the collection policy rather than pinning it indefinitely. A writer
+ * publishes an entry by renaming a finished staging file over it, so removing
+ * an entry can only make a reader miss and compute the answer again, never read
+ * a partial one; a staging file a crashed writer left behind is an entry nobody
+ * uses, and ages out like one.
+ *
+ * A part absent or nonordinary at admission is left alone. A pass that gets
+ * beyond the interval gate attempts marker publication after eviction; physical
+ * path validation does not retain a directory handle against concurrent root
+ * replacement. Failures are swallowed, since a collection must never fail the
+ * launch that triggered it.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordinary-root validation selects physical spelling for the pass, subject to that path retaining its identity during later lookups. Age and oldest-first size eviction operate on atomically published answer files, whose deletion means a cache miss rather than a partial answer; no directory handle freezes the root against concurrent replacement.
+ * @evidence contracts/common.md#clear-and-simple-design Admission, age eviction, fresh accounting and size eviction are separate phases, followed by one retry marker publication.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout-independent file metadata drives reclamation; failures are tolerated because cache availability is optional, not hidden to fabricate a computed answer.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain payloads, hit-touch metadata, atomic publication and failure behavior under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation lstat rejects aliased root leaves at admission, and later paths use the observed physical root instead of the original ancestor alias. Native per-file removal handles sharing restrictions without shell assumptions; physical spelling is not an ongoing object-identity pin.
+ * @evidence contracts/performance.md#efficient-algorithms Two metadata scans and optional numeric timestamp sorting cost O(entries log entries), with temporary metadata and filename/path text scaling with admitted entries. Root validation and native metadata operations add path work, and interval-marker reading/encoding costs its text bytes; cached answer payload bytes are not read.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Answer equivalence is established by owning readers and producer keys, not eviction.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Thirty-day age and 2 GiB-triggered LRU target historical state; all entries used within the protection window and failed deletions can exceed the budget until later retry.
+ */
+function pruneCacheFileRoot(root, options = {}) {
+    try {
+        const stats = node_fs_1.default.lstatSync(root);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return;
+        root = SourceBuildCacheLayout_1.SourceBuildCacheLayout.canonicalPluginCacheRoot(root);
+        const marker = node_path_1.default.join(root, CachePrunePolicy_1.CachePrunePolicy.GC_MARKER_FILE);
+        const now = options.now ?? Date.now();
+        const lastRun = SourceBuildCacheLayout_1.SourceBuildCacheLayout.readTimestamp(marker);
+        if (options.force !== true &&
+            lastRun !== null &&
+            lastRun <= now &&
+            now - lastRun < CachePrunePolicy_1.CachePrunePolicy.GC_INTERVAL_MS)
+            return;
+        const maxBytes = options.maxBytes ?? CachePrunePolicy_1.CachePrunePolicy.MAX_BYTES;
+        const protectedAgeMs = options.protectedAgeMs ?? CachePrunePolicy_1.CachePrunePolicy.PROTECTED_AGE_MS;
+        const targetBytes = options.targetBytes ?? CachePrunePolicy_1.CachePrunePolicy.TARGET_BYTES;
+        for (const entry of collectEntries(root))
+            if (now - entry.lastUsedAt > CachePrunePolicy_1.CachePrunePolicy.ENTRY_MAX_AGE_MS)
+                removeEntry(entry.file);
+        const remaining = collectEntries(root);
+        let total = remaining.reduce((sum, entry) => sum + entry.size, 0);
+        if (total > maxBytes) {
+            for (const entry of remaining.sort((a, b) => a.lastUsedAt - b.lastUsedAt)) {
+                if (total <= targetBytes)
+                    break;
+                if (now - entry.lastUsedAt <= protectedAgeMs)
+                    continue;
+                if (removeEntry(entry.file))
+                    total -= entry.size;
+            }
+        }
+        SourceBuildCacheLayout_1.SourceBuildCacheLayout.replaceCacheMetadataFile(marker, `${total > maxBytes
+            ? now - CachePrunePolicy_1.CachePrunePolicy.GC_INTERVAL_MS + protectedAgeMs
+            : now}\n`);
+    }
+    catch {
+        // Collection is opportunistic; the launch proceeds when it fails.
+    }
+}
+/** Snapshot ordinary files, excluding the collector's own interval marker. */
+function collectEntries(root) {
+    const entries = [];
+    let dirents;
+    try {
+        dirents = node_fs_1.default.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return entries;
+    }
+    for (const dirent of dirents) {
+        if (!dirent.isFile() || dirent.name === CachePrunePolicy_1.CachePrunePolicy.GC_MARKER_FILE)
+            continue;
+        const file = node_path_1.default.join(root, dirent.name);
+        try {
+            const stats = node_fs_1.default.lstatSync(file);
+            if (!stats.isFile())
+                continue;
+            entries.push({ file, lastUsedAt: stats.mtimeMs, size: stats.size });
+        }
+        catch {
+            // Removed or replaced since the listing: not an entry this pass sees.
+        }
+    }
+    return entries;
+}
+/** Attempt one payload deletion and report whether the path remains absent. */
+function removeEntry(file) {
+    try {
+        node_fs_1.default.rmSync(file, { force: true });
+        return !node_fs_1.default.existsSync(file);
+    }
+    catch {
+        // Windows may refuse while another process holds the file open.
+        return false;
+    }
+}
+//# sourceMappingURL=pruneCacheFileRoot.js.map

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

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

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

@@ -0,0 +1,28 @@
+import type { IGoBuildCachePruneOptions } from "./IGoBuildCachePruneOptions";
+/**
+ * Attempt byte-policy eviction of selected ordinary Go cache files.
+ *
+ * A maintenance intent blocks new build leases. If any existing lease remains,
+ * maintenance yields without object eviction; coordination metadata can still
+ * change. A later invocation may retry after normal admission checks. Only
+ * ordinary files immediately inside Go's two-hex buckets enter accounting;
+ * nested executable-cache directories, other kinds, coordination metadata and
+ * Go's trim marker are outside this byte policy. Missing observations or failed
+ * removals can leave actual storage above its thresholds without a hard bound.
+ *
+ * Pending, unknown or malformed native guards skip eviction regardless of lease
+ * heartbeat age. Shared-cache admission remains independent of this deletion
+ * protection. Older versions do not cooperate with native guards.
+ *
+ * @evidence contracts/common.md#principled-implementation A published maintenance intent precedes the live-lease check, so builders and deletion coordinate over the same owned physical root before object eviction.
+ * @evidence contracts/common.md#clear-and-simple-design Admission, lease exclusion, eviction and marker publication occur in order; finally invokes intent finish, whose completion/removal remain best-effort.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Go bucket spelling follows its object-cache layout; missing heartbeat startup yields instead of assuming exclusion.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain lease exclusion and which populations are outside the byte policy; inline prose explains delayed over-budget retry.
+ * @evidence contracts/portability.md#os-neutral-implementation Observed ordinary-root spelling, native Dirents and per-file removals avoid shell operations and OS-default identity assumptions; sequential metadata checks do not pin later pathnames.
+ * @evidence contracts/performance.md#efficient-algorithms Listing includes root/bucket entries and their names; selected-file native stats and two O(N log N) numeric sorts account for N observed files without reading payload bytes. Arrays/Sets retain path text and metadata. Root validation, marker bytes, lease-record scans and heartbeat startup add delegated native/JSON costs; inaccessible observations can undercount rather than certify total disk usage.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Go establishes object equivalence; maintenance chooses eviction rather than reusable computation identity.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Default 8 GiB triggers removal toward 6 GiB of accounted files, with a target-sized metadata-recent reserve. Live/unknown leases, missing observations, excluded kinds and failed deletion prevent a hard disk bound. Finally calls intent finish; ordinary synchronous callers do not join refresher termination, while opted-in owners join tracked exit/close and receive failures. Native guards can retain inputs without an age bound; record cleanup can fail; marker pacing requires another invocation and does not schedule maintenance itself.
+ */
+export declare function pruneGoBuildCacheRoot(root: string, options?: IGoBuildCachePruneOptions): void;

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

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneGoBuildCacheRoot = pruneGoBuildCacheRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceNativeRetirement_1 = require("../../../internal/SourceNativeRetirement");
+const GoBuildCacheCoordination_1 = require("./GoBuildCacheCoordination");
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+/**
+ * Attempt byte-policy eviction of selected ordinary Go cache files.
+ *
+ * A maintenance intent blocks new build leases. If any existing lease remains,
+ * maintenance yields without object eviction; coordination metadata can still
+ * change. A later invocation may retry after normal admission checks. Only
+ * ordinary files immediately inside Go's two-hex buckets enter accounting;
+ * nested executable-cache directories, other kinds, coordination metadata and
+ * Go's trim marker are outside this byte policy. Missing observations or failed
+ * removals can leave actual storage above its thresholds without a hard bound.
+ *
+ * Pending, unknown or malformed native guards skip eviction regardless of lease
+ * heartbeat age. Shared-cache admission remains independent of this deletion
+ * protection. Older versions do not cooperate with native guards.
+ *
+ * @evidence contracts/common.md#principled-implementation A published maintenance intent precedes the live-lease check, so builders and deletion coordinate over the same owned physical root before object eviction.
+ * @evidence contracts/common.md#clear-and-simple-design Admission, lease exclusion, eviction and marker publication occur in order; finally invokes intent finish, whose completion/removal remain best-effort.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Go bucket spelling follows its object-cache layout; missing heartbeat startup yields instead of assuming exclusion.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain lease exclusion and which populations are outside the byte policy; inline prose explains delayed over-budget retry.
+ * @evidence contracts/portability.md#os-neutral-implementation Observed ordinary-root spelling, native Dirents and per-file removals avoid shell operations and OS-default identity assumptions; sequential metadata checks do not pin later pathnames.
+ * @evidence contracts/performance.md#efficient-algorithms Listing includes root/bucket entries and their names; selected-file native stats and two O(N log N) numeric sorts account for N observed files without reading payload bytes. Arrays/Sets retain path text and metadata. Root validation, marker bytes, lease-record scans and heartbeat startup add delegated native/JSON costs; inaccessible observations can undercount rather than certify total disk usage.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Go establishes object equivalence; maintenance chooses eviction rather than reusable computation identity.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Default 8 GiB triggers removal toward 6 GiB of accounted files, with a target-sized metadata-recent reserve. Live/unknown leases, missing observations, excluded kinds and failed deletion prevent a hard disk bound. Finally calls intent finish; ordinary synchronous callers do not join refresher termination, while opted-in owners join tracked exit/close and receive failures. Native guards can retain inputs without an age bound; record cleanup can fail; marker pacing requires another invocation and does not schedule maintenance itself.
+ */
+function pruneGoBuildCacheRoot(root, options = {}) {
+    let intent;
+    try {
+        const cacheRoot = GoBuildCacheCoordination_1.GoBuildCacheCoordination.canonicalGoBuildCacheRoot(root);
+        if (SourceNativeRetirement_1.SourceNativeRetirement.isProtected(cacheRoot))
+            return;
+        const marker = node_path_1.default.join(cacheRoot, GO_BUILD_CACHE_GC_MARKER_FILE);
+        const now = options.now ?? Date.now();
+        const lastRun = SourceBuildCacheLayout_1.SourceBuildCacheLayout.readTimestamp(marker);
+        if (options.force !== true &&
+            lastRun !== null &&
+            lastRun <= now &&
+            now - lastRun < GO_BUILD_CACHE_GC_INTERVAL_MS) {
+            return;
+        }
+        intent = GoBuildCacheCoordination_1.GoBuildCacheCoordination.createGoBuildCacheCoordinationRecord(cacheRoot, GoBuildCacheCoordination_1.GoBuildCacheCoordination.GO_BUILD_CACHE_MAINTENANCE_DIR);
+        if (!intent.startHeartbeat()) {
+            // Maintenance is opportunistic. Without an independent heartbeat a
+            // synchronous scan could look abandoned while it is still deleting, so
+            // yield instead of weakening the build/maintenance exclusion.
+            return;
+        }
+        if (GoBuildCacheCoordination_1.GoBuildCacheCoordination.collectLiveGoBuildCacheCoordinationRecords(cacheRoot, GoBuildCacheCoordination_1.GoBuildCacheCoordination.GO_BUILD_CACHE_LEASE_DIR, now).length !== 0) {
+            return;
+        }
+        if (SourceNativeRetirement_1.SourceNativeRetirement.isProtected(cacheRoot))
+            return;
+        const remainingBytes = pruneGoBuildCacheEntries(cacheRoot, {
+            maxBytes: options.maxBytes ?? GO_BUILD_CACHE_MAX_BYTES,
+            now,
+            protectedAgeMs: options.protectedAgeMs ?? GO_BUILD_CACHE_PROTECTED_AGE_MS,
+            targetBytes: options.targetBytes ?? GO_BUILD_CACHE_TARGET_BYTES,
+        });
+        // If recent protection or a transient delete failure left the cache above
+        // the ceiling, retry after the protection window instead of suppressing
+        // every maintenance attempt for a full day.
+        const maxBytes = options.maxBytes ?? GO_BUILD_CACHE_MAX_BYTES;
+        const protectedAgeMs = options.protectedAgeMs ?? GO_BUILD_CACHE_PROTECTED_AGE_MS;
+        const markerTimestamp = remainingBytes > maxBytes
+            ? now - GO_BUILD_CACHE_GC_INTERVAL_MS + protectedAgeMs
+            : now;
+        SourceBuildCacheLayout_1.SourceBuildCacheLayout.replaceCacheMetadataFile(marker, `${markerTimestamp}\n`);
+    }
+    catch {
+        // Go-cache GC is opportunistic; builds still proceed when it fails.
+    }
+    finally {
+        intent?.finish();
+    }
+}
+// Go's own object-cache trim is age-based and has no size ceiling. The default
+// ttsc-owned cache therefore triggers collection above 8 GiB and trims toward
+// 6 GiB of selected ordinary files. A target-sized newest cohort eligible by
+// observed mtime (including the declared one-hour access granularity allowance)
+// is reserved; this is not proof of actual recent use or a hard storage ceiling.
+const GO_BUILD_CACHE_GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const GO_BUILD_CACHE_MAX_BYTES = 8 * 1024 * 1024 * 1024;
+const GO_BUILD_CACHE_TARGET_BYTES = 6 * 1024 * 1024 * 1024;
+const GO_BUILD_CACHE_PROTECTED_AGE_MS = 60 * 60 * 1000;
+const GO_BUILD_CACHE_GC_MARKER_FILE = ".ttsc-gc";
+// Go amortizes cache-hit mtime writes over one hour. An object used inside
+// ttsc's one-hour protection window may therefore still carry an mtime almost
+// one additional hour old.
+const GO_BUILD_CACHE_ACCESS_MTIME_GRANULARITY_MS = 60 * 60 * 1000;
+/** Prune oldest objects toward the byte target while reserving a recent cohort. */
+function pruneGoBuildCacheEntries(root, options) {
+    const entries = collectGoBuildCacheObjects(root);
+    let total = entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (total <= options.maxBytes) {
+        return total;
+    }
+    // Protect the newest recent objects only up to one target-sized cohort
+    // reserve. Protecting every object younger than an hour would let repeated
+    // 2.9 GiB cold builds grow without bound during that hour.
+    const protectedFiles = new Set();
+    let protectedBytes = 0;
+    for (const entry of [...entries].sort((a, b) => b.lastUsedAt - a.lastUsedAt)) {
+        if (options.now - entry.lastUsedAt >
+            options.protectedAgeMs + GO_BUILD_CACHE_ACCESS_MTIME_GRANULARITY_MS) {
+            continue;
+        }
+        if (protectedBytes >= options.targetBytes) {
+            break;
+        }
+        if (protectedBytes + entry.size > options.targetBytes) {
+            break;
+        }
+        protectedFiles.add(entry.file);
+        protectedBytes += entry.size;
+    }
+    for (const entry of entries.sort((a, b) => a.lastUsedAt - b.lastUsedAt)) {
+        if (total <= options.targetBytes) {
+            return total;
+        }
+        if (protectedFiles.has(entry.file)) {
+            continue;
+        }
+        try {
+            node_fs_1.default.rmSync(entry.file, { force: true });
+            total -= entry.size;
+        }
+        catch {
+            // A concurrent antivirus/indexer can transiently hold a file on Windows.
+        }
+    }
+    return total;
+}
+/** Snapshot ordinary files in Go's two-hex object buckets. */
+function collectGoBuildCacheObjects(root) {
+    const output = [];
+    let buckets;
+    try {
+        buckets = node_fs_1.default.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return output;
+    }
+    for (const bucket of buckets) {
+        if (!bucket.isDirectory() || !/^[0-9a-f]{2}$/.test(bucket.name)) {
+            continue;
+        }
+        const directory = node_path_1.default.join(root, bucket.name);
+        let files;
+        try {
+            files = node_fs_1.default.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.isFile()) {
+                continue;
+            }
+            const absolute = node_path_1.default.join(directory, file.name);
+            try {
+                const stats = node_fs_1.default.statSync(absolute);
+                output.push({
+                    file: absolute,
+                    lastUsedAt: stats.mtimeMs,
+                    size: stats.size,
+                });
+            }
+            catch { }
+        }
+    }
+    return output;
+}
+//# sourceMappingURL=pruneGoBuildCacheRoot.js.map

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

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

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

@@ -0,0 +1,46 @@
+import type { IPluginCachePruneOptions } from "./IPluginCachePruneOptions";
+/**
+ * Attempt age/size-based eviction in the plugin binary cache.
+ *
+ * Normally once a day (unless `force`), entries unused for 30 days are eligible
+ * for removal and, past a 2 GiB threshold, oldest eligible entries are removed
+ * toward 80% of it (`CachePrunePolicy`). A target-sized cohort of recently used
+ * entries, active builds and entries named in `protectedEntries` survive. When
+ * the protected set alone keeps the root over the ceiling, the daily marker is
+ * backdated so a later invocation becomes eligible after the protection window
+ * instead of a day later. Failed removals, protected/live/unknown owners and
+ * incomplete accounting can leave the cache above its thresholds indefinitely.
+ * Exceptions are swallowed; native calls and delegated retries can still block
+ * a build.
+ *
+ * Payload deletion acquires the same v3 per-key lease as a builder. A task
+ * retired while it was still running remains protected until its exact
+ * release-owned completion or proven process absence. Old v2 clients use an
+ * independent namespace, so their liveness check is conservative observation
+ * rather than atomic cross-version serialization. Returned binaries have
+ * independent process-reader reservations. Deletion inspects them under its key
+ * lease and preserves live or unknown consumers, including after a producer has
+ * completed and released its build lease.
+ *
+ * Pending, unknown or malformed native guards protect both payload and lock
+ * history independently of owner PID or age. Older compiler versions do not
+ * implement this protection and cannot safely share quarantined roots.
+ *
+ * Binary eviction preserves coordination roots. A v3 retired generation is
+ * reclaimed only after its holder and every registered observer are provably
+ * gone; their tokens may otherwise still act on that generation. Older v2
+ * generations have no observer registry and remain untouched. Persistent roots
+ * therefore still grow with historical keys even after binaries are evicted.
+ *
+ * @evidence contracts/common.md#principled-implementation Binary deletion acquires a v3 per-key lease and rechecks old v2 plus unfinished retired-task ownership; completed payload work and reusable fence history have distinct proofs, under the cooperating protocol's lifetime premises.
+ * @evidence contracts/common.md#clear-and-simple-design Binary accounting and generation-history reclamation remain separate phases because their ownership lifetimes differ.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Old v2 capabilities are not assumed expired; unknown ownership defers reclamation instead of hiding protocol uncertainty under a timeout.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish target-sized recent protection, retry behavior and persistent coordination-root growth.
+ * @evidence contracts/portability.md#os-neutral-implementation Root and history-child lstat/realpath checks and payload Dirent selection use observed native kinds and spelling; these sequential observations do not pin pathnames against replacement. Native deletion failures defer eviction without assuming volume case policy.
+ * @evidence contracts/performance.md#efficient-algorithms Age and size phases take two recursive payload metadata snapshots; two entry sorts add O(E log E) comparisons. Work includes entry/path text, native size/timestamp observations, explicit exclusions and repeated per-key owner/generation/observer/reader JSON and liveness scans, plus recursive deletion contents. Binary bytes are not read, but inaccessible size observations can undercount. Delegated lock inspection/retirement can retry without a deadline.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Producers and build locks establish valid binary reuse; this operation selects reclamation candidates.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each deletion attempt owns one v3 lease with finally release/reporting; cleanup failure may retain ownership, and eligible native retries can block indefinitely. Inspection can publish process-lifetime observer records. Removal of payload/history is attempted, not guaranteed: live/unknown readers, protected entries, failures, old v2 history and persistent roots can retain bytes or historical keys without a finite bound. Backdated markers only enable a later invocation.
+ */
+export declare function prunePluginCacheRoot(root: string, options?: IPluginCachePruneOptions): void;