ttsc 0.34.1 → 0.34.3

package/src/compiler/internal/resolveNativeTypeScriptPackage.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Find native TypeScript from a filename used as a Node resolution anchor.
+ *
+ * The nearest ancestor manifest declaring TypeScript or its npm aliases owns
+ * discovery. Its aliases targeting `typescript` precede the ordinary name. A
+ * manifest reporting a compiler major below 7 belongs to the JavaScript
+ * compiler and is skipped. Missing or nonnumeric version metadata retains the
+ * existing path-discovery behavior; executable availability is the caller's
+ * responsibility. Alias candidates must report the actual package name
+ * `typescript` and a native major. Multiple distinct native alias installs are
+ * ambiguous and require an explicit binary. Read and parse errors propagate,
+ * except a disappeared manifest is treated as an absent candidate.
+ *
+ * @evidence contracts/common.md#principled-implementation Project and ancestor dependency maps supply npm aliases by their declared target; Node resolves those arbitrary names from the caller's filename, and installed name/version metadata verifies native identity. Distinct native alias installs are rejected as ambiguous rather than selected by spelling or declaration order.
+ * @evidence contracts/common.md#clear-and-simple-design One owner selects manifest metadata for executable resolution and plugin version keys so they cannot choose different package names.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The real package identity and npm alias syntax define discovery; no particular alias, consumer identity or guessed executable is embedded.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines anchor semantics, alias precedence, legacy rejection, incomplete metadata behavior and propagated read failures.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire follows native Node package resolution and synchronous filesystem reads without shell commands or path case assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms The ancestor walk parses its manifests and visits their declared dependency entries once, then resolves and reads only A distinct aliases plus the ordinary name. Sorting alias names costs O(A log A); Node lookup, realpath and manifest bytes contribute delegated costs. Installed dependency trees are never scanned.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Project installations can change between calls, and this operation owns no invalidation source that would justify a retained result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous reads retain no open handles and the caller owns the returned metadata.
+ */
+export function resolveNativeTypeScriptPackage(
+  from: string,
+): { packageJson: string; manifest: Record<string, unknown> } | undefined {
+  const requireFrom = createRequire(from);
+  const aliases = new Set<string>();
+  for (
+    let directory = path.dirname(from);
+    ;
+    directory = path.dirname(directory)
+  ) {
+    const project = readManifest(path.join(directory, "package.json"));
+    let declaresTypeScript = false;
+    for (const field of [
+      "dependencies",
+      "devDependencies",
+      "optionalDependencies",
+    ]) {
+      const dependencies = project?.[field];
+      if (dependencies === null || typeof dependencies !== "object") continue;
+      declaresTypeScript ||= Object.hasOwn(dependencies, "typescript");
+      for (const [name, specifier] of Object.entries(dependencies))
+        if (
+          name !== "typescript" &&
+          typeof specifier === "string" &&
+          /^npm:typescript(?:@|$)/.test(specifier)
+        )
+          aliases.add(name);
+    }
+    if (declaresTypeScript || aliases.size) break;
+    if (path.dirname(directory) === directory) break;
+  }
+  let selected:
+    | { packageJson: string; manifest: Record<string, unknown> }
+    | undefined;
+  for (const name of [...aliases].sort().concat("typescript")) {
+    if (name === "typescript" && selected) return selected;
+    let packageJson: string;
+    try {
+      packageJson = requireFrom.resolve(`${name}/package.json`);
+    } catch {
+      continue;
+    }
+    const manifest = readManifest(packageJson);
+    if (!manifest) continue;
+    const majorText =
+      typeof manifest.version === "string"
+        ? manifest.version.split(".")[0]!
+        : "";
+    const major = /^\d+$/.test(majorText) ? Number(majorText) : NaN;
+    if (major < 7) continue;
+    if (
+      name !== "typescript" &&
+      (manifest.name !== "typescript" || !Number.isFinite(major))
+    )
+      continue;
+    const candidate = { packageJson, manifest };
+    if (name === "typescript") return candidate;
+    if (
+      selected &&
+      fs.realpathSync(selected.packageJson) !== fs.realpathSync(packageJson)
+    )
+      throw new Error(
+        "ttsc: multiple native TypeScript aliases are installed; select one with --binary or TTSC_TSGO_BINARY.",
+      );
+    selected = candidate;
+  }
+  return selected;
+}
+
+/** Read current manifest bytes, including after Node cached an older path. */
+function readManifest(file: string): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+  } catch (error) {
+    if (
+      ["ENOENT", "ENOTDIR"].includes(
+        (error as NodeJS.ErrnoException).code ?? "",
+      )
+    )
+      return undefined;
+    throw error;
+  }
+}

