ttsc 0.31.0 → 0.31.1

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

@@ -17,8 +17,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.
@@ -99,7 +99,10 @@ export namespace NativeSourcePackages {
       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 +113,28 @@ 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);
       }
-      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,
+      );
       SourcePluginWorkspace.writeGoWork(
         scratch,
         SourcePluginWorkspace.findTtscOverlayDirs(),
@@ -142,9 +154,13 @@ export namespace NativeSourcePackages {
       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,
+      );
     }
   }
 
@@ -182,7 +198,9 @@ export namespace NativeSourcePackages {
         readers,
         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 +208,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.
@@ -210,7 +228,10 @@ export namespace NativeSourcePackages {
     env: NodeJS.ProcessEnv,
     readers = new Map<string, SourcePluginWorkspace.GoModReader>(),
   ): 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 +240,15 @@ 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,
         proposal: !group[0]!.ownModule,
         packages: group.map(({ entry }) => ({ entry })),
       });
@@ -258,21 +283,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 +342,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 +382,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 +399,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;
   }
 }

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

@@ -74,6 +74,48 @@ export namespace PluginBuildEnvironmentReadings {
       : undefined;
   }
 
+  /**
+   * Qualify a batch in one synchronous observation transaction. Shared SDK
+   * paths and the complete variable identity are read once, even when several
+   * plugin directories use them. Missing readings remain explicitly missing.
+   *
+   * WARNING (#1712): this map belongs only to the following synchronous proof.
+   * Never retain it across an await, delivery, build boundary or publication. A
+   * process-permanent positive witness would miss changed Go tools and GOENV
+   * files (#1516); independently checking it in every helper instead multiplies
+   * a thousands-file GOROOT scan by modules and proof layers.
+   *
+   * @evidence contracts/common.md#principled-implementation One current variable snapshot and native path observation are compared against each reading's own expected witness; conflicting expected states cannot both pass.
+   * @evidence contracts/common.md#clear-and-simple-design One batch operation owns shared validation without changing synchronous reads or native worker publication boundaries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined is retained for absent or stale authority; no positive verdict survives this explicit observation transaction.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs state scope, missing semantics and the performance/correctness regressions prevented by the lifetime restriction.
+   * @evidence contracts/portability.md#os-neutral-implementation Existing native witness keys preserve filesystem, link and ambient-variable distinctions; no platform case assumption is added.
+   * @evidence contracts/performance.md#efficient-algorithms Full variables are indexed once; each distinct witnessed path is queried once while each reading compares its own witness entries. Work is proportional to variable bytes, total witness entries and unique native dependencies rather than repeated native SDK scans.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only current native observations within this synchronous batch are shared; the returned digests do not authorize reuse after another asynchronous boundary.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The native observation map is call-local and the digest map transfers to its immediate proof caller; no handle or historical registry is acquired.
+   */
+  export function cachedAll(
+    directories: Iterable<string>,
+  ): ReadonlyMap<string, string | undefined> {
+    let variables: string | undefined;
+    const current = new Map<string, string>();
+    const result = new Map<string, string | undefined>();
+    for (const directory of directories) {
+      if (result.has(directory)) continue;
+      const known = readings.get(
+        directory + (variables ??= key("", process.env)),
+      );
+      result.set(
+        directory,
+        known !== undefined &&
+          PluginBuildEnvironmentWitness.holds(known.witness, undefined, current)
+          ? known.environment
+          : undefined,
+      );
+    }
+    return result;
+  }
+
   /**
    * Read synchronously for clients whose API owns synchronous native work.
    * Explicit refresh preserves the original fresh-comparison semantics.

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

@@ -144,7 +144,9 @@ export namespace PluginBuildEnvironmentWitness {
    * observation. The existing private opt-in trace retains the first actual
    * mismatch without repeating its lookup or changing the refusal. An optional
    * observation label separates preparation and build epochs in that trace; it
-   * does not change validation or authorize publication.
+   * does not change validation or authorize publication. A supplied native
+   * observation map belongs to one synchronous batch only; never reuse it after
+   * an await, delivery, environment mutation or publication boundary.
    *
    * @evidence contracts/common.md#principled-implementation Universal comparison requires every dependency to match its pre-read signature and immediately rejects a refused or changed path.
    * @evidence contracts/common.md#clear-and-simple-design Validation uses the same signature helper as capture, keeping identity and timestamp policy in one place.
@@ -153,16 +155,24 @@ export namespace PluginBuildEnvironmentWitness {
    * @evidence contracts/portability.md#os-neutral-implementation Validation reads actual Node metadata using the same link-following semantics as capture.
    * @evidence contracts/performance.md#efficient-algorithms Validation iterates dependencies until mismatch and performs native stat/link queries or ambient-variable serialization. Windows environment matching enumerates names and lowercases text per witnessed variable, so P alone does not bound that work. Native path/link/name/value/numeric bytes contribute cost; file content is not read and unavailable native observations share the helper's missing marker. An enabled private trace serializes the first mismatch's already-computed text through its existing bounded sink.
    *
-   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call must establish current validity; caching that answer would conceal external changes.
+   * @evidence contracts/performance.md#reuse-equivalent-work A caller-owned synchronous batch may share current native observations, comparing each witness against its own expected state; ordinary calls and all later observation phases establish new validity.
    * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation retains no handles or additional historical state.
    */
