ttsc 0.30.4 → 0.31.0

package/src/plugin/internal/source/pluginModuleReplaceDirectories.ts

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolvePhysicalPath } from "../../../internal/pathIdentity/resolvePhysicalPath";
+import { GoSourceInputs } from "./GoSourceInputs";
+import { GoToolResolution } from "./GoToolResolution";
+import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
+import { resolveGoCompiler } from "./resolveGoCompiler";
+import { selectPluginModuleReplaceDirectories } from "./selectPluginModuleReplaceDirectories";
+import { spawnGoTool } from "./spawnGoTool";
+
+/**
+ * The local directories outside a plugin's Go module that its `go.mod`
+ * `replace` directives name before the build prepares its scratch sources.
+ *
+ * A `replace` whose target is a filesystem path (Go's rule: absolute, or
+ * beginning with `./` or `../`) makes the build compile that directory as the
+ * replaced module. A target inside the module is copied and keyed with it. An
+ * outside target supplies a separate source population: the cache key digests
+ * it, the load reports its state among `pluginSources`, and a watch observes
+ * it. buildSourcePlugin snapshots and proves that target's copy, then anchors
+ * the replacement to the copy before compiling. A relative target also has to
+ * resolve from the module's own directory, as it does for `go build` there, and
+ * not from the scratch copy the build runs in.
+ *
+ * The directives are read through `go mod edit -json`, Go's own reading of
+ * `go.mod`, not a copy of its grammar. Only the main module's directives count,
+ * as Go ignores the `replace` directives of every other module.
+ *
+ * @param moduleRoot The plugin's Go module root, which holds its `go.mod`.
+ * @param env The build's effective environment.
+ * @param goBinary The Go tool the build runs, or `undefined` to resolve it as
+ *   the build does.
+ * @returns Each replacement outside the module, sorted by module path: the
+ *   replaced module path and version, the target as `go.mod` spells it, and the
+ *   target's absolute path.
+ * @throws On non-ENOENT manifest reads, or when the replace-triggered Go query
+ *   fails or supplies an unusable JSON result. A no-marker manifest skips Go
+ *   parsing here; this is not general go.mod validation.
+ * @evidence contracts/common.md#principled-implementation When the replace marker triggers a query, Go parses its grammar. Unversioned local targets selected outside best-effort root/target spellings are reported, resolving relative paths from the original module; unavailable identity resolution does not certify complete physical containment.
+ * @evidence contracts/common.md#clear-and-simple-design A cheap no-replace scan avoids an unnecessary subprocess, while Go JSON parsing and physical containment stay in one owning operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation uses Go's supported mod-edit interface instead of a handwritten grammar or special-casing particular dependency names.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain external versus internal replacement ownership, original-directory resolution and returned spellings; failure behavior is documented.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path and physical-path resolution determine containment; Go local-path syntax accepts native absolute paths and Windows-relative backslashes only on Windows.
+ * @evidence contracts/performance.md#efficient-algorithms Full manifest read/UTF-8 marker scan can skip Go parsing. Otherwise native tool/env/capture and full JSON work precede a pass over all parsed directives, not only returned ones; each selected local target uses native best-effort identity resolution, which can traverse ancestors/probe case. Sorting returned module/version strings processes their bytes, with complete manifest/output/path arrays retained transiently and no replacement content digest scan here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This reader establishes the current module directives; callers share resulting source readings in computeCacheKey, not a stale directive memo here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation acquires no retained handle or historical registry; spawnGoTool owns synchronous capture and its cleanup attempts, which can fail. Manifest/JSON/native identity contexts are call-owned and selected records transfer to the caller without pinning future directory state.
+ */
+export function pluginModuleReplaceDirectories(
+  moduleRoot: string,
+  env: NodeJS.ProcessEnv,
+  goBinary?: string,
+): IPluginModuleReplaceDirectory[] {
+  const root = path.resolve(moduleRoot);
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(root, "go.mod"), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  // Every `replace` directive spells the word, so a file without it has none,
+  // and Go need not be run to read it. A file with it is read by Go itself.
+  if (!text.includes("replace")) return [];
+  const go =
+    goBinary ??
+    GoToolResolution.resolveGoToolForBuild(
+      resolveGoCompiler(env).binary,
+      env,
+      root,
+    );
+  const result = spawnGoTool(go, ["mod", "edit", "-json"], {
+    cwd: root,
+    encoding: "utf8",
+    env: GoSourceInputs.goBuildEnv(go, undefined, env),
+    windowsHide: true,
+  });
+  if (result.error !== undefined || result.status !== 0)
+    throw new Error(
+      `ttsc: reading ${path.join(root, "go.mod")} failed: ${
+        result.error?.message ?? (result.stderr || result.stdout)
+      }`,
+    );
+  const parsed = JSON.parse(result.stdout) as {
+    Replace?: readonly {
+      New?: { Path?: string; Version?: string };
+      Old?: { Path?: string; Version?: string };
+    }[];
+  };
+  return selectPluginModuleReplaceDirectories(
+    root,
+    parsed.Replace ?? [],
+    resolvePhysicalPath,
+  );
+}