package/src/compiler/internal/resolveTsgo.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import { resolveNativeTypeScriptPackage } from "./resolveNativeTypeScriptPackage";
 import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
 
 /**
@@ -12,13 +13,14 @@ import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
  * 1. Select `opts.binary`, or consult `TTSC_TSGO_BINARY` only when it is absent. A
  *    nonempty override must be an existing absolute path; returns `{ binary,
  *    packageJson: "", packageRoot, version: "custom" }`.
- * 2. `typescript` resolved from the project `cwd`.
- * 3. `typescript` resolved from `opts.resolveFrom` (for test harnesses and
- *    embedders that anchor to a different directory).
+ * 2. Declared npm aliases targeting TypeScript, then native `typescript`, from
+ *    `cwd`.
+ * 3. The same discovery from `opts.resolveFrom` (for test harnesses and embedders
+ *    that anchor to a different directory).
  *
  * Throws a descriptive error when the package or platform path is missing.
  * Manifest read/parse failures can propagate directly. Existence does not
- * certify a regular executable, native ABI or compiler version compatibility;
+ * certify a regular executable, native ABI or compiler-target compatibility;
  * this operation selects paths and metadata without executing them. Platform
  * package resolution is anchored at the chosen TypeScript manifest and can
  * follow Node's ancestor search, rather than proving both packages occupy one
@@ -29,7 +31,7 @@ import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Package names and lib/tsc suffixes follow the native TypeScript distribution contract. Missing dependencies remain descriptive errors rather than invented compiler paths or fixture-specific substitutes.
  * @evidence contracts/common.md#meaningful-documentation Ordered precedence, custom metadata and failures are documented separately, and the fallback anchor member explains its filename semantics following the documentation skill.
  * @evidence contracts/portability.md#os-neutral-implementation Native path APIs validate absolute overrides and select the Windows executable suffix; createRequire anchors resolution to actual package files without shell quoting or OS-derived case policy.
- * @evidence contracts/performance.md#efficient-algorithms A precedence sequence makes at most two TypeScript resolution attempts, one platform resolution and one manifest parse of M bytes. Node ancestor/package lookup, native existence checks and path text work have delegated costs; Windows environment override selection scans environment keys through SidecarEnvironment. Returned metadata does not retain the full parsed manifest.
+ * @evidence contracts/performance.md#efficient-algorithms Up to two anchors delegate ancestor manifest and alias discovery before one platform lookup. Dependency declaration counts, alias lookups, manifest bytes and path work determine cost; Windows environment selection scans environment keys through SidecarEnvironment. Returned metadata does not retain parsed manifests.
  *
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work Overrides and consumer installations are mutable filesystem authority; this resolver owns no dependency invalidation source that could justify retaining a custom result across calls.
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous package reads retain no handles or tasks; returned path and version strings transfer to the caller without a historical metadata table.
@@ -39,7 +41,7 @@ export function resolveTsgo(
     /** Explicit path to a native `tsc` binary; bypasses package resolution. */
     binary?: string;
 
