ttsc 0.35.0 → 0.36.0

package/src/compiler/internal/CompilationSnapshot.ts

@@ -0,0 +1,97 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
+
+/**
+ * Own one read-once compiler view across sequential native stages. Its private
+ * document stores actual compiler text and lookup answers, including absence;
+ * each invocation starts empty and removes its storage after its final stage.
+ * Disk freshness remains a separate cache-admission decision.
+ *
+ * @evidence contracts/common.md#principled-implementation A unique invocation ID and versioned private document share first-read answers through the driver's supported VFS, without changing source paths or the selected compiler.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous owner brackets the sequential compiler operation and its transport cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The driver consumes real captured text; no filesystem methods or compiler internals are replaced.
+ * @evidence contracts/common.md#meaningful-documentation Prose states read-once semantics, sequential stage ownership, absence and independent freshness admission.
+ * @evidence contracts/portability.md#os-neutral-implementation Native temporary-directory creation and path APIs own transport; environment merging preserves Windows key semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Construction writes an empty document; each native stage parses prior captured text/predicates and dirty flushes encode and write the complete reached population. Normal UTF-8 remains plain text, while invalid UTF-8 is encoded losslessly and decoded once per stage.
+ * @evidence contracts/performance.md#reuse-equivalent-work Only stages of this invocation share captured answers; unrelated invocations have fresh IDs and documents.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous owner attempts identity-checked cleanup after success or failure; native captured bytes have no population cap. A failed initial identity read or cleanup can leave storage behind; cleanup failure retains the original thrown error or completed result.
+ */
+export namespace CompilationSnapshot {
+  export const ENV = "TTSC_COMPILATION_SNAPSHOT";
+
+  /**
+   * Run sequential native stages with a new invocation-owned input document.
+   * The supplied environment is copied; same-directory identity guards cleanup,
+   * and cleanup failure retains the operation error or completed result.
+   *
+   * @evidence contracts/common.md#principled-implementation A unique invocation ID and versioned private document share first-read answers through the driver's supported VFS, without changing source paths or the selected compiler.
+   * @evidence contracts/common.md#clear-and-simple-design One synchronous owner brackets the sequential compiler operation and its transport cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The driver consumes real captured text; no filesystem methods or compiler internals are replaced.
+   * @evidence contracts/common.md#meaningful-documentation Prose states read-once semantics, sequential stage ownership, absence and independent freshness admission.
+   * @evidence contracts/portability.md#os-neutral-implementation Native temporary-directory creation and path APIs own transport; environment merging preserves Windows key semantics.
+   * @evidence contracts/performance.md#efficient-algorithms Construction writes an empty document; each native stage parses prior captured text/predicates and dirty flushes encode and write the complete reached population. Normal UTF-8 remains plain text, while invalid UTF-8 is encoded losslessly and decoded once per stage.
+   * @evidence contracts/performance.md#reuse-equivalent-work Only stages of this invocation share captured answers; unrelated invocations have fresh IDs and documents.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous owner attempts identity-checked cleanup after success or failure; native captured bytes have no population cap. A failed initial identity read or cleanup can leave storage behind; cleanup failure retains the original thrown error or completed result.
+   */
+  export function run<T>(
+    environment: NodeJS.ProcessEnv | undefined,
+    operation: (environment: NodeJS.ProcessEnv) => T,
+  ): T {
+    const directory = createCanonicalTempDirectory("ttsc-input-snapshot-");
+    const ownership = fs.lstatSync(directory);
+    let completed: T | undefined;
+    let failed = false;
+    let failure: unknown;
+    try {
+      const file = path.join(directory, "inputs.json");
+      fs.writeFileSync(
+        file,
+        JSON.stringify({
+          version: 1,
+          id: crypto.randomUUID(),
+          reads: {},
+          files: {},
+          directories: {},
+          entries: {},
+          realpaths: {},
+          stats: {},
+        }),
+      );
+      const env = SidecarEnvironment.merge(environment, { [ENV]: file });
+      completed = operation(env);
+      return completed;
+    } catch (error) {
+      failed = true;
+      failure = error;
+      throw error;
+    } finally {
+      try {
+        const current = fs.lstatSync(directory);
+        if (
+          !current.isDirectory() ||
+          current.isSymbolicLink() ||
+          current.dev !== ownership.dev ||
+          current.ino !== ownership.ino
+        )
+          throw new Error("Compilation snapshot directory ownership changed");
+        fs.rmSync(directory, { recursive: true });
+      } catch (error) {
+        if (failed)
+          throw new AggregateError(
+            [failure, error],
+            "Compilation snapshot and cleanup failed",
+            { cause: failure },
+          );
+        throw new AggregateError(
+          [completed, error],
+          "Compilation completed but snapshot cleanup failed",
+          { cause: completed },
+        );
+      }
+    }
+  }
+}

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

