ttsc 0.31.1 → 0.31.3

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

@@ -0,0 +1,151 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { E2ETrace } from "../../../internal/E2ETrace";
+import type { PluginContentIdentities } from "./PluginContentIdentities";
+import { SourceBuildCacheLayout } from "./SourceBuildCacheLayout";
+import { recordCacheFileUse } from "./recordCacheFileUse";
+
+/**
+ * Answers a plugin load computed from inputs it could identify by content, kept
+ * in the plugin cache root under that identity so a later process with equal
+ * inputs reads the answer instead of computing it again.
+ *
+ * WARNING (#1721, #1723): the key is the whole proof. A caller must fold into
+ * `identity` every input that can change the answer, as content identities
+ * (`PluginContentIdentities`) or the authoritative live probe results, never a
+ * path, a timestamp or a value it merely expects to be stable. An answer is
+ * written only after the computation succeeded on inputs the caller proved
+ * unchanged around it; a failed or unproved computation is never recorded,
+ * since a later process could not tell it from a current one.
+ *
+ * Entries are single files published by rename, aged out by the single-file
+ * collector and removed by `ttsc clean`. Their identity includes the format tag
+ * and the ttsc version, so another release never reads them.
+ *
+ * @evidence contracts/common.md#principled-implementation The content-addressed key carries every caller-declared input identity; reads accept only a matching format, version and kind, and writes are refused for unproved computations by the caller contract.
+ * @evidence contracts/common.md#clear-and-simple-design One owner stores and loads opaque answers; callers own key composition, validation of the answer shape and the decision to record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No answer is guessed; a missing, corrupt or foreign entry is a miss and the caller computes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the key contract that prevents stale answers, the recording rule and the storage lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joins and same-directory rename publication; keys are hashed text, independent of path dialect.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members state their own costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members define reuse through the caller's identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Members state retention; the namespace holds no state.
+ */
+export namespace PluginLoadAnswers {
+  /**
+   * The answer recorded for `identity`, or `undefined` when none is.
+   *
+   * @param store The opened store, or `undefined` for no persistence.
+   * @param kind Answer family; families never share entries.
+   * @param identity Every input identity the answer depends on.
+   * @evidence contracts/common.md#principled-implementation An entry is returned only for the same format, version, kind and identity hash; the caller validates the value's shape.
+   * @evidence contracts/common.md#clear-and-simple-design One lookup returns an opaque value or undefined.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreadable or foreign entries are misses.
+   * @evidence contracts/common.md#meaningful-documentation Parameters describe the identity contract.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path join and file read.
+   * @evidence contracts/performance.md#efficient-algorithms Hashes the serialized identity and reads one small file; a hit refreshes its use time.
+   * @evidence contracts/performance.md#reuse-equivalent-work Processes share an answer only for an identical serialized identity under the same version.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Nothing is retained in memory; the collector owns entry lifetime.
+   */
+  export function read(
+    store: PluginContentIdentities.Store | undefined,
+    kind: string,
+    identity: unknown,
+  ): unknown {
+    if (store === undefined) return undefined;
+    const file = answerFile(store, kind, identity);
+    try {
+      const entry = JSON.parse(
+        fs.readFileSync(file, "utf8"),
+      ) as Partial<IEntry>;
+      if (
+        entry.format !== FORMAT ||
+        entry.version !== store.version ||
+        entry.kind !== kind ||
+        !Object.prototype.hasOwnProperty.call(entry, "value")
+      )
+        return undefined;
+      recordCacheFileUse(file);
+      E2ETrace.capabilityResolution("plugin-load-answer", {
+        kind,
+        outcome: "reused",
+      });
+      return entry.value;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Record `value` as the answer for `identity`. Failures are ignored: the
+   * answer just computed stands, and the next process computes it again.
+   *
+   * @param store The opened store, or `undefined` for no persistence.
+   * @param kind Answer family.
+   * @param identity Every input identity the answer depends on.
+   * @param value JSON-serializable answer the caller proved for `identity`.
+   * @evidence contracts/common.md#principled-implementation Publication happens only when the caller decided the computation was proven; the entry records the same identity framing that read checks.
+   * @evidence contracts/common.md#clear-and-simple-design One atomic publication through the shared metadata writer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed write never fails the load or fabricates an entry.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states failure behavior.
+   * @evidence contracts/portability.md#os-neutral-implementation Same-directory staging and rename through the shared writer.
+   * @evidence contracts/performance.md#efficient-algorithms Serializes the identity and value once and writes one small file.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Publication creates the reusable entry; read owns reuse.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One file per identity, removed by the single-file collector or `ttsc clean`; staging cleanup belongs to the shared writer.
+   */
+  export function write(
+    store: PluginContentIdentities.Store | undefined,
+    kind: string,
+    identity: unknown,
+    value: unknown,
+  ): void {
+    if (store === undefined) return;
+    const file = answerFile(store, kind, identity);
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      SourceBuildCacheLayout.replaceCacheMetadataFile(
+        file,
+        JSON.stringify({
+          format: FORMAT,
+          version: store.version,
+          kind,
+          value,
+        } satisfies IEntry),
+      );
+      E2ETrace.capabilityResolution("plugin-load-answer", {
+        kind,
+        outcome: "recorded",
+      });
+    } catch {
+      // The answer just computed stands; only its reuse is lost.
+    }
+  }
+
+  /** Entry format tag; move it when the entry shape changes. */
+  const FORMAT = "ttsc-plugin-load-answer-v1";
+
+  interface IEntry {
+    format: string;
+    version: string;
+    kind: string;
+    value: unknown;
+  }
+
+  function answerFile(
+    store: PluginContentIdentities.Store,
+    kind: string,
+    identity: unknown,
+  ): string {
+    const key = crypto
+      .createHash("sha256")
+      .update(JSON.stringify([FORMAT, store.version, kind, identity]))
+      .digest("hex");
+    return path.join(
+      store.root,
+      SourceBuildCacheLayout.ANSWER_CACHE_DIRNAME,
+      `${key}.json`,
+    );
+  }
+}

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

@@ -53,6 +53,18 @@ export namespace SourceBuildCacheLayout {
   /** Directory of the capability-resolution answers inside the cache root. */
   export const CAPABILITY_CACHE_DIRNAME = "capabilities";
 
+  /**
+   * Directory of the content identities a plugin load proves from metadata
+   * (`PluginContentIdentities`) inside the cache root.
+   */
+  export const IDENTITY_CACHE_DIRNAME = "identities";
+
+  /**
+   * Directory of the plugin-load answers keyed by those identities, such as Go
+   * package selections and runtime capabilities (`PluginLoadAnswers`).
+   */
+  export const ANSWER_CACHE_DIRNAME = "answers";
+
   /** Directory of the ttsx runtime inside the cache root. */
   export const RUNTIME_CACHE_DIRNAME = "ttsx";
 
@@ -72,6 +84,8 @@ export namespace SourceBuildCacheLayout {
   export const CACHE_FILE_DIRNAMES: readonly string[] = [
     DESCRIPTOR_CACHE_DIRNAME,
     CAPABILITY_CACHE_DIRNAME,
+    IDENTITY_CACHE_DIRNAME,
+    ANSWER_CACHE_DIRNAME,
     ORPHAN_CACHE_DIRNAME,
   ];
 

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

@@ -1,11 +1,15 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
+import { runtimeExecutableIdentity } from "../../../internal/runtimeExecutableIdentity";
 import { GoEnvironmentReading } from "./GoEnvironmentReading";
 import { GoSourceInputs } from "./GoSourceInputs";
 import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import { PluginContentIdentities } from "./PluginContentIdentities";
+import { PluginLoadAnswers } from "./PluginLoadAnswers";
 import { SourcePluginAdmission } from "./SourcePluginAdmission";
 import { copiesPluginSourceEntry } from "./copiesPluginSourceEntry";
 import { formatGoWorkPath } from "./formatGoWorkPath";
@@ -240,13 +244,23 @@ export namespace SourcePluginWorkspace {
    * Caller views share that native state and syntax, while each default
    * diagnostic label remains with its current caller.
    *
+   * An optional record store carries the Go environment-file discovery hint
+   * across processes, and the parse of identical bytes by the same Go command
+   * (#1729): every launch otherwise ran `go mod edit -json` on an unchanged
+   * `go.mod`. A recorded parse is keyed by the manifest bytes, the content
+   * identities of the launcher and of the `GOROOT/bin/go` the live `go env
+   * -json GOROOT` reports, the `GOENV` file's bytes, and every `GO*`/`CGO_*`
+   * variable the command receives. It is consulted and written only under the
+   * same qualified tool witness that admits in-load sharing, so the live
+   * witness query still runs on every load.
+   *
    * @evidence contracts/common.md#principled-implementation Actual go mod edit JSON determines module/replacement identities; current bytes, selected/dispatched-tool metadata and Go's environment-file witness qualify reuse under the existing metadata-distinguishability premise. Environment values are copied at reader creation. Missing go.mod returns the existing empty module observation, and moving tool/manifest inputs cannot publish a parsed record.
    * @evidence contracts/common.md#clear-and-simple-design One factory acquires load-owned native reader state by selected tool; a thin caller view forwards its diagnostic label without duplicating the byte-content map. Current reads and post-parse byte/tool comparisons qualify insertion.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts No custom Go manifest parser or global context-insensitive memo is introduced.
    * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
    * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and temporary cwd avoid deep Windows working-directory limits; the selected tool handles manifest syntax.
    * @evidence contracts/performance.md#efficient-algorithms Reader acquisition performs a selected-tool registry lookup; every nonmissing read qualifies tool/environment metadata and reads current manifest bytes. A cold or stale witness first observes the selected launcher; an unavailable or nonfile launcher skips optional environment acquisition and permits only the actual uncached parse attempt. An observed file lends its same pre-read stat to the witness before acquiring current Go values and GOENV evidence through the common reader, without a GOROOT walk. Only complete native GOENV/GOROOT locations qualify syntax sharing; a dispatched tool is witnessed before parsing. Unavailable native environment acquisition disables syntax sharing while preserving actual parse success or failure. Each distinct byte string that earns stable successful syntax in that tool epoch runs Go mod edit and complete JSON parsing once, then rechecks bytes/tool metadata before caching; copied manifests share that parse. Failed queries remain uncached and report the current caller's diagnostic label.
-   * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; parsed syntax is not cross-load or native containment authority. Caller views share native state while preserving failure attribution; diagnostic labels are not syntax cache inputs.
+   * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; parsed syntax is never native containment authority. Across loads only a parse recorded under the content identities of the bytes, both Go executables, the GOENV file and the Go variables is reused, and only under a qualified live tool witness. Caller views share native state while preserving failure attribution; diagnostic labels are not syntax cache inputs.
    * @evidence contracts/performance.md#bound-retention-and-release-resources The map retains distinct manifest bytes and parsed syntax for its caller's load/build lifetime; process/output capture cleanup remains delegated.
    */
   export function createGoModReader(
@@ -254,6 +268,7 @@ export namespace SourcePluginWorkspace {
     pluginName: string,
     env: NodeJS.ProcessEnv,
     readers?: Map<string, GoModReader>,
+    identities?: PluginContentIdentities.Store,
   ): GoModReader {
     const existing = readers?.get(goBinary);
     if (existing !== undefined)
@@ -275,6 +290,9 @@ export namespace SourcePluginWorkspace {
     const cache = new Map<string, GoModInfo>();
     const environment = { ...env };
     let toolWitness: PluginBuildEnvironmentWitness.Record | undefined;
+    // The tool part of a recorded parse's identity, formed with each qualified
+    // witness; undefined without a store or a provable tool.
+    let toolIdentity: unknown;
     const reader: GoModReader = {
       read(dir, diagnosticPlugin = pluginName) {
         OwnedSynchronousProcess.checkpoint();
@@ -315,6 +333,7 @@ export namespace SourcePluginWorkspace {
                   environment,
                   ["GOROOT"],
                   witness,
+                  identities,
                 )
               : undefined;
           if (
@@ -338,6 +357,16 @@ export namespace SourcePluginWorkspace {
             complete && PluginBuildEnvironmentWitness.holds(witness)
               ? witness
               : undefined;
+          toolIdentity =
+            toolWitness === undefined || identities === undefined
+              ? undefined
+              : goModToolIdentity(
+                  goBinary,
+                  observed!.GOROOT as string,
+                  observed!.GOENV as string,
+                  environment,
+                  identities,
+                );
         }
         // UTF-8 decoding is lossy for malformed input. Only identical bytes
         // can share Go syntax, even when Go serializes two inputs identically.
@@ -346,6 +375,26 @@ export namespace SourcePluginWorkspace {
         if (cached !== undefined) {
           return cached;
         }
+        // WARNING (#1729): a new process asks the record store before running
+        // Go on bytes this exact command already parsed. Never key this on a
+        // path or on the reader's metadata witness alone.
+        const answer =
+          toolIdentity === undefined
+            ? undefined
+            : [
+                toolIdentity,
+                crypto.createHash("sha256").update(bytes).digest("hex"),
+              ];
+        const recalled =
+          answer === undefined
+            ? undefined
+            : recallGoModInfo(
+                PluginLoadAnswers.read(identities, GO_MOD_SYNTAX, answer),
+              );
+        if (recalled !== undefined) {
+          cache.set(byteKey, recalled);
+          return recalled;
+        }
         const info = readGoModInfo(
           resolved,
           goBinary,
@@ -365,7 +414,14 @@ export namespace SourcePluginWorkspace {
           );
         // An unavailable environment observation can still execute a fresh Go
         // parse, but it cannot authorize sharing that result on another call.
-        if (toolWitness !== undefined) cache.set(byteKey, info);
+        if (toolWitness !== undefined) {
+          cache.set(byteKey, info);
+          if (answer !== undefined)
+            PluginLoadAnswers.write(identities, GO_MOD_SYNTAX, answer, {
+              modulePath: info.modulePath,
+              directives: info.directives,
+            });
+        }
         return info;
       },
     };
@@ -445,6 +501,124 @@ export namespace SourcePluginWorkspace {
     };
   }
 
+  /** Answer family of `go mod edit -json` parses (`PluginLoadAnswers`). */
+  const GO_MOD_SYNTAX = "go-mod-syntax";
+
+  /**
+   * Everything besides the manifest bytes that decides how `go mod edit -json`
+   * parses them, by content: the launcher, the `GOROOT/bin/go` the live query
+   * reported, the `GOENV` file that can select another toolchain, and the Go
+   * variables the command receives. `undefined` when an executable cannot be
+   * identified or the file cannot be read, so the parse runs.
+   */
+  function goModToolIdentity(
+    goBinary: string,
+    goRoot: string,
+    goEnv: string,
+    env: NodeJS.ProcessEnv,
+    identities: PluginContentIdentities.Store,
+  ): unknown {
+    const dispatchedPath = path.join(
+      goRoot,
+      "bin",
+      process.platform === "win32" ? "go.exe" : "go",
+    );
+    // Only an executable the store can prove from metadata may key the record:
+    // streaming both executables on a device without a reference would cost
+    // more than the parse it replaces.
+    if (
+      !provableFromMetadata(goBinary, identities) ||
+      !provableFromMetadata(dispatchedPath, identities)
+    )
+      return undefined;
+    const launcher = runtimeExecutableIdentity(goBinary, identities);
+    const dispatched = runtimeExecutableIdentity(dispatchedPath, identities);
+    if (launcher === undefined || dispatched === undefined) return undefined;
+    let goEnvFile: string | null;
+    if (goEnv === "off") goEnvFile = "off";
+    else
+      try {
+        goEnvFile = crypto
+          .createHash("sha256")
+          .update(fs.readFileSync(goEnv))
+          .digest("hex");
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+          return undefined;
+        goEnvFile = null;
+      }
+    return [
+      1,
+      launcher,
+      goRoot,
+      dispatched,
+      goEnv,
+      goEnvFile,
+      Object.entries(GoSourceInputs.goBuildEnv(goBinary, undefined, env))
+        .filter(
+          (entry): entry is [string, string] =>
+            entry[1] !== undefined && /^(GO|CGO_)/i.test(entry[0]),
+        )
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),
+    ];
+  }
+
+  /**
+   * Whether the file's stamp is separable from the store's reference on its
+   * device, the precondition for proving its bytes from a record.
+   */
+  function provableFromMetadata(
+    file: string,
+    identities: PluginContentIdentities.Store,
+  ): boolean {
+    try {
+      return PluginContentIdentities.separable(
+        identities.references,
+        fs.statSync(file, { bigint: true }),
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * A recorded parse in the shape `readGoModInfo` returns, or `undefined` when
+   * the record does not have it.
+   */
+  function recallGoModInfo(value: unknown): GoModInfo | undefined {
+    if (typeof value !== "object" || value === null) return undefined;
+    const record = value as { modulePath?: unknown; directives?: unknown };
+    if (
+      (record.modulePath !== null && typeof record.modulePath !== "string") ||
+      !Array.isArray(record.directives) ||
+      !record.directives.every(isReplaceDirective)
+    )
+      return undefined;
+    const directives = record.directives as NonNullable<GoModJson["Replace"]>;
+    return {
+      modulePath: record.modulePath,
+      directives,
+      replacements: directives
+        .map(jsonReplacementToGoModReplacement)
+        .filter((replacement) => replacement !== null),
+    };
+  }
+
+  function isReplaceDirective(value: unknown): boolean {
+    if (typeof value !== "object" || value === null) return false;
+    const directive = value as Record<string, unknown>;
+    return [directive.Old, directive.New].every(
+      (side) =>
+        side === undefined ||
+        (typeof side === "object" &&
+          side !== null &&
+          ["Path", "Version"].every((key) => {
+            const field = (side as Record<string, unknown>)[key];
+            return field === undefined || typeof field === "string";
+          })),
+    );
+  }
+
   function jsonReplacementToGoModReplacement(
     replacement: NonNullable<GoModJson["Replace"]>[number],
   ): GoModReplacement | null {

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

@@ -18,6 +18,7 @@ import { PluginBinaryUse } from "./PluginBinaryUse";
 import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
 import type { PluginBuildLockLease } from "./PluginBuildLockLease";
 import { PluginBuildLockProtocol } from "./PluginBuildLockProtocol";
+import { PluginContentIdentities } from "./PluginContentIdentities";
 import { SourceBuildCacheLayout } from "./SourceBuildCacheLayout";
 import type { SourceBuildFilesystemOperations } from "./SourceBuildFilesystemOperations";
 import { SourcePluginAdmission } from "./SourcePluginAdmission";
@@ -88,8 +89,8 @@ import { withGoBuildCacheLease } from "./withGoBuildCacheLease";
  * @evidence contracts/common.md#prohibited-implementation-shortcuts A changed witness is never overwritten or accepted. A fresh epoch takes a new toolchain reading and performs the actual build or qualified adoption; source, native and cleanup failures stay terminal. No selected SDK tool is warmed by a special command, and no foreign environment or memo is rebased. Shared Go objects retain their owner's toolID/actionID contract; same-version custom tool semantics beyond that contract are not newly guaranteed.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain effective environment, recorded-input comparisons and their trust/observation limits, reader registration and managed versus explicit roots; option-map comments state their reading provenance with blank member separation.
  * @evidence contracts/portability.md#os-neutral-implementation Node path/physical-cache/temp APIs preserve native identities; executable resolution and Windows command handling are isolated owners, and the binary filename explicitly follows its executable platform.
- * @evidence contracts/performance.md#efficient-algorithms At most three epochs redo native toolchain observation, key construction, materialization and guarded admission; each can run one Go build, preceded by one batched package metadata command when the loader requires ownership admission. The shared compiler reader can itself make three version observations, hence at most nine such cold observations for a persistently moving compiler and no build when its key witness fails. Full-file bytes, entries, path/sort text, contributors, external trees and witness populations drive work. Scoped cancellation is sampled between phases/entries/commands and does not bound native calls or delegated hashing. First source digest readings are reused across epochs, while each scratch is independently checked. Existing lock contention has its separate wait budget and native Go compiler work remains delegated.
- * @evidence contracts/performance.md#reuse-equivalent-work Existing binaries and concurrent builders share the version/platform/source/environment key with reader admission before return, assuming trustworthy cache producers and supplied digest maps. Fixed trimpath compilation removes disposable snapshot paths from Go object identities. Shared load readings and sequential source/toolchain comparisons reject observed changes; metadata reuse and unobserved concurrent mutation remain the underlying witnesses' limits.
+ * @evidence contracts/performance.md#efficient-algorithms At most three epochs redo native toolchain observation, key construction, materialization and guarded admission; the first can key on the load's witnessed same-directory reading instead of observing the toolchain again, and later ones always observe it. Each can run one Go build, preceded by one batched package metadata command when the loader requires ownership admission. The shared compiler reader can itself make three version observations, hence at most nine such cold observations for a persistently moving compiler and no build when its key witness fails. Full-file bytes, entries, path/sort text, contributors, external trees and witness populations drive work. Scoped cancellation is sampled between phases/entries/commands and does not bound native calls or delegated hashing. First source digest readings are reused across epochs, while each scratch is independently checked. Existing lock contention has its separate wait budget and native Go compiler work remains delegated.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing binaries and concurrent builders share the version/platform/source/environment key with reader admission before return, assuming trustworthy cache producers and supplied digest maps. The key's content digests come from the record store when their separable metadata still matches, so a new process does not read unchanged sources, SDK or compiler bytes to find an existing binary (#1722). Fixed trimpath compilation removes disposable snapshot paths from Go object identities. Shared load readings and sequential source/toolchain comparisons reject observed changes; metadata reuse and unobserved concurrent mutation remain the underlying witnesses' limits.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Scratch directories and build/cache leases have finally-based cleanup, including cancellation; cancelled work admits no new post-build prune pass. Scratch removal or lease cleanup can fail, and selected synchronous child settlement does not join arbitrary descendants. Repeated commands can repeat external tool effects; only ttsc-owned failed outputs are discarded, and Go-owned object entries retain their existing lifetime. Pending binary cleanup is best-effort. Reader tokens and their process map grow with distinct physical keys until process exit. Managed pruning attempts age/LRU reclamation while protecting live, unknown and selected entries, so it is not a hard disk bound; explicit roots remain caller-managed.
  */
 export function buildSourcePlugin(opts: {
@@ -113,7 +114,21 @@ export function buildSourcePlugin(opts: {
    */
   environmentDigests?: Map<string, string>;
 
+  /**
+   * Witnesses of the readings in `environmentDigests` (`computeCacheKey`), so
+   * the first epoch keys on a reading package selection already took. A
+   * discarded epoch reads the toolchain again instead.
+   */
+  environmentWitnesses?: Map<string, PluginBuildEnvironmentWitness.Record>;
+
   filesystem?: Partial<SourceBuildFilesystemOperations>;
+
+  /**
+   * Record store the loader opened for this load, so its key reuses content
+   * identities across processes (#1722); a standalone build opens its own.
+   */
+  identities?: PluginContentIdentities.Store;
+
   label?: string;
   overlayDirs?: readonly string[];
   quiet?: boolean;
@@ -140,9 +155,17 @@ export function buildSourcePlugin(opts: {
   for (let attempt = 0; ; attempt += 1) {
     OwnedSynchronousProcess.checkpoint();
     const environmentDigests = new Map(opts.environmentDigests);
+    // Only the first epoch may key on a reading taken before it; a discarded
+    // epoch means the toolchain moved, so later ones read it again.
+    const environmentWitnesses =
+      opts.environmentWitnesses === undefined
+        ? undefined
+        : new Map(attempt === 0 ? opts.environmentWitnesses : []);
     try {
       const binary = buildSourcePluginAttempt(
-        attempt === 0 ? opts : { ...opts, goModReaders: undefined },
+        attempt === 0
+          ? { ...opts, environmentWitnesses }
+          : { ...opts, environmentWitnesses, goModReaders: undefined },
         env,
         sourceDigests,
         environmentDigests,
@@ -152,6 +175,8 @@ export function buildSourcePlugin(opts: {
         opts.sourceDigests?.set(directory, digest);
       for (const [directory, digest] of environmentDigests)
         opts.environmentDigests?.set(directory, digest);
+      for (const [directory, witness] of environmentWitnesses ?? [])
+        opts.environmentWitnesses?.set(directory, witness);
       return binary;
     } catch (error) {
       if (
@@ -192,6 +217,18 @@ function buildSourcePluginAttempt(
   );
   ensureExecutableGoToolchain(goBinary, compiler.bundled);
   OwnedSynchronousProcess.checkpoint();
+  const identities =
+    opts.identities ??
+    PluginContentIdentities.open({
+      projectRoot: opts.baseDir,
+      cacheDir: opts.cacheDir,
+      env,
+      sources: [
+        dir,
+        ...overlayDirs,
+        ...contributors.map((contributor) => contributor.source),
+      ],
+    });
   // The digest of every directory the key covers, as the key read it, which
   // the build proves against what it compiled.
   const goModReader = SourcePluginWorkspace.createGoModReader(
@@ -199,6 +236,7 @@ function buildSourcePluginAttempt(
     opts.pluginName,
     env,
     opts.goModReaders,
+    identities,
   );
   const environmentWitness: PluginBuildEnvironmentWitness.Record = new Map();
   const key = computeCacheKey({
@@ -211,8 +249,10 @@ function buildSourcePluginAttempt(
     goModReader,
     filesystem: opts.filesystem,
     goBinary,
+    identities,
     overlayDirs,
     environmentDigests,
+    environmentWitnesses: opts.environmentWitnesses,
     sourceDigests,
     ttscVersion: opts.ttscVersion,
     tsgoVersion: opts.tsgoVersion,