-    /** Directory from which to discover `typescript`. */
+    /** Directory from which to discover native TypeScript. */
     cwd?: string;
 
     /**
@@ -75,26 +77,23 @@ export function resolveTsgo(
   }
 
   const cwd = path.resolve(opts.cwd ?? process.cwd());
-  // Resolve the package.json of typescript.
-  // Try cwd first, then the optional resolveFrom anchor.
-  let packageJson: string;
-  packageJson =
-    resolveTypeScriptPackageJson(path.join(cwd, "package.json")) ??
+  const selected =
+    resolveNativeTypeScriptPackage(path.join(cwd, "package.json")) ??
     (opts.resolveFrom
-      ? resolveTypeScriptPackageJson(opts.resolveFrom)
-      : undefined) ??
-    "";
-  if (!packageJson) {
+      ? resolveNativeTypeScriptPackage(opts.resolveFrom)
+      : undefined);
+  if (!selected) {
     throw new Error(
       [
-        "ttsc: typescript is required.",
+        "ttsc: native TypeScript 7 or newer is required.",
         "Install the native TypeScript compiler in the consuming project:",
         "  npm i -D typescript",
+        "For legacy tooling, declare an npm:typescript@^7 alias in package.json.",
       ].join("\n"),
     );
   }
 
-  const manifest = readPackageJson(packageJson);
+  const { packageJson, manifest } = selected;
   const packageRoot = path.dirname(packageJson);
   const platformPackage = `@typescript/typescript-${process.platform}-${process.arch}`;
   const platformResolver = createRequire(packageJson);
@@ -107,7 +106,7 @@ export function resolveTsgo(
     throw new Error(
       [
         `ttsc: platform-specific TypeScript binary not found (${platformPackage}).`,
-        "Reinstall typescript with optional dependencies enabled.",
+        "Reinstall the selected native TypeScript package with optional dependencies enabled.",
       ].join("\n"),
     );
   }
@@ -132,21 +131,3 @@ export function resolveTsgo(
       typeof manifest.version === "string" ? manifest.version : "unknown",
   };
 }
-
-/**
- * Resolve TypeScript relative to an absolute filename accepted by
- * createRequire. Returns undefined when the anchor or package cannot be
- * resolved.
- */
-function resolveTypeScriptPackageJson(from: string): string | undefined {
-  try {
-    return createRequire(from).resolve("typescript/package.json");
-  } catch {
-    return undefined;
-  }
-}
-
-/** Parse a JSON file and return the result as a plain object. */
-function readPackageJson(file: string): Record<string, unknown> {
-  return JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-}

package/src/internal/CompilerResultAdapter.ts

@@ -217,15 +217,17 @@ function toCompilerResult(project: ProjectResult): ITtscCompilerResult {
 }
 
 /**
- * Adapt source/build outcome and copy optional advisory references only when
- * present.
+ * Adapt source/build outcome and preserve optional advisory values. Mapper
+ * project inputs join each source's declared dependencies on success and
+ * failure; they do not become compiler-read observations or completeness
+ * certificates.
  *
- * @evidence contracts/common.md#principled-implementation Undefined advisory fields are omitted; present empty/false values and references survive both success and failure, alongside the existing diagnostic decision.
+ * @evidence contracts/common.md#principled-implementation Undefined advisory fields are omitted and present empty/false values survive both success and failure. Universal mapper declarations join source dependencies with own-key safety; compiler completeness and read witnesses retain their independent meaning.
  * @evidence contracts/common.md#clear-and-simple-design One optional-field projection is shared by the two result branches.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter does not manufacture graph, host-read or completeness proof and does not discard it solely because the build failed.
- * @evidence contracts/common.md#meaningful-documentation The native sentence states omission policy and reference ownership.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes mapper declarations from read proof and completeness on both result branches.
  * @evidenceExclude contracts/portability.md#os-neutral-implementation Advisory values are passed through without native path normalization or capability inference.
- * @evidence contracts/performance.md#efficient-algorithms Fixed optional-field checks retain references without scanning map text; diagnostic classification and empty-failure formatting have their delegated data costs.
+ * @evidence contracts/performance.md#efficient-algorithms Optional fields retain references unless mapper inputs require a per-source Set union. Work and copied storage follow source keys plus each source's dependency/input text; diagnostic classification and failure formatting keep their delegated costs.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adaptation coordinates no reusable compiler/worker or outcome cache.
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned source/advisory objects remain reachable under caller ownership; this operation owns no process, lease or historical registry.
  */
