ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { prunesPluginSourceDirectory } from "./prunesPluginSourceDirectory";
+
+/**
+ * The directories of one plugin source directory that an observer of the source
+ * watches: the directory itself and every directory below it outside those the
+ * build passes over (`prunesPluginSourceDirectory`: a nested `node_modules`, a
+ * repository's `.git`, ttsc's own `.ttsc`).
+ *
+ * These are candidate directories for nonrecursive observation. Native watcher
+ * acquisition, event delivery and later topology changes belong to consumers;
+ * this sequential listing does not prove every edit was observed. Names pruned
+ * by policy are omitted regardless of who writes them. `ttsc --watch` and the
+ * `ttscserver` selection-input capture share this enumeration rule. The root
+ * uses stat (and may be an alias); listed child links are not descended into. A
+ * non-directory root has no results, but a queued directory can disappear after
+ * being appended to the returned list.
+ *
+ * @param root The plugin source directory.
+ * @returns Absolute directories, `root` first.
+ * @throws When a directory cannot be read for a reason other than having
+ *   vanished while it was listed.
+ * @evidence contracts/common.md#principled-implementation The explicit stack visits ordinary unpruned directories, including the root, giving nonrecursive watchers the directory population needed to observe source additions and edits.
+ * @evidence contracts/common.md#clear-and-simple-design Iterative traversal and one vanished-entry classifier keep enumeration separate from watcher acquisition and callback ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Directory pruning delegates the actual source contract instead of hiding expensive or failing consumer directories behind local exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states root-first candidates, root-alias/vanishing-entry behavior and the separate consumer ownership of watcher acquisition, topology updates and event delivery.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's stat/Dirent/path APIs establish native directory kinds; only ENOENT/ENOTDIR mean a vanished entry, without OS-specific case assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms One traversal visits E listed entries without recursive JavaScript call depth. Processing includes root resolution/stat, native listings and name/path construction; returned/queued D paths retain their text, and one directory's Dirent array adds peak-listing space. This accounts for entry/path bytes as well as counts, without allocating watchers.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This lists current directories; the consumer owns sharing and replacing watcher populations.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The listing opens no lasting watcher or handle; its caller owns resources created from the returned paths.
+ */
+export function collectPluginSourceDirectories(root: string): string[] {
+  const directory = path.resolve(root);
+  try {
+    if (!fs.statSync(directory).isDirectory()) return [];
+  } catch (error) {
+    if (isVanishedFilesystemEntry(error)) return [];
+    throw error;
+  }
+  const directories: string[] = [];
+  const stack = [directory];
+  while (stack.length !== 0) {
+    const current = stack.pop()!;
+    directories.push(current);
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (error) {
+      if (isVanishedFilesystemEntry(error)) continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !prunesPluginSourceDirectory(entry.name)) {
+        stack.push(path.join(current, entry.name));
+      }
+    }
+  }
+  return directories;
+}
+
+function isVanishedFilesystemEntry(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}

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

