ttsc 0.19.0 → 0.19.2

package/lib/structures/ITtscCompilerTransformation.d.ts

@@ -9,6 +9,39 @@ import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
  */
 export type ITtscCompilerTransformation = ITtscCompilerTransformation.ISuccess | ITtscCompilerTransformation.IFailure | ITtscCompilerTransformation.IException;
 export declare namespace ITtscCompilerTransformation {
+    /**
+     * Host-owned reference graph of the transformed program, mirroring the
+     * envelope's optional `graph` section.
+     *
+     * The graph is the language-semantic input bound of the transform under `tsc
+     * --incremental` semantics: any symbol a file can reference is reachable
+     * through its import/reference closure or is ambient. Bundler adapters
+     * register, per transformed file `F`, the reachability closure of
+     * {@link edges} from `F` together with {@link globals} and {@link configs}, so
+     * persistent caches and watch graphs invalidate soundly without per-plugin
+     * dependency reporting.
+     *
+     * Keys and values follow the same convention as {@link ISuccess.typescript}:
+     * project-relative slash paths, falling back to absolute slash paths outside
+     * the project root.
+     */
+    interface IReferenceGraph {
+        /**
+         * Direct resolved references per file: imports, re-exports, `///
+         * <reference>` targets, and type reference directives — type-only edges
+         * included. Direct edges only; consumers compute transitive reachability
+         * themselves.
+         */
+        edges: Record<string, string[]>;
+        /**
+         * Files contributing to the global scope (ambient declaration files, script
+         * files, global augmentations, `typeRoots` entries). A change to any of
+         * them can affect every file in the program.
+         */
+        globals: string[];
+        /** The project tsconfig followed by its `extends` ancestry. */
+        configs: string[];
+    }
     /** Successful source-to-source transformation result. */
     interface ISuccess {
         /** Indicates that transformation completed without diagnostics. */
@@ -36,6 +69,54 @@ export declare namespace ITtscCompilerTransformation {
          * invalidation. ttsc passes the paths through verbatim.
          */
         dependencies?: Record<string, string[]>;
+        /**
+         * Transformed files (keyed like {@link typescript}) whose
+         * {@link dependencies} entry the transform host declares **complete**: every
+         * input beyond the file itself and the universal
+         * {@link IReferenceGraph.configs} chain is listed there.
+         *
+         * The declaration narrows invalidation. For a listed file a consumer uses
+         * `dependencies[F] ∪ graph.configs` instead of the union with the
+         * host-owned `reach(graph.edges, F) ∪ graph.globals` bound, so a change to
+         * a file the transform never consulted no longer re-runs it. Unlisted files
+         * keep the union, so a mixed envelope composes per file.
+         *
+         * This is a responsibility transfer, not a hint: an omission makes the
+         * consumer serve stale output, and that is a defect of the declaring plugin
+         * rather than of the host. Producers list a file only when the reported set
+         * is derived from what the transform actually consulted (a Checker-driven
+         * generator's per-file consulted-declaration list). When several plugin
+         * entries contribute to one file, the envelope's author may list it only if
+         * every contributing entry declared its own list complete for it.
+         *
+         * The config chain a listed file keeps is {@link graph}'s, so a host that
+         * declares completeness should stamp {@link graph} too; without it a listed
+         * file retains no universal input at all.
+         *
+         * Optional, and never required for correctness: an envelope without this
+         * field keeps the sound host-owned bound. A file that is both listed here
+         * and in {@link volatile} keeps the union, since the two claims contradict
+         * and the conservative one wins.
+         */
+        dependenciesComplete?: string[];
+        /**
+         * Host-owned reference graph of the transformed program.
+         *
+         * Optional: only present when the transform host stamped a `graph` section
+         * into its stdout envelope (the built-in native host and the linked-plugin
+         * host always do; external sidecars adopt through the driver SDK).
+         * Malformed sections are dropped, never fatal — the field is advisory
+         * invalidation metadata, not output.
+         */
+        graph?: IReferenceGraph;
+        /**
+         * Transformed files (keyed like {@link typescript}) whose output depends on
+         * non-file inputs (environment, time, network) as declared by the transform
+         * plugin via the envelope's optional `volatile` list. No file-dependency
+         * scheme can represent such inputs, so consumers must exclude these files
+         * from caching instead of watching more files.
+         */
+        volatile?: string[];
     }
     /** Source-to-source transformation result that completed with diagnostics. */
     interface IFailure {
@@ -57,6 +138,23 @@ export declare namespace ITtscCompilerTransformation {
          * transform did not complete its pass.
          */
         dependencies?: Record<string, string[]>;
+        /**
+         * Files whose reported dependency list the host declares complete. Same
+         * shape and semantics as {@link ISuccess.dependenciesComplete}; may be
+         * partial when the transform did not complete its pass.
+         */
+        dependenciesComplete?: string[];
+        /**
+         * Host-owned reference graph. Same shape and semantics as
+         * {@link ISuccess.graph}; may be absent when diagnostics prevented the host
+         * from loading the program.
+         */
+        graph?: IReferenceGraph;
+        /**
+         * Volatile transformed files. Same shape and semantics as
+         * {@link ISuccess.volatile}.
+         */
+        volatile?: string[];
     }
     /** Unexpected host-level error during transformation. */
     interface IException {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttsc",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "General-purpose TypeScript-Go compiler, runtime, plugin host, and LSP host.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -35,13 +35,13 @@
     "typescript": "^7.0.2"
   },
   "optionalDependencies": {
-    "@ttsc/linux-x64": "0.19.0",
-    "@ttsc/darwin-x64": "0.19.0",
-    "@ttsc/linux-arm64": "0.19.0",
-    "@ttsc/darwin-arm64": "0.19.0",
-    "@ttsc/linux-arm": "0.19.0",
-    "@ttsc/win32-x64": "0.19.0",
-    "@ttsc/win32-arm64": "0.19.0"
+    "@ttsc/linux-x64": "0.19.2",
+    "@ttsc/linux-arm": "0.19.2",
+    "@ttsc/linux-arm64": "0.19.2",
+    "@ttsc/darwin-x64": "0.19.2",
+    "@ttsc/win32-x64": "0.19.2",
+    "@ttsc/win32-arm64": "0.19.2",
+    "@ttsc/darwin-arm64": "0.19.2"
   },
   "sideEffects": false,
   "files": [

package/shim/compiler/incremental.go

@@ -0,0 +1,58 @@
+// gen_shims:hand-maintained
+//
+// Reference-graph parts of tsgo's own incremental engine (`tsc --incremental`
+// semantics), linked from internal/execute/incremental so ttsc's transform
+// envelopes can carry the same language-semantic input bound the compiler
+// itself uses for invalidation: per-file direct resolved references and the
+// files that contribute to the global scope.
+package compiler
+
+import (
+  _ "unsafe"
+
+  innerast "github.com/microsoft/typescript-go/internal/ast"
+  "github.com/microsoft/typescript-go/internal/collections"
+  innercompiler "github.com/microsoft/typescript-go/internal/compiler"
+  "github.com/microsoft/typescript-go/internal/tspath"
+
+  // The linknamed symbols below live in the incremental package; the blank
+  // import compiles it into every shim consumer so the references resolve.
+  _ "github.com/microsoft/typescript-go/internal/execute/incremental"
+)
+
+//go:linkname incrementalGetReferencedFiles github.com/microsoft/typescript-go/internal/execute/incremental.getReferencedFiles
+func incrementalGetReferencedFiles(program *innercompiler.Program, file *innerast.SourceFile) *collections.Set[tspath.Path]
+
+//go:linkname incrementalFileAffectsGlobalScope github.com/microsoft/typescript-go/internal/execute/incremental.fileAffectsGlobalScope
+func incrementalFileAffectsGlobalScope(file *innerast.SourceFile) bool
+
+// GetReferencedFilePaths returns the canonical paths of every file that `file`
+// directly references in `program`: resolved imports and re-exports (type-only
+// included), `/// <reference>` targets, resolved type reference directives,
+// module augmentations, and ambient-module declaration files. This is exactly
+// the per-file `referencedMap` entry tsgo's incremental engine stores in
+// `tsbuildinfo`, so the result is the sound language-semantic upper bound on
+// which program files a symbol in `file` can resolve through.
+//
+// The returned strings are tspath.Path values (case-canonicalized on
+// case-insensitive filesystems); map them back to real file names through
+// Program.GetSourceFileByPath when the original spelling matters.
+func GetReferencedFilePaths(program *Program, file *innerast.SourceFile) []string {
+  set := incrementalGetReferencedFiles(program, file)
+  if set == nil {
+    return nil
+  }
+  out := make([]string, 0, set.Len())
+  for path := range set.Keys() {
+    out = append(out, string(path))
+  }
+  return out
+}
+
+// FileAffectsGlobalScope reports whether editing `file` can change the global
+// scope: global-scope module augmentations, ambient declaration files, and
+// script (non-module) files. Mirrors the predicate tsgo's incremental engine
+// uses to decide that a change must invalidate every file in the program.
+func FileAffectsGlobalScope(file *innerast.SourceFile) bool {
+  return incrementalFileAffectsGlobalScope(file)
+}

package/shim/core/shim.go

@@ -50,6 +50,11 @@ const (
   JsxEmitReactJSXDev = innercore.JsxEmitReactJSXDev
 )
 
+// Version reports the TypeScript compiler version typescript-go implements, in
+// the same form `tsc --version` prints. A graph snapshot publishes it so a
+// consumer can tell which checker resolved the facts it is reading.
+func Version() string { return innercore.Version() }
+
 // NewTextRange constructs a closed/open [pos, end) text range.
 func NewTextRange(pos, end int) TextRange { return innercore.NewTextRange(pos, end) }
 

package/src/TtscCompiler.ts

@@ -259,8 +259,11 @@ interface ProjectResult {
 
 interface ProjectTransformation {
   dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
   result: TtscBuildResult;
   typescript: Record<string, string>;
+  volatile?: string[];
 }
 
 function runProject(task: () => ProjectResult): ITtscCompilerResult {
@@ -371,20 +374,32 @@ function toCompilerResult(project: ProjectResult): ITtscCompilerResult {
 function toCompilerTransformation(
   project: ProjectTransformation,
 ): ITtscCompilerTransformation {
-  const { dependencies, result, typescript } = project;
-  const dependencyField = dependencies === undefined ? {} : { dependencies };
+  const {
+    dependencies,
+    dependenciesComplete,
+    graph,
+    result,
+    typescript,
+    volatile,
+  } = project;
+  const advisoryFields = {
+    ...(dependencies === undefined ? {} : { dependencies }),
+    ...(dependenciesComplete === undefined ? {} : { dependenciesComplete }),
+    ...(graph === undefined ? {} : { graph }),
+    ...(volatile === undefined ? {} : { volatile }),
+  };
   if (result.status === 0 && !hasErrorDiagnostics(result.diagnostics)) {
     return {
       ...(result.diagnostics.length === 0
         ? {}
         : { diagnostics: result.diagnostics }),
-      ...dependencyField,
+      ...advisoryFields,
       type: "success",
       typescript,
     };
   }
   return {
-    ...dependencyField,
+    ...advisoryFields,
     diagnostics:
       result.diagnostics.length === 0
         ? [createProcessDiagnostic(result)]

package/src/compiler/internal/transformProjectInMemory.ts

@@ -6,6 +6,7 @@ import {
 } from "../../plugin/internal/loadProjectPlugins";
 import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
 import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
+import type { ITtscCompilerTransformation } from "../../structures/ITtscCompilerTransformation";
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
@@ -41,8 +42,11 @@ import { outputText, spawnNative } from "./spawnNative";
  */
 export function transformProjectInMemory(options: ITtscCompilerContext): {
   dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
   result: TtscBuildResult;
   typescript: Record<string, string>;
+  volatile?: string[];
 } {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const project = readProjectConfig({
@@ -74,8 +78,11 @@ function transformProjectWithNativeHost(
   project: ITtscParsedProjectConfig,
 ): {
   dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
   result: TtscBuildResult;
   typescript: Record<string, string>;
+  volatile?: string[];
 } {
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
@@ -101,9 +108,7 @@ function transformProjectWithNativeHost(
     outputText(res.stderr),
   );
   return {
-    ...(output.dependencies === undefined
-      ? {}
-      : { dependencies: output.dependencies }),
+    ...envelopeSideChannels(output),
     result: {
       diagnostics: output.diagnostics,
       status: res.status ?? 1,
@@ -120,8 +125,11 @@ function transformProjectWithPlugins(
   project: ITtscParsedProjectConfig,
 ): {
   dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
   result: TtscBuildResult;
   typescript: Record<string, string>;
+  volatile?: string[];
 } {
   const loaded = loadProjectPlugins({
     binary: resolveBinary(options) ?? "",
@@ -159,9 +167,7 @@ function transformProjectWithPlugins(
   if (transformers.length === 0) {
     const transformed = transformProjectWithNativeHost(options, project);
     return {
-      ...(transformed.dependencies === undefined
-        ? {}
-        : { dependencies: transformed.dependencies }),
+      ...envelopeSideChannels(transformed),
       result: appendBuildOutput(checked, transformed.result),
       typescript: transformed.typescript,
     };
@@ -196,12 +202,39 @@ function transformProjectWithPlugins(
     stdout: "",
     stderr: outputText(res.stderr),
   };
+  return {
+    ...envelopeSideChannels(output),
+    result: appendBuildOutput(checked, result),
+    typescript: output.typescript,
+  };
+}
+
+/**
+ * Collect the optional advisory envelope fields (`dependencies`,
+ * `dependenciesComplete`, `graph`, `volatile`) into a spreadable object,
+ * omitting absent fields so downstream result shapes stay free of `undefined`
+ * keys.
+ */
+function envelopeSideChannels(output: {
+  dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
+  volatile?: string[];
+}): {
+  dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
+  volatile?: string[];
+} {
   return {
     ...(output.dependencies === undefined
       ? {}
       : { dependencies: output.dependencies }),
-    result: appendBuildOutput(checked, result),
-    typescript: output.typescript,
+    ...(output.dependenciesComplete === undefined
+      ? {}
+      : { dependenciesComplete: output.dependenciesComplete }),
+    ...(output.graph === undefined ? {} : { graph: output.graph }),
+    ...(output.volatile === undefined ? {} : { volatile: output.volatile }),
   };
 }
 
@@ -368,24 +401,34 @@ function nativePluginEnv(
  * treated as a protocol error and throws with the stderr/stdout context. JSON
  * parse errors are also wrapped with the same context message.
  *
- * The optional `dependencies` field (per-file consulted-source lists, see
- * `ITtscCompilerTransformation`) is forwarded when well-formed; entries that
- * are not string arrays are dropped rather than failing the transform — the
- * field is advisory watch metadata, not output.
+ * The optional `dependencies`, `dependenciesComplete`, `graph`, and `volatile`
+ * fields (see `ITtscCompilerTransformation`) are forwarded when well-formed;
+ * entries that do not match the expected shape are dropped rather than failing
+ * the transform — the fields are advisory invalidation metadata, not output.
+ *
+ * Dropping a malformed `dependenciesComplete` member is the safe direction on
+ * purpose: an unlisted file keeps the sound host-owned bound, so a garbled
+ * declaration costs over-invalidation, never a stale output.
  */
 function parseNativeTransformOutput(
   stdout: string,
   stderr: string,
 ): {
   dependencies?: Record<string, string[]>;
+  dependenciesComplete?: string[];
   diagnostics: ITtscCompilerDiagnostic[];
+  graph?: ITtscCompilerTransformation.IReferenceGraph;
   typescript: Record<string, string>;
+  volatile?: string[];
 } {
   try {
     const parsed = JSON.parse(stdout) as {
       dependencies?: Record<string, string[]>;
+      dependenciesComplete?: string[];
       diagnostics?: ITtscCompilerDiagnostic[];
+      graph?: ITtscCompilerTransformation.IReferenceGraph;
       typescript?: Record<string, string>;
+      volatile?: string[];
     };
     if (!isTextRecord(parsed.typescript)) {
       throw new Error(
@@ -393,8 +436,14 @@ function parseNativeTransformOutput(
       );
     }
     const dependencies = parseDependencyLists(parsed.dependencies);
+    const dependenciesComplete = parseFileList(parsed.dependenciesComplete);
+    const graph = parseReferenceGraph(parsed.graph);
+    const volatile = parseFileList(parsed.volatile);
     return {
       ...(dependencies === undefined ? {} : { dependencies }),
+      ...(dependenciesComplete === undefined ? {} : { dependenciesComplete }),
+      ...(graph === undefined ? {} : { graph }),
+      ...(volatile === undefined ? {} : { volatile }),
       diagnostics: Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [],
       typescript: parsed.typescript,
     };
@@ -434,6 +483,51 @@ function parseDependencyLists(
   return Object.keys(output).length === 0 ? undefined : output;
 }
 
+/**
+ * Normalize the optional `graph` envelope section with the same tolerance as
+ * `dependencies`: non-object sections are dropped, edge entries that are not
+ * string arrays are dropped, and non-string list members are filtered. A
+ * section carrying nothing usable collapses to `undefined`.
+ */
+function parseReferenceGraph(
+  value: unknown,
+): ITtscCompilerTransformation.IReferenceGraph | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const section = value as {
+    configs?: unknown;
+    edges?: unknown;
+    globals?: unknown;
+  };
+  const edges = parseDependencyLists(section.edges) ?? {};
+  const globals = parseFileList(section.globals) ?? [];
+  const configs = parseFileList(section.configs) ?? [];
+  if (
+    Object.keys(edges).length === 0 &&
+    globals.length === 0 &&
+    configs.length === 0
+  ) {
+    return undefined;
+  }
+  return { configs, edges, globals };
+}
+
+/**
+ * Normalize an optional string-list envelope field (`dependenciesComplete`,
+ * `volatile`, and the `globals`/`configs` graph sections), or `undefined` when
+ * absent or carrying nothing usable.
+ */
+function parseFileList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const files = value.filter(
+    (entry): entry is string => typeof entry === "string" && entry.length !== 0,
+  );
+  return files.length === 0 ? undefined : files;
+}
+
 /** Type guard: true when `value` is a non-null, non-array object of strings. */
 function isTextRecord(value: unknown): value is Record<string, string> {
   return (

package/src/structures/ITtscCompilerTransformation.ts

@@ -14,6 +14,42 @@ export type ITtscCompilerTransformation =
   | ITtscCompilerTransformation.IException;
 
 export namespace ITtscCompilerTransformation {
+  /**
+   * Host-owned reference graph of the transformed program, mirroring the
+   * envelope's optional `graph` section.
+   *
+   * The graph is the language-semantic input bound of the transform under `tsc
+   * --incremental` semantics: any symbol a file can reference is reachable
+   * through its import/reference closure or is ambient. Bundler adapters
+   * register, per transformed file `F`, the reachability closure of
+   * {@link edges} from `F` together with {@link globals} and {@link configs}, so
+   * persistent caches and watch graphs invalidate soundly without per-plugin
+   * dependency reporting.
+   *
+   * Keys and values follow the same convention as {@link ISuccess.typescript}:
+   * project-relative slash paths, falling back to absolute slash paths outside
+   * the project root.
+   */
+  export interface IReferenceGraph {
+    /**
+     * Direct resolved references per file: imports, re-exports, `///
+     * <reference>` targets, and type reference directives — type-only edges
+     * included. Direct edges only; consumers compute transitive reachability
+     * themselves.
+     */
+    edges: Record<string, string[]>;
+
+    /**
+     * Files contributing to the global scope (ambient declaration files, script
+     * files, global augmentations, `typeRoots` entries). A change to any of
+     * them can affect every file in the program.
+     */
+    globals: string[];
+
+    /** The project tsconfig followed by its `extends` ancestry. */
+    configs: string[];
+  }
+
   /** Successful source-to-source transformation result. */
   export interface ISuccess {
     /** Indicates that transformation completed without diagnostics. */
@@ -44,6 +80,57 @@ export namespace ITtscCompilerTransformation {
      * invalidation. ttsc passes the paths through verbatim.
      */
     dependencies?: Record<string, string[]>;
+
+    /**
+     * Transformed files (keyed like {@link typescript}) whose
+     * {@link dependencies} entry the transform host declares **complete**: every
+     * input beyond the file itself and the universal
+     * {@link IReferenceGraph.configs} chain is listed there.
+     *
+     * The declaration narrows invalidation. For a listed file a consumer uses
+     * `dependencies[F] ∪ graph.configs` instead of the union with the
+     * host-owned `reach(graph.edges, F) ∪ graph.globals` bound, so a change to
+     * a file the transform never consulted no longer re-runs it. Unlisted files
+     * keep the union, so a mixed envelope composes per file.
+     *
+     * This is a responsibility transfer, not a hint: an omission makes the
+     * consumer serve stale output, and that is a defect of the declaring plugin
+     * rather than of the host. Producers list a file only when the reported set
+     * is derived from what the transform actually consulted (a Checker-driven
+     * generator's per-file consulted-declaration list). When several plugin
+     * entries contribute to one file, the envelope's author may list it only if
+     * every contributing entry declared its own list complete for it.
+     *
+     * The config chain a listed file keeps is {@link graph}'s, so a host that
+     * declares completeness should stamp {@link graph} too; without it a listed
+     * file retains no universal input at all.
+     *
+     * Optional, and never required for correctness: an envelope without this
+     * field keeps the sound host-owned bound. A file that is both listed here
+     * and in {@link volatile} keeps the union, since the two claims contradict
+     * and the conservative one wins.
+     */
+    dependenciesComplete?: string[];
+
+    /**
+     * Host-owned reference graph of the transformed program.
+     *
+     * Optional: only present when the transform host stamped a `graph` section
+     * into its stdout envelope (the built-in native host and the linked-plugin
+     * host always do; external sidecars adopt through the driver SDK).
+     * Malformed sections are dropped, never fatal — the field is advisory
+     * invalidation metadata, not output.
+     */
+    graph?: IReferenceGraph;
+
+    /**
+     * Transformed files (keyed like {@link typescript}) whose output depends on
+     * non-file inputs (environment, time, network) as declared by the transform
+     * plugin via the envelope's optional `volatile` list. No file-dependency
+     * scheme can represent such inputs, so consumers must exclude these files
+     * from caching instead of watching more files.
+     */
+    volatile?: string[];
   }
 
   /** Source-to-source transformation result that completed with diagnostics. */
@@ -69,6 +156,26 @@ export namespace ITtscCompilerTransformation {
      * transform did not complete its pass.
      */
     dependencies?: Record<string, string[]>;
+
+    /**
+     * Files whose reported dependency list the host declares complete. Same
+     * shape and semantics as {@link ISuccess.dependenciesComplete}; may be
+     * partial when the transform did not complete its pass.
+     */
+    dependenciesComplete?: string[];
+
+    /**
+     * Host-owned reference graph. Same shape and semantics as
+     * {@link ISuccess.graph}; may be absent when diagnostics prevented the host
+     * from loading the program.
+     */
+    graph?: IReferenceGraph;
+
+    /**
+     * Volatile transformed files. Same shape and semantics as
+     * {@link ISuccess.volatile}.
+     */
+    volatile?: string[];
   }
 
   /** Unexpected host-level error during transformation. */

package/tools/shim_audit/baseline.json

@@ -669,7 +669,6 @@
     "FUNC|core|ResolveConfigFileNameOfProjectReference",
     "FUNC|core|ShouldRewriteModuleSpecifier",
     "FUNC|core|UTF16Len",
-    "FUNC|core|Version",
     "FUNC|core|VersionMajorMinor",
     "FUNC|core|WithRequestID",
     "FUNC|diagnosticwriter|FormatDiagnosticWithColorAndContext",
@@ -678,6 +677,8 @@
     "FUNC|diagnosticwriter|TryClearScreen",
     "FUNC|diagnosticwriter|WriteFormatDiagnostic",
     "FUNC|diagnosticwriter|WriteFormatDiagnostics",
+    "FUNC|execute/incremental|ComputeHash",
+    "FUNC|execute/incremental|GetMTime",
     "FUNC|printer|FormatGeneratedName",
     "FUNC|printer|GetDefaultIndentSize",
     "FUNC|printer|GetEmitContext",

package/tools/shim_audit/main.go

@@ -90,6 +90,19 @@ var shimDirs = map[string]string{
   "vfs/osvfs":        "vfs/osvfs",
 }
 
+// auditOnlyInternal lists upstream internal packages that shim sources
+// reference — go:linkname targets and blank imports that compile them into
+// consumer binaries — without owning a shim directory of their own. They are
+// loaded for type information so the shim import scan can resolve them; their
+// exported surface then enters the ratcheted reachable-gap scan like any other
+// loaded package, so unneeded helpers are accepted into baseline.json rather
+// than silently skipped.
+var auditOnlyInternal = []string{
+  // shim/compiler/incremental.go linknames the incremental engine's
+  // reference-graph functions (getReferencedFiles, fileAffectsGlobalScope).
+  "execute/incremental",
+}
+
 // reachable holds, per upstream package suffix, the set of upstream symbol names
 // the shim makes nameable (selector references + linkname targets).
 type reachable map[string]map[string]bool
@@ -525,6 +538,10 @@ func loadInner(anchorDir string) (map[string]*packages.Package, error) {
     full = append(full, internalPrefix+suffix)
     expected[suffix] = true
   }
+  for _, suffix := range auditOnlyInternal {
+    full = append(full, internalPrefix+suffix)
+    expected[suffix] = true
+  }
   loaded, err := packages.Load(&packages.Config{
     Dir:  anchorDir,
     Mode: packages.LoadTypes | packages.NeedDeps | packages.NeedImports,