ttsc 0.30.4 → 0.31.0

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

@@ -0,0 +1,47 @@
+/**
+ * The state of one plugin source directory as a plugin binary is built from it:
+ * the digest of its sources (`pluginSourceDigest`) together with the
+ * environment a build there is keyed on (`pluginBuildEnvironment`).
+ *
+ * The plugin cache key covers both selected identities (`computeCacheKey`): a
+ * changed `GOFLAGS`, cgo setting, C compiler, or Go toolchain builds another
+ * binary as surely as an edited source file does. The transform envelope
+ * reports this state for directories selected by the loader's pluginSources
+ * policy, which omits installed ttsc directories, and a consumer that keeps the
+ * output beyond its process proves it through the `ttsc/plugin-source` entry,
+ * with no rule of its own. For a plugin's own module root the environment is
+ * the one its build keyed on exactly. For a contributor or an overlay, which
+ * the build reads under the plugin's module root, it is the environment a build
+ * there would take. It is not an assertion that arbitrary directory-local tool
+ * or environment resolution is identical to the host module's resolution.
+ *
+ * Sources are read unless the caller supplies their digest. Under this
+ * process's own environment the environment is read once per directory and set
+ * of variables (`processPluginBuildEnvironment`), and a proof that must not
+ * accept a stale one compares through `pluginSourceStateHolds`, which reads it
+ * again before it refutes a state.
+ *
+ * @param directory The source directory.
+ * @param options.env An effective environment other than this process's, which
+ *   is read fresh.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller already read it.
+ * @param options.environment The directory's `pluginBuildEnvironment`, when the
+ *   caller already read it, as a plugin build's key does.
+ * @returns The state, as lowercase hex.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation The state combines source and environment digests because both affect compiled plugin behavior; supplied readings preserve the exact inputs a build already keyed on.
+ * @evidence contracts/common.md#clear-and-simple-design One composition function delegates source selection and environment resolution to their owning implementations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The state is derived from real source/toolchain readings rather than compile output or an assumed stable process environment.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain module-root versus overlay environment meaning and the provenance required for supplied digests.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source and toolchain identity are delegated to the shared filesystem/process readers; the final digest is platform-independent serialized text.
+ * @evidence contracts/performance.md#efficient-algorithms Composition serializes/hashes supplied digest strings whose public inputs are not length-validated; owning generated digests are fixed-width hex. Missing readings delegate native source enumeration/full reads and environment variable/witness/tool/SDK work, without establishing an unmeasured dominant cost ranking.
+ * @evidence contracts/performance.md#reuse-equivalent-work Supplied source/environment strings are trusted producer readings, not independently revalidated here. Process-environment memos require their owner's variable/path witness checks; explicit injected environments are read fresh. Equality inherits the selected-source and native metadata premises.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function retains no resource or state after returning; process-environment memo lifetime belongs to its separate owner.
+ */
+export declare function pluginSourceState(directory: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    environment?: string;
+    sourceDigest?: string;
+}): string;

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

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSourceState = pluginSourceState;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const pluginBuildEnvironment_1 = require("./pluginBuildEnvironment");
+const pluginSourceDigest_1 = require("./pluginSourceDigest");
+const processPluginBuildEnvironment_1 = require("./processPluginBuildEnvironment");
+/**
+ * The state of one plugin source directory as a plugin binary is built from it:
+ * the digest of its sources (`pluginSourceDigest`) together with the
+ * environment a build there is keyed on (`pluginBuildEnvironment`).
+ *
+ * The plugin cache key covers both selected identities (`computeCacheKey`): a
+ * changed `GOFLAGS`, cgo setting, C compiler, or Go toolchain builds another
+ * binary as surely as an edited source file does. The transform envelope
+ * reports this state for directories selected by the loader's pluginSources
+ * policy, which omits installed ttsc directories, and a consumer that keeps the
+ * output beyond its process proves it through the `ttsc/plugin-source` entry,
+ * with no rule of its own. For a plugin's own module root the environment is
+ * the one its build keyed on exactly. For a contributor or an overlay, which
+ * the build reads under the plugin's module root, it is the environment a build
+ * there would take. It is not an assertion that arbitrary directory-local tool
+ * or environment resolution is identical to the host module's resolution.
+ *
+ * Sources are read unless the caller supplies their digest. Under this
+ * process's own environment the environment is read once per directory and set
+ * of variables (`processPluginBuildEnvironment`), and a proof that must not
+ * accept a stale one compares through `pluginSourceStateHolds`, which reads it
+ * again before it refutes a state.
+ *
+ * @param directory The source directory.
+ * @param options.env An effective environment other than this process's, which
+ *   is read fresh.
+ * @param options.sourceDigest The directory's `pluginSourceDigest`, when the
+ *   caller already read it.
+ * @param options.environment The directory's `pluginBuildEnvironment`, when the
+ *   caller already read it, as a plugin build's key does.
+ * @returns The state, as lowercase hex.
+ * @throws When a listed source file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation The state combines source and environment digests because both affect compiled plugin behavior; supplied readings preserve the exact inputs a build already keyed on.
+ * @evidence contracts/common.md#clear-and-simple-design One composition function delegates source selection and environment resolution to their owning implementations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The state is derived from real source/toolchain readings rather than compile output or an assumed stable process environment.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain module-root versus overlay environment meaning and the provenance required for supplied digests.
+ * @evidence contracts/portability.md#os-neutral-implementation Native source and toolchain identity are delegated to the shared filesystem/process readers; the final digest is platform-independent serialized text.
+ * @evidence contracts/performance.md#efficient-algorithms Composition serializes/hashes supplied digest strings whose public inputs are not length-validated; owning generated digests are fixed-width hex. Missing readings delegate native source enumeration/full reads and environment variable/witness/tool/SDK work, without establishing an unmeasured dominant cost ranking.
+ * @evidence contracts/performance.md#reuse-equivalent-work Supplied source/environment strings are trusted producer readings, not independently revalidated here. Process-environment memos require their owner's variable/path witness checks; explicit injected environments are read fresh. Equality inherits the selected-source and native metadata premises.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function retains no resource or state after returning; process-environment memo lifetime belongs to its separate owner.
+ */
+function pluginSourceState(directory, options = {}) {
+    return node_crypto_1.default
+        .createHash("sha256")
+        .update(`source=${options.sourceDigest ?? (0, pluginSourceDigest_1.pluginSourceDigest)(directory)}\n` +
+        `environment=${options.environment ??
+            (options.env === undefined
+                ? (0, processPluginBuildEnvironment_1.processPluginBuildEnvironment)(directory)
+                : (0, pluginBuildEnvironment_1.pluginBuildEnvironment)(directory, options.env))}\n`)
+        .digest("hex");
+}
+//# sourceMappingURL=pluginSourceState.js.map

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;