ttsc 0.30.4 → 0.31.0

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

@@ -0,0 +1,330 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { SourceNativeRetirement } from "../../../internal/SourceNativeRetirement";
+import { isContendedCandidateRename } from "../../../internal/isContendedCandidateRename";
+import type { PluginBuildLockFence } from "./PluginBuildLockFence";
+import type { PluginBuildLockObservation } from "./PluginBuildLockObservation";
+import { PluginBuildLockOwner } from "./PluginBuildLockOwner";
+import { PluginBuildLockProtocol } from "./PluginBuildLockProtocol";
+
+/**
+ * Classify the current state of a plugin build lock directory.
+ *
+ * Occupied v3 observations register this process as a fence holder and confirm
+ * the generation before returning. These records move into its tombstone and
+ * remain until the observer is provably gone. No heartbeat or timeout
+ * establishes that a live observer cannot act.
+ *
+ * An owner record whose generation is missing or mismatched remains active and
+ * inconclusive: another generation's absent PID cannot authorize this one.
+ * Unusable owner metadata also remains inconclusive regardless of age. Ordinary
+ * v3 publication includes the complete owner record; old legacy builders could
+ * continue after best-effort owner publication failed.
+ *
+ * Unknown or malformed native guards refuse same-key observations. Pending
+ * guards preserve active ownership even when the Node holder is absent, so
+ * bounded wait cannot turn PID or age into native reclamation authority.
+ *
+ * @evidence contracts/common.md#principled-implementation An observer is registered under a captured generation before owner classification; generation rechecks prevent a replacement from inheriting the captured fence, whose reserved retirement destination survives the builder's death.
+ * @evidence contracts/common.md#clear-and-simple-design Protocol selection, generation observation and legacy fence capture have separate helpers; the public result distinguishes absence from active and abandoned ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A replaced generation causes re-observation or a released handoff; ambiguous process errors are not interpreted as death, and observer age cannot replace liveness proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe observer registration, token retention and inconclusive owner metadata before the tags; private comments explain generation races and legacy record compatibility.
+ * @evidence contracts/portability.md#os-neutral-implementation Node filesystem and path APIs carry native access, while ESRCH-only local probing distinguishes absent processes from permission failure or remote identity.
+ * @evidence contracts/performance.md#efficient-algorithms Each observation scans native guards before direct generation paths; it does not scan generation directories; costs include native path resolution and protocol/generation/owner/fence JSON bytes, hostname checks and optional liveness probes. Publication adds candidate writes/rename/recursive cleanup. Failed v3 registration or changing legacy capture can re-enter the synchronous loop, which has no attempt or elapsed-time bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work A module's nonce shares one observer registration across polls of the same generation; liveness and current identity remain freshly observed because they can change between requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate records have finally cleanup that can fail, including after publication. Published records remain under the cooperating collector policy until observer absence is proven; distinct generations observed by live/unknown processes have no count or age bound here. Continued pathname churn may retain this synchronous observation without a deadline; it starts no asynchronous task.
+ */
+export function inspectPluginBuildLock(
+  lockDir: string,
+): PluginBuildLockObservation {
+  const protocolDir =
+    PluginBuildLockProtocol.pluginBuildLockProtocolDir(lockDir);
+  SourceNativeRetirement.assertAvailable(protocolDir);
+  for (;;) {
+    if (PluginBuildLockProtocol.isPluginBuildLockProtocolV3(protocolDir)) {
+      const current = inspectV3PluginBuildLock(protocolDir);
+      if (current.state !== "released") {
+        return current;
+      }
+    }
+    const legacy = captureLegacyPluginBuildLockFence(lockDir);
+    if (legacy !== null) {
+      return inspectLegacyPluginBuildLock(lockDir, legacy);
+    }
+    if (pluginBuildLockPathMissing(lockDir)) {
+      return { state: "released" };
+    }
+    // The path changed while its legacy fence was being captured. Re-observe
+    // the replacement rather than attaching the old state to a new owner.
+  }
+}
+
+// Each loaded module records one observer per generation. A random process
+// incarnation token keeps a reused PID or another worker's module separate.
+const PLUGIN_BUILD_LOCK_OBSERVER = crypto.randomBytes(16).toString("hex");
+
+function inspectV3PluginBuildLock(lockDir: string): PluginBuildLockObservation {
+  const generationDir = path.join(
+    lockDir,
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_CURRENT_DIR,
+  );
+  const generation = readPluginBuildLockGeneration(generationDir);
+  if (generation === null) {
+    if (pluginBuildLockPathMissing(generationDir)) {
+      return { state: "released" };
+    }
+    throw new Error(
+      `ttsc plugin build lock has no valid ${PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE}: ${generationDir}`,
+    );
+  }
+  if (!registerPluginBuildLockObserver(lockDir, generationDir, generation)) {
+    return { state: "released" };
+  }
+  const fence: PluginBuildLockFence = { protocol: "v3", generation };
+  const owner = PluginBuildLockOwner.read(generationDir);
+  // Owner and generation are read through a mutable current pathname. A
+  // replacement must not inherit an earlier generation's liveness decision.
+  if (readPluginBuildLockGeneration(generationDir) !== generation) {
+    return { state: "released" };
+  }
+  if (owner !== null) {
+    const label = PluginBuildLockOwner.describe(owner);
+    if (owner.generation !== generation) {
+      return {
+        state: "active",
+        owner: `${label} with unconfirmed generation metadata`,
+        fence,
+      };
+    }
+    if (PluginBuildLockOwner.gone(owner)) {
+      if (SourceNativeRetirement.isProtected(lockDir))
+        return {
+          state: "active",
+          owner: `${label} with native retirement pending`,
+          fence,
+        };
+      return {
+        state: "abandoned",
+        reason: `${label} is no longer running`,
+        fence,
+      };
+    }
+    return {
+      state: "active",
+      owner: label,
+      fence,
+    };
+  }
+
+  // Normal v3 publication includes a complete owner record. Its absence or
+  // unreadability is inconclusive, not a creator window that age can expire.
+  return {
+    state: "active",
+    owner: `lock generation with unconfirmed ${PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+    fence,
+  };
+}
+
+/**
+ * Publish this process's fence ownership before returning an observation. A
+ * claim moves with current into its tombstone. Retirement prevents further
+ * claims from entering that old generation, so collection sees a closed set.
+ */
+function registerPluginBuildLockObserver(
+  protocolDir: string,
+  generationDir: string,
+  generation: string,
+): boolean {
+  const observers = path.join(
+    generationDir,
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OBSERVERS_DIR,
+  );
+  const observer = path.join(observers, PLUGIN_BUILD_LOCK_OBSERVER);
+  try {
+    fs.mkdirSync(observers);
+  } catch (error) {
+    if (PluginBuildLockProtocol.isMissingPathError(error)) return false;
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  if (!fs.existsSync(observer)) {
+    const candidate = path.join(
+      protocolDir,
+      `observer-candidate-${PLUGIN_BUILD_LOCK_OBSERVER}-${generation}`,
+    );
+    fs.mkdirSync(candidate);
+    try {
+      fs.writeFileSync(
+        path.join(
+          candidate,
+          PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE,
+        ),
+        `${JSON.stringify({ hostname: os.hostname(), pid: process.pid })}\n`,
+        { encoding: "utf8", flag: "wx" },
+      );
+      try {
+        fs.renameSync(candidate, observer);
+      } catch (error) {
+        if (PluginBuildLockProtocol.isMissingPathError(error)) return false;
+        if (
+          !PluginBuildLockProtocol.isRenameDestinationOccupied(error, observer)
+        )
+          throw error;
+      }
+    } finally {
+      fs.rmSync(candidate, { force: true, recursive: true });
+    }
+  }
+  // A claim accidentally published into a successor cannot authorize the old
+  // fence. Its harmless extra record is collected when this process exits.
+  return readPluginBuildLockGeneration(generationDir) === generation;
+}
+
+function inspectLegacyPluginBuildLock(
+  lockDir: string,
+  legacy: PluginBuildLockProtocol.LegacyPluginBuildLockFence,
+): PluginBuildLockObservation {
+  const owner = PluginBuildLockOwner.read(lockDir);
+  if (owner !== null) {
+    const label = PluginBuildLockOwner.describe(owner);
+    if (PluginBuildLockOwner.gone(owner)) {
+      return {
+        state: "abandoned",
+        reason: `${label} is no longer running`,
+        fence: legacy.fence,
+      };
+    }
+    return {
+      state: "active",
+      owner: label,
+      fence: legacy.fence,
+    };
+  }
+
+  // Old builders treated owner publication as best effort and could continue
+  // working without that file. Directory age cannot prove their task ended.
+  return {
+    state: "active",
+    owner: `legacy lock with unconfirmed ${PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+    fence: legacy.fence,
+  };
+}
+
+function captureLegacyPluginBuildLockFence(
+  lockDir: string,
+): PluginBuildLockProtocol.LegacyPluginBuildLockFence | null {
+  if (PluginBuildLockProtocol.isPluginBuildLockProtocolV3(lockDir)) {
+    return null;
+  }
+
+  let legacyMtimeMs: number;
+  try {
+    legacyMtimeMs = fs.statSync(lockDir).mtimeMs;
+  } catch (error) {
+    if (PluginBuildLockProtocol.isMissingPathError(error)) return null;
+    throw error;
+  }
+
+  const fenceDir = path.join(
+    lockDir,
+    PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR,
+  );
+  let captured =
+    PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+  if (captured === null) {
+    const generation = crypto.randomBytes(16).toString("hex");
+    // Keep candidates beside the legacy lock. Creating one inside `lockDir`
+    // would advance its mtime before a contender publishes the shared fence;
+    // a concurrent contender could then record an old lock as freshly created.
+    const candidateDir = `${lockDir}.legacy-candidate-${generation}`;
+    try {
+      fs.mkdirSync(candidateDir);
+      fs.writeFileSync(
+        path.join(
+          candidateDir,
+          PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD,
+        ),
+        `${JSON.stringify({ generation, legacyMtimeMs })}\n`,
+        "utf8",
+      );
+      try {
+        fs.renameSync(candidateDir, fenceDir);
+        captured = {
+          fence: { protocol: "legacy", generation },
+          legacyMtimeMs,
+        };
+      } catch (error) {
+        if (isContendedCandidateRename(error)) {
+          captured =
+            PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+          // The fence lives inside the legacy lock, so a fence another
+          // process recorded and that is gone by now went with a lock that
+          // was released or retired meanwhile.
+          if (captured === null && !fs.existsSync(fenceDir)) return null;
+        } else if (PluginBuildLockProtocol.isMissingPathError(error)) {
+          return null;
+        } else {
+          throw error;
+        }
+      }
+    } catch (error) {
+      if (PluginBuildLockProtocol.isMissingPathError(error)) {
+        return null;
+      }
+      throw error;
+    } finally {
+      fs.rmSync(candidateDir, { force: true, recursive: true });
+    }
+  }
+  if (captured === null) {
+    throw new Error(`invalid legacy plugin build lock fence: ${fenceDir}`);
+  }
+
+  // A stale observer can resume after the legacy holder released or another
+  // process retired the path. Confirm both the legacy layout and token after
+  // publication; v3 ownership is kept in the orthogonal sibling directory.
+  const confirmed =
+    PluginBuildLockProtocol.readLegacyPluginBuildLockFence(fenceDir);
+  if (
+    PluginBuildLockProtocol.isPluginBuildLockProtocolV3(lockDir) ||
+    confirmed === null ||
+    confirmed.fence.generation !== captured.fence.generation
+  ) {
+    return null;
+  }
+  return captured;
+}
+
+function readPluginBuildLockGeneration(generationDir: string): string | null {
+  try {
+    const generation = fs
+      .readFileSync(
+        path.join(
+          generationDir,
+          PluginBuildLockProtocol.PLUGIN_BUILD_LOCK_GENERATION_FILE,
+        ),
+        "utf8",
+      )
+      .trim();
+    return PluginBuildLockProtocol.isPluginBuildLockGeneration(generation)
+      ? generation
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a path lookup proves absence. Permission and sharing failures are
+ * inconclusive, never evidence of a released or old abandoned generation.
+ */
+function pluginBuildLockPathMissing(lockDir: string): boolean {
+  try {
+    fs.statSync(lockDir);
+    return false;
+  } catch (error) {
+    return PluginBuildLockProtocol.isMissingPathError(error);
+  }
+}

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

@@ -0,0 +1,24 @@
+import path from "node:path";
+
+/**
+ * Report whether `child` equals `parent` or is lexically nested beneath it.
+ *
+ * This does not resolve symlinks or establish physical containment.
+ *
+ * @evidence contracts/common.md#principled-implementation Empty relative paths establish equality; rejecting parent traversal and absolute relative results excludes ancestors, siblings and other native volumes.
+ * @evidence contracts/common.md#clear-and-simple-design One lexical predicate exposes containment without mixing physical realpath resolution into callers' already-resolved paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Parent traversal is checked by path components rather than an unsafe string-prefix exception for particular directories.
+ * @evidence contracts/common.md#meaningful-documentation The native comment distinguishes lexical nesting from symlink-safe physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.relative, separator and absolute-path rules cover volume and parent boundaries without inferring filesystem case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated native relative-path construction and prefix checks process supplied path text without enumerating directories. Node's Windows Unicode-folding fallback can allocate component arrays; relative inputs may also consult current-directory state during resolution. Temporary strings/arrays follow those delegated path lengths rather than a fixed allocation count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate compares supplied paths and stores no cross-request result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query retains no handle or state and performs no direct filesystem-entry inspection; any current-directory resolution belongs to the native path operation.
+ */
+export function isPathWithin(child: string, parent: string): boolean {
+  const rel = path.relative(parent, child);
+  return (
+    rel === "" ||
+    (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel))
+  );
+}

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

@@ -0,0 +1,71 @@
+import os from "node:os";
+import path from "node:path";
+
+import { SourceBuildCacheLayout } from "./SourceBuildCacheLayout";
+
+/**
+ * Machine-global cache directories created by pre-0.17 ttsc releases (XDG /
+ * AppData / Library / `~/.cache`). The current default no longer selects these
+ * machine-global roots, though an explicit override can select them. An
+ * upgraded machine can still hold a multi-GB orphaned cache here, so `ttsc
+ * clean` offers them for removal to reclaim that disk. Each entry is the whole
+ * `<userCacheRoot>/ttsc` directory (both its `plugins` and `go-build`), which
+ * was ttsc-owned in those releases. The cleanup transaction still validates
+ * present-day physical ownership and protected directories before deletion.
+ *
+ * The same holds for `<os.tmpdir()>/ttsc-orphan`, where releases that lowered
+ * orphan sources for every run without `TTSC_CACHE_DIR` and never collected
+ * them.
+ *
+ * @evidence contracts/common.md#principled-implementation The set enumerates historically authored ttsc cache locations, accepting environment cache bases only when absolute.
+ * @evidence contracts/common.md#clear-and-simple-design One migration query deduplicates the finite platform-specific candidates without deleting them.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform-specific paths represent actual prior layouts, not compensation for a disproven current-root assumption.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes historical roots from the current workspace policy and explains migration cleanup ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation os.homedir/tmpdir and native path.join provide host bases; explicit Windows/macOS historical layouts are isolated in this migration boundary and relative environment bases are rejected.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns a fresh array; the Set is local to the call.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed candidate count is deduplicated through a call-local Set. Native home/tmp lookup, supplied environment-path text and joined result strings still contribute processing and temporary storage; no directory population is traversed here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The list is recomputed from the environment on each call and no cache is kept.
+ */
+export function legacyGlobalCacheTargets(): string[] {
+  const roots = new Set<string>();
+  const home = os.homedir();
+  const xdg = process.env.XDG_CACHE_HOME;
+  if (xdg && path.isAbsolute(xdg)) {
+    roots.add(path.join(xdg, SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+  }
+  if (process.platform === "win32") {
+    const local = process.env.LOCALAPPDATA;
+    if (local && path.isAbsolute(local)) {
+      roots.add(path.join(local, SourceBuildCacheLayout.TTSC_CACHE_DIRNAME));
+    }
+    if (home) {
+      roots.add(
+        path.join(
+          home,
+          "AppData",
+          "Local",
+          SourceBuildCacheLayout.TTSC_CACHE_DIRNAME,
+        ),
+      );
+    }
+  } else if (process.platform === "darwin" && home) {
+    roots.add(
+      path.join(
+        home,
+        "Library",
+        "Caches",
+        SourceBuildCacheLayout.TTSC_CACHE_DIRNAME,
+      ),
+    );
+  }
+  if (home) {
+    roots.add(
+      path.join(home, ".cache", SourceBuildCacheLayout.TTSC_CACHE_DIRNAME),
+    );
+  }
+  roots.add(path.join(os.tmpdir(), LEGACY_ORPHAN_CACHE_DIRNAME));
+  return [...roots];
+}
+
+/** The temporary-directory parent of the orphan cache in earlier releases. */
+const LEGACY_ORPHAN_CACHE_DIRNAME = "ttsc-orphan";

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

@@ -0,0 +1,59 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+import { GoToolResolution } from "./GoToolResolution";
+import type { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import { hashPluginBuildEnvironment } from "./hashPluginBuildEnvironment";
+import { resolveGoCompiler } from "./resolveGoCompiler";
+
+/**
+ * The digest of the environment a plugin build in `directory` is keyed on: the
+ * Go compiler the build resolves there, the Go build environment `go env`
+ * reports there, and the external toolchain environment
+ * (`hashPluginBuildEnvironment`).
+ *
+ * The compiler is resolved as the build resolves it (`resolveGoCompiler`, then
+ * the toolchain `directory` selects), so for a plugin's own module root this is
+ * the selected identity used by its binary key; it does not certify arbitrary
+ * unobserved tool/launcher inputs. A normal reading probes `go env` and walks
+ * GOROOT metadata. Witnessing a newly selected environment file can repeat the
+ * probe to observe it before reading. Compiler identity reuses a
+ * metadata-and-context memo; a changed SDK manifest rehashes all contributing
+ * content rather than only edited files.
+ *
+ * @param directory The directory a build runs `go` in.
+ * @param env The effective environment, `process.env` by default.
+ * @param witness Receives the paths the reading depends on and no variable
+ *   carries (`hashPluginBuildEnvironment`).
+ * @evidence contracts/common.md#principled-implementation The digest uses the same resolved compiler and environment serializer as the binary key, so reported toolchain state denotes the inputs actually used by the build.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler selection, executable resolution and hashing each stay with their owning helper; this function only composes one environment reading.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result comes from real Go/environment inputs, not a fixed compiler version or a caller-specific substitute.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation identifies the module-directory meaning, cost and witness output, with parameter descriptions and separated acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Executable identity is resolved before probing, and Node filesystem/process boundaries implement native spelling rather than assuming Windows or POSIX paths are interchangeable.
+ * @evidence contracts/performance.md#efficient-algorithms The wrapper resolves the compiler/tool under the supplied environment before delegating full environment hashing. Native resolution/probes, SDK metadata/name/path sorting and changed-manifest full content reads contribute cost; the final hash output is fixed-width but streamed identity/input text and full-file buffers are not. No independent duplicate source-directory digest scan is added here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is the fresh-reading boundary required by builds; processPluginBuildEnvironment owns reuse when a consumer permits it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Its digest and filesystem adapter are call-local; retained compiler/content memo ownership belongs to the hasher.
+ */
+export function pluginBuildEnvironment(
+  directory: string,
+  env: NodeJS.ProcessEnv = process.env,
+  witness?: PluginBuildEnvironmentWitness.Record,
+): string {
+  const goBinary = GoToolResolution.resolveGoToolForBuild(
+    resolveGoCompiler(env).binary,
+    env,
+    directory,
+    witness,
+  );
+  const hash = crypto.createHash("sha256");
+  hashPluginBuildEnvironment(
+    hash,
+    goBinary,
+    directory,
+    env,
+    { readFile: (location) => fs.readFileSync(location) },
+    witness,
+  );
+  return hash.digest("hex");
+}

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

@@ -0,0 +1,30 @@
+import { parentPort } from "node:worker_threads";
+
+import { serializeCompilerError } from "../../../internal/serializeCompilerError";
+import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import { pluginBuildEnvironment } from "./pluginBuildEnvironment";
+
+/**
+ * Observe one requested native toolchain environment on the exclusive worker.
+ * Explicit environment values reach every Go/toolchain reader; no caller
+ * process globals are written. Only actual readings and pre-read witnesses
+ * cross the worker boundary, and failures retain their real error details.
+ */
+parentPort?.on(
+  "message",
+  (request: { directory: string; env: NodeJS.ProcessEnv }) => {
+    try {
+      const witness: PluginBuildEnvironmentWitness.Record = new Map();
+      parentPort!.postMessage({
+        environment: pluginBuildEnvironment(
+          request.directory,
+          request.env,
+          witness,
+        ),
+        witness,
+      });
+    } catch (error) {
+      parentPort!.postMessage({ thrown: serializeCompilerError(error) });
+    }
+  },
+);

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

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Package-version labels used by plugin build keys (`computeCacheKey`) and
+ * persisted transform identities. These are metadata inputs, not a measurement
+ * of the executable actually selected for an invocation.
+ *
+ * Transform reuse also depends on inputs, plugin sources, build environment and
+ * the producer's declared proofs; these labels alone certify none of them. A
+ * consumer that keeps a transform's output beyond the process that produced it,
+ * as a persisted shared compile of `@ttsc/unplugin` is, names it by these
+ * versions with the rule the build applies instead of a copy of it: ttsc's own
+ * package version, and the version of the `typescript` package the project
+ * resolves, or `"unknown"` when resolution/read/parse fails or its version is
+ * absent. The host label falls back to `"0.0.0"` and is cached even after an
+ * unsuccessful first read. The host installation is assumed stable for the
+ * process lifetime; changing its manifest does not refresh that label.
+ *
+ * @param projectRoot The project base used to resolve
+ *   `typescript/package.json`.
+ * @evidence contracts/common.md#principled-implementation Package-version labels supply the same metadata tuple used by plugin keys; absent/unreadable metadata receives the documented unknown/default label rather than an executable identity certificate.
+ * @evidence contracts/common.md#clear-and-simple-design Host-version and project-version readers are separate because one installation is stable within the process while project resolution varies per call.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Node package resolution determines the actual project dependency; no particular project or fixture version is embedded.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains persisted-output consumers, metadata fallbacks and the process-stable host premise without claiming that version labels establish executable or output equivalence.
+ * @evidence contracts/portability.md#os-neutral-implementation Node createRequire and path APIs locate package metadata using native module resolution without manual separator or case normalization.
+ * @evidence contracts/performance.md#efficient-algorithms Each call performs project package resolution and, when successful, reads/parses its manifest bytes; module search/path work and metadata size are not fixed by one logical manifest lookup. The host manifest is attempted only on the first invocation, including native path and JSON costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work All callers share the host installation's process-stable version; the project compiler version is resolved afresh so different project roots do not share a false identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This helper retains one host-version label for the process lifetime, whose text follows its manifest value rather than a fixed byte limit; the helper's retained label count is independent of project count. Native module-resolution caches belong to Node, and synchronous file reads leave no persistent descriptor here.
+ */
+export function pluginBuildVersions(projectRoot: string): {
+  tsgo: string;
+  ttsc: string;
+} {
+  return { tsgo: readTsgoVersion(projectRoot), ttsc: readTtscVersion() };
+}
+
+let cachedTtscVersion: string | null = null;
+
+function readTtscVersion(): string {
+  if (cachedTtscVersion !== null) return cachedTtscVersion;
+  try {
+    const file = path.resolve(
+      __dirname,
+      "..",
+      "..",
+      "..",
+      "..",
+      "package.json",
+    );
+    const pkg = JSON.parse(fs.readFileSync(file, "utf8")) as {
+      version?: string;
+    };
+    cachedTtscVersion = pkg.version ?? "0.0.0";
+  } catch {
+    cachedTtscVersion = "0.0.0";
+  }
+  return cachedTtscVersion;
+}
+
+function readTsgoVersion(projectRoot: string): string {
+  try {
+    const projectRequire = createRequire(
+      path.join(projectRoot, "package.json"),
+    );
+    const pkgPath = projectRequire.resolve("typescript/package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
+      version?: string;
+    };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}