@@ -0,0 +1,90 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { GoSourceInputs } from "./GoSourceInputs";
+
+/**
+ * The files of one plugin source directory that a plugin build keys its binary
+ * on, as absolute paths in sorted order.
+ *
+ * Every regular file below the directory counts, except those in a directory
+ * excluded by the snapshot policy (`node_modules`, `.git`, `.ttsc`), files with
+ * excluded workspace, archive or sidecar names, and editor backups ending in
+ * `~`. The one reading of that rule: the cache key hashes these files
+ * (`computeCacheKey`), and the transform envelope reports their digest
+ * (`pluginSourceDigest`) within each directory's state (`pluginSourceState`),
+ * so the two cannot disagree about what a plugin's source is. A consumer that
+ * keeps a digest while the metadata of these files holds still, rather than
+ * reading their bytes on every proof, stats exactly this list, through the
+ * `ttsc/plugin-source` entry.
+ *
+ * Selection follows ttsc's declared naming policy, not Go's EmbedFiles. Data
+ * under excluded names or directories is omitted even when a raw Go package can
+ * embed it. The returned population describes the materialized source snapshot,
+ * not every input the original package could use.
+ *
+ * A link (a symbolic link or a Windows junction) outside those directories is
+ * refused rather than skipped. The build would compile what it names, which
+ * neither this list nor anything keyed on it covers; a Go module zip excludes
+ * links from a module's content for the same reason.
+ *
+ * @param root The source directory: a plugin's Go module root, an overlay
+ *   module, a contributor's source, or a `replace` target outside the module.
+ * @throws When the directory holds a link the build would read.
+ * @throws When enumeration fails for a reason other than a vanished entry.
+ * @evidence contracts/common.md#principled-implementation The recursive Dirent walk selects reported regular files under the shared prune/omit policy and refuses contributing links observed during enumeration. The returned path list is not an atomic snapshot or a retained handle pinning each entry against later replacement; copying/content readers own their subsequent observations.
+ * @evidence contracts/common.md#clear-and-simple-design One private traversal owns enumeration and one final sort establishes deterministic file order for every downstream digest.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared source rules apply the declared kind/name exclusions instead of adapting the key to observed fixtures or inferring Go dependency membership from names.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs identify counted files, explicit exclusions, the Go embed limitation, link rejection and the common reader used by keys and proofs.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joining and Dirent kinds distinguish ordinary files, directories and links, including junctions; neither case folding nor slash-only identity is assumed.
+ * @evidence contracts/performance.md#efficient-algorithms Enumeration visits unpruned entries and sorts F selected native path strings with O(F log F) comparisons whose text length matters. Native readdir/Dirent/name/path construction and recursion also cost work; it retains complete selected path bytes and ancestor listing arrays, not file contents.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This supplies a fresh source population to its callers; cached digests and validation reuse are owned by those callers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous walk retains only the returned path list and transient recursion state, with no persistent handle or task.
+ */
+export function collectPluginSourceFiles(root: string): string[] {
+  const out: string[] = [];
+  const directory = path.resolve(root);
+  walk(directory, directory, out);
+  out.sort();
+  return out;
+}
+
+function walk(root: string, dir: string, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      // A link where the build passes over anyway stays irrelevant. Any other
+      // is refused: the build would compile what it names, which neither this
+      // list, the key, nor a watch covers, and a copy of the module cannot
+      // recreate a link without the symlink privilege on Windows.
+      if (
+        GoSourceInputs.shouldPruneDirectory(entry.name) ||
+        GoSourceInputs.shouldOmitSourceFile(entry.name)
+      )
+        continue;
+      throw new Error(
+        `ttsc: plugin source ${root} contains a link at ${full}. A plugin's Go ` +
+          `sources are its own files, as a Go module zip holds them: replace the ` +
+          `link with the files it names, or give the linked directory a go.mod of ` +
+          `its own and name it through a replace directive in the plugin's go.mod.`,
+      );
+    }
+    if (entry.isDirectory()) {
+      if (GoSourceInputs.shouldPruneDirectory(entry.name)) continue;
+      walk(root, full, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (GoSourceInputs.shouldOmitSourceFile(entry.name)) continue;
+    out.push(full);
+  }
+}

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