@@ -233,7 +235,7 @@ export function toCompilerTransformation(
   project: ProjectTransformation,
 ): ITtscCompilerTransformation {
   const {
-    dependencies,
+    dependencies: reportedDependencies,
     dependenciesComplete,
     graph,
     hostInputHashes,
@@ -247,6 +249,27 @@ export function toCompilerTransformation(
     typescript,
     volatile,
   } = project;
+  let dependencies = reportedDependencies;
+  if (graph?.contentMapperInputs?.length) {
+    const keys = new Set([
+      ...Object.keys(typescript),
+      ...Object.keys(graph.edges),
+    ]);
+    dependencies = Object.fromEntries([
+      ...Object.entries(dependencies ?? {}).filter(([key]) => !keys.has(key)),
+      ...Array.from(keys, (key) => [
+        key,
+        [
+          ...new Set([
+            ...(Object.hasOwn(dependencies ?? {}, key)
+              ? dependencies![key]!
+              : []),
+            ...graph.contentMapperInputs!,
+          ]),
+        ].filter((input) => input !== key),
+      ]),
+    ]);
+  }
   const advisoryFields = {
     ...(dependencies === undefined ? {} : { dependencies }),
     ...(dependenciesComplete === undefined ? {} : { dependenciesComplete }),

package/src/internal/nativeBinary.ts

@@ -7,5 +7,9 @@
  * `@ttsc/unplugin` runs its native watch helpers, imports them from here, so
  * the helper always comes from the binary ttsc itself uses and no consumer
  * carries a copy of the rules.
+ *
+ * `resolveTsgo` selects the consumer's native TypeScript compiler, including
+ * npm aliases targeting TypeScript used alongside legacy tooling.
  */
 export { resolveBinary } from "../compiler/internal/resolveBinary";
+export { resolveTsgo } from "../compiler/internal/resolveTsgo";

package/src/launcher/internal/prepareExecution.ts

@@ -743,7 +743,9 @@ function collectLinkDirectories(projectRoot: string): string[] {
 }
 
 /**
- * Whether mirroring `directory` would reach a filesystem or temporary root.
+ * Whether mirroring `directory` would reach a filesystem root, the temporary
+ * root or any of its ancestors. A caller can place its temporary root inside
+ * its project; its parents still contain shared entries outside that project.
  * Identity comparison is required on Windows, where `os.tmpdir()` can carry an
  * 8.3 component while a project created below it is returned in long spelling.
  */
@@ -754,7 +756,10 @@ function isUnsafeVirtualParent(
   const resolved = identities.resolve(directory);
   const root = identities.resolve(path.parse(resolved.path).root);
   const temporaryRoot = identities.resolve(os.tmpdir());
-  return resolved.key === root.key || resolved.key === temporaryRoot.key;
+  return (
+    resolved.key === root.key ||
+    identities.isWithin(resolved.path, temporaryRoot.path)
+  );
 }
 
 /**

package/src/plugin/internal/source/pluginBuildVersions.ts

@@ -1,7 +1,6 @@
-import fs from "node:fs";
-import { createRequire } from "node:module";
 import path from "node:path";
 
+import { resolveNativeTypeScriptPackage } from "../../../compiler/internal/resolveNativeTypeScriptPackage";
 import { ttscPackageVersion } from "./ttscPackageVersion";
 
 /**
@@ -14,14 +13,15 @@ import { ttscPackageVersion } from "./ttscPackageVersion";
  * consumer that keeps a transform's output beyond the process that produced it,
  * as a persisted shared compile of `@ttsc/unplugin` is, names it by these
  * versions with the rule the build applies instead of a copy of it: ttsc's own
- * package version, and the version of the `typescript` package the project
- * resolves, or `"unknown"` when resolution/read/parse fails or its version is
- * absent. The host label falls back to `"0.0.0"` and is cached even after an
- * unsuccessful first read. The host installation is assumed stable for the
- * process lifetime; changing its manifest does not refresh that label.
+ * package version, and the version of the native TypeScript package the project
+ * selects (declared npm aliases before `typescript`), or `"unknown"` when
+ * resolution/read/parse fails or its version is absent. The host label falls
+ * back to `"0.0.0"` and is cached even after an unsuccessful first read. The
+ * host installation is assumed stable for the process lifetime; changing its
+ * manifest does not refresh that label.
  *
- * @param projectRoot The project base used to resolve
- *   `typescript/package.json`.
+ * @param projectRoot The project base used to resolve the native TypeScript
+ *   manifest.
  * @evidence contracts/common.md#principled-implementation Package-version labels supply the same metadata tuple used by plugin keys; absent/unreadable metadata receives the documented unknown/default label rather than an executable identity certificate.
  * @evidence contracts/common.md#clear-and-simple-design The host label comes from its own owner (`ttscPackageVersion`), which a reader needing only that label calls without this function's project resolution; the project-version reader is separate because project resolution varies per call.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Node package resolution determines the actual project dependency; no particular project or fixture version is embedded.
@@ -40,14 +40,12 @@ export function pluginBuildVersions(projectRoot: string): {
 
 function readTsgoVersion(projectRoot: string): string {
   try {
-    const projectRequire = createRequire(
+    const selected = resolveNativeTypeScriptPackage(
       path.join(projectRoot, "package.json"),
     );
-    const pkgPath = projectRequire.resolve("typescript/package.json");
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
-      version?: string;
-    };
-    return pkg.version ?? "unknown";
+    return typeof selected?.manifest.version === "string"
+      ? selected.manifest.version
+      : "unknown";
   } catch {
     return "unknown";
   }

package/src/structures/ITtscCompilerTransformation.ts

@@ -51,6 +51,23 @@ 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 {
+    /**
+     * Effective native possible-root suffixes and output-directory exclusions.
+     * A report that differs from a host's provisional policy requires a new
+     * membership walk. Directory paths are absolute; null clears an option.
+     * Authored files/include and explicit excludes remain configuration
+     * inputs.
+     */
+    membership?: {
+      /** Original suffix spellings admitted by the compiler and its mappers. */
+      inputExtensions: string[];
+
+      /** Effective absolute output directory, or null when unset. */
+      outDir: string | null;
+
+      /** Effective absolute declaration directory, or null when unset. */
+      declarationDir: string | null;
+    };
     /**
      * Direct resolved references per file: imports, re-exports, `///
      * <reference>` targets, and type reference directives — type-only edges
@@ -82,10 +99,20 @@ export namespace ITtscCompilerTransformation {
 
     /**
      * Automatic type discovery and resolution inputs that affect every source,
-     * including effective type-root directory membership.
+     * including compiler response files and effective type-root directory
+     * membership. Failed loads can retain their observed CLI/config recovery
+     * paths here without a completed Program or source population.
      */
     resolutionInputs?: string[];
 
+    /**
+     * Mapper package manifests and dynamic project watchedFiles. These are
+     * declared dependencies for every output, including files whose plugin
+     * dependencies are complete. They carry no compiler-read proof: consumers
+     * must witness them before compilation and compare afterward.
+     */
+    contentMapperInputs?: string[];
+
     /**
      * Filesystem predicates recorded during construction and resolver replay
      * for this graph. Each property is independent: `fileExists: false` and

package/targets/7.1/bridge/compiler/neutral.go

@@ -3,6 +3,8 @@ package compiler
 import (
   "context"
   "errors"
+  "path/filepath"
+  "sort"
   "sync"
 
   innerast "github.com/microsoft/TypeScript/tsc/internal/ast"
@@ -52,7 +54,7 @@ func NewHost(currentDirectory innertspath.RootedDirectoryPath, fs innervfs.FS, d
 // @evidence contracts/common.md#prohibited-implementation-shortcuts The compiler's own runExternalCode gate and mapper resolution decide whether mappers run; no ttsc authorization or mapping policy is added.
 // @evidence contracts/common.md#meaningful-documentation Native prose states when mappers run, the nil meaning and the 7.0 difference.
 // @evidence contracts/portability.md#os-neutral-implementation Mapper processes start through spawnContentMapper's os/exec boundary in each mapper package's directory; the supplied FS owns every file read.
-// @evidenceExclude contracts/performance.md#efficient-algorithms The type stores two handles and chooses no algorithm.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This declaration chooses no algorithm; its fields retain shared mapper state and resolved manifest names.
 // @evidence contracts/performance.md#reuse-equivalent-work Every host built from one ProjectHosts shares one mapper project, so an incremental generation reuses the processes the first generation started.
 // @evidence contracts/performance.md#bound-retention-and-release-resources The mapper project and host, and with them every spawned mapper process, live until Close; Close releases them once.
 type ProjectHosts struct {
@@ -60,6 +62,7 @@ type ProjectHosts struct {
   project   contentmapper.Project
   closeOnce sync.Once
   closeErr  error
+  manifests []string
 }
 
 // NewProjectHosts returns the hosts of Programs built from config. It starts
@@ -69,8 +72,8 @@ type ProjectHosts struct {
 // @evidence contracts/common.md#clear-and-simple-design One gate returns either a nil value or a value holding the mapper project.
 // @evidence contracts/common.md#prohibited-implementation-shortcuts Mapper resolution and its diagnostics stay with the config parser; this function adds none.
 // @evidence contracts/common.md#meaningful-documentation Native prose states that construction starts no process.
-// @evidence contracts/portability.md#os-neutral-implementation Construction performs no native operation; mapper processes start later through spawnContentMapper.
-// @evidenceExclude contracts/performance.md#efficient-algorithms Construction checks one option and one slice length.
+// @evidence contracts/portability.md#os-neutral-implementation Native filepath.Join constructs manifest paths in resolved package directories; mapper processes start later through spawnContentMapper.
+// @evidence contracts/performance.md#efficient-algorithms Construction checks the gate and copies each configured mapper package directory into a manifest path. Cost and returned path storage follow mapper count and path text.
 // @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call opens its own mapper state; callers share it by holding the value.
 // @evidence contracts/performance.md#bound-retention-and-release-resources The returned value owns the mapper host and project until Close.
 func NewProjectHosts(config *innertsoptions.ParsedCommandLine) *ProjectHosts {
@@ -79,8 +82,15 @@ func NewProjectHosts(config *innertsoptions.ParsedCommandLine) *ProjectHosts {
   }
   diagnosticLocale, _ := innerlocale.Parse(config.CompilerOptions().Locale)
   mappers := contentmapper.NewHost(context.Background(), contentmapper.SpawnerFunc(spawnContentMapper), diagnosticLocale)
+  manifests := make([]string, 0, len(config.ContentMappers()))
+  for _, mapper := range config.ContentMappers() {
+    if mapper.PackageDirectory != "" {
+      manifests = append(manifests, filepath.Join(string(mapper.PackageDirectory), "package.json"))
+    }
+  }
   return &ProjectHosts{
-    mappers: mappers,
+    manifests: manifests,
+    mappers:   mappers,
     project: mappers.Project(contentmapper.ProjectSpec{
       ConfigFileName:  config.ConfigName(),
       Mappers:         config.ContentMappers(),
@@ -89,6 +99,31 @@ func NewProjectHosts(config *innertsoptions.ParsedCommandLine) *ProjectHosts {
   }
 }
 
+// Dependencies returns mapper manifests and upstream-declared dynamic inputs.
+// WatchedFiles can open dynamic project configuration; its error is returned
+// alongside manifests so callers keep recovery inputs without claiming success.
+//
+// @evidence contracts/common.md#principled-implementation Uses the pinned upstream Project.WatchedFiles declaration and resolved mapper package directories; it does not infer reads from mapper code.
+// @evidence contracts/common.md#clear-and-simple-design One projection transfers the project-owned dependency population without changing the mapper protocol.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Upstream errors remain errors and manifests remain available for recovery; no post-compile hash is invented.
+// @evidence contracts/common.md#meaningful-documentation Native prose documents lazy opening, declaration scope and partial error results.
+// @evidence contracts/portability.md#os-neutral-implementation Native filepath.Join anchors manifests in resolved package directories; upstream watched paths retain their absolute native spelling.
+// @evidence contracts/performance.md#efficient-algorithms Copies declared input names and sorts them; upstream WatchedFiles can open dynamic mapper projects and perform protocol IO.
+// @evidence contracts/performance.md#reuse-equivalent-work Upstream project state shares opened configuration; each returned slice is independently owned.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned names escape to the caller; ProjectHosts still owns mapper lifetime through Close.
+func (h *ProjectHosts) Dependencies() ([]string, error) {
+  if h == nil {
+    return nil, nil
+  }
+  inputs := append([]string(nil), h.manifests...)
+  watched, err := h.project.WatchedFiles()
+  for _, file := range watched {
+    inputs = append(inputs, string(file))
+  }
+  sort.Strings(inputs)
+  return inputs, err
+}
+
 // Host returns a compiler host over fs, like NewHost, that transforms
 // content-mapped files through this project's mappers.
 //

package/utility/host.go

@@ -48,6 +48,9 @@ type hostOptions struct {
   // host sets it (to an OverlayFS), so build/check/transform leave it nil and
   // LoadProgram falls back to the default filesystem.
   fs vfs.FS
+
+  // failureInputs receives the loader's actual pre-Program recovery graph.
+  failureInputs func(*driver.TransformGraph)
 }
 
 // transformResult is the JSON envelope written to stdout by RunTransform.
@@ -115,8 +118,8 @@ func RunCheck(args []string) int {
 //
 // After successful flag admission, requested metadata is attempted on both
 // successful and failed checks and belongs to that check generation. A missing
-// generation is explicitly incomplete; rejected flag admission installs no
-// publication defer. Input authority does not erase status or diagnostics.
+// generation is explicitly incomplete but retains observed load-recovery paths.
+// Rejected flag admission installs no publication defer. Input authority does not erase status or diagnostics.
 // Callers own the metadata artifact's removal and supplied-stream lifetime.
 // Diagnostic/report writes are best-effort and are not delivery receipts.
 //
@@ -135,9 +138,13 @@ func RunCheckWithIO(args []string, stdout, stderr io.Writer) (status int) {
   }
   opts.noEmit = true
   var prog *driver.Program
+  var recovery *driver.TransformGraph
+  if opts.checkObservationsJSON != "" {
+    opts.failureInputs = func(graph *driver.TransformGraph) { recovery = graph }
+  }
   defer func() {
     if opts.checkObservationsJSON != "" {
-      if err := driver.WriteCheckObservationsJSON(opts.checkObservationsJSON, prog); err != nil {
+      if err := driver.WriteCheckRecoveryObservationsJSON(opts.checkObservationsJSON, prog, recovery); err != nil {
         fmt.Fprintf(opts.stderr, "ttsc utility: check observations write failed: %v\n", err)
         if status == 0 {
           status = 3
@@ -307,8 +314,9 @@ func RunTransform(args []string) int {
 // Failed projects retain diagnostics and recovery inputs but publish no partial
 // TypeScript. Encoding or response-write failure returns 3; project failure
 // returns 2.
-// Recovery envelopes require a loaded generation; flag admission or load failure
-// returns before response construction. A loaded generation's graph is captured
+// Rejected flag admission or a loader error returns before response construction.
+// Config/argument diagnostics can retain observed recovery predicates without a
+// Program. A loaded generation's graph is captured
 // before linked program hooks mutate its ASTs. Diagnostic stream reporting is
 // best-effort; response encoding and returned write errors determine delivery
 // status. Callers own the supplied stream lifetimes.
@@ -326,16 +334,20 @@ func RunTransformWithIO(args []string, stdout, stderr io.Writer) int {
   if !ok {
     return 2
   }
+  out := transformResult{TypeScript: map[string]string{}}
+  opts.failureInputs = func(graph *driver.TransformGraph) { out.Graph = graph }
   prog, _, diags, ok := loadUtilityProgramWithDiagnostics(opts)
   if !ok {
     return 2
   }
-  out := transformResult{TypeScript: map[string]string{}}
   if prog != nil {
     defer prog.Close()
     // The same failed Program owns the missing resolution candidates needed
     // for recovery. Capture them before closing it or applying mutations.
     out.Graph = driver.NewTransformGraph(prog, opts.cwd)
+  } else {
+    unavailable := false
+    out.ObservationsComplete = &unavailable
   }
   if len(diags) != 0 {
     driver.WritePrettyDiagnostics(opts.stderr, diags, opts.cwd)
@@ -605,6 +617,7 @@ func loadUtilityProgramWithDiagnostics(opts hostOptions) (*driver.Program, []dri
     Checkers:           opts.checkers,
     TsgoArgs:           opts.tsgoArgs,
     FS:                 opts.fs,
+    OnFailureInputs:    opts.failureInputs,
   })
   if err != nil {
     fmt.Fprintf(opts.stderr, "ttsc utility: %v\n", err)