ttsc 0.30.4 → 0.31.0

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

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * What of a Go source plugin, and of its toolchain, the build and the cache key
+ * both see.
+ *
+ * The source walk and the cache key must agree on which files count, or an
+ * irrelevant file would bust the cached binary (or a relevant one would not),
+ * and the build must run with the same toolchain environment the key hashed.
+ *
+ * Membership is ttsc's declared snapshot naming policy, not Go dependency
+ * discovery. Excluded entries are neither copied nor hashed, even when Go could
+ * embed them in the original package. File-backed plugin data must use names
+ * and directories included by this policy. Generated workspace files belong to
+ * the scratch build; the caller's excluded workspace bytes are not preserved.
+ *
+ * @evidence contracts/common.md#principled-implementation One policy defines the selected source snapshot and fixed artifact flags so hashing, copying and observers agree on its population; name exclusions do not establish which files a raw Go package could consume.
+ * @evidence contracts/common.md#clear-and-simple-design Source-name predicates and invocation-environment construction are centralized for consumers instead of copying their policies across loaders and watchers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The declared naming exclusions apply uniformly to source consumers, including deliberately embedded data with matching names; GOWORK and managed GOCACHE express the scratch build protocol rather than fixture-specific exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish the snapshot naming policy from Go input discovery and describe excluded data and workspace ownership; invocation and artifact-flag prose explains their separate build responsibilities.
+ * @evidence contracts/portability.md#os-neutral-implementation Native roots use Node path APIs; the same configured sidecar-name exclusions apply across platforms without deriving filesystem capabilities from the running OS.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups input policies; each function owns its environment or membership processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Fixed policies are not retained computation; this namespace owns no runtime memo.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Policy collections have fixed population and do not own external resources.
+ */
+export namespace GoSourceInputs {
+  /**
+   * Artifact flags shared by native compilation and its environment identity.
+   *
+   * Go's trimpath removes disposable materialization paths from object keys and
+   * debug information. Runtime source locations identify module files; source
+   * diagnostics and embedded file contents still come from the snapshot.
+   */
+  export const BUILD_FLAGS: readonly string[] = Object.freeze(["-trimpath"]);
+
+  /**
+   * Names of directories excluded below a plugin source root: a nested
+   * `node_modules`, a repository's `.git`, and ttsc's own `.ttsc`. An observer
+   * outside this package, such as `ttscserver`'s native host, is handed this
+   * list rather than a copy of it.
+   */
+  export const PRUNED_SOURCE_DIRECTORY_NAMES: readonly string[] = [
+    "node_modules",
+    ".git",
+    ".ttsc",
+  ];
+
+  const PRUNE_DIRS = new Set(PRUNED_SOURCE_DIRECTORY_NAMES);
+
+  const GENERATED_WORKSPACE_FILES = new Set(["go.work", "go.work.sum"]);
+
+  /**
+   * The environment of a `go` invocation: `GOWORK=auto`, ttsc's own `GOCACHE`
+   * when a cache root is given, and `GOROOT` inferred from the binary's
+   * location when the copied environment's value is absent or empty. Build
+   * callers supply the managed cache; metadata callers retain their ambient
+   * GOCACHE.
+   *
+   * @evidence contracts/common.md#principled-implementation A copied environment receives explicit workspace/cache settings and an inferred SDK root only when its existing GOROOT value is absent or empty; nonempty caller values remain unchanged.
+   * @evidence contracts/common.md#clear-and-simple-design One constructor serves build and metadata invocations; omitting the cache root intentionally keeps read-only probes separate from owned-cache writes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The caller's environment is preserved rather than mutating process globals, and documented Go variables express supported invocation policy.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states override precedence and why only actual builds receive managed GOCACHE; tags have separate presentation.
+   * @evidence contracts/portability.md#os-neutral-implementation Native SDK inference delegates to path APIs, and Go's environment variables carry process configuration across supported operating systems.
+   * @evidence contracts/performance.md#efficient-algorithms Environment enumeration copies E property references and processes key names; values are not deep-copied. SDK inference also performs native path-text construction and an existence query, whose filesystem/path costs are not bounded by E alone.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each invocation needs its effective environment copy; no retained computation is coordinated here.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only a call-local environment object is created.
+   */
+  export function goBuildEnv(
+    goBinary: string,
+    goBuildCacheRoot?: string,
+    effectiveEnv: NodeJS.ProcessEnv = process.env,
+  ): NodeJS.ProcessEnv {
+    const env = { ...effectiveEnv };
+    env.GOWORK = "auto";
+    // Only the actual `go build` needs ttsc's GOCACHE; read-only metadata spawns
+    // (`go mod edit`, `go env`, `go version`) call goBuildEnv with no cache root
+    // and inherit ambient GOCACHE rather than receiving the managed build
+    // cache here. This constructor does not certify child-side effects.
+    if (goBuildCacheRoot) {
+      env.GOCACHE = goBuildCacheRoot;
+    }
+    const goRoot = inferGoRoot(goBinary);
+    if (goRoot && !env.GOROOT) {
+      env.GOROOT = goRoot;
+    }
+    return env;
+  }
+
+  /**
+   * Infer an SDK root for an absolute binary path inside `<root>/bin` when
+   * `<root>/src/runtime` exists. The binary basename and runtime entry kind are
+   * not validated here; `null` means this layout check did not match.
+   *
+   * @evidence contracts/common.md#principled-implementation An absolute binary path under bin and an existing src/runtime path establish this layout inference; the selected compiler's actual identity belongs to its resolution/probing owner, and other layouts leave the caller's environment unchanged.
+   * @evidence contracts/common.md#clear-and-simple-design Small early returns expose each required layout condition without a speculative toolchain-discovery abstraction.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout recognition uses the SDK's real structure, not a particular user's install path or expected test directory.
+   * @evidence contracts/common.md#meaningful-documentation Native prose documents the recognized layout and null meaning rather than merely repeating the return type.
+   * @evidence contracts/portability.md#os-neutral-implementation Node absolute/dirname/join operations use native path syntax; the Go SDK's bin and src/runtime components are distribution-defined names.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms A fixed sequence of native absolute/dirname/basename/join operations and one existence query checks the layout without enumerating a source tree. Path text and native lookup still contribute cost; fixed operation count is not a constant-byte filesystem bound.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Existence is checked for the current invocation rather than memoized independently of SDK changes.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function retains no state or native handle.
+   */
+  export function inferGoRoot(goBinary: string): string | null {
+    if (!path.isAbsolute(goBinary)) return null;
+    const binDir = path.dirname(goBinary);
+    if (path.basename(binDir) !== "bin") return null;
+    const goRoot = path.dirname(binDir);
+    return fs.existsSync(path.join(goRoot, "src", "runtime")) ? goRoot : null;
+  }
+
+  /**
+   * Whether a directory is excluded from the source snapshot: `node_modules`,
+   * `.git`, and `.ttsc`. Membership is by name, even for caller-owned data.
+   *
+   * @evidence contracts/common.md#principled-implementation Exact membership in the shared directory-name set makes every source consumer use the same snapshot omission rule.
+   * @evidence contracts/common.md#clear-and-simple-design One predicate exposes policy without requiring walkers to duplicate its set.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts These are declared subtree exclusions, not a test of whether every matching directory is owned by a package manager, repository or cache.
+   * @evidence contracts/common.md#meaningful-documentation Native prose names the omitted directory categories, with a blank line before tags.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This name-membership predicate performs no native lookup or path interpretation.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms A prebuilt three-name set avoids rebuilding policy per directory; lookup still compares/hashes the supplied name under native JavaScript string/Set behavior and does not inspect directory content.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Static policy lookup does not coordinate a completed or in-flight computation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The fixed module policy has constant population and owns no external resource.
+   */
+  export function shouldPruneDirectory(name: string): boolean {
+    return PRUNE_DIRS.has(name);
+  }
+
+  /**
+   * Names of files excluded from the snapshot: workspace files and names
+   * commonly used for operating-system sidecars. Excluding them avoids key
+   * changes on unrelated workspace or file-browser writes, but also excludes
+   * caller-authored data with those names. An observer that runs outside this
+   * package, such as `ttscserver`'s native host, is handed this list rather
+   * than a copy of it.
+   */
+  export const OMITTED_SOURCE_FILE_NAMES: readonly string[] = [
+    ...GENERATED_WORKSPACE_FILES,
+    ".DS_Store",
+    "Thumbs.db",
+  ];
+
+  /**
+   * File suffixes excluded from the snapshot: archive names commonly produced
+   * by `npm pack`, and backup names ending in `~`. These suffixes remain
+   * excluded when the files hold deliberately authored plugin data.
+   */
+  export const OMITTED_SOURCE_FILE_SUFFIXES: readonly string[] = [
+    ".tgz",
+    ".tar.gz",
+    "~",
+  ];
+
+  /**
+   * Whether a file name is excluded from the source snapshot
+   * (`OMITTED_SOURCE_FILE_NAMES`, `OMITTED_SOURCE_FILE_SUFFIXES`).
+   *
+   * @evidence contracts/common.md#principled-implementation Exact names and defined suffixes decide snapshot omission consistently for source digests, copies and observers, independently of Go embed directives.
+   * @evidence contracts/common.md#clear-and-simple-design Shared name/suffix lists keep the complete file-exclusion policy visible to external observers and this predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The published name policy applies without inspecting file contents or treating matching embedded data as an exception; it does not claim all excluded files are irrelevant to Go.
+   * @evidence contracts/common.md#meaningful-documentation Native prose points to the documented categories rather than inventing an additional omission policy.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This string predicate does not interpret native path identity or access the filesystem.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms The policy lists have fixed size; suffix comparison costs at most their total fixed suffix lengths, without traversing file contents.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Static policy lookup does not share runtime computation across requests.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only fixed policy constants are referenced.
+   */
+  export function shouldOmitSourceFile(name: string): boolean {
+    return (
+      OMITTED_SOURCE_FILE_NAMES.includes(name) ||
+      OMITTED_SOURCE_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix))
+    );
+  }
+}

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

