ttsc 0.26.2 → 0.28.0

package/lib/launcher/internal/runtimeHooks.js

@@ -10,7 +10,9 @@ exports.entryModuleFormat = entryModuleFormat;
 exports.restoreStrippedNodeBuiltinScheme = restoreStrippedNodeBuiltinScheme;
 exports.projectModuleOptions = projectModuleOptions;
 exports.isWithin = isWithin;
+exports.dependencyCacheKey = dependencyCacheKey;
 exports.readDependencyCache = readDependencyCache;
+exports.dependencyCacheRoot = dependencyCacheRoot;
 exports.acquireDependencyBuildLock = acquireDependencyBuildLock;
 exports.releaseDependencyBuildLock = releaseDependencyBuildLock;
 exports.reclaimDependencyBuildLock = reclaimDependencyBuildLock;
@@ -27,6 +29,7 @@ const resolveEmittedJavaScript_1 = require("../../compiler/internal/resolveEmitt
 const resolveTsgo_1 = require("../../compiler/internal/resolveTsgo");
 const runBuild_1 = require("../../compiler/internal/runBuild");
 const spawnNative_1 = require("../../compiler/internal/spawnNative");
+const createCanonicalTempDirectory_1 = require("../../internal/createCanonicalTempDirectory");
 const projectInputPathIdentity_1 = require("../../internal/projectInputPathIdentity");
 const servedSourceMap_1 = require("./servedSourceMap");
 /**
@@ -67,25 +70,39 @@ const RESOLVABLE_EXTENSIONS = [
     ".mjs",
     ".cjs",
 ];
+/** Union of the ttsx rescue probes and Node's built-in CommonJS probes. */
+const DESCRIPTOR_PROBE_EXTENSIONS = [
+    ...RESOLVABLE_EXTENSIONS,
+    ".json",
+    ".node",
+];
 /** TypeScript source extensions these hooks compile. */
 const TYPESCRIPT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"];
-let manifestCache;
-function manifest() {
-    if (manifestCache !== undefined) {
-        return manifestCache;
+let environmentManifestCache;
+const registeredManifests = [];
+function environmentManifest() {
+    if (environmentManifestCache !== undefined) {
+        return environmentManifestCache;
     }
     const file = process.env.TTSX_RUNTIME_MANIFEST;
     if (file === undefined || file.length === 0) {
-        manifestCache = null;
-        return manifestCache;
+        environmentManifestCache = null;
+        return environmentManifestCache;
     }
     try {
-        manifestCache = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        environmentManifestCache = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
     }
     catch {
-        manifestCache = null;
+        environmentManifestCache = null;
     }
-    return manifestCache;
+    return environmentManifestCache;
+}
+/** Every checked entry emit available to this runtime, in ownership order. */
+function runtimeManifests() {
+    const inherited = environmentManifest();
+    return inherited === null
+        ? registeredManifests
+        : [inherited, ...registeredManifests];
 }
 /**
  * Lowest Node.js the ttsx source runtime supports. The synchronous
@@ -154,6 +171,7 @@ function assertNodeRuntimeSupport() {
     }
 }
 let installed = false;
+let prepareRuntimeEntry;
 /**
  * Install the source-loading hooks on the current (main) thread. Idempotent:
  * the bootstrap installs them for the entry process, and `NODE_OPTIONS`
@@ -164,10 +182,21 @@ let installed = false;
  * `require()` made from inside a CommonJS module that was itself reached
  * through an ESM `import` (the interop translator loads it on the raw CJS
  * path). The ESM graph goes through `registerHooks`; the CommonJS `require`
- * graph goes through `Module._extensions` — the canonical loader extension
- * point `ts-node`/`tsx` use for the same reason.
+ * graph goes through `Module._extensions` and `Module._resolveFilename` — the
+ * canonical loader extension points `ts-node`/`tsx` use for the same reason.
+ *
+ * Both halves of that second graph are required, and they answer different
+ * questions. `_extensions` decides how a file that was _found_ is compiled, and
+ * Node reuses its keys when it probes an extensionless request, so
+ * `require("./x")` reaches `x.ts` for free. Nothing there resolves a request
+ * that already carries an extension: `require("./x.js")` backed only by `x.ts`
+ * is a resolution failure before any compiler is consulted, which is why the
+ * rescue is installed on `_resolveFilename` as well (samchon/ttsc#1280).
  */
-function installRuntimeHooks() {
+function installRuntimeHooks(options = {}) {
+    if (options.prepareEntry !== undefined) {
+        prepareRuntimeEntry = options.prepareEntry;
+    }
     if (installed) {
         return;
     }
@@ -182,6 +211,7 @@ function installRuntimeHooks() {
     }
     (0, node_module_1.registerHooks)({ load, resolve });
     installCommonJsHook();
+    installCommonJsResolveHook();
 }
 /**
  * Register a CommonJS `require` handler for each TypeScript source extension so
@@ -191,12 +221,95 @@ function installRuntimeHooks() {
 function installCommonJsHook() {
     const extensions = node_module_1.Module._extensions;
     const compile = (module, filename) => {
-        module._compile(resolveServedSource(filename).source, filename);
+        const parent = module.parent?.filename;
+        module._compile(resolveServedSource(filename, (0, node_url_1.pathToFileURL)(filename).href, typeof parent !== "string" || !isTypeScriptSource(parent)).source, filename);
     };
     for (const extension of [".ts", ".tsx", ".cts"]) {
         extensions[extension] = compile;
     }
 }
+/**
+ * Map a JavaScript spelling back to its TypeScript source on the CommonJS
+ * resolution path, so `require("./x.js")` finds `x.ts` when nothing emitted
+ * `x.js`.
+ *
+ * TypeScript asks authors to write the emitted `.js` extension in a relative
+ * specifier, so this spelling is the documented one rather than a mistake, and
+ * the ESM `resolve` hook has always rescued it. The CommonJS graph could not,
+ * and on Node 22 that graph is reached by every `require()` inside a CommonJS
+ * module the ESM loader evaluated — `module.registerHooks` sees the `import()`
+ * of that module and nothing within it. Node 24 routes the same `require`
+ * through the hooks, which is why the gap was only ever visible on the oldest
+ * runtime ttsx supports (`engines.node` is `>=22.15.0`).
+ *
+ * The wrapper only ever answers a request Node's own resolver already refused,
+ * so a resolution that succeeds is never perturbed, and a request no candidate
+ * satisfies rethrows Node's original error with its `MODULE_NOT_FOUND` code and
+ * `requireStack` intact. `require.resolve` shares this entry point and is
+ * rescued with it, except in its `{ paths }` form, which resolves against the
+ * caller's list rather than the parent this reads.
+ */
+function installCommonJsResolveHook() {
+    const internals = node_module_1.Module;
+    const original = internals._resolveFilename;
+    internals._resolveFilename = function resolveFilename(request, parent, isMain, options) {
+        try {
+            return original.call(this, request, parent, isMain, options);
+        }
+        catch (error) {
+            const rescued = rescueCommonJsRequest(request, parent, options);
+            if (rescued === null) {
+                throw error;
+            }
+            return rescued;
+        }
+    };
+}
+/**
+ * The TypeScript source a refused CommonJS request names, or `null`.
+ *
+ * Only a relative or absolute request can be rescued: a bare specifier is a
+ * package lookup, whose own resolver already probed every extension the
+ * installed `_extensions` keys declare.
+ *
+ * Two shapes decline before that. `_resolveFilename` is an internal entry point
+ * anything may call, so a non-string request reaches here as readily as a
+ * specifier does, and reading it would replace Node's own argument error with a
+ * `TypeError` from this file. And `require.resolve(request, { paths })`
+ * resolves against the caller's list, which this rescue does not consult, so
+ * answering it from the parent's directory would be a different question's
+ * answer.
+ */
+function rescueCommonJsRequest(request, parent, options) {
+    if (typeof request !== "string") {
+        return null;
+    }
+    if (typeof options === "object" &&
+        options !== null &&
+        Array.isArray(options.paths)) {
+        return null;
+    }
+    let base;
+    if (node_path_1.default.isAbsolute(request)) {
+        base = request;
+    }
+    else if (isRelativeSpecifier(request)) {
+        const from = parent?.filename;
+        if (typeof from !== "string") {
+            return null;
+        }
+        base = node_path_1.default.resolve(node_path_1.default.dirname(from), request);
+    }
+    else {
+        return null;
+    }
+    for (const candidate of typescriptSourcesForJavaScriptSpecifier(base)) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
 /**
  * The module format of the entry source file, derived from the entry project's
  * compiler options (via the runtime manifest) the same way the served files are
@@ -204,11 +317,14 @@ function installCommonJsHook() {
  * `require` or an ESM `import`.
  */
 function entryModuleFormat(entryFile) {
-    const m = manifest();
-    return moduleFormat(entryFile, m === null ? null : (m.moduleOptions ?? {})) === "module"
+    const real = realPath(entryFile);
+    const owner = findEntryEmit(real)?.manifest;
+    return moduleFormat(entryFile, owner === undefined ? null : (owner.moduleOptions ?? {})) === "module"
         ? "module"
         : "commonjs";
 }
+/** TypeScript URLs resolved at a JavaScript-to-TypeScript entry boundary. */
+const runtimeEntryUrls = new Set();
 /**
  * Rescue an extensionless or directory relative specifier that Node's resolver
  * rejected. Only runs after `nextResolve` throws, so a successful resolution is
@@ -216,17 +332,344 @@ function entryModuleFormat(entryFile) {
  * original error is rethrown, preserving `ERR_MODULE_NOT_FOUND`.
  */
 function resolve(specifier, context, nextResolve) {
+    recordPluginDescriptorResolutionCandidates(specifier, context.parentURL);
     try {
-        return rememberCommonJsNamedInterop(restoreStrippedNodeBuiltinScheme(specifier, nextResolve(specifier, context)), context);
+        const result = rememberRuntimeEntry(rememberCommonJsNamedInterop(restoreStrippedNodeBuiltinScheme(specifier, nextResolve(specifier, context)), context), context);
+        recordPluginDescriptorResolution(specifier, context.parentURL, result.url);
+        return result;
     }
     catch (error) {
         const rescued = probeRescuableSpecifier(specifier, context.parentURL);
         if (rescued === null) {
             throw error;
         }
-        return rememberCommonJsNamedInterop({ shortCircuit: true, url: rescued }, context);
+        const result = rememberRuntimeEntry(rememberCommonJsNamedInterop({ shortCircuit: true, url: rescued }, context), context);
+        recordPluginDescriptorResolution(specifier, context.parentURL, result.url);
+        return result;
     }
 }
+/**
+ * Fingerprint every path whose state can redirect one descriptor import.
+ *
+ * This runs before the real resolver. Reporting candidates only after the
+ * descriptor finished would pair an earlier descriptor result with later file
+ * state when a higher-priority candidate appeared during evaluation.
+ */
+function recordPluginDescriptorResolutionCandidates(specifier, parentURL) {
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return;
+    if ((0, node_module_1.isBuiltin)(specifier) || specifier.startsWith("node:"))
+        return;
+    const parent = runtimeFilePath(parentURL);
+    if (parent === undefined)
+        return;
+    const recorded = new Set();
+    const record = (candidate) => {
+        const resolved = node_path_1.default.resolve(candidate);
+        if (recorded.has(resolved))
+            return;
+        recorded.add(resolved);
+        recordPluginDescriptorInput({
+            parent,
+            resolved,
+        });
+    };
+    const recordManifestTargets = (value, directory, allowBare = false) => {
+        if (typeof value === "string") {
+            if (value !== "" &&
+                (allowBare || value.startsWith("./") || value.startsWith("../"))) {
+                recordBase(node_path_1.default.resolve(directory, value));
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                recordManifestTargets(item, directory, allowBare);
+            }
+            return;
+        }
+        if (value !== null && typeof value === "object") {
+            for (const item of Object.values(value)) {
+                recordManifestTargets(item, directory, allowBare);
+            }
+        }
+    };
+    const recordPackageManifests = (file) => {
+        for (let directory = node_path_1.default.dirname(file);; directory = node_path_1.default.dirname(directory)) {
+            const manifest = node_path_1.default.join(directory, "package.json");
+            record(manifest);
+            if (isFile(manifest))
+                return;
+            const parentDirectory = node_path_1.default.dirname(directory);
+            if (parentDirectory === directory)
+                return;
+        }
+    };
+    const localBases = (value) => {
+        if (value.startsWith("file:"))
+            return [(0, node_url_1.fileURLToPath)(value)];
+        const raw = node_path_1.default.resolve(node_path_1.default.dirname(parent), value);
+        const suffixStart = value.search(/[?#]/);
+        if (suffixStart === -1)
+            return [raw];
+        const pathname = value.slice(0, suffixStart);
+        return pathname === ""
+            ? [raw]
+            : [...new Set([raw, node_path_1.default.resolve(node_path_1.default.dirname(parent), pathname)])];
+    };
+    const bases = new Set();
+    const recordBase = (base) => {
+        const resolvedBase = node_path_1.default.resolve(base);
+        if (bases.has(resolvedBase))
+            return;
+        bases.add(resolvedBase);
+        record(resolvedBase);
+        for (const candidate of typescriptSourcesForJavaScriptSpecifier(resolvedBase)) {
+            record(candidate);
+        }
+        for (const extension of DESCRIPTOR_PROBE_EXTENSIONS) {
+            record(resolvedBase + extension);
+        }
+        const manifestFile = node_path_1.default.join(resolvedBase, "package.json");
+        record(manifestFile);
+        for (const extension of DESCRIPTOR_PROBE_EXTENSIONS) {
+            record(node_path_1.default.join(resolvedBase, `index${extension}`));
+        }
+        try {
+            const manifest = JSON.parse(node_fs_1.default.readFileSync(manifestFile, "utf8").replace(/^\uFEFF/, ""));
+            recordManifestTargets(manifest.exports, resolvedBase);
+            recordManifestTargets(manifest.module, resolvedBase, true);
+            recordManifestTargets(manifest.main, resolvedBase, true);
+        }
+        catch {
+            // The real resolver owns malformed package diagnostics.
+        }
+    };
+    if (specifier.startsWith(".") ||
+        node_path_1.default.isAbsolute(specifier) ||
+        specifier.startsWith("file:")) {
+        try {
+            for (const base of localBases(specifier)) {
+                recordPackageManifests(base);
+                if (isFile(base))
+                    record(base);
+                else
+                    recordBase(base);
+            }
+        }
+        catch {
+            // The real resolver owns invalid URL spellings.
+        }
+        return;
+    }
+    const parts = specifier.split("/");
+    const packageParts = parts[0]?.startsWith("@")
+        ? parts.slice(0, 2)
+        : parts.slice(0, 1);
+    if (packageParts.some((part) => part === undefined || part === ""))
+        return;
+    const packageName = packageParts.join("/");
+    const subpath = parts.slice(packageParts.length);
+    for (const searchPath of (0, node_module_1.createRequire)(parent).resolve.paths(specifier) ??
+        []) {
+        const packageDirectory = node_path_1.default.join(searchPath, packageName);
+        recordBase(packageDirectory);
+        if (subpath.length !== 0) {
+            recordBase(node_path_1.default.join(packageDirectory, ...subpath));
+        }
+        // CommonJS resolution continues past an existing but unusable package
+        // directory. Record every search root before the resolver runs so a
+        // farther selected package retains evaluation-time hashes for its
+        // superseding candidates.
+    }
+}
+/**
+ * Report one resolved descriptor edge to the parent loader. The channel is
+ * armed by the generated descriptor shim only after ttsx's own bootstrap and
+ * imports have loaded, keeping compiler implementation files out of the
+ * project's persistent-cache inputs.
+ */
+function recordPluginDescriptorResolution(specifier, parentURL, resolvedURL) {
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return;
+    const out = process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_OUT;
+    if (out === undefined || out.length === 0)
+        return;
+    const resolved = runtimeFilePath(resolvedURL);
+    if (resolved === undefined)
+        return;
+    const parent = runtimeFilePath(parentURL);
+    recordPluginDescriptorInput({
+        ...(parent === undefined ? {} : { parent }),
+        resolved,
+        specifier,
+    });
+    for (let directory = node_path_1.default.dirname(resolved);; directory = node_path_1.default.dirname(directory)) {
+        const manifest = node_path_1.default.join(directory, "package.json");
+        recordPluginDescriptorInput({
+            ...(parent === undefined ? {} : { parent }),
+            resolved: manifest,
+        });
+        if (isFile(manifest))
+            break;
+        const parentDirectory = node_path_1.default.dirname(directory);
+        if (parentDirectory === directory)
+            break;
+    }
+}
+function recordPluginDescriptorInput(record) {
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return;
+    const out = process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_OUT;
+    if (out === undefined || out.length === 0)
+        return;
+    recordPluginDescriptorInputOnce(record);
+    const resolved = node_path_1.default.resolve(record.resolved);
+    const parsed = node_path_1.default.parse(resolved);
+    let current = parsed.root;
+    const relative = node_path_1.default.relative(parsed.root, resolved);
+    for (const segment of relative.split(node_path_1.default.sep).slice(0, -1)) {
+        if (segment === "")
+            continue;
+        current = node_path_1.default.join(current, segment);
+        try {
+            if (node_fs_1.default.lstatSync(current).isSymbolicLink()) {
+                recordPluginDescriptorInputOnce({ resolved: current });
+            }
+        }
+        catch {
+            break;
+        }
+    }
+}
+/** Record one path without recursively revisiting its lexical ancestors. */
+function recordPluginDescriptorInputOnce(record) {
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return;
+    const out = process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_OUT;
+    if (out === undefined || out.length === 0)
+        return;
+    try {
+        const beforeSignature = pluginDescriptorInputMetadataSignature(record.resolved);
+        const observedHash = pluginDescriptorInputHash(record.resolved);
+        const observedRealpath = pluginDescriptorInputRealpath(record.resolved);
+        const afterSignature = pluginDescriptorInputMetadataSignature(record.resolved);
+        const unstable = record.unstable === true ||
+            beforeSignature === undefined ||
+            afterSignature === undefined ||
+            beforeSignature !== afterSignature ||
+            (record.hash !== undefined && record.hash !== observedHash) ||
+            (record.realpath !== undefined && record.realpath !== observedRealpath) ||
+            (record.signature !== undefined && record.signature !== afterSignature);
+        node_fs_1.default.appendFileSync(out, `${JSON.stringify({
+            ...record,
+            hash: observedHash,
+            realpath: observedRealpath,
+            ...(unstable ? { unstable: true } : { signature: afterSignature }),
+        })}\n`, "utf8");
+    }
+    catch {
+        // Dependency reporting is advisory to cache reuse; the selected entry is
+        // still retained by the parent if this best-effort side channel fails.
+    }
+}
+function pluginDescriptorInputRealpath(file) {
+    try {
+        return node_fs_1.default.realpathSync.native(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** Metadata identity that exposes content-preserving A-B-A replacement. */
+function pluginDescriptorInputMetadataSignature(file) {
+    const requested = node_path_1.default.resolve(file);
+    let current = requested;
+    for (;;) {
+        try {
+            const link = node_fs_1.default.lstatSync(current, { bigint: true });
+            let target = link;
+            if (link.isSymbolicLink()) {
+                try {
+                    target = node_fs_1.default.statSync(current, { bigint: true });
+                }
+                catch {
+                    // A broken link's own metadata cannot expose its target appearing
+                    // and disappearing during evaluation. Decline cache proof instead.
+                    return undefined;
+                }
+            }
+            return [
+                node_path_1.default.relative(current, requested),
+                link.dev,
+                link.ino,
+                link.mode,
+                link.size,
+                link.mtimeNs,
+                link.ctimeNs,
+                target.dev,
+                target.ino,
+                target.mode,
+                target.size,
+                target.mtimeNs,
+                target.ctimeNs,
+            ].join(":");
+        }
+        catch (error) {
+            if (!isMissingPathError(error))
+                return undefined;
+            const parent = node_path_1.default.dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+        }
+    }
+}
+function pluginDescriptorInputHash(file) {
+    try {
+        if (node_fs_1.default.statSync(file).isDirectory()) {
+            return pluginDescriptorDirectoryHash();
+        }
+        return node_crypto_1.default
+            .createHash("sha256")
+            .update(node_fs_1.default.readFileSync(file))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/** Stable public fingerprint for an existing directory candidate's kind. */
+function pluginDescriptorDirectoryHash() {
+    return node_crypto_1.default
+        .createHash("sha256")
+        .update("ttsc:host-input:directory\0")
+        .digest("hex");
+}
+function runtimeFilePath(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.startsWith("file:")) {
+        try {
+            return node_path_1.default.resolve((0, node_url_1.fileURLToPath)(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return node_path_1.default.isAbsolute(value) ? node_path_1.default.resolve(value) : undefined;
+}
+/** Remember an ESM root until its synchronous load hook prepares the project. */
+function rememberRuntimeEntry(result, context) {
+    if (result.url.startsWith("file:") &&
+        isTypeScriptSource((0, node_url_1.fileURLToPath)(result.url)) &&
+        (context.parentURL === undefined ||
+            !context.parentURL.startsWith("file:") ||
+            !isTypeScriptSource((0, node_url_1.fileURLToPath)(context.parentURL)))) {
+        runtimeEntryUrls.add(result.url);
+    }
+    return result;
+}
 /**
  * Restore a `node:` builtin URL when affected Node releases return the exact
  * prefix-stripped spelling from their synchronous CommonJS resolver.
@@ -244,6 +687,12 @@ function restoreStrippedNodeBuiltinScheme(specifier, result) {
         : result;
 }
 const builtProjects = new Map();
+// A descriptor evaluator's dependency emit must never be reused by another
+// process. PIDs are eventually recycled while the disk cache persists, so PID
+// alone cannot provide that isolation. One cryptographically random process
+// nonce keeps every evaluator generation distinct while `builtProjects` still
+// shares repeated imports inside this process.
+const descriptorProcessCacheNonce = node_crypto_1.default.randomBytes(16).toString("hex");
 /** File URLs whose CommonJS source was reached from an ESM parent import. */
 const commonJsNamedInteropUrls = new Set();
 const commonJsNameScanSources = new Map();
@@ -255,15 +704,15 @@ function load(url, context, nextLoad) {
     if (!isTypeScriptSource(filename)) {
         return nextLoad(url, context);
     }
-    const { format, source } = resolveRuntimeSource(filename, url);
+    const { format, source } = resolveRuntimeSource(filename, url, runtimeEntryUrls.delete(url) || isProcessEntry(filename));
     return {
         format,
         shortCircuit: true,
         source,
     };
 }
-function resolveRuntimeSource(filename, url = (0, node_url_1.pathToFileURL)(filename).href) {
-    const served = resolveServedSource(filename, url);
+function resolveRuntimeSource(filename, url = (0, node_url_1.pathToFileURL)(filename).href, prepareAsEntry = false) {
+    const served = resolveServedSource(filename, url, prepareAsEntry);
     const format = moduleFormat(filename, served.moduleOptions);
     return {
         format,
@@ -272,6 +721,13 @@ function resolveRuntimeSource(filename, url = (0, node_url_1.pathToFileURL)(file
             : served.source,
     };
 }
+/** Whether `filename` is the TypeScript main module named on Node's argv. */
+function isProcessEntry(filename) {
+    const entry = process.argv[1];
+    return (entry !== undefined &&
+        isTypeScriptSource(entry) &&
+        realPath(node_path_1.default.resolve(entry)) === realPath(filename));
+}
 function rememberCommonJsNamedInterop(result, context) {
     if (shouldExposeCommonJsNamedExports(result.url, context.parentURL)) {
         commonJsNamedInteropUrls.add(result.url);
@@ -316,9 +772,9 @@ function owningModuleOptions(filename) {
         return null;
     }
     const real = realPath(filename);
-    const m = manifest();
-    if (m !== null && entryEmitPath(m, real) !== null) {
-        return m.moduleOptions ?? {};
+    const owner = findEntryEmit(real)?.manifest;
+    if (owner !== undefined) {
+        return owner.moduleOptions ?? {};
     }
     const tsconfig = nearestTsconfig(real);
     if (tsconfig === null) {
@@ -330,10 +786,7 @@ function owningModuleOptions(filename) {
     }
     let options = {};
     try {
-        const project = (0, readProjectConfig_1.readProjectConfig)({
-            cwd: node_path_1.default.dirname(tsconfig),
-            tsconfig,
-        });
+        const project = readPluginDescriptorProjectConfig(tsconfig);
         options = projectModuleOptions(project.compilerOptions);
     }
     catch {
@@ -347,6 +800,108 @@ function owningModuleOptions(filename) {
     moduleOptionsCache.set(tsconfig, options);
     return options;
 }
+/**
+ * Read one owning config while its discovered chain stays unchanged.
+ *
+ * A preliminary read discovers `extends`; an accepted read is bracketed by
+ * equal fingerprints over that exact chain. If churn never settles, ttsx can
+ * still execute the last project but reports every observed config as unstable,
+ * preventing a later snapshot from certifying the torn result.
+ */
+function readPluginDescriptorProjectConfig(tsconfig) {
+    const read = () => (0, readProjectConfig_1.readProjectConfig)({ cwd: node_path_1.default.dirname(tsconfig), tsconfig });
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return read();
+    const observed = new Set([node_path_1.default.resolve(tsconfig)]);
+    let project;
+    try {
+        project = read();
+    }
+    catch (error) {
+        recordPluginDescriptorProjectInputs(observed, true);
+        throw error;
+    }
+    let inputs = normalizedProjectConfigPaths(project, tsconfig);
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        for (const input of inputs)
+            observed.add(input);
+        const before = pluginDescriptorInputHashes(inputs);
+        const beforeRealpaths = pluginDescriptorInputRealpaths(inputs);
+        const beforeSignatures = pluginDescriptorInputMetadataSignatures(inputs);
+        let candidate;
+        try {
+            candidate = read();
+        }
+        catch (error) {
+            recordPluginDescriptorProjectInputs(observed, true);
+            throw error;
+        }
+        const candidateInputs = normalizedProjectConfigPaths(candidate, tsconfig);
+        for (const input of candidateInputs)
+            observed.add(input);
+        const after = pluginDescriptorInputHashes(candidateInputs);
+        const afterRealpaths = pluginDescriptorInputRealpaths(candidateInputs);
+        const afterSignatures = pluginDescriptorInputMetadataSignatures(candidateInputs);
+        if (equalPluginDescriptorInputLists(inputs, candidateInputs) &&
+            equalPluginDescriptorInputHashes(before, after) &&
+            equalPluginDescriptorInputHashes(beforeRealpaths, afterRealpaths) &&
+            beforeSignatures !== undefined &&
+            afterSignatures !== undefined &&
+            equalPluginDescriptorInputHashes(beforeSignatures, afterSignatures)) {
+            for (const input of candidateInputs) {
+                recordPluginDescriptorInput({
+                    hash: after[input],
+                    realpath: afterRealpaths[input],
+                    resolved: input,
+                    signature: afterSignatures[input],
+                });
+            }
+            return candidate;
+        }
+        project = candidate;
+        inputs = candidateInputs;
+    }
+    recordPluginDescriptorProjectInputs(observed, true);
+    return project;
+}
+function normalizedProjectConfigPaths(project, requestedConfig) {
+    return [
+        ...new Set([requestedConfig, ...project.configPaths].map((file) => node_path_1.default.resolve(file))),
+    ].sort();
+}
+function pluginDescriptorInputHashes(inputs) {
+    return Object.fromEntries(inputs.map((input) => [input, pluginDescriptorInputHash(input)]));
+}
+function pluginDescriptorInputRealpaths(inputs) {
+    return Object.fromEntries(inputs.map((input) => [input, pluginDescriptorInputRealpath(input)]));
+}
+function pluginDescriptorInputMetadataSignatures(inputs) {
+    const output = {};
+    for (const input of inputs) {
+        const signature = pluginDescriptorInputMetadataSignature(input);
+        if (signature === undefined)
+            return undefined;
+        output[node_path_1.default.resolve(input)] = signature;
+    }
+    return output;
+}
+function equalPluginDescriptorInputLists(first, second) {
+    return (first.length === second.length &&
+        first.every((input, index) => input === second[index]));
+}
+function equalPluginDescriptorInputHashes(first, second) {
+    return (Object.keys(first).length === Object.keys(second).length &&
+        Object.entries(first).every(([input, hash]) => second[input] === hash));
+}
+function recordPluginDescriptorProjectInputs(inputs, unstable) {
+    for (const input of inputs) {
+        const resolved = node_path_1.default.resolve(input);
+        recordPluginDescriptorInput({
+            resolved,
+            ...(unstable ? { unstable: true } : {}),
+        });
+    }
+}
 /** Narrow a resolved project's compiler options to the emit-format pair. */
 function projectModuleOptions(compilerOptions) {
     return {
@@ -365,12 +920,31 @@ function projectModuleOptions(compilerOptions) {
  * "transform"` type-strip. Shared by the ESM `load` hook and the CommonJS
  * `require` handler.
  */
-function resolveServedSource(filename, url = (0, node_url_1.pathToFileURL)(filename).href) {
+function resolveServedSource(filename, url = (0, node_url_1.pathToFileURL)(filename).href, prepareAsEntry = false) {
     const real = realPath(filename);
-    const served = serveEntryEmit(real);
+    // Only the public preload can prepare a newly discovered root. Direct ttsx
+    // has one pre-built manifest and historically relies on trailing-stem
+    // recovery when Windows presents the same source through its short and long
+    // temp-path spellings (the lint TypeScript-config loader is one such case).
+    // Treating that boundary as prepare-only would discard the existing emit and
+    // feed ESM source into CommonJS interop, producing ERR_REQUIRE_CYCLE_MODULE.
+    const prepareEntry = prepareAsEntry ? prepareRuntimeEntry : undefined;
+    // A JavaScript-to-TypeScript boundary is a new checked root unless an
+    // existing manifest proves exact ownership. Trailing-stem recovery is not
+    // ownership evidence: two out-of-include `index.ts` roots can otherwise map
+    // to the first manifest's `index.js`, skipping the second root's diagnostics.
+    let served = serveEntryEmit(real, prepareEntry === undefined);
     if (served !== null) {
         return withInlineSourceMap(served);
     }
+    if (prepareEntry !== undefined) {
+        registeredManifests.push(prepareEntry(real));
+        served = serveEntryEmit(real);
+        if (served === null) {
+            throw new Error(`ttsx: prepared entry emit not found for ${filename}`);
+        }
+        return withInlineSourceMap(served);
+    }
     const built = serveDependencyEmit(real);
     if (built !== null) {
         return withInlineSourceMap(built);
@@ -447,7 +1021,7 @@ function emitOrphanAsCommonJs(filename) {
             return hit;
         }
     }
-    const outDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "ttsx-orphan-"));
+    const outDir = (0, createCanonicalTempDirectory_1.createCanonicalTempDirectory)("ttsx-orphan-");
     try {
         const res = (0, spawnNative_1.spawnNative)(tsgo, [
             filename,
@@ -508,7 +1082,7 @@ function emitCommonJsForNameScan(filename) {
         commonJsNameScanSources.set(real, null);
         return null;
     }
-    const outDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "ttsx-export-scan-"));
+    const outDir = (0, createCanonicalTempDirectory_1.createCanonicalTempDirectory)("ttsx-export-scan-");
     try {
         const res = (0, spawnNative_1.spawnNative)(tsgo, [
             real,
@@ -936,54 +1510,93 @@ function isIdentifierName(name) {
  * `rootDir` cannot have a mirrored emit, so it falls through to the dependency
  * paths.
  */
-function serveEntryEmit(real) {
-    const m = manifest();
-    if (m === null) {
-        return null;
-    }
-    const emitted = entryEmitPath(m, real);
-    if (emitted === null) {
+function serveEntryEmit(real, allowStemFallback = true) {
+    const owner = findEntryEmit(real, allowStemFallback);
+    if (owner === null) {
         return null;
     }
-    const source = readFileOrNull(emitted);
+    const source = readFileOrNull(owner.emittedFile);
     return source === null
         ? null
         : {
-            emittedFile: emitted,
-            moduleOptions: m.moduleOptions ?? {},
+            emittedFile: owner.emittedFile,
+            moduleOptions: owner.manifest.moduleOptions ?? {},
             source,
             sourceFile: real,
         };
 }
+/**
+ * Find the manifest that owns `real`. Explicit prepared roots win, followed by
+ * exact mirrored paths across every manifest. Only then may legacy stem
+ * recovery run, so one manifest's approximate match cannot shadow another's
+ * exact emit.
+ */
+function findEntryEmit(real, allowStemFallback = true) {
+    const manifests = runtimeManifests();
+    for (const candidate of manifests) {
+        if (candidate.entrySource !== undefined &&
+            candidate.entryFile !== undefined &&
+            realPath(candidate.entrySource) === real &&
+            node_fs_1.default.existsSync(candidate.entryFile)) {
+            return { emittedFile: candidate.entryFile, manifest: candidate };
+        }
+    }
+    for (const candidate of manifests) {
+        const emitted = entryEmitPath(candidate, real, false);
+        if (emitted !== null) {
+            return { emittedFile: emitted, manifest: candidate };
+        }
+    }
+    if (!allowStemFallback) {
+        return null;
+    }
+    for (const candidate of manifests) {
+        const emitted = entryEmitPath(candidate, real, true);
+        if (emitted !== null) {
+            return { emittedFile: emitted, manifest: candidate };
+        }
+    }
+    return null;
+}
 /**
  * The entry project's emitted JavaScript for `real`, or `null` when that
  * project did not emit it. Shared with `owningModuleOptions` so "the entry
  * project owns this file" means exactly one thing in both places.
  */
-function entryEmitPath(m, real) {
-    const cached = entryEmitPathCache.get(real);
-    if (cached !== undefined) {
-        return cached;
+function entryEmitPath(m, real, allowStemFallback = true) {
+    const cache = allowStemFallback
+        ? entryEmitPathCache
+        : exactEntryEmitPathCache;
+    let manifestCache = cache.get(m);
+    if (manifestCache === undefined) {
+        manifestCache = new Map();
+        cache.set(m, manifestCache);
+    }
+    if (manifestCache.has(real)) {
+        return manifestCache.get(real) ?? null;
     }
     const resolved = isWithin(real, m.rootDir)
         ? (0, resolveEmittedJavaScript_1.resolveEmittedJavaScript)({
+            allowStemFallback,
             emittedFiles: m.emittedFiles,
             outDir: m.emitDir,
             projectRoot: m.rootDir,
             sourceFile: real,
         })
         : null;
-    entryEmitPathCache.set(real, resolved);
+    manifestCache.set(real, resolved);
     return resolved;
 }
 /**
  * Memo for `entryEmitPath`, because it is now on the `resolve` hook's path
  * through `owningModuleOptions` — once per import specifier — and a miss inside
  * `resolveEmittedJavaScript` walks the whole emit tree. The entry emit is
- * written once before the run starts and never changes under it, so one answer
- * per path is the only one there is.
+ * written once before the run starts and never changes under it. Registration
+ * can add several independent entry emits, so the manifest is part of the cache
+ * identity as well as the source path.
  */
-const entryEmitPathCache = new Map();
+const entryEmitPathCache = new WeakMap();
+const exactEntryEmitPathCache = new WeakMap();
 /**
  * True when `real` is `directory` itself or sits beneath it. Handles a root
  * `directory` (`/`, `C:\`): naively appending a separator would yield `//`,
@@ -1075,11 +1688,7 @@ function ensureProjectBuilt(tsconfig) {
     return built;
 }
 function dependencyCachePaths(tsconfig) {
-    const key = node_crypto_1.default
-        .createHash("sha256")
-        .update(tsconfig)
-        .digest("hex")
-        .slice(0, 16);
+    const key = dependencyCacheKey(tsconfig);
     const root = dependencyCacheRoot();
     return {
         cacheDir: node_path_1.default.join(root, key),
@@ -1088,6 +1697,24 @@ function dependencyCachePaths(tsconfig) {
         root,
     };
 }
+/** Derive one dependency cache key; exported for isolation regressions. */
+function dependencyCacheKey(tsconfig, options = {}) {
+    const descriptorLoad = options.descriptorLoad ?? process.env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1";
+    return (node_crypto_1.default
+        .createHash("sha256")
+        .update(tsconfig)
+        // Descriptor evaluation promises a result bound to this process's exact
+        // input observations. Reusing an emit another evaluator built can pair
+        // that process's old source/config bytes with this process's later hashes.
+        // Keep ordinary ttsx worker sharing, but isolate descriptor builds with a
+        // non-reusable process nonce; the in-process `builtProjects` map still
+        // compiles each owning project once.
+        .update(descriptorLoad
+        ? `\0descriptor-process:${options.descriptorNonce ?? descriptorProcessCacheNonce}`
+        : "")
+        .digest("hex")
+        .slice(0, 16));
+}
 /** The immutable emit directory of one build generation under `cacheDir`. */
 function dependencyGenerationDir(cacheDir, generation) {
     return node_path_1.default.join(cacheDir, `gen-${generation}`);
@@ -1216,7 +1843,7 @@ function sleepSync(ms) {
  * never be reused.
  */
 function buildDependency(tsconfig, cacheDir, metaPath) {
-    const project = (0, readProjectConfig_1.readProjectConfig)({ cwd: node_path_1.default.dirname(tsconfig), tsconfig });
+    const project = readPluginDescriptorProjectConfig(tsconfig);
     const generation = newDependencyGeneration();
     const emitDir = dependencyGenerationDir(cacheDir, generation);
     node_fs_1.default.rmSync(emitDir, { force: true, recursive: true });
@@ -1303,10 +1930,19 @@ function publishDependencyMeta(metaPath, meta) {
         throw error;
     }
 }
-function dependencyCacheRoot() {
-    const m = manifest();
-    return m !== null && m.depCacheDir.length !== 0
-        ? m.depCacheDir
+function dependencyCacheRoot(env = process.env) {
+    // Descriptor evaluators are disposable and must not leave one isolated emit
+    // generation in the shared temp cache per load. Their result file already
+    // lives in the evaluator-owned directory that the parent removes in
+    // `finally`; put dependency emits beside it so that cleanup owns both.
+    if (env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1" &&
+        typeof env.TTSC_PLUGIN_DESCRIPTOR_OUT === "string" &&
+        node_path_1.default.isAbsolute(env.TTSC_PLUGIN_DESCRIPTOR_OUT)) {
+        return node_path_1.default.join(node_path_1.default.dirname(env.TTSC_PLUGIN_DESCRIPTOR_OUT), "dependency-cache");
+    }
+    const owner = runtimeManifests().find((candidate) => candidate.depCacheDir.length !== 0);
+    return owner !== undefined
+        ? owner.depCacheDir
         : node_path_1.default.join(node_os_1.default.tmpdir(), "ttsx-dep");
 }
 // -----------------------------------------------------------------------------
@@ -1588,7 +2224,6 @@ function formatDuration(ms) {
     const remainder = seconds % 60;
     return minutes === 0 ? `${seconds}s` : `${minutes}m ${remainder}s`;
 }
-/** Owning-tsconfig cache keyed by directory, mirroring `packageTypeCache`. */
 const tsconfigCache = new Map();
 const moduleOptionsCache = new Map();
 /**
@@ -1609,13 +2244,30 @@ function nearestTsconfig(file) {
     for (;;) {
         const cached = tsconfigCache.get(directory);
         if (cached !== undefined) {
-            return rememberTsconfig(chain, cached);
+            if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1") {
+                return rememberTsconfig(chain, cached.result, cached.candidates);
+            }
+            // Bracket the cached selection with the same candidate observations the
+            // parent later reconciles. A nearer config created between a liveness
+            // check and reporting must conflict, not be paired with the cached
+            // farther result and certified as current.
+            recordPluginDescriptorTsconfigCandidates(cached.candidates);
+            const current = nearestExistingTsconfig(cached.candidates);
+            recordPluginDescriptorTsconfigCandidates(cached.candidates);
+            if (current === cached.result) {
+                return rememberTsconfig(chain, cached.result, cached.candidates);
+            }
+            // Descriptor factories can deliberately create a config before a lazy
+            // import. A lookup cached while an earlier import ran must not keep
+            // serving the orphan lane after the nearest candidate changed.
+            tsconfigCache.delete(directory);
         }
         if (node_path_1.default.basename(directory) === "node_modules") {
             return rememberTsconfig(chain, null);
         }
         chain.push(directory);
         const candidate = node_path_1.default.join(directory, "tsconfig.json");
+        recordPluginDescriptorTsconfigCandidates([candidate]);
         if (isFile(candidate)) {
             return rememberTsconfig(chain, candidate);
         }
@@ -1626,12 +2278,33 @@ function nearestTsconfig(file) {
         directory = parent;
     }
 }
-function rememberTsconfig(directories, result) {
-    for (const directory of directories) {
-        tsconfigCache.set(directory, result);
+function nearestExistingTsconfig(candidates) {
+    for (const candidate of candidates) {
+        if (isFile(candidate))
+            return node_path_1.default.resolve(candidate);
+    }
+    return null;
+}
+function rememberTsconfig(directories, result, tailCandidates = []) {
+    let candidates = [...tailCandidates];
+    for (let index = directories.length - 1; index >= 0; index -= 1) {
+        const directory = directories[index];
+        candidates = [node_path_1.default.join(directory, "tsconfig.json"), ...candidates];
+        tsconfigCache.set(directory, { candidates, result });
     }
     return result;
 }
+/** Report every owning-config candidate observed by the nearest-config walk. */
+function recordPluginDescriptorTsconfigCandidates(candidates) {
+    if (process.env.TTSC_PLUGIN_DESCRIPTOR_INPUTS_ACTIVE !== "1")
+        return;
+    for (const candidate of candidates) {
+        const resolved = node_path_1.default.resolve(candidate);
+        recordPluginDescriptorInput({
+            resolved,
+        });
+    }
+}
 function readFileOrNull(file) {
     if (file === null) {
         return null;
@@ -1730,6 +2403,15 @@ const JS_TO_TS_EXTENSIONS = new Map([
     [".mjs", [".mts"]],
     [".cjs", [".cts"]],
 ]);
+/** Candidate sources that can satisfy one missing JavaScript spelling. */
+function typescriptSourcesForJavaScriptSpecifier(file) {
+    const extension = node_path_1.default.extname(file).toLowerCase();
+    const substitutions = JS_TO_TS_EXTENSIONS.get(extension);
+    if (substitutions === undefined)
+        return [];
+    const stem = file.slice(0, file.length - extension.length);
+    return substitutions.map((candidate) => stem + candidate);
+}
 /**
  * Rescue a `specifier` that Node's resolver rejected: map a JavaScript
  * extension back to its TypeScript source, or probe candidate extensions /