ttsc 0.31.0 → 0.31.2

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

@@ -3,9 +3,12 @@ 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 type { PluginContentIdentities } from "./PluginContentIdentities";
 import { SourcePluginAdmission } from "./SourcePluginAdmission";
+import { copiesPluginSourceEntry } from "./copiesPluginSourceEntry";
 import { formatGoWorkPath } from "./formatGoWorkPath";
 import { spawnGoTool } from "./spawnGoTool";
 
@@ -13,20 +16,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 +61,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 +180,7 @@ export namespace SourcePluginWorkspace {
   interface GoModInfo {
     readonly modulePath: string | null;
     readonly replacements: readonly GoModReplacement[];
+    readonly directives: NonNullable<GoModJson["Replace"]>;
   }
 
   /**
@@ -190,17 +198,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 +234,148 @@ 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. An optional record store
+   * only carries the Go environment-file discovery hint across processes; it
+   * never carries a parse.
    *
-   * @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>,
+    identities?: PluginContentIdentities.Store,
   ): 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,
+                  identities,
+                )
+              : 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 +435,7 @@ export namespace SourcePluginWorkspace {
 
     return {
       modulePath: json.Module?.Path ?? null,
+      directives: json.Replace ?? [],
       replacements: (json.Replace ?? [])
         .map(jsonReplacementToGoModReplacement)
         .filter((replacement) => replacement !== null),
@@ -322,6 +445,7 @@ export namespace SourcePluginWorkspace {
   function emptyGoModInfo(): GoModInfo {
     return {
       modulePath: null,
+      directives: [],
       replacements: [],
     };
   }
@@ -441,6 +565,5 @@ export namespace SourcePluginWorkspace {
     }
   }
 
-
   const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
 }