ttsc 0.35.0 → 0.36.1

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

@@ -16,18 +16,21 @@ import { PassthroughFlags } from "./PassthroughFlags";
  * when its read-only option and source probes succeeded. Compiler status,
  * 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.
+ * Admission requires stable effective options and physical source paths before
+ * and after emission, plus unchanged response files and selected executable
+ * bytes. A reported source list proves the emitting selection independently of
+ * roots rediscovered by showConfig after emission. When an unreported host's
+ * shown roots change, the union of inspected source populations must still
+ * predict a unique physical owner for each previously predicted write; new
+ * sources can only introduce ambiguity. 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 +50,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. Parsed settings exclude rediscovered showConfig.files. A reporting producer proves its emitting selection; an observed host with changed roots rechecks source selection and includes additional candidates only to reject conflicting physical owners of previously predicted writes. 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; changed observed roots add one native source probe and a deduplicated union of the two populations. 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 +147,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);
@@ -159,6 +162,7 @@ export function runExternalEmitProvenance(options: {
     : `Emitting source selection differs from its inspection (${probe.files.length} inspected, ${listed.length} reported); first differing inspected path ${JSON.stringify(probe.files[firstDifference])}, reported path ${JSON.stringify(listed[firstDifference === -1 ? probe.files.length : firstDifference])}.`;
   let stage = "response-file reinspection";
   try {
+    let sources = probe.files;
     for (const [file, before] of probe.responseObservations) {
       if (!stable) break;
       stable = CompilerArgumentsInspection.observeInputFile(file) === before;
@@ -166,10 +170,22 @@ export function runExternalEmitProvenance(options: {
         failure = `Compiler response file changed across emission: ${JSON.stringify(file)}.`;
     }
     stage = "effective configuration reinspection";
-    if (stable && readConfig(options)?.text !== probe.text) {
-      stable = false;
-      failure =
-        "Effective configuration changed or could not be reinspected after emission.";
+    if (stable) {
+      const after = readConfig(options);
+      if (after?.signature !== probe.signature) {
+        stable = false;
+        failure =
+          "Effective configuration changed or could not be reinspected after emission.";
+      } else if (
+        observed &&
+        JSON.stringify(after.config.files) !==
+          JSON.stringify(probe.config.files)
+      ) {
+        stage = "post-emission source-list inspection";
+        // An added root can import an output-colliding source, so inspect its
+        // full dependency selection rather than only predicting that root.
+        sources = [...new Set([...sources, ...readSourceList(options)])];
+      }
     }
     stage = `executable observation of ${JSON.stringify(probe.binaryPath)}`;
     if (stable) {
@@ -185,10 +201,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;
@@ -202,14 +218,15 @@ export function runExternalEmitProvenance(options: {
       const predictOutputs = createOutputPrediction(probe.config, probe.base);
       let predictedSources = 0;
       let sourceExample: string | undefined;
-      for (const source of probe.files) {
+      for (const source of sources) {
         const outputs = predictOutputs(source);
         if (outputs.length === 0) continue;
         predictedSources++;
         sourceExample ??= source;
-        const physicalSource: string = JSON.parse(
-          probe.observations.get(source)!,
-        )[0];
+        // Observed writes were predicted before the host ran. A newly selected
+        // source can make their ownership ambiguous, never establish a new write.
+        const physicalSource =
+          probe.observations.get(source) ?? observeSourceIdentity(source);
         for (const output of outputs) {
           const sources = owners.get(output) ?? new Set<string>();
           sources.add(physicalSource);
@@ -335,43 +352,11 @@ function prepareProbe(
         "Original argv does not establish a supported selected configuration directory.",
       );
     stage = "compiler source-list inspection";
-    const listed = spawnNative(
-      options.binary,
-      [
-        ...options.args,
-        "--listFilesOnly",
-        "true",
-        "--listEmittedFiles",
-        "false",
-      ],
-      options,
-    );
-    if (listed.error || listed.status === null || listed.signal !== null)
-      return unavailable(
-        `Selected producer source-list inspection did not complete normally (status ${listed.status}, signal ${listed.signal}, error ${listed.error?.message ?? "none"}).`,
-      );
-    const files = compilerSourceList(
-      String(listed.stdout).split(/\r?\n/),
-      options.cwd,
-    );
-    if (
-      files.length === 0 ||
-      !files.every(
-        (file) =>
-          path.isAbsolute(file) &&
-          /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/.test(file),
-      )
-    )
-      return unavailable(
-        `Source-list inspection returned ${files.length} paths and no complete supported source population; first unsupported candidate: ${JSON.stringify(files.find((file) => !path.isAbsolute(file) || !/\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/.test(file)))}.`,
-      );
+    const files = readSourceList(options);
     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)
@@ -394,6 +379,37 @@ function prepareProbe(
   }
 }
 
+/** Both source inspections use the same native reporting and admission rules. */
+function readSourceList(
+  options: Parameters<typeof runExternalEmitProvenance>[0],
+): string[] {
+  const listed = spawnNative(
+    options.binary,
+    [...options.args, "--listFilesOnly", "true", "--listEmittedFiles", "false"],
+    options,
+  );
+  if (listed.error || listed.status === null || listed.signal !== null)
+    throw new Error(
+      `Selected producer source-list inspection did not complete normally (status ${listed.status}, signal ${listed.signal}, error ${listed.error?.message ?? "none"}).`,
+    );
+  const files = compilerSourceList(
+    String(listed.stdout).split(/\r?\n/),
+    options.cwd,
+  );
+  if (
+    files.length === 0 ||
+    !files.every(
+      (file) =>
+        path.isAbsolute(file) &&
+        /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/.test(file),
+    )
+  )
+    throw new Error(
+      `Source-list inspection returned ${files.length} paths and no complete supported source population; first unsupported candidate: ${JSON.stringify(files.find((file) => !path.isAbsolute(file) || !/\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/.test(file)))}.`,
+    );
+  return files;
+}
+
 /**
  * Compiler diagnostics may start with an absolute filename too. Exclude only
  * recognized diagnostic renderings, preserving every other absolute candidate
@@ -411,14 +427,20 @@ function compilerSourceList(lines: readonly string[], cwd: string): string[] {
   );
 }
 
-/** ShowConfig resolves inherited settings and argv overrides in the producer. */
+/**
+ * ShowConfig resolves inherited settings and argv overrides in the producer.
+ * Its expanded files describe the current directory, not the completed emit.
+ * Root changes are handled separately from settings: reporting producers name
+ * their emitting sources, while observed hosts recheck possible contributors.
+ */
 function readConfig(options: Parameters<typeof runExternalEmitProvenance>[0]):
   | {
       config: {
         compilerOptions: Record<string, unknown>;
         references?: unknown[];
+        files?: string[];
       };
-      text: string;
+      signature: string;
     }
   | undefined {
   const result = spawnNative(
@@ -427,8 +449,7 @@ function readConfig(options: Parameters<typeof runExternalEmitProvenance>[0]):
     options,
   );
   if (result.error || result.status !== 0) return undefined;
-  const text = String(result.stdout);
-  const config = JSON.parse(text);
+  const config = JSON.parse(String(result.stdout));
   if (
     !config ||
     typeof config !== "object" ||
@@ -438,7 +459,9 @@ function readConfig(options: Parameters<typeof runExternalEmitProvenance>[0]):
     (config.references !== undefined && !Array.isArray(config.references))
   )
     return undefined;
-  return { config, text };
+  const settings = { ...config };
+  delete settings.files;
+  return { config, signature: JSON.stringify(settings) };
 }
 
 /** ShowConfig path options are relative to the selected config's directory. */
@@ -644,3 +667,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