@@ -13,6 +13,8 @@ import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOpt
 import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
 import type { TtscCommonOptions } from "../../../structures/internal/TtscCommonOptions";
 import type { TtscPluginSourceInputsHandler } from "../../../structures/internal/TtscSingleFileEmitOptions";
+import { CompilationSnapshot } from "../CompilationSnapshot";
+import { compileProjectInMemory } from "../compileProjectInMemory";
 import { outputText } from "../outputText";
 import { CompilerProjectSelection } from "../project/CompilerProjectSelection";
 import { readProjectConfig } from "../project/readProjectConfig";
@@ -226,6 +228,11 @@ export namespace BuildExecution {
       clearInheritedTsgoArgs(env, extra);
     }
     clearInheritedSemanticConfigPath(env, extra);
+    SidecarEnvironment.write(
+      env,
+      CompilationSnapshot.ENV,
+      SidecarEnvironment.read(extra, CompilationSnapshot.ENV),
+    );
     // The anchor is per-invocation state owned by this host: when this run
     // declared none (and the caller's env does not name one), drop any value
     // inherited from an ancestor ttsc process so a nested build never
@@ -363,22 +370,45 @@ export namespace BuildExecution {
    * opted-in native host reports its captured generation, while the direct
    * compiler adapter admits only a stable observed selection and supported
    * output layout. Unknown ownership remains explicit for consumers rather than
-   * guessed.
+   * guessed. Native runtime stages share one invocation-owned read-once view;
+   * configured checks followed by the exact installed compiler emit through its
+   * matching native target, while custom compiler executables remain
+   * delegated.
    *
    * @evidence contracts/common.md#principled-implementation Ordered checks block emit on failure and retain negotiated same-generation input observations for the actual check verb; effectful fix/format results keep their distinct command contract without fabricated reusable check metadata; transforms use one compatible host. Normally completed native partial emission and supported stable external emission can retain actual-write provenance alongside unchanged nonzero status, while interrupted or unknown generations establish no proof.
    * @evidence contracts/common.md#clear-and-simple-design This dispatcher owns phase policy while argv, spawning, normalization and fallback comparison remain shared helpers used by one-shot and watch lanes.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts Format bypass follows its write-only contract; capability-based diagnostics/provenance and failure fallback preserve supported producer semantics without plugin-name shortcuts, foreign mutation or filename-based ownership guesses.
    * @evidence contracts/common.md#meaningful-documentation Native prose states ordering, format effects and thrown boundary failures; branch comments explain nonobvious emission and display policies.
    * @evidence contracts/portability.md#os-neutral-implementation Commands preserve native executable/argv/cwd boundaries; provenance uses a canonical unique temporary directory and absolute native wire paths without post-compile realpath reconstruction or OS-derived case folding.
-   * @evidence contracts/performance.md#efficient-algorithms Plugin/stage selection scans the configured population; each command includes argv/env publication and native runtime probes under its helpers. Required proof adds artifact or external inspection/JSON/source-executable observation work, plus association/path processing. Accumulating phase reports can recopy earlier bytes; there is no supplied bound on total reports, proof bytes or child duration.
-   * @evidence contracts/performance.md#reuse-equivalent-work A check host declaring TypeScript diagnostics avoids an equivalent extra successful check, while compatible transform plugins share one host; effectful configured checks still execute in order.
-   * @evidence contracts/performance.md#bound-retention-and-release-resources Phase results and command/proof records stay build-local and returned data transfer to the caller, with uncapped report/association bytes. Native proof setup observes ownership before finally, so setup failure can leave allocation unclaimed; accepted artifacts reach identity-checked cleanup attempts. Replaced parents remain untouched. Cleanup aggregates an earlier throw or nonzero result; other cleanup errors propagate without certifying release. Delegated capture/descendant release remains with its owner; no resident history is retained here.
+   * @evidence contracts/performance.md#efficient-algorithms Plugin/stage selection scans the configured population; each command includes argv/env publication and native runtime probes under its helpers. Required proof adds artifact or external inspection/JSON/source-executable observation work, plus association/path processing. Native runtime snapshot stages parse the preceding full document and dirty stages serialize/write its complete captured population. Accumulating phase reports can recopy earlier bytes; there is no supplied bound on total reports, proof bytes or child duration.
+   * @evidence contracts/performance.md#reuse-equivalent-work A check host declaring TypeScript diagnostics avoids an equivalent extra successful check, while compatible transform plugins share one host; effectful configured checks still execute in order. Captured answers are shared only across the sequential native stages of this invocation, independently of later cache admission.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Phase results and command/proof records stay build-local and returned data transfer to the caller, with uncapped report/association bytes. Native proof setup observes ownership before finally, so setup failure can leave allocation unclaimed; accepted artifacts reach identity-checked cleanup attempts. Replaced parents remain untouched. Cleanup aggregates an earlier throw or nonzero result; other cleanup errors propagate without certifying release. The snapshot coordinator attempts identity-checked transport cleanup and retains an original error or completed result when cleanup fails. Captured text and full document buffers follow reached input bytes without a cap. Delegated capture/descendant release remains with its owner; no resident history is retained here.
    */
   export function runPreparedBuild(
     options: RunBuildOptions,
     timing: BuildTiming.BuildTiming,
     execution: ReturnType<typeof resolveExecutionContext>,
     buildOptions: RunBuildOptions,
+  ): TtscBuildResult {
+    if (
+      buildOptions.forceEmitProvenance === true &&
+      execution.nativePlugins.length !== 0
+    )
+      return CompilationSnapshot.run(buildOptions.env, (env) =>
+        runPreparedSnapshotBuild(options, timing, execution, {
+          ...buildOptions,
+          env,
+        }),
+      );
+    return runPreparedSnapshotBuild(options, timing, execution, buildOptions);
+  }
+
+  /** Execute one already selected build without replacing compiler authority. */
+  function runPreparedSnapshotBuild(
+    options: RunBuildOptions,
+    timing: BuildTiming.BuildTiming,
+    execution: ReturnType<typeof resolveExecutionContext>,
+    buildOptions: RunBuildOptions,
   ): TtscBuildResult {
     if (execution.compilerSelection.inspectionError !== undefined) {
       const diagnosed = runTsgo(execution, [], buildOptions);
@@ -463,6 +493,14 @@ export namespace BuildExecution {
             execution,
           );
         }
+      } else if (
+        buildOptions.forceEmitProvenance === true &&
+        isProjectCompiler(execution, buildOptions)
+      ) {
+        result = appendBuildOutput(
+          checked,
+          runSnapshotCompilerBuild(execution, buildOptions),
+        );
       } else {
         if (
           buildOptions.skipDiagnosticsCheck !== true &&
@@ -979,6 +1017,60 @@ export namespace BuildExecution {
     );
   }
 
+  /**
+   * Preserve custom compiler executables while recognizing the project's exact
+   * compiler.
+   */
+  function isProjectCompiler(
+    execution: ReturnType<typeof resolveExecutionContext>,
+    options: RunBuildOptions,
+  ): boolean {
+    if (execution.tsgo.version !== "custom") return true;
+    try {
+      const env = SidecarEnvironment.merge(process.env, options.env, {
+        TTSC_TSGO_BINARY: undefined,
+      });
+      const installed = resolveTsgo({ cwd: execution.projectRoot, env });
+      return (
+        fs.realpathSync.native(installed.binary) ===
+        fs.realpathSync.native(execution.tsgo.binary)
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /** Emit through the selected upstream target's native VFS after native checks. */
+  function runSnapshotCompilerBuild(
+    execution: ReturnType<typeof resolveExecutionContext>,
+    options: RunBuildOptions,
+  ): TtscBuildResult {
+    const forwarded = TsgoArguments.createNativeBuildTsgoArgs(
+      execution,
+      options,
+    );
+    const env = SidecarEnvironment.merge(options.env, {
+      [TSGO_ARGS_ENV]: JSON.stringify(forwarded),
+      [TSGO_ARGS_CWD_ENV]: execution.compilerSelection.compilerArgsCwd,
+    });
+    const compiled = compileProjectInMemory({
+      cwd: execution.projectRoot,
+      projectRoot: execution.projectRoot,
+      tsconfig: execution.tsconfig,
+      env,
+      plugins: [],
+      cacheDir: options.cacheDir,
+    });
+    const emittedFiles: string[] = [];
+    for (const [name, text] of Object.entries(compiled.output)) {
+      const output = path.resolve(execution.projectRoot, name);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, text);
+      emittedFiles.push(output);
+    }
+    return { ...compiled.result, emittedFiles };
+  }
+
   /**
    * Run `tsgo` with the full emit arguments and parse `TSFILE:` lines from
    * stdout into `emittedFiles`. Internally requested TSFILE lines are stripped;

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/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,

package/src/compiler/internal/sharedHost/inheritedSidecarEnv.ts

@@ -1,3 +1,4 @@
+import { CompilationSnapshot } from "../CompilationSnapshot";
 import { SidecarEnvironment } from "./SidecarEnvironment";
 import { clearInheritedSemanticConfigPath } from "./clearInheritedSemanticConfigPath";
 import { clearInheritedTsgoArgs } from "./clearInheritedTsgoArgs";
@@ -6,7 +7,8 @@ import { publishLinkedTransformPlugins } from "./publishLinkedTransformPlugins";
 /**
  * Merge inherited and caller environments with native variable-name identity,
  * then clear per-invocation payloads this lane never published: forwarded tsgo
- * arguments, semantic config ownership and the linked-plugin manifest.
+ * arguments, compilation snapshot, semantic config ownership and the
+ * linked-plugin manifest.
  *
  * Use it at every spawn whose child can reach `driver.LoadProgram` — the
  * `api-compile` / `api-transform` hosts, and the plugin loader, whose `ttsx`
@@ -40,6 +42,11 @@ export function inheritedSidecarEnv(
   );
   clearInheritedTsgoArgs(env, callerEnv);
   clearInheritedSemanticConfigPath(env, callerEnv);
+  SidecarEnvironment.write(
+    env,
+    CompilationSnapshot.ENV,
+    SidecarEnvironment.read(callerEnv, CompilationSnapshot.ENV),
+  );
   publishLinkedTransformPlugins(env, callerEnv, []);
   return env;
 }

package/src/compiler/internal/transformProjectInMemory.ts

@@ -11,6 +11,7 @@ import type { ITtscCompilerTransformation } from "../../structures/ITtscCompiler
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import { CompilationSnapshot } from "./CompilationSnapshot";
 import { appendBuildOutput, mergeCheckGraphs } from "./build/appendBuildOutput";
 import { normalizeBuildOutput } from "./build/normalizeBuildOutput";
 import { buildNativeCompiler } from "./buildNativeCompiler";
@@ -60,10 +61,10 @@ import { spawnNative } from "./spawnNative";
  * @evidence contracts/common.md#clear-and-simple-design One router composes built-in and plugin-backed transforms; envelope parsers, environment construction, proof merging and negative-only observation limits have separate shared helpers.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing input proof cannot be repaired by a postcompile baseline; conventional deferred config reads accept only the actual native consumer's proof, while malformed required TypeScript output is a protocol error.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe transform lanes and stage ordering; separated result members distinguish output, advisory graph/dependency data, evaluation witnesses and unstable source markers under documentation guidance.
- * @evidence contracts/performance.md#efficient-algorithms Stage filtering, declared-input Sets and proof maps scale with plugin/input counts; merged paths are sorted with path-text comparison costs. Each stage can rehash/re-realpath declared inputs, serialize plugin/config records and parse complete output; discovery, native capability probes, source builds and child execution remain delegated costs of this call. No byte/work ceiling or measured dominant-cost ranking is asserted.
- * @evidence contracts/performance.md#reuse-equivalent-work Source-plugin artifacts are shared by their owning loader; this transform intentionally produces a current generation and gives downstream consumers the graph, source states and host witnesses required to qualify reuse.
+ * @evidence contracts/performance.md#efficient-algorithms Stage filtering, declared-input Sets and proof maps scale with plugin/input counts; merged paths are sorted with path-text comparison costs. Each stage can rehash/re-realpath declared inputs, serialize plugin/config records and parse complete output; discovery, native capability probes, source builds and child execution remain delegated costs of this call. The invocation snapshot adds full captured-population parsing and dirty document encoding/writes per native stage. No byte/work ceiling or measured dominant-cost ranking is asserted.
+ * @evidence contracts/performance.md#reuse-equivalent-work Descriptor/source discovery precedes snapshot allocation so invocation-private paths do not vary its environment cache identity. Source-plugin artifacts are shared by their owning loader; this transform intentionally produces a current generation and gives downstream consumers the graph, source states and host witnesses required to qualify reuse.
  *
- * @evidence contracts/performance.md#bound-retention-and-release-resources This router retains discovery records, per-stage proof maps and accumulated diagnostics/output until synchronous stage completion, then transfers the returned envelope. Native capture/observation owners attempt their own cleanup; suppressed cleanup failures and descendant release remain unconfirmed where those owners do not join them. Artifact-cache retention belongs to the builder, and no stage timeout or input/output byte ceiling is supplied here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This router retains discovery records, per-stage proof maps and accumulated diagnostics/output until synchronous stage completion, then transfers the returned envelope. The invocation coordinator attempts identity-checked snapshot removal and propagates or aggregates removal failure. Other native capture/observation owners attempt their own cleanup; suppressed cleanup failures and descendant release remain unconfirmed where those owners do not join them. Artifact-cache retention belongs to the builder, and no stage timeout or input/output byte ceiling is supplied here.
  *
  * @evidence contracts/portability.md#os-neutral-implementation Native paths remain filesystem coordinates, child argv are arrays, and environment helpers preserve Windows key equivalence and explicit Node/tsgo/config anchors without shell parsing or native method patching.
  */
@@ -123,6 +124,16 @@ export function transformProjectInMemory(options: ITtscCompilerContext): {
     projectRoot: options.projectRoot,
     tsconfig: options.tsconfig,
   });
+  return CompilationSnapshot.run(options.env, (env) =>
+    transformWithSnapshot({ ...options, env }, loaded),
+  );
+}
+
+/** Run native checks and transformation after descriptor/source discovery. */
+function transformWithSnapshot(
+  options: ITtscCompilerContext,
+  loaded: ReturnType<typeof loadProjectPlugins>,
+): ReturnType<typeof transformProjectInMemory> {
   if (loaded.nativePlugins.length !== 0) {
     // Every step below runs binaries built from these sources, so the output
     // is a function of their state, which the envelope carries for a consumer
@@ -393,7 +404,11 @@ function transformProjectWithPlugins(
     );
     return {
       ...envelopeSideChannels(transformed),
-      graph: mergeCheckGraphs(checked.graph, transformed.graph),
+      graph: mergeTransformGraphs(
+        checked.graph,
+        transformed.graph,
+        checks.length,
+      ),
       ...observationLimitations(
         [loaded, checked, transformed],
         hostInputHashes,
@@ -476,7 +491,7 @@ function transformProjectWithPlugins(
   );
   return {
     ...envelopeSideChannels(output),
-    graph: mergeCheckGraphs(checked.graph, output.graph),
+    graph: mergeTransformGraphs(checked.graph, output.graph, checks.length),
     ...observationLimitations(
       [loaded, checked, output],
       hostInputHashes,
@@ -708,6 +723,7 @@ function runNativeChecks(
     stdout: "",
     stderr: "",
   };
+  let snapshotsComplete = true;
   for (const plugin of checks) {
     const checked = runNativeCheckWithObservations(plugin, (extraArgs) => {
       const res = spawnNative(
@@ -748,7 +764,12 @@ function runNativeChecks(
         project.root,
       );
     });
+    snapshotsComplete &&= checked.graph?.compilationSnapshot !== undefined;
     result = appendBuildOutput(result, checked);
+    if (!snapshotsComplete && result.graph?.compilationSnapshot !== undefined) {
+      const { compilationSnapshot: _snapshot, ...unqualified } = result.graph;
+      result.graph = unqualified;
+    }
     if (result.status !== 0) {
       return result;
     }
@@ -877,3 +898,23 @@ function nativePluginEnv(
   );
   return env;
 }
+
+/**
+ * A legacy check with no graph cannot certify the transform's shared input
+ * view.
+ */
+function mergeTransformGraphs(
+  checked: TtscBuildResult["graph"],
+  transformed: TtscBuildResult["graph"],
+  checks: number,
+): TtscBuildResult["graph"] {
+  const graph = mergeCheckGraphs(checked, transformed);
+  if (
+    graph === undefined ||
+    checks === 0 ||
+    checked?.compilationSnapshot !== undefined
+  )
+    return graph;
+  const { compilationSnapshot: _snapshot, ...unqualified } = graph;
+  return unqualified;
+}

package/src/structures/ITtscCompilerTransformation.ts

@@ -51,6 +51,12 @@ export namespace ITtscCompilerTransformation {
    * @evidence contracts/portability.md#os-neutral-implementation Graph keys use the producer's cwd-relative slash spelling with absolute slash paths for outside-root or cross-volume inputs; this protocol spelling is distinct from reported native realpaths carried by inputRealpaths and observations, which can retain lexical fallback on native VFS errors. The reported compiler case policy governs compiler membership comparisons rather than an OS-name assumption; absent policy or proof does not establish native filesystem capabilities.
    */
   export interface IReferenceGraph {
+    /**
+     * Shared native read-once input view; current delivery authority, never
+     * disk freshness.
+     */
+    compilationSnapshot?: string;
+
     /**
      * Effective native possible-root suffixes and output-directory exclusions.
      * A report that differs from a host's provisional policy requires a new