ttsc 0.31.0 → 0.31.2

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

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -7,9 +8,14 @@ import { SourceNativeRetirement } from "../../../internal/SourceNativeRetirement
 import { createCanonicalTempDirectory } from "../../../internal/createCanonicalTempDirectory";
 import { GoSourceInputs } from "./GoSourceInputs";
 import { GoToolResolution } from "./GoToolResolution";
+import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
+import { PluginContentIdentities } from "./PluginContentIdentities";
+import { PluginLoadAnswers } from "./PluginLoadAnswers";
 import { SourcePluginAdmission } from "./SourcePluginAdmission";
 import { SourcePluginWorkspace } from "./SourcePluginWorkspace";
 import { ensureExecutableGoToolchain } from "./ensureExecutableGoToolchain";
+import { hashPluginBuildEnvironment } from "./hashPluginBuildEnvironment";
+import { pluginSourceDigest } from "./pluginSourceDigest";
 import { resolveGoCompiler } from "./resolveGoCompiler";
 import { resolvePluginGoModule } from "./resolvePluginGoModule";
 import { spawnGoTool } from "./spawnGoTool";
@@ -17,8 +23,8 @@ import { spawnGoTool } from "./spawnGoTool";
 /**
  * Observe Go-selected packages under the native builder's workspace policy.
  *
- * Metadata does not compile dependencies or certify a later build. A cold
- * build repeats ownership admission in its proven, materialized workspace.
+ * Metadata does not compile dependencies or certify a later build. A cold build
+ * repeats ownership admission in its proven, materialized workspace.
  *
  * @evidence contracts/common.md#principled-implementation The selected Go tool, effective environment, shared workspace writer and actual copied package inputs determine package names and errors; Go remains the build-constraint and package-validity authority.
  * @evidence contracts/common.md#clear-and-simple-design One namespace separates contextual observation, metadata framing and ownership admission; source-only contributions are observed inside their selected host module.
@@ -26,7 +32,7 @@ import { spawnGoTool } from "./spawnGoTool";
  * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes metadata selection from compilation and later materialized admission.
  * @evidence contracts/portability.md#os-neutral-implementation Native path/fs operations and the shared Go tool selector preserve environment-name and path identity without blanket case folding; Go itself applies target platform and cgo selection.
  * @evidence contracts/performance.md#efficient-algorithms One list command observes all distinct package entries in each prepared context. Context materialization traverses and copies admitted host/contributor files; workspace setup delegates manifest commands and list skips dependency loading. Framing and JSON parsing process complete output bytes, and retained results scale with selected packages/files.
- * @evidence contracts/performance.md#reuse-equivalent-work Entries are deduplicated within a contextual observation; callers group equivalent module contexts for one load. No metadata result is cached across source, environment or toolchain changes. Cold admission uses the already prepared real build workspace.
+ * @evidence contracts/performance.md#reuse-equivalent-work Entries are deduplicated within a contextual observation; callers group equivalent module contexts for one load. With a record store, a successful selection is answered across loads and processes under an identity built from the content of everything Go reads, so any source, overlay, contributor, manifest, Go variable or toolchain change observes Go again (#1721); erroneous selections are never recorded. Cold admission uses the already prepared real build workspace.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Each metadata scratch has finally-based retirement-aware cleanup, and capture resources belong to spawnGoTool. Unknown native retirement retains scratch under the existing scope; results and complete output remain caller-owned with no independent byte ceiling.
  */
 export namespace NativeSourcePackages {
@@ -59,6 +65,35 @@ export namespace NativeSourcePackages {
     Error?: { Err: string };
   }
 
+  /**
+   * One load's readings, shared by its package selections and its builds:
+   * source directory digests and module build-environment digests, each by
+   * absolute directory. The builds fill and report the same maps, so a load
+   * reads each directory and each module's toolchain once.
+   *
+   * @evidence contracts/common.md#principled-implementation Both maps carry readings already taken in this load under its fixed effective environment; builds still take their own environment reading with a witness.
+   * @evidence contracts/common.md#clear-and-simple-design Two maps already owned by the loader travel together.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The maps never outlive the load; cross-process reuse belongs to the record store.
+   * @evidence contracts/common.md#meaningful-documentation Members state their keys and values.
+   * @evidence contracts/portability.md#os-neutral-implementation Keys are native absolute paths.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A record type runs no algorithm.
+   * @evidence contracts/performance.md#reuse-equivalent-work Selections and builds of one load share one reading per directory and module.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The loader owns both maps for one load.
+   */
+  export interface SelectionReadings {
+    /** `pluginSourceDigest` of each directory this load read. */
+    sources?: Map<string, string>;
+
+    /** Build-environment digest of each module root this load read. */
+    environments?: Map<string, string>;
+
+    /**
+     * Witness of each reading in `environments`, so a build of the same
+     * directory keys on that reading instead of probing Go again.
+     */
+    witnesses?: Map<string, PluginBuildEnvironmentWitness.Record>;
+  }
+
   /**
    * Observe entries together in a private module layout for their context.
    *
@@ -68,7 +103,7 @@ export namespace NativeSourcePackages {
    * @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 copy/path and selected tool/environment owners preserve platform identity; contribution target containment is checked.
    * @evidence contracts/performance.md#efficient-algorithms Copies admitted host/contributor bytes and enumerates entries; workspace setup reads manifests and one list command skips dependencies.
-   * @evidence contracts/performance.md#reuse-equivalent-work All entries share one prepared context; optional readers are scoped to one load and the same selected tool/effective environment.
+   * @evidence contracts/performance.md#reuse-equivalent-work All entries share one prepared context; optional readers are scoped to one load and the same selected tool/effective environment. A supplied record store answers an equal selection without copying or running Go, under the content identity of the module, contributors, overlays, proposal manifests, toolchain/environment digest, Go variables, entries and command; an answer is recorded only when the copies matched their keyed digests, no package reported an error and the overlays still held their digests after Go ran.
    * @evidence contracts/performance.md#bound-retention-and-release-resources Finally releases owned scratch through retirement authority; unknown native closure defers removal and capture cleanup remains delegated.
    */
   export function inspect(opts: {
@@ -78,6 +113,18 @@ export namespace NativeSourcePackages {
     packages: readonly { entry: string; source?: string; name?: string }[];
     readers?: Map<string, SourcePluginWorkspace.GoModReader>;
     proposal?: boolean;
+
+    /**
+     * Record store under which an equal selection is answered without Go
+     * (#1721); without it every load runs the full observation.
+     */
+    identities?: PluginContentIdentities.Store;
+
+    /**
+     * The load's source and environment readings, shared with its builds so one
+     * load reads each directory and each module's toolchain once.
+     */
+    readings?: SelectionReadings;
   }): Package[] {
     const env = SidecarEnvironment.merge(opts.env ?? process.env);
     const { moduleRoot } = resolvePluginGoModule(opts.source, opts.pluginName);
@@ -88,6 +135,22 @@ export namespace NativeSourcePackages {
       moduleRoot,
     );
     ensureExecutableGoToolchain(goBinary, compiler.bundled);
+    // WARNING (#1721): never drop this lookup or narrow its identity. Without
+    // it every warm launch and every unplugin generation copied the module
+    // twice and ran `go list` twice (6 s+ on Windows) to rediscover an answer
+    // its unchanged inputs already determined.
+    const identity =
+      opts.identities === undefined
+        ? undefined
+        : selectionIdentity(opts, moduleRoot, goBinary, env, opts.identities);
+    if (identity !== undefined) {
+      const recalled = recallSelection(
+        PluginLoadAnswers.read(opts.identities, SELECTION_ANSWER, identity),
+        moduleRoot,
+        opts.packages.length,
+      );
+      if (recalled !== undefined) return recalled;
+    }
     const scratch = createCanonicalTempDirectory("ttsc-package-selection-");
     let taskFailure: { error: unknown } | undefined;
     try {
@@ -96,10 +159,19 @@ export namespace NativeSourcePackages {
         retainedPaths: [scratch],
       });
       SourcePluginWorkspace.materialize(moduleRoot, scratch);
+      // An answer is recorded only for the copy its identity describes: a
+      // module edited between the identity reading and the copy observed
+      // other bytes than the key names.
+      let copiesKeyed =
+        identity === undefined ||
+        pluginSourceDigest(scratch) === identity.module;
       if (opts.proposal === true) {
         // Only root manifests change. Relative Go inputs retain the source
         // module layout, while its irrelevant graph/toolchain stays inactive.
-        const hostModule = resolvePluginGoModule(genericHostSource(), opts.pluginName).moduleRoot;
+        const hostModule = resolvePluginGoModule(
+          genericHostSource(),
+          opts.pluginName,
+        ).moduleRoot;
         for (const name of ["go.mod", "go.sum"]) {
           const manifest = path.join(hostModule, name);
           const target = path.join(scratch, name);
@@ -110,19 +182,33 @@ export namespace NativeSourcePackages {
       for (const input of opts.packages) {
         if (input.source === undefined) continue;
         const contributor = { source: input.source, name: input.name! };
-        SourcePluginAdmission.requireContributorPackage(opts.pluginName, contributor);
+        SourcePluginAdmission.requireContributorPackage(
+          opts.pluginName,
+          contributor,
+        );
         const target = path.resolve(scratch, input.entry);
-        if (path.relative(scratch, target).startsWith("..") || target === scratch)
+        if (
+          path.relative(scratch, target).startsWith("..") ||
+          target === scratch
+        )
           throw new Error("ttsc: invalid package selection target");
         if (fs.existsSync(target))
-          throw new Error(`ttsc: package selection target already exists: ${target}`);
+          throw new Error(
+            `ttsc: package selection target already exists: ${target}`,
+          );
         SourcePluginWorkspace.materialize(input.source, target);
+        if (identity !== undefined)
+          copiesKeyed &&=
+            pluginSourceDigest(target) ===
+            identity.entries.find((entry) => entry[0] === input.entry)?.[2];
       }
-      let reader = opts.readers?.get(goBinary);
-      if (reader === undefined) {
-        reader = SourcePluginWorkspace.createGoModReader(goBinary, opts.pluginName, env);
-        opts.readers?.set(goBinary, reader);
-      }
+      const reader = SourcePluginWorkspace.createGoModReader(
+        goBinary,
+        opts.pluginName,
+        env,
+        opts.readers,
+        opts.identities,
+      );
       SourcePluginWorkspace.writeGoWork(
         scratch,
         SourcePluginWorkspace.findTtscOverlayDirs(),
@@ -131,20 +217,44 @@ export namespace NativeSourcePackages {
         env,
         reader,
       );
-      return read({
+      const observed = read({
         cwd: scratch,
         entries: opts.packages.map((input) => input.entry),
         env: GoSourceInputs.goBuildEnv(goBinary, undefined, env),
         goBinary,
         pluginName: opts.pluginName,
       });
+      if (
+        identity !== undefined &&
+        copiesKeyed &&
+        observed.every((input) => input.Error === undefined) &&
+        JSON.stringify(overlayDigests(opts.identities)) ===
+          JSON.stringify(identity.overlays)
+      )
+        PluginLoadAnswers.write(
+          opts.identities,
+          SELECTION_ANSWER,
+          identity,
+          observed.map((input) => ({
+            ...input,
+            Dir:
+              input.Dir === undefined
+                ? undefined
+                : path.relative(scratch, input.Dir),
+          })),
+        );
+      return observed;
     } catch (error) {
       taskFailure = { error };
       throw error;
     } finally {
-      SourceNativeRetirement.releaseResource(scratch, () => {
-        fs.rmSync(scratch, { recursive: true, force: true });
-      }, taskFailure);
+      SourceNativeRetirement.releaseResource(
+        scratch,
+        () => {
+          fs.rmSync(scratch, { recursive: true, force: true });
+        },
+        taskFailure,
+      );
     }
   }
 
@@ -157,13 +267,15 @@ export namespace NativeSourcePackages {
    * @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 module roots retain their selected spelling, without blanket case folding.
    * @evidence contracts/performance.md#efficient-algorithms One grouping pass plus contextual copies and metadata work for each distinct module; output storage scales with input population.
-   * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries in a module share one list; overlay module observations share the load's selected-tool readers, without global metadata caching.
+   * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries in a module share one list; overlay module observations share the load's selected-tool readers, and the load's readings and record store reach each contextual observation so equal selections are answered from their content identity.
    * @evidence contracts/performance.md#bound-retention-and-release-resources Grouping/maps/results live for this call/load; scratch and native captures remain with inspect/read.
    */
   export function ownPackages(
     inputs: readonly { source: string; label: string }[],
     env: NodeJS.ProcessEnv,
     readers = new Map<string, SourcePluginWorkspace.GoModReader>(),
+    identities?: PluginContentIdentities.Store,
+    readings?: SelectionReadings,
   ): Package[] {
     const groups = new Map<string, Array<{ index: number; entry: string }>>();
     inputs.forEach((input, index) => {
@@ -180,9 +292,13 @@ export namespace NativeSourcePackages {
         pluginName: first.label,
         env,
         readers,
+        identities,
+        readings,
         packages: group.map(({ entry }) => ({ entry })),
       });
-      group.forEach(({ index }, offset) => { output[index] = observations[offset]!; });
+      group.forEach(({ index }, offset) => {
+        output[index] = observations[offset]!;
+      });
     }
     return output;
   }
@@ -190,11 +306,11 @@ export namespace NativeSourcePackages {
   /**
    * Propose ownership with the candidate-selected tool before final admission.
    *
-   * Nested transform sources retain their admitted source-module layout but
-   * use unchanged generic host root manifests in scratch. Their outer module
-   * graph and toolchain are not source-only build authority. Module-root and
-   * check sources retain their actual owning module. Executable proposals must
-   * agree in the actual own module; linked proposals in each chosen actual host.
+   * Nested transform sources retain their admitted source-module layout but use
+   * unchanged generic host root manifests in scratch. Their outer module graph
+   * and toolchain are not source-only build authority. Module-root and check
+   * sources retain their actual owning module. Executable proposals must agree
+   * in the actual own module; linked proposals in each chosen actual host.
    *
    * @evidence contracts/common.md#principled-implementation Candidate tool selection occurs at the original owning module and effective environment; only prospective nested source-only manifests change in owned scratch before Go interprets the normal generated workspace.
    * @evidence contracts/common.md#clear-and-simple-design One grouping pass shares each module/proposal context and returns whether actual own-module observation already occurred.
@@ -202,15 +318,20 @@ export namespace NativeSourcePackages {
    * @evidence contracts/common.md#meaningful-documentation Native prose states deterministic proposal authority and mandatory final ownership confirmation.
    * @evidence contracts/portability.md#os-neutral-implementation Native module/tool/environment owners preserve candidate-relative tool and source layout identity.
    * @evidence contracts/performance.md#efficient-algorithms Groups inputs by module and actual/prospective mode, copies each admitted module once per context, and batches entries through Go metadata; retained work scales with source bytes and distinct contexts.
-   * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries share one observation and per-load manifest readers; no result crosses a load or changed context.
+   * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries share one observation and per-load manifest readers; a result crosses loads only through the record store's content identity, so a changed context observes Go again.
    * @evidence contracts/performance.md#bound-retention-and-release-resources Group records live for this call; scratch/process cleanup remains with inspect and no independent output byte cap is imposed.
    */
   export function propose(
     inputs: readonly { source: string; label: string; ownModule?: boolean }[],
     env: NodeJS.ProcessEnv,
     readers = new Map<string, SourcePluginWorkspace.GoModReader>(),
+    identities?: PluginContentIdentities.Store,
+    readings?: SelectionReadings,
   ): Array<{ observation: Package; ownModule: boolean }> {
-    const groups = new Map<string, Array<{ index: number; entry: string; ownModule: boolean }>>();
+    const groups = new Map<
+      string,
+      Array<{ index: number; entry: string; ownModule: boolean }>
+    >();
     inputs.forEach((input, index) => {
       const target = resolvePluginGoModule(input.source, input.label);
       const ownModule = input.ownModule === true || target.entry === ".";
@@ -219,11 +340,17 @@ export namespace NativeSourcePackages {
       group.push({ index, entry: target.entry, ownModule });
       groups.set(key, group);
     });
-    const output: Array<{ observation: Package; ownModule: boolean }> = new Array(inputs.length);
+    const output: Array<{ observation: Package; ownModule: boolean }> =
+      new Array(inputs.length);
     for (const group of groups.values()) {
       const first = inputs[group[0]!.index]!;
       const observations = inspect({
-        source: first.source, pluginName: first.label, env, readers,
+        source: first.source,
+        pluginName: first.label,
+        env,
+        readers,
+        identities,
+        readings,
         proposal: !group[0]!.ownModule,
         packages: group.map(({ entry }) => ({ entry })),
       });
@@ -258,21 +385,38 @@ export namespace NativeSourcePackages {
     OwnedSynchronousProcess.checkpoint();
     const result = spawnGoTool(
       opts.goBinary,
-      ["list", ...GoSourceInputs.BUILD_FLAGS, "-find", "-e", "-json=Dir,Name,GoFiles,CgoFiles,Error", ...entries],
+      [
+        "list",
+        ...GoSourceInputs.BUILD_FLAGS,
+        "-find",
+        "-e",
+        "-json=Dir,Name,GoFiles,CgoFiles,Error",
+        ...entries,
+      ],
       { cwd: opts.cwd, encoding: "utf8", env: opts.env, windowsHide: true },
     );
     OwnedSynchronousProcess.checkpoint();
     if (result.error !== undefined)
-      throw new Error(SourcePluginWorkspace.goSpawnFailureMessage(
-        `selecting Go packages for plugin "${opts.pluginName}"`,
-        opts.pluginName, opts.goBinary, opts.cwd, result.error,
-      ));
+      throw new Error(
+        SourcePluginWorkspace.goSpawnFailureMessage(
+          `selecting Go packages for plugin "${opts.pluginName}"`,
+          opts.pluginName,
+          opts.goBinary,
+          opts.cwd,
+          result.error,
+        ),
+      );
     if (result.status !== 0)
-      throw new Error(`ttsc: selecting Go packages for plugin "${opts.pluginName}" failed:\n${result.stderr || result.stdout}`);
+      throw new Error(
+        `ttsc: selecting Go packages for plugin "${opts.pluginName}" failed:\n${result.stderr || result.stdout}`,
+      );
     const packages = parse(result.stdout);
-    const selected = new Map(packages.map((input) => [
-      input.Dir === undefined ? undefined : fs.realpathSync.native(input.Dir), input,
-    ]));
+    const selected = new Map(
+      packages.map((input) => [
+        input.Dir === undefined ? undefined : fs.realpathSync.native(input.Dir),
+        input,
+      ]),
+    );
     return opts.entries.map((entry) => {
       const dir = fs.realpathSync.native(path.resolve(opts.cwd, entry));
       const input = selected.get(dir);
@@ -300,12 +444,21 @@ export namespace NativeSourcePackages {
     expected?: "executable" | "linked",
   ): "executable" | "linked" {
     if (input.Error !== undefined)
-      throw new Error(`ttsc: plugin "${label}" Go package selection failed: ${input.Error.Err}`);
-    if (input.Name === undefined || (input.GoFiles?.length ?? 0) + (input.CgoFiles?.length ?? 0) === 0)
-      throw new Error(`ttsc: plugin "${label}" source has no Go-selected production files: ${input.Dir ?? "unknown package"}`);
+      throw new Error(
+        `ttsc: plugin "${label}" Go package selection failed: ${input.Error.Err}`,
+      );
+    if (
+      input.Name === undefined ||
+      (input.GoFiles?.length ?? 0) + (input.CgoFiles?.length ?? 0) === 0
+    )
+      throw new Error(
+        `ttsc: plugin "${label}" source has no Go-selected production files: ${input.Dir ?? "unknown package"}`,
+      );
     const actual = input.Name === "main" ? "executable" : "linked";
     if (expected !== undefined && actual !== expected)
-      throw new Error(`ttsc: plugin "${label}" Go package ownership disagrees with its proposal: selected ${actual}, expected ${expected} (${input.Dir ?? "unknown package"})`);
+      throw new Error(
+        `ttsc: plugin "${label}" Go package ownership disagrees with its proposal: selected ${actual}, expected ${expected} (${input.Dir ?? "unknown package"})`,
+      );
     return actual;
   }
 
@@ -331,7 +484,8 @@ export namespace NativeSourcePackages {
       const token = output[offset]!;
       if (start < 0) {
         if (/\s/.test(token)) continue;
-        if (token !== "{") throw new Error("ttsc: invalid Go package metadata stream");
+        if (token !== "{")
+          throw new Error("ttsc: invalid Go package metadata stream");
         start = offset;
         depth = 1;
         continue;
@@ -347,17 +501,25 @@ export namespace NativeSourcePackages {
         if (typeof input !== "object" || input === null || Array.isArray(input))
           throw new Error("ttsc: invalid Go package metadata object");
         const record = input as Package;
-        if ((record.Dir !== undefined && typeof record.Dir !== "string") ||
-            (record.Name !== undefined && typeof record.Name !== "string") ||
-            [record.GoFiles, record.CgoFiles].some((files) => files !== undefined &&
-              (!Array.isArray(files) || files.some((file) => typeof file !== "string"))) ||
-            (record.Error !== undefined && (record.Error === null || typeof record.Error.Err !== "string")))
+        if (
+          (record.Dir !== undefined && typeof record.Dir !== "string") ||
+          (record.Name !== undefined && typeof record.Name !== "string") ||
+          [record.GoFiles, record.CgoFiles].some(
+            (files) =>
+              files !== undefined &&
+              (!Array.isArray(files) ||
+                files.some((file) => typeof file !== "string")),
+          ) ||
+          (record.Error !== undefined &&
+            (record.Error === null || typeof record.Error.Err !== "string"))
+        )
           throw new Error("ttsc: invalid Go package metadata fields");
         packages.push(record);
         start = -1;
       }
     }
-    if (start >= 0) throw new Error("ttsc: incomplete Go package metadata stream");
+    if (start >= 0)
+      throw new Error("ttsc: incomplete Go package metadata stream");
     return packages;
   }
 }
@@ -366,3 +528,158 @@ export namespace NativeSourcePackages {
 function genericHostSource(): string {
   return path.resolve(__dirname, "../../../..", "cmd/utility-host");
 }
+
+/** Answer family of package selections (`PluginLoadAnswers`). */
+const SELECTION_ANSWER = "go-package-selection";
+
+/** Fields `read` asks Go for; part of the selection identity. */
+const SELECTION_FIELDS = "-json=Dir,Name,GoFiles,CgoFiles,Error";
+
+/**
+ * Everything a package selection's answer depends on, by content: the copied
+ * module, each contributor copied into it, every ttsc overlay the generated
+ * workspace uses, the generic host manifests a proposal substitutes, the
+ * toolchain and build environment Go reads, every `GO*`/`CGO_*` variable the
+ * `go list` process receives, the entries and the fixed command. Paths stay
+ * out, so equal content in another location shares the answer, as the binary
+ * key does.
+ */
+interface ISelectionIdentity {
+  format: 1;
+  command: readonly string[];
+  mode: "proposal" | "actual";
+  module: string;
+  environment: string;
+  variables: [string, string][];
+  manifests: (string | null)[] | null;
+  overlays: string[];
+  entries: [string, string | null, string | null][];
+}
+
+function selectionIdentity(
+  opts: Parameters<typeof NativeSourcePackages.inspect>[0],
+  moduleRoot: string,
+  goBinary: string,
+  env: NodeJS.ProcessEnv,
+  identities: PluginContentIdentities.Store,
+): ISelectionIdentity | undefined {
+  try {
+    const readings = opts.readings ?? {};
+    const directory = (root: string): string => {
+      const resolved = path.resolve(root);
+      let digest = readings.sources?.get(resolved);
+      if (digest === undefined) {
+        digest = PluginContentIdentities.sourceDirectory(identities, resolved);
+        readings.sources?.set(resolved, digest);
+      }
+      return digest;
+    };
+    const resolvedRoot = path.resolve(moduleRoot);
+    let environment = readings.environments?.get(resolvedRoot);
+    if (environment === undefined) {
+      const hash = crypto.createHash("sha256");
+      const witness: PluginBuildEnvironmentWitness.Record = new Map();
+      hashPluginBuildEnvironment(
+        hash,
+        goBinary,
+        moduleRoot,
+        env,
+        { readFile: (location) => fs.readFileSync(location) },
+        witness,
+        identities,
+      );
+      environment = hash.digest("hex");
+      readings.environments?.set(resolvedRoot, environment);
+      readings.witnesses?.set(resolvedRoot, witness);
+    }
+    const host =
+      opts.proposal === true
+        ? resolvePluginGoModule(genericHostSource(), opts.pluginName).moduleRoot
+        : undefined;
+    return {
+      format: 1,
+      command: [
+        "list",
+        ...GoSourceInputs.BUILD_FLAGS,
+        "-find",
+        "-e",
+        SELECTION_FIELDS,
+      ],
+      mode: opts.proposal === true ? "proposal" : "actual",
+      module: directory(moduleRoot),
+      environment,
+      variables: 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)),
+      manifests:
+        host === undefined
+          ? null
+          : ["go.mod", "go.sum"].map((name) =>
+              fileDigest(path.join(host, name)),
+            ),
+      overlays: SourcePluginWorkspace.findTtscOverlayDirs().map(directory),
+      entries: opts.packages.map((input) => [
+        input.entry,
+        input.name ?? null,
+        input.source === undefined ? null : directory(input.source),
+      ]),
+    };
+  } catch {
+    // An identity that cannot be formed only costs the real observation.
+    return undefined;
+  }
+}
+
+/** The digest of every overlay module, in the generated workspace's order. */
+function overlayDigests(
+  identities: PluginContentIdentities.Store | undefined,
+): string[] {
+  return SourcePluginWorkspace.findTtscOverlayDirs().map((directory) =>
+    PluginContentIdentities.sourceDirectory(identities, directory),
+  );
+}
+
+/** A small manifest's content digest, or null when it does not exist. */
+function fileDigest(file: string): string | null {
+  try {
+    return crypto
+      .createHash("sha256")
+      .update(fs.readFileSync(file))
+      .digest("hex");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * A recorded selection rebased onto the module it now describes, or `undefined`
+ * when the record does not have the shape `read` produces.
+ */
+function recallSelection(
+  value: unknown,
+  moduleRoot: string,
+  count: number,
+): NativeSourcePackages.Package[] | undefined {
+  if (!Array.isArray(value) || value.length !== count) return undefined;
+  try {
+    const packages = NativeSourcePackages.parse(
+      value.map((input) => JSON.stringify(input)).join("\n"),
+    );
+    if (packages.length !== count) return undefined;
+    return packages.map((input) => ({
+      ...input,
+      Dir:
+        input.Dir === undefined
+          ? undefined
+          : path.resolve(moduleRoot, input.Dir),
+    }));
+  } catch {
+    return undefined;
+  }
+}