@@ -0,0 +1,208 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { GoToolResolution } from "./GoToolResolution";
+import type { ITtscBuildContributor } from "./ITtscBuildContributor";
+import type { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import type { SourceBuildFilesystemOperations } from "./SourceBuildFilesystemOperations";
+import type { SourcePluginWorkspace } from "./SourcePluginWorkspace";
+import { hashPluginBuildEnvironment } from "./hashPluginBuildEnvironment";
+import { pluginModuleReplaceDirectories } from "./pluginModuleReplaceDirectories";
+import { pluginSourceDigest } from "./pluginSourceDigest";
+
+/**
+ * Compute a 32-character lowercase key from a plugin build's SHA-256 digest.
+ *
+ * The key covers ttsc/tsgo versions, platform, entry package, Go compiler
+ * identity, Go build environment variables, overlay module sources, plugin
+ * source files, the local directories outside the module that its `go.mod`
+ * replaces modules with (`pluginModuleReplaceDirectories`), and contributor
+ * source files. An optional required package-ownership population also frames
+ * the key, separating binaries admitted by the matching cold producer from
+ * legacy artifacts; requests without that authority retain their existing key.
+ * Contributors are sorted by name; unique names remove input order dependence,
+ * while equal-name rows retain the sort's input order.
+ *
+ * Each source directory enters the key as its digest (`pluginSourceDigest`),
+ * which the transform envelope reports, with the environment below, as the
+ * state of directories selected by the loader's report policy. Supplied memo
+ * values are trusted producer readings, not revalidated content observations.
+ * `sourceDigests` carries the digests one load already took: every build of the
+ * load keys on one reading of each directory, and the load reports those
+ * readings. The environment enters through `hashPluginBuildEnvironment`, the
+ * rule that reported state takes it from too, and `environmentDigests` carries
+ * the digest of each build directory's, so the load reports it without a second
+ * `go env` run.
+ *
+ * The `ttsc cache` CLI and plugin build pipeline share this key computation.
+ *
+ * @evidence contracts/common.md#principled-implementation The key frames versions, platform, entry, environment and labeled source digests; sorted overlays/contributors and required package ownership remove irrelevant order while local replacements remain actual compiler inputs.
+ * @evidence contracts/common.md#clear-and-simple-design Source identity and toolchain serialization are delegated to their shared owners; optional maps carry one load's readings instead of adding an independent cache policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts All contributors and local module replacements participate; filesystem injection is an explicit byte-reading boundary rather than foreign monkey patching.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain input coverage and the provenance of reported digests; documented optional output maps have blank separation between members.
+ * @evidence contracts/portability.md#os-neutral-implementation Native roots are resolved with Node path APIs and executable resolution; platform/architecture intentionally distinguish incompatible binary artifacts.
+ * @evidence contracts/performance.md#efficient-algorithms Source digest misses enumerate/sort paths and read individual files in full, not bounded streaming chunks. Overlay/contributor ordering compares path/name text; replacement discovery can read a manifest/run Go and native containment queries. Toolchain/env hashing delegates native metadata/probes/full bytes and memo checks without an unmeasured dominant-cost ranking; JSON framing processes all version/entry/label/digest text.
+ * @evidence contracts/performance.md#reuse-equivalent-work Caller-owned sourceDigests share supplied absolute-directory readings across roles without independently verifying their provenance/currentness. EnvironmentDigests receives this call's selected environment identity so reporting can avoid another probe; it does not skip environment hashing. Reuse inherits the selected population and metadata/producer premises.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Output maps belong to the enclosing load; this operation retains no handles or process-wide records itself.
+ */
+export function computeCacheKey(inputs: {
+  contributors?: readonly ITtscBuildContributor[];
+  dir: string;
+  entry: string;
+  env?: NodeJS.ProcessEnv;
+
+  /** Required package ownership, admitted by the matching cold producer. */
+  packageOwnership?: readonly {
+    entry: string;
+    kind: "executable" | "linked";
+  }[];
+
+  /**
+   * Digests of the environment each build directory is keyed on
+   * (`pluginBuildEnvironment`), filled with this build's, so the load reports
+   * its plugin sources' states without reading the environment again.
+   */
+  environmentDigests?: Map<string, string>;
+
+  /**
+   * Receives selected native toolchain dependencies from the environment reader
+   * for later comparison under its metadata-distinguishability premise; it is
+   * not detection of arbitrary unreported tool/launcher reads.
+   */
+  environmentWitness?: PluginBuildEnvironmentWitness.Record;
+
+  /** Byte adapter for delegated SDK identity; plugin source digests use fs. */
+  filesystem?: Partial<SourceBuildFilesystemOperations>;
+  goBinary?: string;
+  goModReader?: SourcePluginWorkspace.GoModReader;
+  overlayDirs?: readonly string[];
+
+  /**
+   * Digests of the source directories this load already read, by absolute path.
+   * Read through, and filled with every directory this key covers.
+   */
+  sourceDigests?: Map<string, string>;
+
+  ttscVersion: string;
+  tsgoVersion: string;
+}): string {
+  const env = inputs.env ?? process.env;
+  const filesystem: SourceBuildFilesystemOperations = {
+    readFile:
+      inputs.filesystem?.readFile ?? DEFAULT_SOURCE_BUILD_FILESYSTEM.readFile,
+  };
+  const goBinary =
+    inputs.goBinary === undefined
+      ? undefined
+      : GoToolResolution.resolveGoToolForBuild(
+          inputs.goBinary,
+          env,
+          inputs.dir,
+        );
+  const hash = crypto.createHash("sha256");
+  hash.update(JSON.stringify(["ttsc", inputs.ttscVersion]));
+  hash.update(JSON.stringify(["tsgo", inputs.tsgoVersion]));
+  hash.update(JSON.stringify(["platform", process.platform, process.arch]));
+  hash.update(JSON.stringify(["entry", inputs.entry]));
+  if (inputs.packageOwnership !== undefined)
+    hash.update(
+      JSON.stringify([
+        "package-ownership",
+        1,
+        [...inputs.packageOwnership].sort((left, right) =>
+          left.entry < right.entry
+            ? -1
+            : left.entry > right.entry
+              ? 1
+              : left.kind < right.kind
+                ? -1
+                : left.kind > right.kind
+                  ? 1
+                  : 0,
+        ),
+      ]),
+    );
+  // Private materialization changes native package working directories. Keep
+  // binaries produced by the former absolute-ancestry layout out of this
+  // layout's cache admissions, including callers with no SDK overlays.
+  hash.update(JSON.stringify(["external-source-layout", 1]));
+  // The same framed values enter the key and the environment-only digest,
+  // which pluginBuildEnvironment reads for this directory.
+  const environment = crypto.createHash("sha256");
+  hashPluginBuildEnvironment(
+    {
+      update: (data: string) => {
+        hash.update(data);
+        environment.update(data);
+      },
+    },
+    goBinary,
+    inputs.dir,
+    env,
+    filesystem,
+    inputs.environmentWitness,
+  );
+  inputs.environmentDigests?.set(
+    path.resolve(inputs.dir),
+    environment.digest("hex"),
+  );
+  hashSourceDirectory(hash, "plugin", inputs.dir, inputs.sourceDigests);
+  // Local replacement targets outside the module supply separately keyed
+  // sources. buildSourcePlugin snapshots and proves their copies before
+  // redirecting the Go replacement directives to the scratch tree.
+  for (const replacement of pluginModuleReplaceDirectories(
+    inputs.dir,
+    env,
+    goBinary,
+    inputs.goModReader,
+  )) {
+    hashSourceDirectory(
+      hash,
+      `replace:${replacement.modulePath}${
+        replacement.version === undefined ? "" : `@${replacement.version}`
+      }`,
+      replacement.directory,
+      inputs.sourceDigests,
+    );
+  }
+  for (const [index, dir] of [...(inputs.overlayDirs ?? [])].sort().entries()) {
+    hashSourceDirectory(hash, `overlay:${index}`, dir, inputs.sourceDigests);
+  }
+  // Hash contributors in sorted-by-name order so two consumers with the
+  // same logical set produce the same key regardless of declaration order
+  // in the host's plugin descriptor.
+  const sortedContributors = [...(inputs.contributors ?? [])].sort((a, b) =>
+    a.name === b.name ? 0 : a.name < b.name ? -1 : 1,
+  );
+  for (const contributor of sortedContributors) {
+    hashSourceDirectory(
+      hash,
+      `contributor:${contributor.name}`,
+      contributor.source,
+      inputs.sourceDigests,
+    );
+  }
+  return hash.digest("hex").slice(0, 32);
+}
+
+const DEFAULT_SOURCE_BUILD_FILESYSTEM: SourceBuildFilesystemOperations =
+  Object.freeze({
+    readFile: (location: string) => fs.readFileSync(location),
+  });
+
+function hashSourceDirectory(
+  hash: crypto.Hash,
+  label: string,
+  root: string,
+  digests: Map<string, string> | undefined,
+): void {
+  const directory = path.resolve(root);
+  let digest = digests?.get(directory);
+  if (digest === undefined) {
+    digest = pluginSourceDigest(directory);
+    digests?.set(directory, digest);
+  }
+  hash.update(JSON.stringify(["dir", label, digest]));
+}

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

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { GoSourceInputs } from "./GoSourceInputs";
+
+/**
+ * Whether a build's copy of a plugin source directory takes the entry at
+ * `location`, by the rule its binary is keyed on (`collectPluginSourceFiles`):
+ * a directory unless the naming policy excludes it, a regular file unless its
+ * name is excluded, and never a link or any other entry.
+ *
+ * The filter does not inspect Go embed directives. An excluded name remains
+ * absent from the copy even when its original bytes are valid Go package data.
+ *
+ * The build verifies its copy against the key's digest of the source
+ * (`pluginSourceDigest`), so the two have to read the same files. A copy that
+ * judged every entry by its name alone would leave out a file the key reads,
+ * such as the `.git` file at the root of a Git worktree or submodule, and read
+ * a directory the key's walk enters, such as one named like an editor backup;
+ * every build of such a source would then fail as edited while it was built.
+ *
+ * A non-root entry observed as a link is refused. The root spelling is admitted
+ * before lstat and relies on the materialization owner's source selection.
+ * Neither this predicate nor the digest walk pins paths against later changes.
+ *
+ * @param root The plugin source directory being copied, which is always taken.
+ * @param location An entry at or below `root`.
+ * @evidence contracts/common.md#principled-implementation Equal resolved root spelling is admitted without kind validation. Other entries use lstat and the digest walk's kind-specific prune/omit policy, refusing observed links; the copy owner owns root validation and post-copy digest comparisons, with sequential pathname observations rather than an atomic snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design One copy filter delegates shared name policy and leaves recursive materialization to fs.cpSync.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Kind-aware matching corrects the false assumption that every entry with a directory-like name is a directory, rather than adding filename exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Owning prose explains key/copy policy agreement, explicit exclusions, worktree .git files, root admission and non-root link/refusal observation limits.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and lstat preserve filesystem entry kinds without following symbolic links or Windows junctions.
+ * @evidence contracts/performance.md#efficient-algorithms Two native path resolutions/comparison precede root admission; other entries add lstat, basename extraction and fixed-policy Set/string queries with path/name costs. The filter allocates no subtree listing; recursive copying and subsequent byte comparisons belong to the materialization owner.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The copy owner shares the resulting snapshot; this per-entry policy predicate stores no computed result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires no lasting handle and retains no state after returning.
+ */
+export function copiesPluginSourceEntry(
+  root: string,
+  location: string,
+): boolean {
+  if (path.resolve(location) === path.resolve(root)) return true;
+  let info: fs.Stats;
+  try {
+    info = fs.lstatSync(location);
+  } catch {
+    return false;
+  }
+  const name = path.basename(location);
+  if (info.isDirectory()) return !GoSourceInputs.shouldPruneDirectory(name);
+  return info.isFile() && !GoSourceInputs.shouldOmitSourceFile(name);
+}

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

@@ -0,0 +1,66 @@
+import path from "node:path";
+
+/**
+ * Plan private copies as translations of each volume's smallest source tree.
+ * Removing ancestors shared by every selected root preserves relative paths
+ * between external sources without carrying their unrelated absolute ancestry
+ * into native compiler working directories. Main-module placement is separate.
+ *
+ * All roots must be supplied together: adding another root can change the
+ * common ancestor. Compact volume ordinals distinguish drives and UNC shares
+ * only inside this private attempt; original paths remain source/key identity.
+ * Descendant depth and the private base can still exceed a native cwd limit.
+ *
+ * @evidence contracts/common.md#principled-implementation Each volume's longest common component prefix is removed uniformly, preserving relative component distances and overlapping roots; distinct volume authorities receive disjoint private namespaces.
+ * @evidence contracts/common.md#clear-and-simple-design One complete-population planning operation returns the original-to-private mapping before copying starts; it neither acquires a lease nor rewrites source inputs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Component translation applies to every supplied root without consumer or length exceptions; it does not flatten modules, rewrite compiler arguments or read live original bytes in place of a snapshot.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains preserved geometry, complete-population ownership, volume ordinals and the remaining native cwd bound.
+ * @evidence contracts/portability.md#os-neutral-implementation The selected native path grammar supplies root parsing and separators; exact component comparison conservatively preserves spelling, including Windows case-sensitive directories and UNC authorities, without realpath or junction substitution.
+ * @evidence contracts/performance.md#efficient-algorithms Each source path is resolved and split once; common-prefix comparisons follow its component population, and volume authority names are sorted once to assign deterministic private ordinals. Returned path text contributes output work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A plan belongs to one complete supplied source population; it caches no filesystem or compiler observation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Maps and component arrays are call-local; only the path mapping transfers to the scratch owner, with no acquired handles or independent resource lifetime.
+ */
+export function createExternalSourceSnapshotLayout(
+  privateRoot: string,
+  directories: readonly string[],
+  paths: typeof path = path,
+): Map<string, string> {
+  const volumes = new Map<
+    string,
+    { common: string[]; sources: Map<string, string[]> }
+  >();
+  for (const directory of directories) {
+    const absolute = paths.resolve(directory);
+    const root = paths.parse(absolute).root;
+    const parts = absolute.slice(root.length).split(paths.sep).filter(Boolean);
+    const volume = volumes.get(root);
+    if (volume === undefined) {
+      volumes.set(root, {
+        common: [...parts],
+        sources: new Map([[absolute, parts]]),
+      });
+      continue;
+    }
+    volume.sources.set(absolute, parts);
+    let commonLength = 0;
+    while (
+      commonLength < volume.common.length &&
+      commonLength < parts.length &&
+      volume.common[commonLength] === parts[commonLength]
+    )
+      ++commonLength;
+    volume.common.length = commonLength;
+  }
+  const copies = new Map<string, string>();
+  const authorities = [...volumes.keys()].sort();
+  for (let ordinal = 0; ordinal < authorities.length; ++ordinal) {
+    const volume = volumes.get(authorities[ordinal]!)!;
+    const destination = paths.join(privateRoot, ordinal.toString(36));
+    for (const [source, parts] of volume.sources)
+      copies.set(
+        source,
+        paths.join(destination, ...parts.slice(volume.common.length)),
+      );
+  }
+  return copies;
+}

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

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { GoSourceInputs } from "./GoSourceInputs";
+
+/**
+ * Attempt POSIX Go toolchain permission repair before metadata reads.
+ *
+ * Package managers can drop the execute bit of the bundled Go SDK. For the
+ * bundled toolchain (`normalizeBundledPermissions`) the `go` and `gofmt`
+ * regular binaries and observed regular files under ordinary `pkg/tool`
+ * directories are normalized to `0755`; for a toolchain the user selected, the
+ * owner-execute bit is added only when no execute bit is present, preserving
+ * other permission bits. Windows requires no POSIX permission repair. A
+ * nonregular main candidate stops repair, and nonregular secondary entries are
+ * skipped. Traversal/repair failures are tolerated; a later Go invocation may
+ * report a relevant native error but is not guaranteed to expose every skipped
+ * repair failure.
+ *
+ * @evidence contracts/common.md#principled-implementation Regular-file admission precedes chmod and a nonregular main candidate stops SDK repair. The caller's bundled-layout flag selects full normalization; selected files otherwise gain owner execution only when no execute bit exists. This is a path-based attempt, not an immutable ownership or race-free handle certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Platform exit, SDK recognition and recursive tool discovery remain explicit; one private file operation owns the permission policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission repair serves packaged SDK installation behavior rather than an injected fixture bypass; native errors are tolerated and ordinary Go execution retains its own failure outcome instead of this helper fabricating success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish owned and selected toolchains and explain the failure boundary rather than promising successful chmod.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows bypasses POSIX permission bits; POSIX uses native stat/chmod and Node path APIs with explicit ownership-dependent modes.
+ * @evidence contracts/performance.md#efficient-algorithms Native path/existence/stat checks precede ordinary-directory enumeration. Selected entries are stat-kind checked and unchanged modes avoid chmod; recursive helper arrays append descendant references through ancestors, so enumeration count alone does not bound path/array work. Native lookup/text/listing buffers contribute cost without reading compiler content.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Permission state must be read on the current installation; no cross-call validity cache is owned here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal holds only its temporary file list and synchronous filesystem operations acquire no retained handle.
+ */
+export function ensureExecutableGoToolchain(
+  goBinary: string,
+  normalizeBundledPermissions: boolean,
+): void {
+  if (process.platform === "win32") return;
+  if (!path.isAbsolute(goBinary) || !fs.existsSync(goBinary)) return;
+  try {
+    if (!ensureExecutableFile(goBinary, normalizeBundledPermissions)) return;
+    const goRoot = GoSourceInputs.inferGoRoot(goBinary);
+    if (!goRoot) return;
+    const gofmt = path.join(path.dirname(goBinary), "gofmt");
+    if (fs.existsSync(gofmt)) {
+      ensureExecutableFile(gofmt, normalizeBundledPermissions);
+    }
+    const toolDir = path.join(goRoot, "pkg", "tool");
+    if (!fs.existsSync(toolDir)) return;
+    for (const file of walkToolFiles(toolDir)) {
+      ensureExecutableFile(file, normalizeBundledPermissions);
+    }
+  } catch {
+    // Let the subsequent go build spawn fail with the real OS error.
+  }
+}
+
+/** Normalize owned files or add only owner execution to a nonexecutable file. */
+function ensureExecutableFile(
+  file: string,
+  normalizeBundledPermissions: boolean,
+): boolean {
+  const stats = fs.statSync(file);
+  if (!stats.isFile()) return false;
+  const mode = stats.mode & 0o7777;
+  if (normalizeBundledPermissions) {
+    if (mode !== 0o755) fs.chmodSync(file, 0o755);
+  } else if ((mode & 0o111) === 0) {
+    fs.chmodSync(file, mode | 0o100);
+  }
+  return true;
+}
+
+function walkToolFiles(dir: string): string[] {
+  const out: string[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      for (const entryToAppend of walkToolFiles(file)) out.push(entryToAppend);
+    } else if (entry.isFile()) {
+      out.push(file);
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Render a millisecond duration for lock diagnostics (`137ms`, `42s`, `9m 3s`).
+ *
+ * Total over every number: the lock state machine reports "released" instead of
+ * an Infinity age, and as defense in depth a non-finite input renders as `an
+ * unknown time` so no public diagnostic prints `Infinitym NaNs`.
+ *
+ * @evidence contracts/common.md#principled-implementation Finite durations are decomposed into milliseconds or whole seconds/minutes; negative short values clamp to zero and nonfinite values use an explicit unknown-duration message.
+ * @evidence contracts/common.md#clear-and-simple-design One numeric formatter owns all diagnostic duration spellings without a second lock-state representation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The nonfinite branch addresses an unsupported numeric duration directly rather than preserving an infinite-age encoding beneath another lock wrapper.
+ * @evidence contracts/common.md#meaningful-documentation Native prose gives millisecond/second/minute examples and explains the unknown-time result.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This performs a fixed number of scalar arithmetic and formatting operations, with no workload-dependent algorithm choice.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The function formats one diagnostic value and stores no shared computation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned string survives the call; no retained resource is acquired.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation formatDuration computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms)) {
+    return "an unknown time";
+  }
+  if (ms < 1_000) {
+    return `${Math.max(0, Math.round(ms))}ms`;
+  }
+  const seconds = Math.floor(ms / 1_000);
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  if (minutes === 0) {
+    return `${seconds}s`;
+  }
+  return `${minutes}m ${remainder}s`;
+}

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

@@ -0,0 +1,42 @@
+import { autoQuoteGoModToken } from "./autoQuoteGoModToken";
+
+/**
+ * Format an absolute filesystem path as a single `go.work`/`go.mod` token.
+ *
+ * The modfile grammar shared by `go.mod` and `go.work` (parsed by
+ * `golang.org/x/mod/modfile`) is whitespace-tokenized, so a `use`/`replace`
+ * path that contains a space — a home or project directory such as `/Users/John
+ * Smith/...` or `C:\Users\John Smith\...` — must be emitted as a quoted string
+ * or `go` cannot parse the generated `go.work`. Normalize Windows separators to
+ * `/` (the workspace convention) and then delegate to
+ * {@link autoQuoteGoModToken}, with its runtime Unicode-table and valid-scalar
+ * decoding limits. This does not validate a physical path or malformed UTF-16.
+ *
+ * Separator normalization is itself a quoting trigger. A Windows UNC
+ * (`\\server\share\...`) or extended-length (`\\?\C:\...`) path normalizes into
+ * a token that starts with `//`, and the modfile lexer reads `//` as a line
+ * comment wherever it appears. Emitted bare, such a token turns its whole
+ * `use`/`replace` line into a comment: `go` exits 0, reports nothing, and the
+ * overlay module simply disappears from the workspace.
+ *
+ * On POSIX, a backslash can be part of a filename. Preserve it there so the
+ * workspace token continues to name the directory the caller supplied. The
+ * explicit platform argument permits callers to format a declared path grammar;
+ * ordinary workspace callers retain the current host by default.
+ *
+ * @evidence contracts/common.md#principled-implementation Windows separator normalization precedes Go's token formatter so UNC and extended-length spellings containing a comment opener are quoted rather than dropped from the workspace; POSIX backslashes retain their filename meaning.
+ * @evidence contracts/common.md#clear-and-simple-design Path protocol spelling and token quoting are two explicit steps, sharing the same Go-style token formatter and its documented Unicode limits as other modfile values.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Quoting responds to Go's actual lexer, including comment openers, rather than a growing list of known project path exceptions.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain space, UNC and extended-length paths, why a bare slash pair loses a workspace entry, and why POSIX backslashes are preserved.
+ * @evidence contracts/portability.md#os-neutral-implementation The host path grammar selects separator conversion: Windows backslashes become Go workspace slashes, including UNC paths, while POSIX backslashes remain literal filename characters.
+ * @evidence contracts/performance.md#efficient-algorithms At most one separator pass and the token formatter's linear quote passes make time and temporary string space proportional to path length.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This converts one supplied path token and owns no shared resolution or build computation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only its returned token survives; no filesystem handle or process is acquired.
+ */
+export function formatGoWorkPath(
+  p: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return autoQuoteGoModToken(platform === "win32" ? p.replace(/\\/g, "/") : p);
+}