package/src/plugin/internal/source/pluginSourceCovers.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+
+import { prunesPluginSourceDirectory } from "./prunesPluginSourceDirectory";
+
+/**
+ * Whether a path below a plugin source directory can bear on the sources in the
+ * directory's state (`pluginSourceState`), so an observer of the directory as a
+ * subtree must hear it.
+ *
+ * The plugin build passes over every directory it prunes
+ * (`prunesPluginSourceDirectory`: a nested `node_modules`, a repository's
+ * `.git`), so nothing below one moves the state, and an observer that watched
+ * them would re-prove the state, or rebuild, for every write of a package
+ * manager or of Git. `ttsc --watch` and `@ttsc/unplugin`'s observers answer the
+ * question with this one rule. An injected filesystem observer can supply its
+ * path grammar explicitly; native compiler and filesystem callers retain the
+ * current process default.
+ *
+ * @param root The plugin source directory.
+ * @param file The path, absolute.
+ * @param kind `"directory"` for a directory an observer would watch, which is
+ *   passed over when any of its own components is pruned; `"entry"` for the
+ *   path an event names, whose own name may be a file the build reads whatever
+ *   it is called, so only the directories above it are checked.
+ * @param platform The observed path grammar, defaulting to the current process.
+ * @evidence contracts/common.md#principled-implementation Relative containment uses the observed path grammar to reject paths outside the source; omitting the final component for entry events preserves files whose names happen to match pruned directory names.
+ * @evidence contracts/common.md#clear-and-simple-design One kind discriminant separates watched-directory membership from event-entry membership without duplicating path containment logic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same shared prune predicate controls source observers rather than a local list adjusted to a particular watcher failure.
+ * @evidence contracts/common.md#meaningful-documentation Native parameter comments explain why a directory's own name counts while an event entry's own name may still be a source file.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32/posix grammar follows the observer's filesystem view while native callers default to process.platform; lexical containment establishes neither physical alias identity nor a volume's case capability.
+ * @evidence contracts/performance.md#efficient-algorithms Relative-path construction and one component scan cost O(P) time and O(P) temporary path/component space, without filesystem enumeration.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is a current path-policy query; watcher and source-state reuse belong to consumers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No watcher or persistent handle is acquired here.
+ */
+export function pluginSourceCovers(
+  root: string,
+  file: string,
+  kind: "directory" | "entry",
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  const relative = paths.relative(root, file);
+  if (relative === "") return true;
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${paths.sep}`) ||
+    paths.isAbsolute(relative)
+  )
+    return false;
+  const components = relative.split(paths.sep);
+  if (kind === "entry") components.pop();
+  return !components.some(prunesPluginSourceDirectory);
+}

package/src/plugin/internal/source/pluginSourceDigest.ts

@@ -0,0 +1,55 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { collectPluginSourceFiles } from "./collectPluginSourceFiles";
+
+/**
+ * The files of one plugin source directory as a plugin build reads them: a
+ * SHA-256 over the relative path and bytes of every file the build keys its
+ * binary on (`collectPluginSourceFiles`), in sorted order. Each JSON header
+ * gives the relative path and exact following byte length, so file contents
+ * cannot imitate another file's boundary.
+ *
+ * A plugin's binary is keyed on these files. Its transform output can also
+ * depend on runtime inputs that the owning producer must report; this digest
+ * alone does not certify all such dependencies. The cache key folds the digest
+ * of each directory it covers (`computeCacheKey`), and the transform envelope
+ * reports each plugin source directory's state
+ * (`ITtscCompilerTransformation.ISuccess.pluginSources`), this digest together
+ * with the build environment (`pluginSourceState`), so a consumer that caches
+ * the output proves it still holds through the `ttsc/plugin-source` entry
+ * (`pluginSourceStateHolds`) instead of a copy of the rule.
+ *
+ * Content rather than size and modification time: the build reads every byte
+ * anyway, and a consumer's proof must not accept an edit that kept a file's
+ * size within one clock tick. A consumer that proves a source on every delivery
+ * may keep a digest under matching metadata and the observing owner's
+ * separability policy, then hand it to `pluginSourceStateHolds`; that judgment
+ * is the consumer's, which owns a clock reference, and the file list is this
+ * one's. A directory that does not exist has the digest of an empty one, as it
+ * keys the build.
+ *
+ * @param directory The source directory.
+ * @returns The digest, as lowercase hex.
+ * @throws When a listed file cannot be read, as the build itself would.
+ * @evidence contracts/common.md#principled-implementation Sorted relative paths and byte lengths form unambiguous JSON headers followed by exact file bytes; embedded newlines cannot imitate another file boundary, and metadata alone cannot establish source equality.
+ * @evidence contracts/common.md#clear-and-simple-design Selection belongs to collectPluginSourceFiles and this function owns only deterministic content hashing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Source identity uses the build's declared file population rather than expected outputs, fixture names or mtime-only shortcuts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish content and metadata proofs, state missing-directory behavior and identify lowercase-hex output and read failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths are made root-relative and slash-normalized only for digest serialization; filesystem reads retain the original native paths.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native lookup and path-text-sensitive comparisons; each selected file is read in full and its normalized relative path/JSON length header plus B content bytes are hashed. Each iteration uses one file Buffer with the complete path population and transient serialization; native reads/path/header bytes also contribute costs.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This computes a fresh digest; load-scoped maps and separable metadata proofs own reuse of that digest.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The hash and per-file buffers are call-local; no persistent descriptor or cache is owned here.
+ */
+export function pluginSourceDigest(directory: string): string {
+  const hash = crypto.createHash("sha256");
+  for (const file of collectPluginSourceFiles(directory)) {
+    const relative = path.relative(directory, file).split(path.sep).join("/");
+    const contents = fs.readFileSync(file);
+    hash.update(JSON.stringify([relative, contents.length]));
+    hash.update(contents);
+  }
+  return hash.digest("hex");
+}

package/src/plugin/internal/source/pluginSourceFilesSignature.ts

@@ -0,0 +1,54 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+import { collectPluginSourceFiles } from "./collectPluginSourceFiles";
+
+/**
+ * The metadata signature of exactly the files a plugin source directory's
+ * digest reads (`collectPluginSourceFiles`), each by its path relative to the
+ * directory, and whether every stamp in it is separable, or `undefined` when a
+ * listed file cannot be stated.
+ *
+ * A host that proves a plugin source often may keep the digest it read while
+ * this signature holds still, as git keeps an index entry, and hand it to
+ * `pluginSourceStateHolds` instead of reading every file again: a file added,
+ * removed or renamed changes the selected population, while content-write
+ * detection relies on the owner's reported metadata and separability premises.
+ * The signature itself does not read content or certify arbitrary metadata
+ * restoration. What metadata/separability proves is the host's to answer, since
+ * only the host owns a clock reference on the filesystem it observes
+ * (`evidence`). The file list is ttsc's, so every host signs exactly what the
+ * build keys on: `@ttsc/unplugin` keeps a digest per delivery this way, and the
+ * capability-resolution cache across processes.
+ *
+ * @param directory The plugin source directory, absolute.
+ * @param evidence One file's metadata signature and separability, or
+ *   `undefined` when it cannot be stated.
+ * @evidence contracts/common.md#principled-implementation Each selected file's relative path and caller-supplied metadata enter the signature, while all separability flags must hold; absent metadata rejects the proof rather than pretending an unreadable file is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design The shared file population stays with ttsc while the observing owner supplies filesystem stamps and its clock-based separability judgment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The function does not infer safe reuse from a quiet watcher or a convenient timestamp; the consumer must establish each stamp's separability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains selected population changes and why metadata/separability premises and the evidence callback belong to the observing host, without equating this signature to content observation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative path spelling identifies files in this process; actual filesystem stamp precision and case capabilities are supplied by the observing owner.
+ * @evidence contracts/performance.md#efficient-algorithms Sorted enumeration includes native listing/path-text comparison costs. Each file invokes caller evidence and hashes relative-path/metadata-signature JSON bytes; callback cost is the observer's work and cannot be bounded by F alone. This function does not reread file content, but retains the full selected path population during the walk.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This returns the validation signature; the consumer owns the digest and permission to reuse it against that signature.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned signature and separability value survive; the callback's external observation resources remain caller-owned.
+ */
+export function pluginSourceFilesSignature(
+  directory: string,
+  evidence: (
+    file: string,
+  ) => { separable: boolean; signature: string } | undefined,
+): { separable: boolean; signature: string } | undefined {
+  const hash = crypto.createHash("sha256");
+  let separable = true;
+  for (const file of collectPluginSourceFiles(directory)) {
+    const observed = evidence(file);
+    if (observed === undefined) return undefined;
+    hash.update(
+      JSON.stringify([path.relative(directory, file), observed.signature]),
+    );
+    separable &&= observed.separable;
+  }
+  return { separable, signature: hash.digest("hex") };
+}

package/src/plugin/internal/source/pluginSourceState.ts

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+
+import { pluginBuildEnvironment } from "./pluginBuildEnvironment";
+import { pluginSourceDigest } from "./pluginSourceDigest";
+import { processPluginBuildEnvironment } from "./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.
+ */
+export function pluginSourceState(
+  directory: string,
+  options: {
+    env?: NodeJS.ProcessEnv;
+    environment?: string;
+    sourceDigest?: string;
+  } = {},
+): string {
+  return crypto
+    .createHash("sha256")
+    .update(
+      `source=${options.sourceDigest ?? pluginSourceDigest(directory)}\n` +
+        `environment=${
+          options.environment ??
+          (options.env === undefined
+            ? processPluginBuildEnvironment(directory)
+            : pluginBuildEnvironment(directory, options.env))
+        }\n`,
+    )
+    .digest("hex");
+}

package/src/plugin/internal/source/pluginSourceStateHolds.ts

@@ -0,0 +1,45 @@
+import { pluginSourceDigest } from "./pluginSourceDigest";
+import { pluginSourceState } from "./pluginSourceState";
+import { processPluginBuildEnvironment } from "./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.
+ */
+export function pluginSourceStateHolds(
+  directory: string,
+  state: string,
+  options: { sourceDigest?: string } = {},
+): boolean {
+  const sourceDigest = options.sourceDigest ?? pluginSourceDigest(directory);
+  if (pluginSourceState(directory, { sourceDigest }) === state) return true;
+  processPluginBuildEnvironment(directory, true);
+  return pluginSourceState(directory, { sourceDigest }) === state;
+}

package/src/plugin/internal/source/processPluginBuildEnvironment.ts

@@ -0,0 +1,40 @@
+import { PluginBuildEnvironmentReadings } from "./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.
+ */
+export function processPluginBuildEnvironment(
+  directory: string,
+  refresh = false,
+): string {
+  return PluginBuildEnvironmentReadings.read(directory, refresh);
+}

package/src/plugin/internal/source/pruneCacheFileRoot.ts

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { CachePrunePolicy } from "./CachePrunePolicy";
+import type { IPluginCachePruneOptions } from "./IPluginCachePruneOptions";
+import { SourceBuildCacheLayout } from "./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.
+ */
+export function pruneCacheFileRoot(
+  root: string,
+  options: Omit<IPluginCachePruneOptions, "protectedEntries"> = {},
+): void {
+  try {
+    const stats = fs.lstatSync(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) return;
+    root = SourceBuildCacheLayout.canonicalPluginCacheRoot(root);
+    const marker = path.join(root, CachePrunePolicy.GC_MARKER_FILE);
+    const now = options.now ?? Date.now();
+    const lastRun = SourceBuildCacheLayout.readTimestamp(marker);
+    if (
+      options.force !== true &&
+      lastRun !== null &&
+      lastRun <= now &&
+      now - lastRun < CachePrunePolicy.GC_INTERVAL_MS
+    )
+      return;
+    const maxBytes = options.maxBytes ?? CachePrunePolicy.MAX_BYTES;
+    const protectedAgeMs =
+      options.protectedAgeMs ?? CachePrunePolicy.PROTECTED_AGE_MS;
+    const targetBytes = options.targetBytes ?? CachePrunePolicy.TARGET_BYTES;
+    for (const entry of collectEntries(root))
+      if (now - entry.lastUsedAt > 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.replaceCacheMetadataFile(
+      marker,
+      `${
+        total > maxBytes
+          ? now - CachePrunePolicy.GC_INTERVAL_MS + protectedAgeMs
+          : now
+      }\n`,
+    );
+  } catch {
+    // Collection is opportunistic; the launch proceeds when it fails.
+  }
+}
+
+/** One ordinary cache file's eviction metadata from this pass. */
+interface ICacheFileEntry {
+  /** Ordinary file path under the physical answer-cache root. */
+  file: string;
+
+  /** Last-use modification timestamp in milliseconds. */
+  lastUsedAt: number;
+
+  /** Snapshot byte size. */
+  size: number;
+}
+
+/** Snapshot ordinary files, excluding the collector's own interval marker. */
+function collectEntries(root: string): ICacheFileEntry[] {
+  const entries: ICacheFileEntry[] = [];
+  let dirents: fs.Dirent[];
+  try {
+    dirents = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+  for (const dirent of dirents) {
+    if (!dirent.isFile() || dirent.name === CachePrunePolicy.GC_MARKER_FILE)
+      continue;
+    const file = path.join(root, dirent.name);
+    try {
+      const stats = fs.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: string): boolean {
+  try {
+    fs.rmSync(file, { force: true });
+    return !fs.existsSync(file);
+  } catch {
+    // Windows may refuse while another process holds the file open.
+    return false;
+  }
+}