ttsc 0.34.2 → 0.35.0

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

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

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

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

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

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

package/src/compiler/internal/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>;
-}