-  export function holds(witness: Record, observation?: string): boolean {
+  export function holds(
+    witness: Record,
+    observation?: string,
+    currentReadings?: Map<string, string>,
+  ): boolean {
     for (const [file, recorded] of witness) {
-      const current = file.startsWith(ENVIRONMENT_PREFIX)
-        ? environmentSignature(file.slice(ENVIRONMENT_PREFIX.length))
-        : file.startsWith(LINK_PREFIX)
-          ? linkSignature(file.slice(LINK_PREFIX.length))
-          : signature(file);
+      let current = currentReadings?.get(file);
+      if (current === undefined) {
+        current = file.startsWith(ENVIRONMENT_PREFIX)
+          ? environmentSignature(file.slice(ENVIRONMENT_PREFIX.length))
+          : file.startsWith(LINK_PREFIX)
+            ? linkSignature(file.slice(LINK_PREFIX.length))
+            : signature(file);
+        currentReadings?.set(file, current);
+      }
       if (current !== recorded) {
         E2ETrace.capabilityResolution(
           "plugin-build-environment-witness-mismatch",

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

@@ -3,9 +3,11 @@ import os from "node:os";
 import path from "node:path";
 
 import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
+import { GoEnvironmentReading } from "./GoEnvironmentReading";
 import { GoSourceInputs } from "./GoSourceInputs";
-import { copiesPluginSourceEntry } from "./copiesPluginSourceEntry";
+import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
 import { SourcePluginAdmission } from "./SourcePluginAdmission";
+import { copiesPluginSourceEntry } from "./copiesPluginSourceEntry";
 import { formatGoWorkPath } from "./formatGoWorkPath";
 import { spawnGoTool } from "./spawnGoTool";
 
@@ -13,20 +15,23 @@ import { spawnGoTool } from "./spawnGoTool";
  * Share generated Go workspace policy between package selection and building.
  *
  * Package selection must use the builder's overlays, generated workspace and
- * selected tool rather than an ancestor go.work found in a source directory.
- * A load may share installed-overlay manifest records under its pinned tool
- * and effective environment; each unique scratch is read independently. The
- * cold build owns a fresh reader over its proven materialized inputs. Go
- * supplies the workspace's required Go and toolchain directives. These reads
- * preserve the existing installation/version and sequential-stability limits.
+ * selected tool rather than an ancestor go.work found in a source directory. A
+ * load shares early replacement watch, package and build manifest records under
+ * its pinned tool and effective environment; identical current bytes in
+ * independently proven scratch inputs share their Go parse. A moved native tool
+ * clears that reader's syntax memo, and a toolchain retry starts a new reader
+ * scope. Each caller has a diagnostic view over the shared native reader state;
+ * one plugin cannot inherit another plugin's failure label (#1720). Go supplies
+ * the workspace's required Go and toolchain directives. These reads preserve
+ * the existing installation/version and sequential-stability limits.
  *
  * @evidence contracts/common.md#principled-implementation Shared manifest acquisition, managed replacement admission, overlay filtering and Go-owned workspace version selection keep metadata and compilation under the same workspace policy; callers own source materialization and effective environment.
  * @evidence contracts/common.md#clear-and-simple-design One namespace owns the generated workspace and its module reader, overlay discovery and Go launch diagnostics; no second manifest parser or build-tag interpreter is introduced.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual Go mod edit and work use commands interpret manifests; selected tool errors propagate and no static workspace version replaces Go's decision.
  * @evidence contracts/common.md#meaningful-documentation Native prose explains shared policy and caller ownership; private helpers remain part of this operation's review surface.
  * @evidence contracts/portability.md#os-neutral-implementation Native fs/path operations preserve path spelling and formatGoWorkPath owns Go syntax quoting; subprocesses use the existing native wrapper owner with hidden windows.
- * @evidence contracts/performance.md#efficient-algorithms Workspace construction scans module and replacement populations; each module reader memoizes absolute directory results within its owning load or materialized build. Overlay discovery recursively scans admitted directories and sorts paths; native Go output and JSON parsing scale with complete bytes.
- * @evidence contracts/performance.md#reuse-equivalent-work A metadata load shares equivalent installed-overlay observations under one pinned tool/effective environment; unique scratch paths are independent. A materialized build uses its own reader, and no memo crosses a load or changed environment. Metadata and build share policy rather than pretending their independently materialized sources are identical.
+ * @evidence contracts/performance.md#efficient-algorithms Workspace construction scans module and replacement populations; each reader reads current manifest bytes and memoizes equivalent Go syntax within its pinned native tool/load. Overlay discovery recursively scans admitted directories and sorts paths; native Go output and JSON parsing scale with complete bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work Metadata and materialized builds share Go parsing only for identical current manifest bytes under the same pinned tool/effective environment. Independent materialization/content proof remains with each caller; tool movement clears syntax reuse and retries start another scope.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Readers retain module records only for their enclosing load or materialized build; command capture cleanup belongs to spawnGoTool and scratch lifetime belongs to the caller. Native commands can mutate Go-owned state and their selected-child completion does not prove arbitrary descendants retired.
  */
 export namespace SourcePluginWorkspace {
@@ -55,7 +60,8 @@ export namespace SourcePluginWorkspace {
   }
 
   /**
-   * Write the native builder's generated workspace and let Go select its version.
+   * Write the native builder's generated workspace and let Go select its
+   * version.
    *
    * @evidence contracts/common.md#principled-implementation Actual manifest records drive managed overlay filtering and replacement admission; Go work use supplies required directives.
    * @evidence contracts/common.md#clear-and-simple-design The writer shares one reader across source/overlay queries and delegates manifest interpretation to Go.
@@ -173,6 +179,7 @@ export namespace SourcePluginWorkspace {
   interface GoModInfo {
     readonly modulePath: string | null;
     readonly replacements: readonly GoModReplacement[];
+    readonly directives: NonNullable<GoModJson["Replace"]>;
   }
 
   /**
@@ -190,17 +197,19 @@ export namespace SourcePluginWorkspace {
   export interface GoModReader {
     /**
      * Observe the module at this native directory within the reader context.
+     * The optional diagnostic owner overrides the creating caller's label only;
+     * it changes no selected-tool, environment or byte-content authority.
      *
      * @evidence contracts/common.md#principled-implementation The signature associates a native directory with the selected reader's Go-owned module and replacement observation.
-     * @evidence contracts/common.md#clear-and-simple-design One input and one record expose the manifest policy needed by the workspace writer.
+     * @evidence contracts/common.md#clear-and-simple-design A directory and optional diagnostic label expose manifest policy without treating the label as native cache authority.
      * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature supplies no parser, alternate selection policy or stability certificate.
-     * @evidence contracts/common.md#meaningful-documentation Native prose states that the result belongs to the reader context rather than a context-independent directory cache.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states selected-context result ownership and the optional caller label, which changes failure attribution only.
      * @evidence contracts/portability.md#os-neutral-implementation The directory is a native filesystem path; its resolution belongs to the implementing reader.
      * @evidence contracts/performance.md#efficient-algorithms A method signature executes no algorithm; createGoModReader owns acquisition and parsing.
      * @evidence contracts/performance.md#reuse-equivalent-work Implementations supply observations within their selected tool/environment scope; this signature establishes no cross-context memo.
      * @evidence contracts/performance.md#bound-retention-and-release-resources The signature acquires no resource; record retention belongs to the reader's enclosing load or materialized build.
      */
-    read(dir: string): GoModInfo;
+    read(dir: string, diagnosticPlugin?: string): GoModInfo;
   }
 
   interface GoModJson {
@@ -224,36 +233,144 @@ export namespace SourcePluginWorkspace {
   }
 
   /**
-   * Read each module once through Go within one selected-tool context.
+   * Read current manifest bytes and share identical Go parses within one pinned
+   * selected-tool/load context, including copied scratch modules. An optional
+   * registry shares native reader state from the first watch query onward; its
+   * owner must keep one fixed effective environment and discard it on retry.
+   * Caller views share that native state and syntax, while each default
+   * diagnostic label remains with its current caller.
    *
-   * @evidence contracts/common.md#principled-implementation Actual go mod edit JSON determines module/replacement identities; missing go.mod returns the existing empty module observation.
-   * @evidence contracts/common.md#clear-and-simple-design An absolute-directory map wraps one manifest acquisition helper.
+   * @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 Each distinct directory runs one existence query and at most one Go mod edit plus complete JSON parsing.
-   * @evidence contracts/performance.md#reuse-equivalent-work The caller may share this reader only within one load and the same pinned tool/effective environment; directory results are not cross-load authority.
-   * @evidence contracts/performance.md#bound-retention-and-release-resources The map grows with distinct observed directories for its caller's lifetime; process/output capture cleanup remains delegated.
+   * @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#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(
     goBinary: string,
     pluginName: string,
     env: NodeJS.ProcessEnv,
+    readers?: Map<string, GoModReader>,
   ): GoModReader {
+    const existing = readers?.get(goBinary);
+    if (existing !== undefined)
+      return {
+        read: (dir, diagnosticPlugin = pluginName) =>
+          existing.read(dir, diagnosticPlugin),
+      };
+    // WARNING (#1712): parse identical bytes once in this pinned tool/load
+    // context, including early replacement watch projection and copied scratch
+    // manifests. The optional registry belongs to one fixed effective environment
+    // and one load; it is never shared with a toolchain retry. Always read current bytes;
+    // a pathname or metadata-only memo misses manifest edits. Never promote
+    // this map to a process cache: tool/environment epochs change Go authority.
+    // Fixed variable strings do not freeze GOENV or a dispatched Go executable.
+    // Requalify their actual native evidence before every syntax hit; missing
+    // environment authority permits a fresh parse only, never positive reuse.
+    // WARNING (#1720): diagnostic names are per caller, not a syntax/cache input.
+    // Shared views must forward their current label to every failed native read.
     const cache = new Map<string, GoModInfo>();
-    return {
-      read(dir) {
+    const environment = { ...env };
+    let toolWitness: PluginBuildEnvironmentWitness.Record | undefined;
+    const reader: GoModReader = {
+      read(dir, diagnosticPlugin = pluginName) {
         OwnedSynchronousProcess.checkpoint();
         const resolved = path.resolve(dir);
-        const cached = cache.get(resolved);
+        const manifest = path.join(resolved, "go.mod");
+        let bytes: Buffer;
+        try {
+          bytes = fs.readFileSync(manifest);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT")
+            return emptyGoModInfo();
+          throw error;
+        }
+        if (
+          toolWitness === undefined ||
+          !PluginBuildEnvironmentWitness.holds(toolWitness)
+        ) {
+          cache.clear();
+          const witness: PluginBuildEnvironmentWitness.Record = new Map();
+          let launcher: fs.BigIntStats | undefined;
+          try {
+            launcher = fs.statSync(goBinary, { bigint: true });
+          } catch {
+            // Unavailable metadata cannot qualify optional syntax reuse.
+          }
+          if (launcher?.isFile() === true)
+            PluginBuildEnvironmentWitness.add(witness, goBinary, launcher);
+          // GOENV can change toolchain selection without changing env strings.
+          // Share its existing native discovery owner; do not scan GOROOT here.
+          // Do not launch a missing/unobservable tool twice just to learn that
+          // optional cache qualification is unavailable (#1712). The actual
+          // mod-edit attempt below still owns its current failure or success.
+          const observed =
+            launcher?.isFile() === true
+              ? GoEnvironmentReading.read(
+                  goBinary,
+                  os.tmpdir(),
+                  environment,
+                  ["GOROOT"],
+                  witness,
+                )
+              : undefined;
+          if (
+            typeof observed?.GOROOT === "string" &&
+            path.isAbsolute(observed.GOROOT)
+          )
+            PluginBuildEnvironmentWitness.add(
+              witness,
+              path.join(
+                observed.GOROOT,
+                "bin",
+                process.platform === "win32" ? "go.exe" : "go",
+              ),
+            );
+          const complete =
+            typeof observed?.GOROOT === "string" &&
+            path.isAbsolute(observed.GOROOT) &&
+            typeof observed.GOENV === "string" &&
+            (observed.GOENV === "off" || path.isAbsolute(observed.GOENV));
+          toolWitness =
+            complete && PluginBuildEnvironmentWitness.holds(witness)
+              ? witness
+              : undefined;
+        }
+        // UTF-8 decoding is lossy for malformed input. Only identical bytes
+        // can share Go syntax, even when Go serializes two inputs identically.
+        const byteKey = bytes.toString("base64");
+        const cached = cache.get(byteKey);
         if (cached !== undefined) {
           return cached;
         }
-        const info = readGoModInfo(resolved, goBinary, pluginName, env);
-        cache.set(resolved, info);
+        const info = readGoModInfo(
+          resolved,
+          goBinary,
+          diagnosticPlugin,
+          environment,
+        );
+        if (!fs.readFileSync(manifest).equals(bytes))
+          throw new Error(
+            `ttsc: go.mod changed while Go was reading ${manifest}`,
+          );
+        if (
+          toolWitness !== undefined &&
+          !PluginBuildEnvironmentWitness.holds(toolWitness)
+        )
+          throw new Error(
+            `ttsc: Go tool or environment changed while reading ${manifest}`,
+          );
+        // 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);
         return info;
       },
     };
+    readers?.set(goBinary, reader);
+    return reader;
   }
 
   function readGoModInfo(
@@ -313,6 +430,7 @@ export namespace SourcePluginWorkspace {
 
     return {
       modulePath: json.Module?.Path ?? null,
+      directives: json.Replace ?? [],
       replacements: (json.Replace ?? [])
         .map(jsonReplacementToGoModReplacement)
         .filter((replacement) => replacement !== null),
@@ -322,6 +440,7 @@ export namespace SourcePluginWorkspace {
   function emptyGoModInfo(): GoModInfo {
     return {
       modulePath: null,
+      directives: [],
       replacements: [],
     };
   }
@@ -441,6 +560,5 @@ export namespace SourcePluginWorkspace {
     }
   }
 
-
   const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
 }