@@ -0,0 +1,312 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+
+/**
+ * Select the `go` executable spelling a source-plugin build shares across its
+ * phases.
+ *
+ * On Windows, `PATH` and `PATHEXT` lookup and `.cmd`/`.bat` wrappers make a
+ * bare `go` ambiguous: the answer can change between the cache-key probe and
+ * the build if relative lookup is repeated. A successfully selected native path
+ * avoids reinterpreting that name against a later scratch cwd. The path is not
+ * a retained executable handle and cannot prevent replacement; an unresolved
+ * bare name can still be returned for normal spawn failure/search.
+ *
+ * POSIX PATH entries and qualified relative executables are also pinned before
+ * the build moves into its scratch directory.
+ *
+ * @evidence contracts/common.md#principled-implementation Platform-specific candidate lookup supplies a selected spelling when found; POSIX execute access and Windows native-before-wrapper policy determine selection. Unresolved fallback is not a proved target, and returned paths do not pin executable content over time.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns search bases, executable probing and Windows environment spelling so key probes and actual spawns use one policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Candidate selection follows native process rules rather than hardcoding a particular user's Go installation or mutating process.env.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain pinned tool identity, Windows wrapper precedence, search order and environment-case handling.
+ * @evidence contracts/portability.md#os-neutral-implementation Native Node paths separate POSIX permission checks from Windows PATHEXT/cmd wrapper handling; path identity is not inferred from filesystem case assumptions.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups operations; its callable members own search algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This namespace retains no computed resolution; resolveGoToolForBuild defines the build-wide sharing boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no mutable cache or native resource.
+ */
+export namespace GoToolResolution {
+  function isWindowsCommandWrapper(location: string): boolean {
+    return process.platform === "win32" && /\.(?:bat|cmd)$/i.test(location);
+  }
+
+  /**
+   * Pin native PATH and command-wrapper lookup to one build-wide target.
+   *
+   * @evidence contracts/common.md#principled-implementation Native bases resolve against the module directory and POSIX X_OK rejects unusable candidates. A selected spelling avoids later relative cwd reinterpretation; unresolved bare fallback and subsequent replacement remain outside that selection guarantee.
+   * @evidence contracts/common.md#clear-and-simple-design The build-facing resolver delegates Windows wrapper policy and otherwise performs one direct native candidate search.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Pinning corrects repeated relative lookup rather than compensating for a mismatched key after the build.
+   * @evidence contracts/common.md#meaningful-documentation The comment identifies the build-wide pin and the owning namespace explains why cwd changes matter.
+   * @evidence contracts/portability.md#os-neutral-implementation POSIX checks actual execute access while Windows uses its executable/wrapper rules; the returned native path is reused unchanged by build subprocesses.
+   * @evidence contracts/performance.md#efficient-algorithms Base construction processes complete PATH/binary/cwd text; POSIX selection performs native stat/access until a usable candidate. Windows adds fixed native suffixes followed by caller-sized PATHEXT wrapper candidates; extension/name/path bytes, environment lookup and native filesystem work are not bounded by P alone.
+   * @evidence contracts/performance.md#reuse-equivalent-work The resolved target is shared by environment queries and the actual Go build so equivalent phases do not reinterpret relative lookup.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The resolver owns no retained memo or process; the caller keeps the resolved path for its build.
+   */
+  export function resolveGoToolForBuild(
+    binary: string,
+    env: NodeJS.ProcessEnv,
+    cwd: string,
+    witness?: PluginBuildEnvironmentWitness.Record,
+  ): string {
+    if (process.platform !== "win32") {
+      for (const candidate of executableSearchBases(binary, env, cwd)) {
+        if (!isExecutableFile(candidate)) continue;
+        try {
+          fs.accessSync(candidate, fs.constants.X_OK);
+          return candidate;
+        } catch {
+          // A non-executable PATH entry must not shadow a later usable tool.
+        }
+      }
+      return path.isAbsolute(binary) || !hasPathQualifier(binary)
+        ? binary
+        : path.resolve(cwd, binary);
+    }
+    return resolveWindowsGoTool(binary, env, cwd, witness).location ?? binary;
+  }
+
+  interface IWindowsGoToolResolution {
+    location: string | null;
+    wrapper: boolean;
+  }
+
+  /**
+   * Preserve libuv's native target before falling back to cmd/bat wrappers.
+   *
+   * @evidence contracts/common.md#principled-implementation Direct native executable candidates take precedence and cmd/bat fallback uses PATHEXT only after that search; explicit wrapper names retain wrapper identity even when missing.
+   * @evidence contracts/common.md#clear-and-simple-design One result pairs location with wrapper routing so spawn code does not repeat extension policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing wrappers are represented honestly instead of silently selecting another tool to evade spawn failure.
+   * @evidence contracts/common.md#meaningful-documentation The native comment states native-before-wrapper precedence and the result fields name routing facts.
+   * @evidence contracts/portability.md#os-neutral-implementation This isolates Windows native .com/.exe probing from shell-based .cmd/.bat execution and honors configured wrapper extensions.
+   * @evidence contracts/performance.md#efficient-algorithms Candidate construction retains full path strings. Explicit wrappers use one first-match scan; other names scan direct/fixed .com/.exe choices before a caller-sized wrapper-extension pass. Environment/PATHEXT parsing, text comparisons/path construction and native probes contribute costs beyond P times E query count.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The owning build resolver pins this result; this Windows search does not retain completed results itself.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No process or persistent handle is acquired during candidate probing.
+   */
+  export function resolveWindowsGoTool(
+    binary: string,
+    env: NodeJS.ProcessEnv,
+    cwd: string,
+    witness?: PluginBuildEnvironmentWitness.Record,
+  ): IWindowsGoToolResolution {
+    const candidates = executableSearchBases(binary, env, cwd, witness);
+    if (isWindowsCommandWrapper(binary)) {
+      return {
+        location: candidates.find(isExecutableFile) ?? null,
+        wrapper: true,
+      };
+    }
+
+    const hasExtension = windowsFileNameHasExtension(binary);
+    for (const candidate of candidates) {
+      if (hasExtension && isExecutableFile(candidate)) {
+        return { location: candidate, wrapper: false };
+      }
+      for (const extension of [".com", ".exe"]) {
+        const executable = candidate + extension;
+        if (isExecutableFile(executable)) {
+          return { location: executable, wrapper: false };
+        }
+      }
+    }
+
+    const wrapperExtensions = windowsExecutableExtensions(env).filter((ext) =>
+      /\.(?:bat|cmd)$/i.test(ext),
+    );
+    for (const candidate of candidates) {
+      for (const extension of wrapperExtensions) {
+        const executable = candidate + extension;
+        if (isExecutableFile(executable)) {
+          return { location: executable, wrapper: true };
+        }
+      }
+    }
+    return { location: null, wrapper: false };
+  }
+
+  /**
+   * The candidate paths a binary name resolves against, in search order: the
+   * path itself when absolute or qualified, otherwise each `PATH` directory. On
+   * Windows the current directory is searched first, as process creation does,
+   * unless `NoDefaultCurrentDirectoryInExePath` is set.
+   *
+   * @evidence contracts/common.md#principled-implementation Absolute and qualified paths bypass PATH search, while bare names use native ordered bases; Windows quoted entries and the parent-process cwd-search switch preserve libuv lookup distinctions.
+   * @evidence contracts/common.md#clear-and-simple-design Base construction is independent of executable-extension probing, allowing Go and external-command identity readers to share it.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Search fallback uses the native POSIX default or Windows inherited PATH semantics, not a privileged compiler directory.
+   * @evidence contracts/common.md#meaningful-documentation The prose states absolute/qualified handling, current-directory precedence and the disabling switch.
+   * @evidence contracts/portability.md#os-neutral-implementation Node's delimiter and native paths govern POSIX search; Windows semicolon quoting and case-insensitive PATH retrieval are explicit boundaries.
+   * @evidence contracts/performance.md#efficient-algorithms Absolute/qualified inputs take native path checks; bare names split complete PATH text and map directories to full resolved strings. Windows also filters/unquotes entries, can enumerate/casefold environment names and witnesses the ambient cwd-search switch. Path/name/environment bytes and intermediate arrays contribute processing/storage beyond candidate count.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This constructs bases from current arguments and owns no cross-request search cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned candidate array survives; no native resource is retained.
+   */
+  export function executableSearchBases(
+    binary: string,
+    env: NodeJS.ProcessEnv,
+    cwd: string,
+    witness?: PluginBuildEnvironmentWitness.Record,
+  ): string[] {
+    if (path.isAbsolute(binary)) return [binary];
+    if (hasPathQualifier(binary)) return [path.resolve(cwd, binary)];
+
+    const directories =
+      process.platform === "win32"
+        ? splitWindowsSearchPath(readPathEnvironment(env))
+            // libuv skips only genuinely empty slices. A quoted-empty slice
+            // survives that check, unquotes to "", and therefore names cwd.
+            .filter((entry) => entry.length > 0)
+            .map(unquoteWindowsSearchEntry)
+        : readPathEnvironment(env).split(path.delimiter);
+    const noDefaultCurrentDirectory =
+      process.platform === "win32"
+        ? readWindowsEnvironmentValue(
+            process.env,
+            "NoDefaultCurrentDirectoryInExePath",
+          )
+        : undefined;
+    if (process.platform === "win32")
+      PluginBuildEnvironmentWitness.addEnvironment(
+        witness,
+        "NoDefaultCurrentDirectoryInExePath",
+        noDefaultCurrentDirectory,
+      );
+    if (
+      process.platform === "win32" &&
+      noDefaultCurrentDirectory === undefined
+    ) {
+      directories.unshift(cwd);
+    }
+    return directories.map((dir) => path.resolve(cwd, dir, binary));
+  }
+
+  /**
+   * Whether `location` exists and is a regular file, following links.
+   *
+   * This is a file-kind probe; POSIX executable permission is checked by the
+   * build-facing resolver separately.
+   *
+   * @evidence contracts/common.md#principled-implementation stat's regular-file classification rejects directories and missing candidates without claiming execute access from file existence alone.
+   * @evidence contracts/common.md#clear-and-simple-design One kind probe is shared by native and wrapper candidate searches; permission policy stays with the resolver that needs it.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Candidate failures return false rather than introducing a known-tool exception that bypasses the filesystem.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraphs explicitly distinguish file kind from POSIX execute permission.
+   * @evidence contracts/portability.md#os-neutral-implementation Node's native stat follows filesystem aliases; callers separately select OS-specific execution rules rather than guessing them from a filename.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms One native stat query and regular-file predicate avoid directory enumeration/content reads, but path-component/link lookup and native errors still cost work; fixed query count is not a constant-byte filesystem bound.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Fresh file state is probed rather than cached beyond its observation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous stat creates no lasting handle or retained state.
+   */
+  export function isExecutableFile(location: string): boolean {
+    try {
+      return fs.statSync(location).isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  function hasPathQualifier(location: string): boolean {
+    return (
+      location.includes(path.sep) ||
+      (process.platform === "win32" &&
+        (location.includes("/") || /^[a-zA-Z]:/.test(location)))
+    );
+  }
+
+  function windowsFileNameHasExtension(location: string): boolean {
+    const name = path.basename(location);
+    const dot = name.indexOf(".");
+    return dot >= 0 && dot < name.length - 1;
+  }
+
+  function splitWindowsSearchPath(value: string): string[] {
+    const entries: string[] = [];
+    let start = 0;
+    let quote = "";
+    for (let index = 0; index < value.length; index++) {
+      const character = value[index]!;
+      if (quote !== "") {
+        if (character === quote) quote = "";
+      } else if ((character === '"' || character === "'") && index === start) {
+        quote = character;
+      } else if (character === ";") {
+        entries.push(value.slice(start, index));
+        start = index + 1;
+      }
+    }
+    entries.push(value.slice(start));
+    return entries;
+  }
+
+  function unquoteWindowsSearchEntry(location: string): string {
+    const first = location[0];
+    const withoutFirst =
+      first === '"' || first === "'" ? location.slice(1) : location;
+    const last = withoutFirst[withoutFirst.length - 1];
+    return last === '"' || last === "'"
+      ? withoutFirst.slice(0, -1)
+      : withoutFirst;
+  }
+
+  /**
+   * The executable extensions Windows tries, lower-cased and unquoted, from
+   * `PATHEXT` or its documented default.
+   *
+   * @evidence contracts/common.md#principled-implementation Configured or default PATHEXT values are split with Windows quoting rules, normalized and stripped of empty entries before wrapper lookup.
+   * @evidence contracts/common.md#clear-and-simple-design One extension reader shares the same Windows environment and search-entry helpers as PATH lookup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The default extension list is Windows invocation vocabulary, not a test-specific compiler suffix list.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states lowercase/unquoted output and configured-versus-default precedence.
+   * @evidence contracts/portability.md#os-neutral-implementation PATHEXT handling is isolated to the Windows lookup boundary rather than applied to POSIX filenames.
+   * @evidence contracts/performance.md#efficient-algorithms Configured extension text is split/unquoted/lowercased/filtered in linear text passes after environment lookup, which can enumerate/casefold/sort name matches. Intermediate and returned extension arrays scale with full text and caller-supplied population; no independent extension-count bound is enforced.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This reads current environment arguments; the owning resolver keeps any chosen executable.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned extension list has no external lifetime or handle ownership.
+   */
+  export function windowsExecutableExtensions(
+    env: NodeJS.ProcessEnv = process.env,
+  ): readonly string[] {
+    const pathext = readWindowsEnvironmentValue(env, "PATHEXT");
+    const raw = pathext && pathext.length > 0 ? pathext : ".COM;.EXE;.BAT;.CMD";
+    return splitWindowsSearchPath(raw)
+      .map(unquoteWindowsSearchEntry)
+      .map((ext) => ext.toLowerCase())
+      .filter((ext) => ext.length > 0);
+  }
+
+  function readPathEnvironment(env: NodeJS.ProcessEnv = process.env): string {
+    return process.platform === "win32"
+      ? (readWindowsEnvironmentValue(env, "PATH") ??
+          readWindowsEnvironmentValue(process.env, "PATH") ??
+          "")
+      : (env.PATH ?? "/usr/bin:/bin");
+  }
+
+  /**
+   * Read an environment variable with lowercase-name matching. An exact-case
+   * key wins; otherwise the first matching key in sorted order, so the answer
+   * is deterministic when a caller supplied several spellings.
+   *
+   * @evidence contracts/common.md#principled-implementation Exact spelling is preferred; otherwise matching keys are sorted before selecting one, making case-insensitive aliases deterministic for injected environments.
+   * @evidence contracts/common.md#clear-and-simple-design One helper centralizes the Windows variable-spelling policy used by PATH, PATHEXT and shell selection.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The helper reads the supplied environment and does not patch process.env or rename keys to accommodate a consumer.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph records exact-key precedence and sorted fallback when several aliases exist.
+   * @evidence contracts/portability.md#os-neutral-implementation Case-insensitive environment names are a Windows process convention, distinct from filesystem path case policy.
+   * @evidence contracts/performance.md#efficient-algorithms Exact property lookup processes the supplied key without enumeration. Fallback allocates all N key names, lowercases/compares their bytes and sorts K matching strings with text-sensitive comparisons; it avoids sorting unrelated keys but counts alone do not capture name bytes or array storage.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The lookup uses the supplied current environment and retains no normalized map across calls.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No retained state or native handle is owned.
+   */
+  export function readWindowsEnvironmentValue(
+    env: NodeJS.ProcessEnv,
+    name: string,
+  ): string | undefined {
+    const exact = env[name];
+    if (exact !== undefined) return exact;
+    const normalized = name.toLowerCase();
+    const key = Object.keys(env)
+      .filter((candidate) => candidate.toLowerCase() === normalized)
+      .sort()[0];
+    return key === undefined ? undefined : env[key];
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Internal controls for Go object-cache maintenance.
+ *
+ * Sizes are bytes and ages are milliseconds. Omitted controls use the owned
+ * Go-cache retention policy; the clock can be supplied by the invoking owner.
+ * Recent age selects a target-sized cohort with the collector's mtime
+ * allowance, rather than protecting every recent file. This type imposes no
+ * finite-number, range or ordering validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Trigger and target sizes are separate from recent-file protection and the current clock, preserving the collector's independent decisions.
+ * @evidence contracts/common.md#clear-and-simple-design One option record supplies overrides to the existing selected-root collector; omitted fields retain its defaults rather than selecting a different maintenance implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied limits and time are ordinary inputs; production does not detect tests or fabricate object sizes to meet an expected result.
+ * @evidence contracts/common.md#meaningful-documentation Owning prose states byte/millisecond units, defaults, cohort scope and numeric-validation limits; members distinguish interval bypass from build-lease safety and recent-age eligibility from a retention guarantee.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface IGoBuildCachePruneOptions {
+  /** Ignore the interval marker; build-lease exclusion still applies. */
+  force?: boolean;
+
+  /** Size that triggers LRU pruning. */
+  maxBytes?: number;
+
+  /** Size to prune toward once the ceiling is crossed. */
+  targetBytes?: number;
+
+  /** Current wall-clock time in milliseconds since the Unix epoch. */
+  now?: number;
+
+  /** Recent-age threshold for cohort selection, with the mtime allowance added. */
+  protectedAgeMs?: number;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Internal controls for plugin-binary cache maintenance; the single-file
+ * collector uses the same numeric controls without `protectedEntries`.
+ *
+ * Sizes are bytes and ages are milliseconds. Omitted controls use the shared
+ * retention policy. Explicit protected entries are caller-selected cache
+ * directories; the cold-build caller supplies its just-returned entry, but the
+ * collector validates location rather than proving how an entry was produced.
+ * This type imposes no finite-number, range or ordering validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Independent trigger, target, clock and protection fields represent the eviction decisions without confusing byte limits with millisecond age thresholds.
+ * @evidence contracts/common.md#clear-and-simple-design One internal option object configures the existing collector instead of a separate deterministic maintenance implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Overrides are explicit maintenance inputs shared with production; no branch changes behavior by recognizing a test or expected eviction result.
+ * @evidence contracts/common.md#meaningful-documentation Owning prose supplies units, omission behavior and numeric-validation limits; members distinguish forced passes, recent-cohort selection and caller-selected protected entries.
+ * @evidence contracts/portability.md#os-neutral-implementation Protected entries are native cache directories validated against the canonical root; numeric byte and millisecond controls do not encode an OS's case or path rules.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface IPluginCachePruneOptions {
+  /** Ignore the once-daily marker. */
+  force?: boolean;
+
+  /** Size that triggers LRU pruning. */
+  maxBytes?: number;
+
+  /** Current wall-clock time in milliseconds since the Unix epoch. */
+  now?: number;
+
+  /** Recent-use age for the binary cohort or single-file size protection. */
+  protectedAgeMs?: number;
+
+  /** Cache directories explicitly protected by this invocation's caller. */
+  protectedEntries?: readonly string[];
+
+  /** Size to prune toward once the ceiling is crossed. */
+  targetBytes?: number;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * One `replace` directive of a plugin module's `go.mod` whose target is a local
+ * directory outside the module (`pluginModuleReplaceDirectories`).
+ *
+ * `go build` in the original module compiles that directory in place, so ttsc
+ * keys and snapshots it, reports its state, and resolves a relative spelling
+ * from the module's own directory.
+ *
+ * @evidence contracts/common.md#principled-implementation Logical module/version identity, original spelling and resolved directory preserve the distinction needed to hash sources and rewrite the correct Go replacement directive.
+ * @evidence contracts/common.md#clear-and-simple-design One replacement record travels from Go's directive reader to keying and scratch anchoring without reparsing its text.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Module replacements are actual go.mod directives read by Go's editor, not guessed dependencies or consumer-specific overrides.
+ * @evidence contracts/common.md#meaningful-documentation Members distinguish resolved target, original spelling, left-side module identity and optional version, with separated comments.
+ * @evidence contracts/portability.md#os-neutral-implementation Directory carries an absolute native target with best-effort physical spelling, which can retain unresolved suffixes/fallback; spelled preserves modfile syntax and modulePath is a Go identifier, not a path. The record does not pin future native identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface IPluginModuleReplaceDirectory {
+  /** The target's absolute native path with best-effort physical spelling. */
+  directory: string;
+
+  /** The replaced module path, the directive's left side. */
+  modulePath: string;
+
+  /** The target as `go.mod` spells it. */
+  spelled: string;
+
+  /** The replaced version, when the directive names one. */
+  version?: string;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * One contributor's resolved Go source plus its target sub-package name.
+ *
+ * @evidence contracts/common.md#principled-implementation The name fixes the contributor's import suffix and the absolute source identifies the directory hashed and copied into the host module.
+ * @evidence contracts/common.md#clear-and-simple-design Two fields carry the already-resolved contribution, leaving descriptor validation and scratch materialization to their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The name is caller-declared contribution identity, not a fixture-specific package insertion.
+ * @evidence contracts/common.md#meaningful-documentation Members state the contrib target layout and absolute source-path requirement with separate native comments.
+ * @evidence contracts/portability.md#os-neutral-implementation Source carries the caller's resolved absolute native directory. Name is used both as a native contrib-directory component and a Go import suffix; this type does not validate materialization eligibility or pin physical identity, which remain with admission/copy owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface ITtscBuildContributor {
+  /** Sub-package suffix: scratch lands at `<host>/contrib/<name>/`. */
+  name: string;
+
+  /** Absolute path to the contributor's source directory. */
+  source: string;
+}