ttsc 0.34.3 → 0.36.0

package/src/compiler/internal/build/RuntimeInputProof.ts

@@ -0,0 +1,346 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ITtscCompilerTransformation } from "../../../structures/ITtscCompilerTransformation";
+import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
+
+/**
+ * Replay the compiler and native input witnesses of a completed runtime build.
+ * Read predicates keep their original text or raw-byte codec; absence, entry
+ * kind, physical target and directory membership remain independent predicates.
+ * Failed or unsupported observations withhold reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation Replay compares generation witnesses with current existence, stat, decoded text, physical identity and directory membership. Native version-one file, optional-file, entry and directory codecs use explicit tags, raw file/link bytes and sorted nul-delimited records. Compiler text strips UTF-8 BOM or decodes even UTF-16LE/BE bytes before SHA-256; host directory presence uses its separate domain marker.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace separates result admission, declared host inputs, compiler predicates and the native version-one codec. Private physical/absence and SHA-256 helpers serve the codecs without merging their meanings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown codecs, failed reads and producer proof failures decline admission. Only ENOENT/ENOTDIR prove absence; other physical-resolution errors remain unavailable. Following stat classifies compiler views while lstat retains native link kinds; only the producer private output subtree is excluded.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies generation proof, codec ownership and refusal semantics; private helper comments identify query, byte, decoded-text and null/error boundaries.
+ * @evidence contracts/portability.md#os-neutral-implementation Native stat, lstat and realpath retain actual kinds, targets and spellings without case assumptions. POSIX directory names/link targets stay raw bytes, Windows names follow the producer UTF-8 codec, and compiler directory entries sort by UTF-8 bytes.
+ * @evidence contracts/performance.md#efficient-algorithms Replay visits recorded predicates and their bytes or immediate directory entries rather than unrelated trees. Hashing and BOM decoding cost O(bytes), including a big-endian copy; directory codecs cost O(N log N) sorting plus encoded bytes and link queries. Physical resolution follows native path/link traversal.
+ * @evidence contracts/performance.md#reuse-equivalent-work Every retained predicate is observed anew to authorize completed-result reuse. Host capture and admission share the producer codec; no path memo, watcher silence or historical hash independently grants authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Read buffers, decoded text, paths and sorted directory members are call-local and have no proof-reader byte or entry cap. Synchronous calls retain no handle, watcher, process or historical population; only returned proof values escape.
+ */
+export namespace RuntimeInputProof {
+  /**
+   * Validate result-level host witnesses and every reported compiler predicate.
+   * The caller independently proves the selected compiler, project membership
+   * and plugin selection; an absent graph alone grants no completeness.
+   *
+   * @evidence contracts/common.md#principled-implementation Explicit incomplete observations and any graph failure reject reuse; host paths require both content and physical witnesses, and rich compiler predicates are replayed under their own codec.
+   * @evidence contracts/common.md#clear-and-simple-design One admission pass delegates individual compiler observations and native codecs.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing witness fields never become an empty successful observation, and only the caller-owned private output subtree is excluded.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies result admission and the caller's separate completeness obligations.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path resolution anchors producer-relative graph keys, and current physical paths come from native realpath.
+   * @evidence contracts/performance.md#efficient-algorithms Input and predicate populations drive replay; each read hashes its actual bytes and directories sort immediate entry records.
+   * @evidence contracts/performance.md#reuse-equivalent-work Generation witnesses, rather than an identity-key match, decide whether a completed build remains reusable.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary path and predicate records are invocation-owned without retained handles or history.
+   */
+  export function holds(
+    result: TtscBuildResult,
+    projectRoot: string,
+    emitDir: string,
+  ): boolean {
+    if (
+      result.observationsComplete === false ||
+      Object.keys(result.graph?.inputProofFailures ?? {}).length !== 0
+    )
+      return false;
+    try {
+      for (const file of result.hostInputs ?? []) {
+        const [currentPhysical, hash] = observeHostInput(file);
+        if (
+          !Object.hasOwn(result.hostInputHashes ?? {}, file) ||
+          !Object.hasOwn(result.hostInputRealpaths ?? {}, file) ||
+          currentPhysical !== result.hostInputRealpaths![file] ||
+          hash !== result.hostInputHashes![file]
+        )
+          return false;
+      }
+      const graph = result.graph;
+      for (const [name, observed] of Object.entries(
+        graph?.inputObservations ?? {},
+      )) {
+        const file = path.resolve(projectRoot, name);
+        const relative = path.relative(emitDir, file);
+        if (
+          relative === "" ||
+          (!path.isAbsolute(relative) &&
+            relative !== ".." &&
+            !relative.startsWith(".." + path.sep))
+        )
+          continue;
+        if (!observationHolds(file, observed)) return false;
+      }
+      for (const [name, expected] of Object.entries(graph?.inputHashes ?? {})) {
+        if (Object.hasOwn(graph?.inputObservations ?? {}, name)) continue;
+        const file = path.resolve(projectRoot, name);
+        if (physical(file) !== graph?.inputRealpaths?.[name]) return false;
+        let current: string | null = null;
+        try {
+          if (fs.statSync(file).isFile())
+            current = textHash(fs.readFileSync(file));
+        } catch (error) {
+          if (!missing(error)) return false;
+        }
+        if (current !== expected) return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Observe a declared host input under its existing raw-file or directory-kind
+   * codec. Descriptor resolution can declare directories as presence inputs;
+   * those are distinct from compiler source reads and directory enumeration.
+   * Native identity and metadata bracket the observation. Missing paths carry
+   * null witnesses, while unavailable or changing observations throw.
+   *
+   * @evidence contracts/common.md#principled-implementation Raw file bytes and the existing ttsc:host-input:directory domain marker reproduce the descriptor/native host-input contract, with physical identity and full native metadata checked before and after.
+   * @evidence contracts/common.md#clear-and-simple-design One observer supplies the same declared-host codec to input capture and retained-result admission, independently of compiler text and enumeration predicates.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only ENOENT/ENOTDIR establish absence; unsupported entry kinds, read failures and changing witnesses refuse reuse instead of becoming empty content.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes directory presence from directory membership, states the producer codec and explains failure semantics.
+   * @evidence contracts/portability.md#os-neutral-implementation Native following stat, realpath and byte reads retain actual host links and physical spellings without OS-name or separator guesses.
+   * @evidence contracts/performance.md#efficient-algorithms File observations hash their complete byte buffer and bracket native metadata; directory presence hashes a fixed marker without scanning members.
+   * @evidence contracts/performance.md#reuse-equivalent-work Capture and admission share the producer's codec, but every invocation observes current witnesses and retains no path-only truth.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Read buffers and stat records are call-local; synchronous filesystem calls leave no retained handle or watcher.
+   */
+  export function observeHostInput(
+    file: string,
+  ): readonly [string | null, string | null] {
+    const beforePhysical = physical(file);
+    let before: fs.BigIntStats;
+    try {
+      before = fs.statSync(file, { bigint: true });
+    } catch (error) {
+      if (!missing(error)) throw error;
+      if (beforePhysical !== null || physical(file) !== null)
+        throw new Error("Host input changed during absence observation.");
+      return [null, null];
+    }
+    if (!before.isFile() && !before.isDirectory())
+      throw new Error("Unsupported runtime host input kind.");
+    const hash = before.isDirectory()
+      ? digest("ttsc:host-input:directory\0")
+      : digest(fs.readFileSync(file));
+    const after = fs.statSync(file, { bigint: true });
+    const signature = (stat: fs.BigIntStats): string =>
+      [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+    if (
+      signature(before) !== signature(after) ||
+      beforePhysical !== physical(file)
+    )
+      throw new Error("Host input changed during observation.");
+    return [beforePhysical, hash];
+  }
+
+  /** Compare one compiler query record with the corresponding current queries. */
+  function observationHolds(
+    file: string,
+    observed: ITtscCompilerTransformation.IInputObservation,
+  ): boolean {
+    for (const predicate of observed.nativePredicates ?? [])
+      if (
+        predicate.version !== 1 ||
+        !predicate.identityStable ||
+        physical(file) !== predicate.realpath ||
+        nativeDigest(file, predicate.kind) !== predicate.digest
+      )
+        return false;
+    let kind: "file" | "directory" | "missing" = "missing";
+    try {
+      const stat = fs.statSync(file);
+      kind = stat.isDirectory() ? "directory" : "file";
+    } catch (error) {
+      if (!missing(error)) return false;
+    }
+    if (
+      observed.fileExists !== undefined &&
+      observed.fileExists !== (kind === "file")
+    )
+      return false;
+    if (
+      observed.directoryExists !== undefined &&
+      observed.directoryExists !== (kind === "directory")
+    )
+      return false;
+    if (observed.stat !== undefined && observed.stat !== kind) return false;
+    if (observed.readFile !== undefined) {
+      let hash: string | null = null;
+      try {
+        if (kind !== "directory") hash = textHash(fs.readFileSync(file));
+      } catch {
+        /* Compiler read failed. */
+      }
+      if (
+        observed.readFile.ok ? hash !== observed.readFile.hash : hash !== null
+      )
+        return false;
+    }
+    if (observed.realpath !== undefined) {
+      const current = physical(file);
+      if (
+        observed.realpath.ok
+          ? current !== observed.realpath.path
+          : current !== null
+      )
+        return false;
+    }
+    if (observed.accessibleEntries !== undefined) {
+      const directories: string[] = [];
+      const files: string[] = [];
+      let entries: fs.Dirent[] = [];
+      try {
+        entries = fs.readdirSync(file, { withFileTypes: true });
+      } catch {
+        /* Compiler enumeration returns an empty view. */
+      }
+      for (const entry of entries) {
+        try {
+          const stat = entry.isSymbolicLink()
+            ? fs.statSync(path.join(file, entry.name))
+            : entry;
+          if (stat.isDirectory()) directories.push(entry.name);
+          else if (stat.isFile()) files.push(entry.name);
+        } catch {
+          /* Compiler enumeration omits inaccessible link targets. */
+        }
+      }
+      const compare = (a: string, b: string): number =>
+        Buffer.compare(Buffer.from(a), Buffer.from(b));
+      if (
+        JSON.stringify({
+          directories: directories.sort(compare),
+          files: files.sort(compare),
+        }) !== JSON.stringify(observed.accessibleEntries)
+      )
+        return false;
+    }
+    return true;
+  }
+
+  /**
+   * Reproduce native version-one file, optional-file, entry and directory
+   * bytes.
+   */
+  function nativeDigest(file: string, kind: string): string {
+    if (kind === "file") return digest(fs.readFileSync(file));
+    if (kind === "optional-file") {
+      try {
+        return fs.statSync(file).isFile()
+          ? digest(
+              Buffer.concat([Buffer.from("file\0"), fs.readFileSync(file)]),
+            )
+          : digest("missing\0");
+      } catch (error) {
+        if (missing(error)) return digest("missing\0");
+        throw error;
+      }
+    }
+    if (kind === "entry") {
+      try {
+        const entry = fs.lstatSync(file);
+        return entry.isSymbolicLink()
+          ? digest(
+              Buffer.concat([
+                Buffer.from("symlink\0"),
+                fs.readlinkSync(file, { encoding: "buffer" }),
+              ]),
+            )
+          : digest(
+              (entry.isDirectory()
+                ? "directory"
+                : entry.isFile()
+                  ? "file"
+                  : "other") + "\0",
+            );
+      } catch (error) {
+        if (missing(error)) return digest("missing\0");
+        throw error;
+      }
+    }
+    if (kind !== "directory") throw new Error("unsupported native input codec");
+    const records: Buffer[] = [];
+    const names =
+      process.platform === "win32"
+        ? fs.readdirSync(file).map((name) => Buffer.from(name))
+        : fs.readdirSync(file, { encoding: "buffer" });
+    for (const name of names) {
+      const target =
+        process.platform === "win32"
+          ? path.join(file, name.toString())
+          : Buffer.concat([Buffer.from(file + path.sep), name]);
+      const entry = fs.lstatSync(target);
+      const entryKind = entry.isDirectory()
+        ? "directory"
+        : entry.isFile()
+          ? "file"
+          : entry.isSymbolicLink()
+            ? "symlink"
+            : "other";
+      const link = entry.isSymbolicLink()
+        ? fs.readlinkSync(target, { encoding: "buffer" })
+        : Buffer.alloc(0);
+      records.push(
+        Buffer.concat([name, Buffer.from("\0" + entryKind + "\0"), link]),
+      );
+    }
+    records.sort(Buffer.compare);
+    return digest(
+      Buffer.concat(
+        records.flatMap((record, index) =>
+          index === 0 ? [record] : [Buffer.from([0]), record],
+        ),
+      ),
+    );
+  }
+
+  /** Hash compiler-decoded text, retaining the BOM and UTF-16 producer policy. */
+  function textHash(bytes: Buffer): string {
+    if (
+      bytes.length >= 2 &&
+      ((bytes[0] === 0xff && bytes[1] === 0xfe) ||
+        (bytes[0] === 0xfe && bytes[1] === 0xff))
+    ) {
+      const text = Buffer.from(
+        bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2),
+      );
+      if (bytes[0] === 0xfe) text.swap16();
+      return digest(Buffer.from(text.toString("utf16le"), "utf8"));
+    }
+    return digest(
+      bytes.length >= 3 &&
+        bytes[0] === 0xef &&
+        bytes[1] === 0xbb &&
+        bytes[2] === 0xbf
+        ? bytes.subarray(3)
+        : bytes,
+    );
+  }
+
+  /** Obtain a current physical coordinate, with null only for native absence. */
+  function physical(file: string): string | null {
+    try {
+      return fs.realpathSync.native(file);
+    } catch (error) {
+      if (missing(error)) return null;
+      throw error;
+    }
+  }
+
+  /** Classify only native absent-path errors. */
+  function missing(error: unknown): boolean {
+    return (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    );
+  }
+
+  /** SHA-256 of supplied text or raw bytes. */
+  function digest(bytes: string | Buffer): string {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+  }
+}

package/src/compiler/internal/build/TsgoArguments.ts

@@ -195,11 +195,12 @@ export namespace TsgoArguments {
   /**
    * The forwarded-tsgo payload for a native `build`/`check` emit invocation.
    *
-   * The sidecar builds its Program in-process, so the pinned `rootDir` has to
-   * travel the same channel every other tsgo option takes to it — the host flag
-   * set does not declare `--rootDir`, and `filterHostArgs` would strip it.
+   * The sidecar builds its Program in-process, so runtime source-map defaults
+   * and the pinned `rootDir` travel the same channel as other tsgo options —
+   * the host flag set does not declare `--rootDir`, and `filterHostArgs` would
+   * strip it.
    *
-   * @evidence contracts/common.md#principled-implementation The same private layout root used by direct builds is placed in the sidecar compiler-option channel, preserving declared/composite containment while avoiding a new ordinary config-directory restriction without a new host flag.
+   * @evidence contracts/common.md#principled-implementation The same private layout root and forced runtime source-map default used by direct builds precede user arguments in the sidecar compiler-option channel, preserving explicit overrides and declared/composite containment without a new host flag.
    * @evidence contracts/common.md#clear-and-simple-design Root pinning stays in one helper and general payload ordering/serialization stays in createNativeTsgoArgs.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported environment payload carries compiler options instead of injecting unknown flags into strict foreign host parsers.
    * @evidence contracts/common.md#meaningful-documentation Native prose explains why rootDir travels with compiler options rather than through the host flag set.
@@ -215,7 +216,12 @@ export namespace TsgoArguments {
   ): string | undefined {
     return createNativeTsgoArgs(
       options,
-      pinnedRootDirArgs(execution, options),
+      [
+        ...(options.forceRuntimeSourceMap === true
+          ? ["--sourceMap", "true"]
+          : []),
+        ...pinnedRootDirArgs(execution, options),
+      ],
       false,
     );
   }

package/src/compiler/internal/build/appendBuildOutput.ts

@@ -186,6 +186,10 @@ export function mergeCheckGraphs(
     observations[key] = merged;
   }
   return {
+    ...(left.compilationSnapshot !== undefined &&
+    left.compilationSnapshot === right.compilationSnapshot
+      ? { compilationSnapshot: left.compilationSnapshot }
+      : {}),
     edges: mergeLists(left.edges, right.edges),
     ...(membershipConflict ||
     (left.membership ?? right.membership) === undefined

package/src/compiler/internal/build/runBuild.ts

@@ -2,6 +2,8 @@ import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResu
 import { BuildExecution } from "./BuildExecution";
 import { BuildTiming } from "./BuildTiming";
 import type { RunBuildOptions } from "./RunBuildOptions";
+import { RuntimeBuildCache } from "./RuntimeBuildCache";
+import { RuntimeBuildInputs } from "./RuntimeBuildInputs";
 import { WatchInputPublication } from "./WatchInputPublication";
 
 /**
@@ -21,7 +23,7 @@ import { WatchInputPublication } from "./WatchInputPublication";
  * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes returned exit failures from thrown setup/launch errors and explains the project-free branch.
  * @evidence contracts/portability.md#os-neutral-implementation Execution selection and spawning use the shared native path/process boundaries with cwd and separate argv, rather than constructing a shell command here.
  * @evidence contracts/performance.md#efficient-algorithms Timing creation and terminal selection make their own flag projections before the selected preparation/execution path. Delegated configuration, plugin, native/provenance and diagnostic work follows its actual input/report sizes; timing formatting scans ledger labels and output. No measured dominance or duration/output ceiling is established by this wrapper.
- * @evidence contracts/performance.md#reuse-equivalent-work A resolved execution context is carried through preparation and execution, so this build does not reload its plugin selection between phases.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved execution context is carried through preparation and execution without another plugin load; private runtime requests delegate verified completed-emission reuse to RuntimeBuildCache with current input and producer proofs.
  * @evidence contracts/performance.md#bound-retention-and-release-resources The ledger and execution state are build-owned, while returned output/proof/diagnostic records transfer to the caller; no resident handle or historical build is stored here. Delegated native/probe/artifact acquisition and cleanup may be best effort, and thrown setup can precede some cleanup boundaries. This wrapper supplies no duration/output bound or descendant-release certification.
  */
 export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
@@ -36,8 +38,8 @@ export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Awaiting changes only publication completion, preserves compiler/plugin selection and project-free terminal behavior, and sends publication failure through existing setup and cleanup rather than bypassing a pending baseline.
  * @evidence contracts/common.md#meaningful-documentation Entry prose states the publication barrier, order before compilation and internal callers' obligation to complete the sequence and deliver rejection.
  * @evidence contracts/portability.md#os-neutral-implementation BuildExecution retains native cwd, path identity and argument-array ownership across suspension; the namespace adds no independent native boundary.
- * @evidence contracts/performance.md#efficient-algorithms Each selected terminal, context, discovery, preparation and compile phase runs once; each publication adds one await and constant sequence state.
- * @evidence contracts/performance.md#reuse-equivalent-work One resolved execution context serves preparation and compilation without reloading plugins; the namespace retains no completed build or in-flight cache.
+ * @evidence contracts/performance.md#efficient-algorithms Each selected terminal, context, discovery and preparation phase runs once; eligible runtime requests add native source/configuration queries and content proofs before restoring or compiling. Each publication adds one await and constant sequence state.
+ * @evidence contracts/performance.md#reuse-equivalent-work One resolved execution context serves preparation and compilation without reloading plugins; the delegated runtime store reuses completed bytes only under current equal input snapshots and valid producer witnesses, with ordinary compilation on any miss.
  * @evidence contracts/performance.md#bound-retention-and-release-resources The invocation owns its sequence, ledger, context and current handoff while callbacks settle. Selected results transfer to the caller, delegated resource ownership and cleanup stay unchanged, and no resident history is retained.
  */
 export namespace runBuild {
@@ -72,14 +74,27 @@ export namespace runBuild {
       execution,
       setupStartedAt,
     );
-    const result =
-      prepared.result ??
+    const build = () =>
       BuildExecution.runPreparedBuild(
         options,
         timing,
         execution,
         prepared.buildOptions,
       );
+    const proof =
+      prepared.result === undefined
+        ? RuntimeBuildInputs.create(prepared.buildOptions, execution)
+        : undefined;
+    const result =
+      prepared.result ??
+      (proof === undefined
+        ? build()
+        : RuntimeBuildCache.run({
+            directory: options.runtimeCacheDir,
+            emitDir: options.isolateOutputsTo!,
+            ...proof,
+            build,
+          }));
     return BuildTiming.appendTimingOutput(result, timing);
   }
 }

package/src/compiler/internal/build/runExternalEmitProvenance.ts

@@ -17,17 +17,16 @@ import { PassthroughFlags } from "./PassthroughFlags";
  * diagnostics and user-requested file-list display remain owned by that run.
  *
  * Admission requires stable effective options, identical source selection and
- * stable physical paths, file identities and bytes before and after emission,
- * including response files and the selected executable itself. Response
- * inspection preserves native argument-frame boundaries and operand positions;
- * the producer and its probes receive the original argv. The executable's
- * change time is excluded from cross-command equality because that metadata
- * changed in real executions without changing the executable object or bytes;
- * source change times remain proof premises and each read brackets its full
- * metadata. This is an external observation, not an atomic compiler-generation
- * ledger; a concurrent change restored between observations can remain
- * invisible. Unsupported layouts and ambiguous outputs carry an empty ownership
- * list.
+ * stable physical source paths before and after emission, plus unchanged
+ * response files and selected executable bytes. Response inspection preserves
+ * native argument-frame boundaries and operand positions; the producer and its
+ * probes receive the original argv. The executable's change time is excluded
+ * from cross-command equality because that metadata changed in real executions
+ * without changing the executable object or bytes; source contents belong to
+ * the compiler's own Program. Each executable read brackets its full metadata.
+ * This is an external observation, not an atomic compiler-generation ledger; a
+ * concurrent change restored between observations can remain invisible.
+ * Unsupported layouts and ambiguous outputs carry an empty ownership list.
  *
  * A nonzero compiler status can still carry proved writes for an unchecked
  * consumer. Ownership metadata never changes that status or its diagnostics.
@@ -47,12 +46,12 @@ import { PassthroughFlags } from "./PassthroughFlags";
  * in emittedSourceProofFailures. These explanations preserve compiler streams
  * and status; they do not replace missing ownership with a successful claim.
  *
- * @evidence contracts/common.md#principled-implementation Actual TSFILE writes are matched against the supported upstream per-source extension and explicit-root layout under matching compiler-selected inputs and stable physical/content observations. No emitted filename alone establishes ownership; observation gaps remain documented.
+ * @evidence contracts/common.md#principled-implementation Actual TSFILE writes are matched against the supported upstream per-source extension and explicit-root layout under matching compiler-selected inputs and stable physical source identities and response/executable content observations. No emitted filename alone establishes ownership; observation gaps remain documented.
  * @evidence contracts/common.md#clear-and-simple-design One adapter owns read-only compiler probes, the single delegated emission and admission; private helpers isolate option parsing, physical observation and path prediction.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The selected executable and original arguments remain authoritative. Unknown layouts are reported unknown instead of switching compilers, guessing same-stem ownership or consulting source maps.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain producer preservation, unknown states and the non-atomic observation limitation; the investigation record documents the supported upstream naming subset.
  * @evidence contracts/portability.md#os-neutral-implementation Native node:path and filesystem realpath/stat separate writer spelling from physical source identity. Executables receive separate argv entries through spawnNative, without a shell or OS-based case folding.
- * @evidence contracts/performance.md#efficient-algorithms Source and output indexes avoid cross-product matching. Response inspection uses an iterative frame stack and active physical-path set. Repeated response/source/executable observations read and hash complete files; showConfig text, source/output lists, signature JSON, candidate path components and byte buffers are processed at their actual sizes alongside native probes/path operations. No native duration or report-size ceiling follows from using one index.
+ * @evidence contracts/performance.md#efficient-algorithms Source and output indexes avoid cross-product matching. Response inspection uses an iterative frame stack and active physical-path set. Response/executable observations read and hash complete files; source identity checks resolve paths without comparing mutable text; showConfig text, source/output lists, signature JSON, candidate path components and byte buffers are processed at their actual sizes alongside native probes/path operations. No native duration or report-size ceiling follows from using one index.
  * @evidence contracts/performance.md#reuse-equivalent-work Each source observation and predicted output index is shared by all outputs in this invocation. Cross-build reuse is unavailable because arbitrary external producer and filesystem dependencies have no invalidation contract.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Response/config/source tokens and predicted owner sets live for this invocation; returned provenance/refusal records transfer to the caller. Retained bytes grow with complete reports, expanded arguments, paths and observations, while individual file reads allocate full file buffers. Probe capture cleanup is delegated and may be best effort; no timeout, output ceiling or descendant-release certification is provided here.
  */
@@ -144,7 +143,7 @@ export function runExternalEmitProvenance(options: {
   }
 
   // An observed host lists nothing; it compiles the same selected tsconfig, and
-  // the source observations below still prove that selection held still.
+  // the source identity observations below still prove that selection retained its physical owners.
   const listed = observed
     ? probe.files
     : compilerSourceList(lines, options.cwd);
@@ -185,10 +184,10 @@ export function runExternalEmitProvenance(options: {
     for (const [source, before] of probe.observations) {
       if (!stable) break;
       stage = `source observation of ${JSON.stringify(source)}`;
-      const after = CompilerArgumentsInspection.observeInputFile(source);
+      const after = observeSourceIdentity(source);
       stable = after === before;
       if (!stable)
-        failure = `Selected source changed across emission: ${JSON.stringify(source)} (${observationDifference(before, after)}).`;
+        failure = `Selected source identity changed across emission: ${JSON.stringify(source)}.`;
     }
     for (const [file, before] of probe.responseObservations) {
       if (!stable) break;
@@ -207,9 +206,7 @@ export function runExternalEmitProvenance(options: {
         if (outputs.length === 0) continue;
         predictedSources++;
         sourceExample ??= source;
-        const physicalSource: string = JSON.parse(
-          probe.observations.get(source)!,
-        )[0];
+        const physicalSource = probe.observations.get(source)!;
         for (const output of outputs) {
           const sources = owners.get(output) ?? new Set<string>();
           sources.add(physicalSource);
@@ -368,10 +365,7 @@ function prepareProbe(
     const observations = new Map<string, string>();
     for (const source of files) {
       stage = `initial source observation of ${JSON.stringify(source)}`;
-      observations.set(
-        source,
-        CompilerArgumentsInspection.observeInputFile(source),
-      );
+      observations.set(source, observeSourceIdentity(source));
     }
     for (const [file, before] of inspected.observations)
       if (CompilerArgumentsInspection.observeInputFile(file) !== before)
@@ -644,3 +638,11 @@ function writtenJavaScript(stdout: string, cwd: string): string[] {
   }
   return [...outputs];
 }
+
+/**
+ * Source ownership is a physical path; text freshness belongs to cache
+ * admission.
+ */
+function observeSourceIdentity(source: string): string {
+  return fs.realpathSync.native(source);
+}

package/src/compiler/internal/parseNativeTransformOutput.ts

@@ -339,6 +339,7 @@ export function parseReferenceGraph(
     return undefined;
   }
   const section = value as {
+    compilationSnapshot?: unknown;
     candidates?: unknown;
     configs?: unknown;
     edges?: unknown;
@@ -420,6 +421,10 @@ export function parseReferenceGraph(
   }
   return {
     ...(Object.keys(candidates).length === 0 ? {} : { candidates }),
+    ...(typeof section.compilationSnapshot === "string" &&
+    section.compilationSnapshot.length !== 0
+      ? { compilationSnapshot: section.compilationSnapshot }
+      : {}),
     configs,
     edges,
     globals,