ttsc 0.30.4 → 0.31.0

package/src/launcher/internal/prepareExecution.ts

@@ -1,47 +1,109 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { isOutsideRelativePath } from "../../compiler/internal/paths";
+import { EmitOwnershipIndex } from "../../compiler/internal/EmitOwnershipIndex";
+import { privateRuntimeRootDir } from "../../compiler/internal/build/privateRuntimeRootDir";
+import { runBuild } from "../../compiler/internal/build/runBuild";
 import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
-import { resolveEmittedJavaScript } from "../../compiler/internal/resolveEmittedJavaScript";
-import { runBuild } from "../../compiler/internal/runBuild";
-import { createFilesystemPathIdentityContext } from "../../internal/projectInputPathIdentity";
+import { resolveOwningProjectConfig } from "../../compiler/internal/project/resolveOwningProjectConfig";
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
+import { createFilesystemPathIdentityContext } from "../../internal/pathIdentity/createFilesystemPathIdentityContext";
+import { SourceBuildCacheLayout } from "../../plugin/internal/source/SourceBuildCacheLayout";
+import { resolveSourceBuildCachePaths } from "../../plugin/internal/source/resolveSourceBuildCachePaths";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+import { assertTtsxNoWatch } from "./assertTtsxNoWatch";
+import { buildSingleRootProject } from "./buildSingleRootProject";
+import { linkVirtualEntry } from "./linkVirtualEntry";
+import { resolveCacheDir } from "./resolveCacheDir";
+import { type OwningModuleOptions } from "./runtime/OwningModuleOptions";
+import { ProcessOwnedDirectory } from "./runtime/ProcessOwnedDirectory";
+import { RuntimeEmitProvenance } from "./runtime/RuntimeEmitProvenance";
+import { claimRuntimeProjectDirectory } from "./runtime/claimRuntimeProjectDirectory";
+import { runtimeRunKey } from "./runtime/runtimeRunKey";
+import { withRuntimeDirectoryLock } from "./runtime/withRuntimeDirectoryLock";
 import { runtimeCompilerArgs } from "./runtimeCompilerArgs";
-import { type OwningModuleOptions, projectModuleOptions } from "./runtimeHooks";
+import { runtimeEmitProfile } from "./runtimeEmitProfile";
 
 /**
- * Maximum number of ancestor directories above the project root that the
- * virtual filesystem overlay mirrors. Three levels covers the common monorepo
- * layout (workspace-root → packages → package-root) so `node_modules` symlinks
- * resolve correctly without reaching an unsafe boundary.
- */
-const MAX_VIRTUAL_PARENT_DEPTH = 3;
-/**
- * Emit directory of the entry-only fallback build, a sibling of the virtual
- * layout's volume-label directories so it can never collide with a mirrored
- * project path.
+ * Build the owning project and locate the JavaScript emitted from the requested
+ * entry for `ttsx`. An entry excluded from that project receives a checked
+ * single-entry build inheriting its compiler settings.
+ *
+ * Discovery uses the caller's spelling while emit ownership uses filesystem
+ * identity. The result transfers the process-owned runtime directory to the
+ * caller for execution and cleanup. After context creation returns, preparation
+ * failure attempts relinquishment and removal here; native lock or cleanup
+ * failure can prevent release. Context construction owns its acquisition
+ * failures. Successful execution must release the transferred directory through
+ * the runtime directory protocol.
+ *
+ * Source ownership comes from the completed compiler's output-to-source record;
+ * a producer without that record is unsupported for checked execution. An
+ * observed empty output inventory selects the checked single-entry build and
+ * supplies no authority to execute output from the empty project.
+ *
+ * @evidence contracts/common.md#principled-implementation Project discovery retains the requested lexical anchor; validated compiler provenance, not a stem or source-map inference, supplies EmitOwnershipIndex with actual output ownership. An observed empty JavaScript inventory or proven excluded entry selects the checked single-root build, which must supply its own ledger before execution.
+ * @evidence contracts/common.md#clear-and-simple-design Context creation, project compilation, entry fallback and output selection have distinct helpers. After a context returns, one failure boundary attempts cleanup without replacing the original error; construction owns earlier acquisition failures.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or malformed provenance cannot authorize emitted bytes. An empty inventoried build serves nothing and selects the excluded-entry build, which inherits actual project settings and proves its own output rather than stripping source or fabricating an empty ledger.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain discovery, cleanup and mandatory producer provenance; result members distinguish relative output-list paths from absolute output-to-source records without property acknowledgments.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path/identity helpers preserve lexical discovery separately from best-effort native source/cache coordinates. Cooperating directory locks serialize ownership mutations without pinning filesystem objects; virtual layout encodes distinct volume roots through native path operations rather than shell commands.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated config discovery, effective-options preparation and compilation precede native output inventory and provenance-shape inspection. Each nonempty entry lookup builds an EmitOwnershipIndex with record/path/identity costs; an empty inventory or unowned entry selects the additional checked build. Native virtual linking and bounded ancestor traversal add their own entry and byte costs, so entry counts alone do not bound this operation.
+ * @evidence contracts/performance.md#reuse-equivalent-work A context retains the accepted producer record and output inventory for lookup and transfer, without synthesizing ownership or re-reading producer observations. Lookup indexes are constructed per lookup. One original-request reader serves source-root selection, the profile and argument lowering within this context; changed lowered arguments and completed-emit provenance keep their separate observations. Checked fallback shares its own overlay reader within that build and then replaces the generation and recomputes the context profile.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A returned context owns one claimed generation at the resolved cache coordinate. Later failures attempt relinquishment and recursive removal under its cooperative lock; cleanup errors are swallowed to preserve the initiating failure and can retain storage. Success transfers cleanupDir and runtimeCacheDir to the caller, while delegated compilers, identity contexts and construction failures retain their own lifecycle responsibilities.
  */
-const ENTRY_PROJECT_EMIT_DIR = "entry-project";
-
-/** Build the owning project and locate the emitted JavaScript entry for `ttsx`. */
 export function prepareExecution(
   entryFile: string,
   options: TtscCommonOptions & {
+    /** Explicit runtime/plugin cache path relative to the invocation directory. */
     cacheDir?: string;
+
+    /** Explicit project config; absence discovers the entry's owning project. */
     project?: string;
+
     /** Internal cache key for more than one checked entry in this process. */
     runtimeCacheKey?: string;
   } = {},
 ): {
+  /** Claimed runtime generation whose cleanup ownership transfers to the caller. */
   cleanupDir: string;
+
+  /** Native directory coordinate containing this preparation's emitted output. */
   emitDir: string;
-  emittedFiles?: readonly string[];
+
+  /** Emitted JavaScript file owned by the requested source entry. */
   entryFile: string;
+
+  /** Resolved cache coordinate whose cooperative lock serializes run and clean. */
+  runtimeCacheDir: string;
+
+  /** Resolved directory coordinate holding the run when `project` is a link. */
+  runtimeRunsDir: string;
+
+  /** The build's record of its outputs, relative to `emitDir`. */
+  outputs: readonly string[];
+
+  /** Compiler-observed absolute output paths and their contributing sources. */
+  emittedSources: Readonly<Record<string, readonly string[]>>;
+
+  /** Output-specific observed proof failures, without an ownership guarantee. */
+  emittedSourceProofFailures?: Readonly<Record<string, string>>;
+
+  /** Physical source-entry spelling used for emit ownership and Node loading. */
   entrySource: string;
+
+  /** Effective project module settings used to classify emitted runtime files. */
   moduleOptions: OwningModuleOptions;
+
+  /** Where the run keeps its lowered orphan sources, under its cache root. */
+  orphanCacheDir: string;
+
+  /** Owning project's physical directory. */
   projectRoot: string;
+
+  /** Physical source root whose relative paths are mirrored in the runtime emit. */
   rootDir: string;
 } {
   // Two paths, because two different questions are being asked.
@@ -74,53 +136,104 @@ export function prepareExecution(
     return {
       cleanupDir: context.processDir,
       emitDir: context.emitDir,
-      emittedFiles: context.emittedFiles ?? undefined,
       entryFile: emittedEntry,
+      runtimeCacheDir: context.cacheDir,
+      runtimeRunsDir: path.dirname(context.processDir),
       entrySource: entry,
+      outputs: context.outputs,
+      emittedSources: executionProvenance(context),
+      emittedSourceProofFailures: context.emittedSourceProofFailures,
       moduleOptions: context.moduleOptions,
+      orphanCacheDir: context.orphanCacheDir,
       projectRoot: context.root,
       rootDir: context.runtimeRootDir,
     };
   } catch (error) {
-    removeRuntimeOutput(context.processDir);
+    removeRuntimeOutput(context.processDir, context.cacheDir);
     throw error;
   }
 }
 
 /**
- * The JavaScript this build emitted for `entry`, or `null` when it emitted none
- * — which is the signal that the entry sits outside the project's file set.
- *
- * The guard is what makes this an ownership answer rather than a guess. tsgo
- * strips `runtimeRootDir` from every output path, so a file outside that root
- * cannot have an output under `outDir` at all; without the guard the lookup
- * falls through to `resolveEmittedJavaScript`'s trailing-stem matcher, and a
- * `build/release.ts` would happily match the `release.js` emitted for an
- * unrelated `src/release.ts` — running the wrong file instead of compiling the
- * requested one.
+ * Maximum number of ancestor directories above the project root that the
+ * virtual filesystem overlay mirrors. Three levels covers the common monorepo
+ * layout (workspace-root → packages → package-root) so `node_modules` symlinks
+ * resolve correctly without reaching an unsafe boundary.
+ */
+const MAX_VIRTUAL_PARENT_DEPTH = 3;
+
+/**
+ * Emit directory of the entry-only fallback build, a sibling of the virtual
+ * layout's volume-label directories so it can never collide with a mirrored
+ * project path.
+ */
+const ENTRY_PROJECT_EMIT_DIR = "entry-project";
+
+/**
+ * The JavaScript this build proves it emitted from `entry`, or `null` when its
+ * complete provenance excludes that source. Missing, incomplete or ambiguous
+ * ownership throws instead of being treated as an excluded entry.
  *
- * It is lexical on purpose, and it is the same test `resolveEmittedJavaScript`
- * then applies — including its rejection of an entry that _is_ the root. That
- * only holds because both sides are _produced_ physically: the entry by
- * `resolveEntrySpelling`, the root by `resolveRuntimeSourceRoot`. Folding here
- * instead would paper over a mixed pair and disagree with the mirror that runs
- * immediately after; keeping the pair honest is what makes folding
- * unnecessary.
+ * Only an output proven to come from the entry itself counts. A
+ * `scripts/index.ts` outside `include` shares its name with the `src/index.js`
+ * the project build emitted, and taking that output would run the wrong program
+ * instead of compiling the requested one.
  */
 function emittedEntryOf(
   context: ReturnType<typeof createProjectContext>,
   entry: string,
 ): string | null {
-  const relative = path.relative(context.runtimeRootDir, entry);
-  if (relative === "" || isOutsideRelativePath(relative)) {
-    return null;
-  }
-  return resolveEmittedJavaScript({
-    emittedFiles: context.emittedFiles ?? undefined,
-    outDir: context.emitDir,
-    projectRoot: context.runtimeRootDir,
-    sourceFile: entry,
-  });
+  // A completed, inventoried build with no JavaScript cannot own this entry.
+  // This selects another checked build; it grants no authority to serve bytes.
+  if (context.outputs.length === 0) return null;
+  return new EmitOwnershipIndex({
+    emitDir: context.emitDir,
+    emittedSources: executionProvenance(context),
+    emittedSourceProofFailures: context.emittedSourceProofFailures,
+    outputs: context.outputs,
+    rootDir: context.runtimeRootDir,
+  }).find(entry);
+}
+
+/**
+ * Compile an entry the whole-project build did not emit, through a project that
+ * inherits every option and declares only the entry, then point the context at
+ * that build.
+ */
+function buildEntryProject(
+  context: ReturnType<typeof createProjectContext>,
+  options: NonNullable<Parameters<typeof prepareExecution>[1]>,
+  entry: string,
+): void {
+  const emitDir = path.join(context.virtualRoot, ENTRY_PROJECT_EMIT_DIR);
+  const { rootDir, emittedSources, emittedSourceProofFailures } =
+    buildSingleRootProject({
+      checked: true,
+      emitDir,
+      key: context.runtimeCacheKey,
+      options: { ...options, cacheDir: context.pluginCacheDir },
+      projectRoot: context.root,
+      role: "entry",
+      source: entry,
+      tsconfig: context.tsconfig,
+    });
+  context.emitDir = emitDir;
+  context.emittedSourceProofFailures = emittedSourceProofFailures;
+  context.outputs = EmitOwnershipIndex.listOutputs(emitDir);
+  context.emittedSources = requireEmitProvenance(
+    emittedSources,
+    context.tsconfig,
+  );
+  context.runtimeRootDir = rootDir;
+  // Classified by the project itself: the synthesized config only extends it
+  // with overrides that do not touch the module format, and it is already
+  // removed, so a response file expanded through `--showConfig` could not read
+  // it again.
+  context.moduleOptions = runtimeEmitProfile(
+    context.project,
+    options.passthrough,
+    options.binary,
+  ).moduleOptions;
 }
 
 /**
@@ -139,9 +252,10 @@ function emittedEntryOf(
  * transform plugins, `target`, `paths`, and source map all silently dropped —
  * from a run that still prints and still exits zero.
  *
- * Resolving the link widens `rootDir` to the ancestor the two trees share,
- * which is not a cost but the requirement: the file genuinely lives outside the
- * project, and no root that excludes it can compile it.
+ * Resolving the link can place the entry outside the project, which is the
+ * truth rather than a cost: the file genuinely lives there. The project build
+ * then does not emit it, and the entry-only build, whose private layout is
+ * rooted at the volume, compiles it wherever it lives.
  */
 function resolveEntrySpelling(cwd: string, entryFile: string): string {
   const identities = createFilesystemPathIdentityContext({
@@ -151,12 +265,13 @@ function resolveEntrySpelling(cwd: string, entryFile: string): string {
 }
 
 /**
- * Directory-safe identity for one prepared runtime. Direct `ttsx` retains its
- * historical PID directory; the public preload supplies a distinct key for
- * every late TypeScript root so one preparation cannot erase another's emit.
+ * Directory-safe identity for one prepared runtime. Direct `ttsx` names its
+ * directory by this process's run key (`runtimeRunKey`); the public preload
+ * supplies a distinct key for every late TypeScript root so one preparation
+ * cannot erase another's emit.
  */
 function resolveRuntimeCacheKey(runtimeCacheKey: string | undefined): string {
-  const key = runtimeCacheKey ?? String(process.pid);
+  const key = runtimeCacheKey ?? runtimeRunKey();
   if (!/^[A-Za-z0-9._-]+$/.test(key) || key === "." || key === "..") {
     throw new Error(`ttsx: invalid runtime cache key ${JSON.stringify(key)}`);
   }
@@ -164,6 +279,16 @@ function resolveRuntimeCacheKey(runtimeCacheKey: string | undefined): string {
 }
 
 /**
+ * Discover the project and acquire a pinned, process-owned runtime generation.
+ * One effective-options reader serves source-root selection, emit profile and
+ * argument lowering for the initial project request. A single-entry fallback
+ * prepares its own changed request; no reader is reused across invocations.
+ *
+ * The cache-root identity is fixed before descriptor execution can retarget a
+ * lexical alias. Under its directory lock, abandoned generations are swept and
+ * this run claims one private layout. The returned context owns it until
+ * failure cleanup or successful transfer to the execution caller.
+ *
  * @param discoveryFile - The entry as the user named it. Project discovery
  *   walks up from here, so it must not be retargeted through a symlink.
  */
@@ -172,25 +297,52 @@ function createProjectContext(
   discoveryFile: string,
   options: NonNullable<Parameters<typeof prepareExecution>[1]>,
 ) {
-  const project = readProjectConfig(
-    options.project
-      ? {
-          cwd,
-          projectRoot: options.projectRoot,
-          tsconfig: path.resolve(cwd, options.project),
-        }
-      : { cwd, file: discoveryFile, projectRoot: options.projectRoot },
-  );
+  const project = options.project
+    ? readProjectConfig({
+        cwd,
+        projectRoot: options.projectRoot,
+        tsconfig: path.resolve(cwd, options.project),
+      })
+    : discoverOwningProject(cwd, discoveryFile, options);
   const tsconfig = project.path;
   const root = project.root;
+  // Relative response requests use the selected project's compiler cwd, which
+  // can differ from the invocation directory or a solution's nearest config.
+  // Refuse watch before effective-option reporting, cache writes or compilation.
+  assertTtsxNoWatch(options.passthrough ?? [], root);
   const explicitCacheDir = resolveCacheDir(cwd, options.cacheDir);
-  const cacheDirSpelling =
-    explicitCacheDir ??
-    path.join(root, "node_modules", ".cache", "ttsc", "ttsx");
+  const env = SidecarEnvironment.merge(process.env, options.env);
+  const defaultCache =
+    explicitCacheDir === undefined
+      ? defaultRuntimeCacheDir(root, env)
+      : undefined;
+  const cacheDirSpelling = explicitCacheDir ?? defaultCache!.runtime;
   const runtimeCacheKey = resolveRuntimeCacheKey(options.runtimeCacheKey);
-  // Resolved once: it now costs a realpath (and, for a missing directory on
-  // Windows, a case-sensitivity probe) rather than a string join.
-  const runtimeRootDir = resolveRuntimeSourceRoot(project);
+  // These adapters consume one original compiler request before generation
+  // acquisition. Native expansion remains owned by the upstream compiler.
+  const effectiveOptions = readEffectiveCompilerOptions(
+    project,
+    options.passthrough,
+    options.binary,
+  );
+  const privateEmitRootDir = resolveRuntimeSourceRoot(project, effectiveOptions);
+  // Resolved once: resolution costs a realpath (and, for a missing directory on
+  // Windows, a case-sensitivity probe).
+  const runtimeRootDir = createFilesystemPathIdentityContext({
+    throwOnRealpathError: false,
+  }).resolve(privateEmitRootDir).path;
+  const emitProfile = runtimeEmitProfile(
+    project,
+    options.passthrough,
+    options.binary,
+    effectiveOptions,
+  );
+  const runtimePassthrough = runtimeCompilerArgs(
+    project,
+    options.passthrough,
+    options.binary,
+    effectiveOptions,
+  );
   fs.mkdirSync(cacheDirSpelling, { recursive: true });
   // Pin the cache parent before deriving a generation path. Descriptors run
   // after this point and may retarget a caller-controlled symlink or junction;
@@ -198,65 +350,125 @@ function createProjectContext(
   // physical parent selected here.
   const cacheDir =
     createFilesystemPathIdentityContext().resolve(cacheDirSpelling).path;
-  const processDir = path.join(cacheDir, "project", runtimeCacheKey);
+  // The lowered orphan sources outlive the run, so they live in the resolved
+  // cache root beside every other persistent part of it, and a default root
+  // collects them with the rest.
+  const cacheRoot =
+    defaultCache === undefined || defaultCache.runtime === defaultCache.root
+      ? cacheDir
+      : path.dirname(cacheDir);
+  if (defaultCache?.collected === true)
+    SourceBuildCacheLayout.pruneCacheFiles(cacheRoot);
+  // The `project` child can itself be a link. Pin its physical target, sweep
+  // abandoned runs, and publish this run's owner in one locked transaction.
+  // Clean can never observe a newly selected but still unowned index.
+  const processDir = claimRuntimeProjectDirectory(cacheDir, runtimeCacheKey);
   const virtualRoot = path.join(processDir, "fs");
+  const emitDir = virtualPath(
+    virtualRoot,
+    project.compilerOptions.outDir || runtimeRootDir,
+  );
   return {
     project,
+    // Lowered argv is build input, not authority for another effective-options
+    // or completed-emit provenance observation. The reader remains call-local.
+    runtimePassthrough,
     tsconfig,
     root,
     cacheDir,
     runtimeCacheKey,
     processDir,
     pluginCacheDir: explicitCacheDir === undefined ? undefined : cacheDir,
+    orphanCacheDir: path.join(
+      cacheRoot,
+      SourceBuildCacheLayout.ORPHAN_CACHE_DIRNAME,
+    ),
     virtualRoot,
-    emitDir: project.compilerOptions.outDir
-      ? virtualPath(virtualRoot, project.compilerOptions.outDir)
-      : virtualPath(virtualRoot, runtimeRootDir),
+    emitDir,
     // The source-tree root the emit mirrors (tsgo strips this prefix). Used to
     // map a source `.ts` back to its emitted `.js` when the runtime hooks serve
     // the built entry under its source URL.
     runtimeRootDir,
+    // Compiler input names retain their lexical project spelling. Physical
+    // runtime lookup coordinates must not become a containment override.
+    privateEmitRootDir,
     // The tsconfig options that decide the emit format, so the runtime hooks
     // classify each served file the same way tsgo chose when emitting it.
     // `target` belongs here as much as `module` does: with `module` absent tsgo
     // derives the module kind from `target`, so publishing only `module` makes
-    // the hooks guess.
-    moduleOptions: projectModuleOptions(project.compilerOptions),
-    // Force a source map on the transient runtime emit only when the project
-    // configures none — when it already emits `sourceMap` or `inlineSourceMap`,
-    // the serve path inlines/absolutizes that map, so no override is needed
-    // (issue #353).
-    forceRuntimeSourceMap:
-      project.compilerOptions.sourceMap !== true &&
-      project.compilerOptions.inlineSourceMap !== true,
+    // the hooks guess. A `--module` forwarded before the entry decides the
+    // emit as much as the config does, so both are read.
+    moduleOptions: emitProfile.moduleOptions,
+    // Force a source map on the transient runtime emit only when the build
+    // would carry none — when the project or a forwarded flag already emits
+    // `sourceMap` or `inlineSourceMap`, the serve path inlines/absolutizes that
+    // map, so no override is needed.
+    forceRuntimeSourceMap: emitProfile.forceRuntimeSourceMap,
     built: false,
-    emittedFiles: undefined as string[] | undefined,
+    outputs: [] as readonly string[],
+    emittedSourceProofFailures: undefined as
+      | Readonly<Record<string, string>>
+      | undefined,
+    emittedSources: undefined as
+      | Readonly<Record<string, readonly string[]>>
+      | undefined,
   };
 }
 
 /**
- * The source-tree root the emit mirrors, in the same physical spelling as the
- * entry it will be compared against.
+ * The project that owns `file`, found the way the language service finds it.
  *
- * Undeclared, the root is the project's own directory, because that is the one
- * tsgo uses: with a config file in play `GetCommonSourceDirectory` answers that
- * file's directory and never computes a common directory of the input files.
- * The entry's directory is not that root — it is only the same directory when
- * the entry happens to sit beside the tsconfig, which is precisely why a
- * `src/`-shaped project mislaid its emit here (issue #1172) while a flat one
- * worked. `runtimeHooks.ts::resolveDependencySourceRoot` and
- * `watchTopology.ts::inferPerSourceCompilerOutputs` already model the same
- * rule, and `runBuild.ts::pinnedRootDirArgs` pins it for tsgo itself.
+ * The nearest config is where discovery starts, not where it has to stop. A
+ * solution-style config (`"files": []` plus `references`) owns nothing itself,
+ * and compiling an entry through it applies its empty options to code whose
+ * real project sets `experimentalDecorators`, `jsx`, or `paths`. When the
+ * nearest config does not contain the file, the referenced project that does is
+ * used; an explicit `-P` skips all of this.
+ */
+function discoverOwningProject(
+  cwd: string,
+  file: string,
+  options: NonNullable<Parameters<typeof prepareExecution>[1]>,
+): ReturnType<typeof readProjectConfig> {
+  const nearest = readProjectConfig({
+    cwd,
+    file,
+    projectRoot: options.projectRoot,
+  });
+  const owning = resolveOwningProjectConfig({
+    binary: options.binary,
+    file,
+    tsconfig: nearest.path,
+  });
+  return owning === path.resolve(nearest.path)
+    ? nearest
+    : readProjectConfig({
+        cwd,
+        projectRoot: options.projectRoot,
+        tsconfig: owning,
+      });
+}
+
+/**
+ * Select the compiler's lexical private layout root. The context independently
+ * resolves its physical spelling for comparisons with served source files.
+ *
+ * Private ordinary emit without a declared root uses the native volume root.
+ * Unlike the compiler's config-directory default, this does not impose a new
+ * containment error when a check-only project imports sources outside that
+ * directory. Explicit and composite roots retain their containment policy.
+ * TsgoArguments and dependency serving use the same private layout selection.
  *
- * Resolving it is the other half of `resolveEntrySpelling`, and skipping it
- * leaves the comparison mixed rather than merely imprecise. `project.root`
- * arrives through plain `fs.realpathSync`, which resolves reparse points but
- * leaves a Windows 8.3 component alone, while the entry arrives through
- * `fs.realpathSync.native`, which expands it — and `path.relative` folds case
- * but not 8.3. A declared `rootDir` is worse still: it is joined verbatim, so a
- * `rootDir` that is itself a symlinked directory never resolves at all. Either
- * way the gate reads an in-project entry as outside its own root, pays a second
- * whole build for it, and publishes a wider root than the project has.
+ * Resolving the selected root in the context is the other half of
+ * `resolveEntrySpelling`, and skipping it leaves the comparison mixed rather
+ * than merely imprecise. `project.root` arrives through plain
+ * `fs.realpathSync`, which resolves reparse points but leaves a Windows 8.3
+ * component alone, while the entry arrives through `fs.realpathSync.native`,
+ * which expands it — and `path.relative` folds case but not 8.3. A declared
+ * `rootDir` is worse still: it is joined verbatim, so a `rootDir` that is
+ * itself a symlinked directory never resolves at all. Either way the gate reads
+ * an in-project entry as outside its own root, pays a second whole build for
+ * it, and publishes a wider root than the project has.
  *
  * The pass costs nothing in agreement with the root tsgo was pinned to, which
  * stays unresolved on purpose so it matches the spelling tsgo gives the input
@@ -266,56 +478,70 @@ function createProjectContext(
  */
 function resolveRuntimeSourceRoot(
   project: ReturnType<typeof readProjectConfig>,
+  effective: ReturnType<typeof readEffectiveCompilerOptions>,
 ): string {
-  const rootDir = project.compilerOptions.rootDir;
-  const identities = createFilesystemPathIdentityContext({
-    throwOnRealpathError: false,
-  });
-  return identities.resolve(
-    typeof rootDir !== "string"
-      ? project.root
-      : path.isAbsolute(rootDir)
-        ? rootDir
-        : path.resolve(project.root, rootDir),
-  ).path;
+  // A `--rootDir` forwarded before the entry reaches the compiler after the
+  // config, so it is the root the outputs are laid out against. Invalid
+  // arguments fail the build on their own; an unreadable effective config keeps
+  // the declared root until then. A readable explicit reset uses the project
+  // private default instead of reviving the declared root.
+  const rootDir =
+    effective === null ? project.compilerOptions.rootDir : effective("rootDir");
+  return privateRuntimeRootDir(
+    project.root,
+    rootDir,
+    effective === null
+      ? project.compilerOptions.composite
+      : effective("composite"),
+  );
 }
 
+/**
+ * Complete the context's checked project build once, with all compiler output
+ * locations confined to its private emit directory.
+ *
+ * Record emitted files before linking source neighbors, so linked user files
+ * cannot masquerade as compiler output. Only a successful build publishes the
+ * completed context. Failure releases the claimed generation and preserves the
+ * compiler's diagnostic output in the thrown error.
+ */
 function buildProject(
   context: ReturnType<typeof createProjectContext>,
   options: NonNullable<Parameters<typeof prepareExecution>[1]>,
 ): void {
   if (context.built) return;
 
-  fs.mkdirSync(context.cacheDir, { recursive: true });
-  fs.rmSync(context.processDir, { recursive: true, force: true });
-  fs.mkdirSync(path.dirname(context.emitDir), { recursive: true });
+  // A successful empty solution may write no directory. Own an empty output
+  // container before compilation so its inventory can still prove exclusion
+  // and select the checked single-entry lane without hiding enumeration errors.
+  fs.mkdirSync(context.emitDir, { recursive: true });
   const result = runBuild({
     binary: options.binary,
     checkers: options.checkers,
     cwd: context.root,
     emit: true,
     env: options.env,
-    forceListEmittedFiles: true,
     cacheDir: context.pluginCacheDir,
     outDir: context.emitDir,
-    passthrough: runtimeCompilerArgs(
-      context.project,
-      options.passthrough,
-      options.binary,
-    ),
+    // Every output this build writes stays in ttsx's private directory: a
+    // declared `declarationDir`, `tsBuildInfoFile`, or `outFile`, and any
+    // output location forwarded on the command line, would otherwise land in
+    // the user's tree.
+    isolateOutputsTo: context.emitDir,
+    passthrough: context.runtimePassthrough,
     // `context.emitDir` is ttsx's own temp directory, not an output the project
-    // asked for, and tsgo demands an explicit `rootDir` (TS5011) as soon as any
-    // `outDir` is in play. Pinning the root tsgo would infer keeps a check-only
-    // project runnable without moving its emit (issue #1172); a project that
-    // declares `rootDir` is left exactly as it is, which is also the root
-    // `resolveRuntimeSourceRoot` published above.
+    // asked for. A private ordinary volume-root layout permits the full input
+    // graph without adding config-directory containment to a check-only
+    // project. Declared and composite roots retain their compiler policy,
+    // matching the root recorded by resolveRuntimeSourceRoot above.
     pinInferredRootDir: true,
+    privateEmitRootDir: context.privateEmitRootDir,
     // Emit a source map on the transient entry emit (a PID-isolated temp dir,
     // never the consumer's `outDir`) so the serve path can inline it under the
     // source URL. Routed as a dedicated build option, not a forwarded tsgo
-    // flag, so it never reaches a native plugin host's argument parser (issue
-    // #353).
+    // flag, so it never reaches a native plugin host's argument parser.
     forceRuntimeSourceMap: context.forceRuntimeSourceMap,
+    forceEmitProvenance: true,
     pluginConfigDir: options.pluginConfigDir,
     plugins: options.plugins,
     quiet: true,
@@ -324,16 +550,24 @@ function buildProject(
     tsconfig: context.tsconfig,
   });
   if (result.status === 0) {
+    // Record the build's outputs before the virtual layout links the user's
+    // own files in beside them. Without an `outDir` the emit directory is the
+    // mirror of the project root, and a `tool.js` linked there from the user's
+    // tree would otherwise be recorded as the output of `tool.ts`.
+    context.outputs = EmitOwnershipIndex.listOutputs(context.emitDir);
+    // An empty solution may not run an emitting producer. Its observed empty
+    // inventory selects the entry-only build, which must prove its own writes.
+    context.emittedSources =
+      context.outputs.length === 0
+        ? undefined
+        : requireEmitProvenance(result.emittedSources, context.tsconfig);
+    context.emittedSourceProofFailures = result.emittedSourceProofFailures;
     linkVirtualProjectLayout(context);
     context.built = true;
-    context.emittedFiles =
-      result.emittedFiles && result.emittedFiles.length !== 0
-        ? result.emittedFiles
-        : undefined;
     return;
   }
 
-  removeRuntimeOutput(context.processDir);
+  removeRuntimeOutput(context.processDir, context.cacheDir);
   const detail = [
     `ttsx: project check failed for ${context.tsconfig}`,
     result.stderr || result.stdout,
@@ -344,181 +578,117 @@ function buildProject(
 }
 
 /**
- * Build an entry the owning project's file set does not contain.
- *
- * `ttsc` selects a _file set_: a project whose `include` is `src` must emit
- * only `src` into `outDir`, and a `clear.ts`, a `build/release.ts`, or a
- * `lint.config.ts` beside the tsconfig has no business in `lib`. `ttsx` selects
- * an _entry_: it needs that same project's compiler options, not its file list.
- * Those two requirements are not in conflict, but the whole-project build
- * cannot satisfy the second one, so an entry it did not emit is compiled here
- * through a project that inherits every option and declares only the entry.
- *
- * The synthesized tsconfig is written beside the real one on purpose. `extends`
- * with an absolute path would resolve from anywhere, but `${configDir}` and
- * `paths` are anchored to the directory of the config that consumes them, so
- * any other location silently retargets them. It is removed as soon as the
- * build returns.
- *
- * `rootDir` widens to the nearest directory holding both the project root and
- * the entry — for the layout this exists for, the project root itself; for an
- * entry that is a symlink out of the tree, the ancestor the two trees share. It
- * has to widen at least that far, because the inherited `rootDir` (`src`) does
- * not contain the entry and tsgo emits an input outside `rootDir` to its own
- * source path.
- *
- * Widening costs precision, not safety. The manifest's `rootDir` bounds which
- * files the runtime hooks will try to serve from this emit, so a wide one
- * admits more sources to the lookup — but the lookup only ever answers with a
- * file from this build's own emit directory, whether from `emittedFiles` or a
- * scan of `outDir` (`resolveEmittedJavaScript`). What a wide root risks is the
- * exact mirror missing and the trailing-stem matcher picking the wrong output
- * _of this build_; it cannot reach a raw source on disk.
+ * Validate a completed producer's ledger before publishing its runtime context.
+ * An empty record is authoritative absence; an omitted or malformed record must
+ * not be replaced by source-map or filename inference.
  */
-function buildEntryProject(
+function requireEmitProvenance(
+  value: unknown,
+  tsconfig: string,
+): Readonly<Record<string, readonly string[]>> {
+  if (!RuntimeEmitProvenance.isRecord(value)) {
+    throw new Error(
+      `ttsx: selected emitting producer cannot provide source ownership for ${JSON.stringify(tsconfig)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Read the ledger already validated when this context's build completed.
+ * Preparation cannot route or transfer a context whose build never published
+ * it.
+ */
+function executionProvenance(
   context: ReturnType<typeof createProjectContext>,
-  options: NonNullable<Parameters<typeof prepareExecution>[1]>,
-  entry: string,
-): void {
-  // `entry` already carries the one spelling `prepareExecution` decided on.
-  // tsgo compares it against `rootDir` textually — `GetCommonSourceDirectory`
-  // takes `rootDir` verbatim and `ContainsPath` is lexical — so a mismatch here
-  // is not a near miss: the entry counts as outside `rootDir`, and tsgo emits
-  // it to its own source path with the extension changed instead of under
-  // `outDir`, writing a `.js` and its map beside the user's `.ts` where nothing
-  // cleans them up.
-  const rootDir = commonAncestorDirectory(path.dirname(entry), context.root);
-  const tsconfig = path.join(
-    context.root,
-    `.ttsx-entry.${context.runtimeCacheKey}.tsconfig.json`,
-  );
-  fs.writeFileSync(
-    tsconfig,
-    JSON.stringify(
-      {
-        extends: context.tsconfig.replace(/\\/g, "/"),
-        compilerOptions: { rootDir: rootDir.replace(/\\/g, "/") },
-        // `files` alone does not displace an inherited `include`, and an
-        // inherited `exclude` could drop the entry back out of the program, so
-        // both are overridden explicitly.
-        files: [entry.replace(/\\/g, "/")],
-        include: [],
-        exclude: [],
-      },
-      null,
-      2,
-    ),
-    "utf8",
-  );
-  try {
-    const project = readProjectConfig({
-      cwd: context.root,
-      projectRoot: options.projectRoot,
-      tsconfig,
-    });
-    const emitDir = path.join(context.virtualRoot, ENTRY_PROJECT_EMIT_DIR);
-    fs.mkdirSync(emitDir, { recursive: true });
-    const result = runBuild({
-      binary: options.binary,
-      checkers: options.checkers,
-      cwd: context.root,
-      emit: true,
-      env: options.env,
-      forceListEmittedFiles: true,
-      cacheDir: context.pluginCacheDir,
-      outDir: emitDir,
-      passthrough: runtimeCompilerArgs(
-        project,
-        options.passthrough,
-        options.binary,
-      ),
-      forceRuntimeSourceMap: context.forceRuntimeSourceMap,
-      pluginConfigDir: options.pluginConfigDir,
-      plugins: options.plugins,
-      quiet: true,
-      resolvedProject: project,
-      singleThreaded: options.singleThreaded,
-      tsconfig,
-    });
-    if (result.status !== 0) {
-      removeRuntimeOutput(context.processDir);
-      throw new Error(
-        [
-          `ttsx: entry check failed for ${entry}`,
-          result.stderr || result.stdout,
-        ]
-          .filter((line) => line.trim().length !== 0)
-          .join("\n"),
-      );
-    }
-    context.emitDir = emitDir;
-    context.runtimeRootDir = rootDir;
-    context.moduleOptions = projectModuleOptions(project.compilerOptions);
-    context.emittedFiles =
-      result.emittedFiles && result.emittedFiles.length !== 0
-        ? result.emittedFiles
-        : undefined;
-  } finally {
-    try {
-      fs.rmSync(tsconfig, { force: true });
-    } catch {
-      // Best effort: a leftover synthesized tsconfig must not mask a build
-      // failure, and it is runtime-scoped so it can never be mistaken for a
-      // real project config.
-    }
+): Readonly<Record<string, readonly string[]>> {
+  if (context.emittedSources === undefined) {
+    throw new Error("ttsx: completed emit has no source ownership record");
   }
+  return context.emittedSources;
 }
 
 /**
- * The nearest directory containing both `left` and `right`, in the physical
- * spelling both of them share.
- *
- * Containment is asked through the same filesystem-identity predicate the
- * runtime hooks use, and the answer is resolved through it too. Its caller now
- * passes an already-resolved directory, so the two spellings agree before the
- * walk starts; the predicate stays because this returns a `rootDir` that tsgo
- * takes verbatim, and answering in anything but the physical spelling would
- * leave tsgo unable to place a sibling source under it.
+ * The runtime cache a run uses when `--cache-dir` names none: the `ttsx` area
+ * below the source-plugin cache root selected for the same project and
+ * environment, or, when the default workspace-local directory is read-only, one
+ * below the system temp directory keyed by the project.
  *
- * Falls back to the entry's directory when there genuinely is no shared
- * ancestor, as on two different Windows volumes: the entry still has to
- * compile, and a root that contains it is the closest thing to correct
- * available.
+ * Every run writes its output into a directory of its own below the cache and
+ * removes it on exit, so any writable parent serves; the workspace-local
+ * default keeps related projects together. A `--cache-dir` the user named is
+ * never replaced: it is the user's choice, and a failure there is reported.
  */
-function commonAncestorDirectory(left: string, right: string): string {
-  const identities = createFilesystemPathIdentityContext({
-    throwOnRealpathError: false,
-  });
-  const from = identities.resolve(path.resolve(left)).path;
-  const target = identities.resolve(path.resolve(right)).path;
-  let current = from;
-  for (;;) {
-    if (identities.isWithin(current, target)) {
-      return current;
+function defaultRuntimeCacheDir(
+  root: string,
+  env: NodeJS.ProcessEnv,
+): {
+  /** Whether ttsc collects the root, which it does for its own default. */
+  collected: boolean;
+
+  /** The cache root the runtime directory lives in. */
+  root: string;
+
+  /** The runtime's own directory. */
+  runtime: string;
+} {
+  const paths = resolveSourceBuildCachePaths(root, undefined, env);
+  const local = path.join(
+    paths.root,
+    SourceBuildCacheLayout.RUNTIME_CACHE_DIRNAME,
+  );
+  try {
+    if (!env.TTSC_CACHE_DIR) {
+      SourceBuildCacheLayout.markDefaultWorkspaceCacheRoot(paths.root);
     }
-    const parent = path.dirname(current);
-    if (parent === current) {
-      return from;
+    fs.mkdirSync(local, { recursive: true });
+    return {
+      collected: !env.TTSC_CACHE_DIR,
+      root: paths.root,
+      runtime: local,
+    };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (
+      env.TTSC_CACHE_DIR ||
+      (code !== "EACCES" && code !== "EPERM" && code !== "EROFS")
+    ) {
+      throw error;
     }
-    current = parent;
   }
+  const fallback = path.join(
+    os.tmpdir(),
+    "ttsc-ttsx",
+    crypto.createHash("sha256").update(root).digest("hex").slice(0, 16),
+  );
+  return { collected: false, root: fallback, runtime: fallback };
 }
 
-function removeRuntimeOutput(directory: string): void {
+/**
+ * Relinquish and remove a pinned generation under its runtime-directory lock.
+ * Cleanup is best effort during failure handling; a cleanup error must not hide
+ * the original compiler or preparation error. Abandoned runs remain
+ * discoverable by the process-ownership sweep.
+ */
+function removeRuntimeOutput(directory: string, runtimeCacheDir: string): void {
   try {
-    fs.rmSync(directory, { recursive: true, force: true });
+    withRuntimeDirectoryLock(runtimeCacheDir, () => {
+      ProcessOwnedDirectory.relinquish(directory);
+      fs.rmSync(directory, { recursive: true, force: true });
+    });
   } catch {
     // Best effort: cleanup must not hide the original preparation failure.
   }
 }
 
-function resolveCacheDir(cwd: string, cacheDir?: string): string | undefined {
-  if (!cacheDir) {
-    return undefined;
-  }
-  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
-}
-
+/**
+ * Mirror selected project ancestors beside emitted output so native module
+ * lookup can reach source neighbors and installed dependencies.
+ *
+ * Existing virtual entries, including compiler output, win over linked user
+ * entries. Each source directory is enumerated once; linkVirtualEntry owns the
+ * native file/directory link representation.
+ */
 function linkVirtualProjectLayout(
   context: ReturnType<typeof createProjectContext>,
 ): void {
@@ -536,75 +706,12 @@ function linkVirtualProjectLayout(
   }
 }
 
-// Exported for direct exercise by the ttsx e2e suite: the Windows fallback
-// branches below cannot be reached through a spawned run on CI (creating a
-// file-symlink fixture needs the very privilege the fallback avoids).
-export function linkVirtualEntry(
-  realEntry: string,
-  virtualEntry: string,
-  entry: fs.Dirent,
-): void {
-  if (entry.isDirectory()) {
-    // Use junction points on Windows; plain symlinks elsewhere.
-    fs.symlinkSync(
-      realEntry,
-      virtualEntry,
-      process.platform === "win32" ? "junction" : undefined,
-    );
-    return;
-  }
-  if (entry.isFile()) {
-    try {
-      // Hard-link first: cheap, preserves inode, no extra disk usage.
-      fs.linkSync(realEntry, virtualEntry);
-    } catch {
-      // Cross-device or unsupported filesystem: fall back to a full copy.
-      fs.copyFileSync(realEntry, virtualEntry);
-    }
-    return;
-  }
-  if (
-    process.platform === "win32" &&
-    entry.isSymbolicLink() &&
-    isDirectorySymlinkTarget(realEntry)
-  ) {
-    fs.symlinkSync(realEntry, virtualEntry, "junction");
-    return;
-  }
-  // Symlinks (and other special entries) are re-symlinked as-is. On Windows,
-  // a file symlink needs SeCreateSymbolicLinkPrivilege (admin or Developer
-  // Mode), so mirror the plain-file branch's hard-link/copy fallback instead
-  // of failing the run (#306). A link whose target no longer exists is
-  // skipped: it can serve no module, and none of the fallbacks can
-  // materialize it without symlink privileges.
-  try {
-    fs.symlinkSync(realEntry, virtualEntry);
-  } catch {
-    if (!fs.existsSync(realEntry)) {
-      return;
-    }
-    try {
-      fs.linkSync(realEntry, virtualEntry);
-    } catch {
-      fs.copyFileSync(realEntry, virtualEntry);
-    }
-  }
-}
-
-function isDirectorySymlinkTarget(realEntry: string): boolean {
-  try {
-    return fs.statSync(realEntry).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Walk from `projectRoot` upward (up to `MAX_VIRTUAL_PARENT_DEPTH` steps),
  * stopping early at a workspace root (`pnpm-workspace.yaml` or `.git`). The
- * collected directories are reversed so callers can iterate outermost-first,
- * which lets inner symlinks override outer ones without conflicting mkdir
- * calls.
+ * collected directories are reversed so callers can construct parent layouts
+ * before their children. Existing virtual entries win when neighboring source
+ * entries are linked, preserving the compiler's own emitted files.
  */
 function collectLinkDirectories(projectRoot: string): string[] {
   const out: string[] = [];
@@ -650,16 +757,21 @@ function isUnsafeVirtualParent(
  *
  * On POSIX the root is always `/`, so every path shares the same prefix —
  * represented here as `"posix"`. On Windows, drive letters and UNC roots each
- * get a sanitized label (e.g. `"C_"` for `C:\`), preventing collisions between
- * paths from different drives inside the same virtual root.
+ * get a full SHA-256 label of their UTF-16 root spelling. This fixed-size
+ * native component distinguishes roots such as UNC shares `a-b` and `a_b` under
+ * the hash's collision-resistance premise, without punctuation folding or
+ * expansion beyond the host's component-length limit. Relative paths remain
+ * unchanged.
  */
 function virtualPath(root: string, absolute: string): string {
   const parsed = path.parse(path.resolve(absolute));
   const label =
     parsed.root === path.sep
       ? "posix"
-      : parsed.root.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") ||
-        "root";
+      : crypto
+          .createHash("sha256")
+          .update(parsed.root, "utf16le")
+          .digest("hex");
   const relative = path.relative(parsed.root, path.resolve(absolute));
   return path.join(root, label, relative);
 }