ttsc 0.30.3 → 0.31.0

package/src/launcher/internal/runtime/RuntimeFilesystem.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+
+/**
+ * Filesystem predicates the runtime hooks and the dependency lock share.
+ *
+ * Missing-component errno classification and followed regular-file stat share
+ * one meaning across lock recovery and the serve lanes. A code-shaped caller
+ * value is not authenticated native evidence, and file kind is not proof of
+ * readable contents or a pinned path identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Missing-component code classification and followed regular-file stat are distinct predicates; they do not authenticate arbitrary error-shaped inputs or certify readable contents.
+ * @evidence contracts/common.md#clear-and-simple-design One small namespace shares the two filesystem predicates without retaining an alternate filesystem model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Predicates use documented Node fs and errno semantics; no consumer-specific path or foreign API replacement determines the answer.
+ * @evidence contracts/common.md#meaningful-documentation The namespace describes the common decision boundary and each function documents its own missing-path or regular-file meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native stat and portable ENOENT/ENOTDIR error codes establish file type and absence without guessing from the host OS name.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups predicates and does not independently choose a computation strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace retains no query cache or in-flight computation; each predicate inspects its current argument.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no retained state, handle or task.
+ */
+export namespace RuntimeFilesystem {
+  /**
+   * Whether an ordinarily readable code is ENOENT or ENOTDIR, the native
+   * missing-component classifications. Nullish values or unrelated readable
+   * codes return false. Accessor/proxy exceptions propagate; an arbitrary
+   * caller-supplied code is not authenticated filesystem evidence.
+   *
+   * @evidence contracts/common.md#principled-implementation Only the two missing-component codes classify true; permission or other readable codes classify false. Native callers supply the provenance of their caught errors rather than this predicate authenticating unknown values.
+   * @evidence contracts/common.md#clear-and-simple-design One code projection and two literal comparisons keep classification identical across callers without claiming total access to arbitrary objects.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No broad exception-to-absence fallback or expected path name replaces the documented errno distinction.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes code classification from authenticated absence and documents nullish/unrelated values and exceptional property access.
+   * @evidence contracts/portability.md#os-neutral-implementation Node's documented errno codes represent native absence across hosts without inspecting platform-specific error message text.
+   * @evidence contracts/performance.md#efficient-algorithms For native errors with ordinary code data, one property projection and two fixed literal comparisons allocate no traversal or history. Arbitrary caller accessors/proxies can perform work or throw; fixed predicate steps do not bound their behavior.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Error values are immediate caller inputs and establish no shared computation or invalidation boundary.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate retains no state or native resource.
+   */
+  export function isMissingPathError(error: unknown): boolean {
+    const code = (error as NodeJS.ErrnoException | null)?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+  }
+
+  /**
+   * Whether `candidate` exists and is a regular file, following links. Failed
+   * stat calls return false, including missing and unreadable paths.
+   *
+   * @evidence contracts/common.md#principled-implementation Native stat follows links and classifies regular files rather than directories or special files; failure returns false, while success certifies only observed kind, not readable contents or stable identity.
+   * @evidence contracts/common.md#clear-and-simple-design A single fs query and boolean failure boundary make the serve predicate independent of lock-error classification.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The answer comes from the actual filesystem type rather than filename extension or fixture path.
+   * @evidence contracts/common.md#meaningful-documentation The native comment explains link following and failed-stat behavior so callers know false does not distinguish missing from denied access.
+   * @evidence contracts/portability.md#os-neutral-implementation fs.statSync exposes the native file type and link behavior; native spelling is preserved without separator or case rewriting.
+   * @evidence contracts/performance.md#efficient-algorithms One native stat classifies the supplied path without an explicit parent listing or content read; native path resolution/link traversal and latency are not bounded by that single call count.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work File existence and type may change between calls; this predicate owns no validity identity for cached answers.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous stat leaves no descriptor or task retained after the call.
+   */
+  export function isFile(candidate: string): boolean {
+    try {
+      return fs.statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  }
+}

package/src/launcher/internal/runtime/RuntimeHookOptions.ts

@@ -0,0 +1,23 @@
+import type { RuntimeEntryPreparer } from "./RuntimeEntryPreparer";
+
+/**
+ * Options of {@link installRuntimeHooks}.
+ *
+ * Direct `ttsx` installs the hooks without options: its one entry project was
+ * prepared by the parent before the child started. `ttsc/register` passes
+ * `prepareEntry`, because a host such as Mocha discovers TypeScript roots only
+ * after the hooks are live.
+ *
+ * @evidence contracts/common.md#principled-implementation An optional preparation callback distinguishes a prebuilt direct entry from a host that discovers roots after registration; absence preserves the direct launcher's existing manifest ownership.
+ * @evidence contracts/common.md#clear-and-simple-design The single optional callback delegates checked preparation to its owner instead of mixing compiler options or build state into hook configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Host preparation is an explicit injection boundary; this options type introduces no foreign mutation or consumer-specific branch.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain why the callback is optional and how direct ttsx differs from a discovering host, while the field retains native documentation without tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The callback's named type specifies a resolved native filename and an owning manifest, keeping filesystem representation explicit at the preparation boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface RuntimeHookOptions {
+  /** Prepare and type-check a TypeScript root discovered after registration. */
+  prepareEntry?: RuntimeEntryPreparer;
+}

package/src/launcher/internal/runtime/RuntimeIsolatedEmit.ts

@@ -0,0 +1,88 @@
+/**
+ * Compiler arguments shared by orphan execution and export-name preparation.
+ *
+ * These isolated emits ignore consumer configuration and use ES2022 lowering.
+ * The runtime chooses the source's module format before calling this policy;
+ * export-name preparation requests CommonJS. Execution includes source maps,
+ * while speculative name preparation keeps its output separate from the runtime
+ * orphan cache. Compiler invocation and fallback belong to the caller.
+ *
+ * @evidence contracts/common.md#principled-implementation Both callers use the same isolated compiler policy and the cache includes that policy's original token sequence, preserving lowering and cache identity together.
+ * @evidence contracts/common.md#clear-and-simple-design One internal namespace owns argument construction and its cache discriminator; invocation, source ownership and fallback remain in the runtime hook owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported compiler flags express isolation and lowering without rewriting source text, replacing a compiler or adding a test-only execution path.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish execution maps, CommonJS name preparation and the caller's remaining compiler/fallback responsibilities.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This namespace groups argument-data operations; the caller owns native executable, cwd, file and process boundaries.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The container performs no computation; its members describe argument and discriminator construction.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace coordinates no cached or in-flight emit; the caller uses its discriminator in the actual cache policy.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Immutable policy tokens retain fixed data and no handles, tasks or request history.
+ */
+export namespace RuntimeIsolatedEmit {
+  /**
+   * Build the isolated emit arguments for an already selected source and
+   * format.
+   *
+   * Module execution uses ESNext emit; CommonJS execution and name preparation
+   * use CommonJS emit. Only execution requests external maps and inline source
+   * content. Paths remain separate argument values, including spaces.
+   *
+   * @evidence contracts/common.md#principled-implementation The selected format supplies the native module flag, fixed isolation flags suppress config and type-checking, and the purpose controls only the existing map suffix.
+   * @evidence contracts/common.md#clear-and-simple-design A fresh ordered token array combines selected input/output values with one common policy and the execution-only map pair.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Arguments are ordinary compiler options, not shell text, synthetic compiler outputs or source-value substitutions.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph identifies format mapping, map ownership and path-token preservation without claiming actual lowering ran.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This operation copies opaque path values into argv and accesses no native path, file or process; the invocation owner supplies their supported context.
+   * @evidence contracts/performance.md#efficient-algorithms A fixed policy and fixed optional suffix create a constant number of token references; input and output strings are retained as values without scanning their text or compiling source.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Argument construction coordinates no completed or in-flight compilation; emit reuse belongs to the caller's content and compiler identity policy.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned array transfers to the caller and no historical input, handle or task remains in this operation.
+   */
+  export function compilerArgs(
+    input: string,
+    outDir: string,
+    format: "commonjs" | "module",
+    purpose: "execution" | "export-scan",
+  ): string[] {
+    return [
+      input,
+      "--module",
+      format === "commonjs" ? "commonjs" : "esnext",
+      ...ISOLATED_EMIT_ARGS,
+      ...(purpose === "execution" ? ["--sourceMap", "--inlineSources"] : []),
+      "--outDir",
+      outDir,
+    ];
+  }
+
+  /**
+   * The original NUL-separated isolated policy tokens included in orphan keys.
+   * Module format and the source-map version remain separate caller-owned key
+   * inputs. This string does not prove compiler or source identity.
+   *
+   * @evidence contracts/common.md#principled-implementation Joining the same base tokens used by argument construction preserves the existing cache discriminator byte order and separators.
+   * @evidence contracts/common.md#clear-and-simple-design The policy discriminator comes from its single token owner rather than a duplicated list in the runtime cache.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The discriminator describes actual flags; it does not substitute for the caller's compiler/content observations or certify a cache hit.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph distinguishes base policy from module/map and actual identity inputs in the cache key.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Joining fixed option strings has no native platform boundary.
+   * @evidence contracts/performance.md#efficient-algorithms Joining the fixed policy visits its total token text and allocates one result string; there are no input-dependent source or file scans.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation supplies a discriminator and coordinates no reusable emit; cache admission remains with its caller.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned string belongs to the caller; no historical values, handles or tasks are retained.
+   */
+  export function policyKey(): string {
+    return ISOLATED_EMIT_ARGS.join("\0");
+  }
+}
+
+/**
+ * Config-free lowering leaves type diagnostics with the checked entry owner.
+ * Isolation avoids imported const-enum inlining and secondary emits. Unowned
+ * TSX uses the automatic JSX runtime, respecting any source import pragma.
+ */
+const ISOLATED_EMIT_ARGS = [
+  "--ignoreConfig",
+  "--target",
+  "es2022",
+  "--jsx",
+  "react-jsx",
+  "--noCheck",
+  "--skipLibCheck",
+  "--noResolve",
+  "--isolatedModules",
+] as const;

package/src/launcher/internal/runtime/RuntimeLoaderCapabilities.ts

@@ -0,0 +1,256 @@
+import { registerHooks } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Worker, threadId } from "node:worker_threads";
+
+import { E2ETrace } from "../../../internal/E2ETrace";
+
+/**
+ * What this runtime's module loader does on its own, read by asking it rather
+ * than by its version.
+ *
+ * The ttsx runtime serves TypeScript through `module.registerHooks`, the
+ * supported customization API. How far that API reaches, and how the loader
+ * shapes a CommonJS module imported from ESM, differ between Node releases in
+ * both directions, so this helper instance memoizes actual public-API probes.
+ * Main-thread temporary hooks deregister afterwards; the separate worker owns
+ * its hooks until termination. The runtime installer invokes these before its
+ * own hooks exist, so nothing they load is recorded as an input of the
+ * program.
+ *
+ * @evidence contracts/common.md#principled-implementation Public loader probes observe the actual require.resolve, namespace and hooked-import behavior instead of deriving it from a release number; each boolean selects the runtime path matching that observed capability.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns three independent lazy capability answers and their private probes, keeping loader adaptation choices with the hook consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Temporary registerHooks/deregister boundaries are supported customization, not private-loader mutation; the worker tests a real ESM-to-CommonJS path rather than a fixture version table.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why loader differences require observation and describe each affected behavior; worker comments distinguish synchronous require from the probed import path.
+ * @evidence contracts/portability.md#os-neutral-implementation Native filenames become URLs through pathToFileURL and workers use Node APIs; no shell quoting, separator substitution or OS-name case rule implements the probes.
+ * @evidence contracts/performance.md#efficient-algorithms Three memoized probe paths delegate native resolution/module loading or Worker initialization; input path text, loader work and startup latency are not bounded by the fixed probe count. Atomics waits at most ten seconds after worker construction; that wait is not a bound on constructor or teardown latency.
+ * @evidence contracts/performance.md#reuse-equivalent-work Completed booleans serve this helper instance under the installer's stable native-loader premise; arbitrary later external hook changes are not re-probed. Propagated exceptions leave initialization unset; worker construction/failure/no-answer paths can instead memoize conservative false.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Three booleans remain with this helper instance. Main-thread temporary hooks deregister in finally; the probe namespace/cache belongs to Node. Worker termination is requested asynchronously after the answer wait, so completed teardown and release of its hooks/streams are not certified by return.
+ */
+export namespace RuntimeLoaderCapabilities {
+  /**
+   * Whether `require.resolve` consults resolve hooks registered with
+   * `module.registerHooks`.
+   *
+   * A runtime whose `require.resolve` does consult them resolves a TypeScript
+   * source through ttsx's own resolve hook; one that does not answers from
+   * Node's resolver alone, which knows no TypeScript source.
+   *
+   * @evidence contracts/common.md#principled-implementation A sentinel request through require.resolve observes whether the public resolve hook was actually consulted, giving the consumer grounds for its corresponding resolution lane.
+   * @evidence contracts/common.md#clear-and-simple-design The public accessor exposes one cached capability while a private probe owns registration and cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No private Node resolver is patched and no version-specific expected answer replaces the actual supported-hook observation.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish hook-aware and native-only resolution and explain why the distinction affects TypeScript sources.
+   * @evidence contracts/portability.md#os-neutral-implementation The probe uses a native filename converted with pathToFileURL; Node supplies synchronous module resolution on each supported host.
+   * @evidence contracts/performance.md#efficient-algorithms One sentinel request through temporary public hooks initializes the boolean; path text and delegated native resolution are initialization costs. Later calls read the helper-instance memo without another registration.
+   * @evidence contracts/performance.md#reuse-equivalent-work requireResolve stores the running loader's stable capability for subsequent consumers; a thrown probe does not store an invented answer.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally; this helper instance retains the boolean. Node and the surrounding installed runtime own any delegated module/cache state.
+   */
+  export function requireResolveConsultsHooks(): boolean {
+    requireResolve ??= probeRequireResolve();
+    return requireResolve;
+  }
+
+  /**
+   * Whether the namespace of a CommonJS module imported from ESM carries a
+   * `module.exports` export beside `default` and the statically detected
+   * names.
+   *
+   * @evidence contracts/common.md#principled-implementation Importing the side-effect-free CommonJS probe through public hooks observes whether the actual ESM namespace contains module.exports, so facade shape follows the running loader.
+   * @evidence contracts/common.md#clear-and-simple-design The accessor exposes only the namespace capability, with source construction and temporary hooks isolated in its private probe.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A real namespace is inspected rather than fabricating the export from a Node version or modifying CommonJS globals.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module.exports from default and static names, which is the fact facade callers need.
+   * @evidence contracts/portability.md#os-neutral-implementation path.join and pathToFileURL preserve native probe filenames and URL spelling; no hand-built file URL assumes drive or separator syntax.
+   * @evidence contracts/performance.md#efficient-algorithms One hooked importer delegates native CommonJS/ESM loading and namespace-key enumeration, including native path text and loader work; later calls read this helper-instance memo.
+   * @evidence contracts/performance.md#reuse-equivalent-work The namespace convention is stable for the running loader, so the cached boolean is shared by all facades; failed probing propagates rather than guessing the convention.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally. The helper retains its boolean; Node owns the probe CommonJS/ESM cache entries, which are not explicitly evicted here.
+   */
+  export function commonJsNamespaceCarriesModuleExports(): boolean {
+    moduleExportsKey ??= probeModuleExportsKey();
+    return moduleExportsKey;
+  }
+
+  /**
+   * Whether a CommonJS module the ESM loader evaluates from source a load hook
+   * returned exposes `require.cache` and `require.extensions` as objects.
+   *
+   * A runtime that does not (Node 22) evaluates it with a narrower `require`:
+   * no `cache`, `extensions`, or `resolve.paths`, whose calls go through the
+   * ESM loader and cannot load a module Node's CommonJS loader would load.
+   * Whenever any load hook is registered, every CommonJS module an `import`
+   * reaches takes that path there, the ones the hook passes to `nextLoad`
+   * included.
+   *
+   * @evidence contracts/common.md#principled-implementation A worker runs an actual ESM import whose hooked CommonJS body observes cache/extensions object properties; only that positive result permits the caller's unadapted lane. This does not independently test every require method or arbitrary CommonJS dependency.
+   * @evidence contracts/common.md#clear-and-simple-design The synchronous accessor hides worker coordination and returns one cached loader capability rather than exposing timing or worker state to hook consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The probe registers supported hooks in its own worker and preserves public createRequire adaptation on uncertain results instead of replacing Node internals.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain narrowed require and why passthrough CommonJS imports are affected; private prose identifies the required asynchronous import path.
+   * @evidence contracts/portability.md#os-neutral-implementation Node workers and pathToFileURL handle the native execution boundary without process shell commands or platform-specific loader guesses.
+   * @evidence contracts/performance.md#efficient-algorithms Worker construction delegates native thread/startup work; one four-byte shared answer and a bounded Atomics wait coordinate this attempt. Repeated accessor calls read the helper-instance memo, including cached conservative negatives, without another worker.
+   * @evidence contracts/performance.md#reuse-equivalent-work The running Node loader's require behavior is shared across imports; a conservative negative result after failure consistently selects the facade that supplies ordinary require.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One worker belongs to initialization and receives terminate in finally; one boolean remains afterwards. The synchronous accessor does not await termination, so completion of teardown is not independently bounded here. Opt-in observations distinguish its actual creation, termination request returning a Promise, and exit event under one probe id. No await, rejection handler or error listener changes the existing termination/unhandled-error behavior. Exit reports this worker lifecycle only and cannot establish an OS executable-lock owner.
+   */
+  export function hookedCommonJsImportKeepsRequire(): boolean {
+    hookedCommonJsRequire ??= probeHookedCommonJsRequire();
+    return hookedCommonJsRequire;
+  }
+
+  let requireResolve: boolean | undefined;
+  let moduleExportsKey: boolean | undefined;
+  let hookedCommonJsRequire: boolean | undefined;
+  let probeTraceOrdinal = 0;
+
+  /**
+   * Ask the runtime by running the path that narrows `require`: an `import()`,
+   * whose CommonJS dependency the ESM loader evaluates from a hook's source. A
+   * synchronous `require()` path is not the asynchronous import path whose
+   * behavior this probe asks about. The import runs in a worker thread with
+   * hooks of its own that answer only the probe's two virtual modules, while
+   * this thread waits for its answer.
+   */
+  function probeHookedCommonJsRequire(): boolean {
+    const answer = new Int32Array(new SharedArrayBuffer(4));
+    let worker: Worker;
+    try {
+      worker = new Worker(HOOKED_COMMONJS_REQUIRE_PROBE, {
+        eval: true,
+        stderr: true,
+        stdout: true,
+        workerData: answer,
+      });
+    } catch {
+      return false;
+    }
+    const workerThreadId = worker.threadId;
+    const probeId = process.env.TTSC_E2E_TRACE
+      ? String(++probeTraceOrdinal)
+      : undefined;
+    if (probeId !== undefined) {
+      try {
+        const fields = { probeId, pid: process.pid, threadId, workerThreadId };
+        E2ETrace.capabilityResolution("runtime-loader-worker-created", fields);
+        worker.once("exit", (exitCode) =>
+          E2ETrace.capabilityResolution("runtime-loader-worker-exited", {
+            ...fields,
+            exitCode,
+          }),
+        );
+      } catch {
+        // Observer registration must not change the probe or worker errors.
+      }
+    }
+    try {
+      Atomics.wait(answer, 0, 0, HOOKED_COMMONJS_REQUIRE_PROBE_TIMEOUT_MS);
+    } finally {
+      void worker.terminate();
+      if (probeId !== undefined)
+        E2ETrace.capabilityResolution(
+          "runtime-loader-worker-terminate-requested",
+          {
+            probeId,
+            pid: process.pid,
+            threadId,
+            workerThreadId,
+          },
+        );
+    }
+    // Anything but a "kept" answer counts as narrowed: the facade the runtime
+    // then uses supplies the supported public createRequire adaptation,
+    // while worker startup and requested termination remain separate costs.
+    return answer[0] === 1;
+  }
+
+  function probeRequireResolve(): boolean {
+    const sentinel = `./.ttsc-require-resolve-probe-${process.pid}`;
+    let consulted = false;
+    const probe = registerHooks({
+      resolve(specifier, context, nextResolve) {
+        if (specifier !== sentinel) return nextResolve(specifier, context);
+        consulted = true;
+        return { shortCircuit: true, url: pathToFileURL(__filename).href };
+      },
+    });
+    try {
+      require.resolve(sentinel);
+    } catch {
+      // A runtime that never consulted the hook refuses the sentinel.
+    } finally {
+      probe.deregister();
+    }
+    return consulted;
+  }
+
+  function probeModuleExportsKey(): boolean {
+    const module = path.join(__dirname, "interopProbe.js");
+    const importer = path.join(
+      __dirname,
+      `.ttsc-interop-probe-${process.pid}.mjs`,
+    );
+    const importerUrl = pathToFileURL(importer).href;
+    const probe = registerHooks({
+      resolve(specifier, context, nextResolve) {
+        return specifier === importer || specifier === importerUrl
+          ? { shortCircuit: true, url: importerUrl }
+          : nextResolve(specifier, context);
+      },
+      load(url, context, nextLoad) {
+        return url === importerUrl
+          ? {
+              format: "module",
+              shortCircuit: true,
+              source: `import * as namespace from ${JSON.stringify(pathToFileURL(module).href)};\nexport default Object.keys(namespace);\n`,
+            }
+          : nextLoad(url, context);
+      },
+    });
+    // A probe that fails says nothing about the shape, so it is not guessed.
+    try {
+      const keys = (require(importer) as { default: unknown }).default;
+      return Array.isArray(keys) && keys.includes("module.exports");
+    } finally {
+      probe.deregister();
+    }
+  }
+}
+
+/**
+ * How long the probe waits for its worker. No startup latency is guaranteed;
+ * the answer wait is ten seconds after construction and does not bound worker
+ * creation or completed termination.
+ */
+const HOOKED_COMMONJS_REQUIRE_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * The worker body of `probeHookedCommonJsRequire`: an ES module importing a
+ * CommonJS module that reports whether cache/extensions are objects, both
+ * served from source by the worker's own hooks. It stores 1 when kept, 2 when
+ * narrowed, and 3 when the import failed.
+ */
+const HOOKED_COMMONJS_REQUIRE_PROBE = `
+const { workerData } = require("node:worker_threads");
+const { registerHooks } = require("node:module");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+const base = path.join(__dirname, ".ttsc-hooked-require-probe-" + process.pid);
+const importer = pathToFileURL(base + ".mjs").href;
+const moduleUrl = pathToFileURL(base + ".cjs").href;
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === importer) return { shortCircuit: true, url: importer };
+    if (specifier === moduleUrl || specifier === base + ".cjs")
+      return { shortCircuit: true, url: moduleUrl };
+    return nextResolve(specifier, context);
+  },
+  load(url, context, nextLoad) {
+    if (url === importer)
+      return { format: "module", shortCircuit: true, source: "import kept from " + JSON.stringify(moduleUrl) + ";\\nexport default kept;\\n" };
+    if (url === moduleUrl)
+      return { format: "commonjs", shortCircuit: true, source: "module.exports = typeof require.cache === 'object' && typeof require.extensions === 'object';\\n" };
+    return nextLoad(url, context);
+  },
+});
+const answer = (value) => {
+  Atomics.store(workerData, 0, value);
+  Atomics.notify(workerData, 0);
+};
+import(importer).then((namespace) => answer(namespace.default === true ? 1 : 2), () => answer(3));
+`;

package/src/launcher/internal/runtime/RuntimeManifest.ts

@@ -0,0 +1,77 @@
+import type { OwningModuleOptions } from "./OwningModuleOptions";
+
+/**
+ * Checked build metadata inherited by a direct ttsx child or registered by a
+ * host that discovers roots after hook installation.
+ *
+ * The directories and actual compiler emit observations describe already-built
+ * output; the hooks use them to establish which preparation owns a source. This
+ * transport shape does not authenticate its producer or current artifact bytes;
+ * trusted preparation and immutable emit are registry/index premises.
+ *
+ * @evidence contracts/common.md#principled-implementation Native source/emit roots, actual output-to-source observations and owning format options bind serving to one checked preparation; optional entry/output-list/policy fields cannot replace the required compiler provenance.
+ * @evidence contracts/common.md#clear-and-simple-design One serializable build manifest groups serving identity and its run-owned caches, keeping loader callbacks and mutable lock state outside the transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit entry/output ownership and plugin policy replace basename guesses or independently chosen transform behavior for later roots.
+ * @evidence contracts/common.md#meaningful-documentation The purpose and separated member comments explain trusted preparation scope, native coordinates, producer provenance, relative output separators, format defaults, caller-owned orphan storage lifetime and false-only plugin policy without member tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native root/entry/cache paths and producer-native provenance keys remain distinct from slash-separated relative outputs. Producer identity observations and consumer filesystem conversions own physical alias handling; the structural strings do not pin a namespace or certify that every root observation succeeded.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface RuntimeManifest {
+  /** Project root of the entry's owning tsconfig. */
+  readonly projectRoot: string;
+
+  /** Source-tree root the emit mirrors (tsgo strips this prefix). */
+  readonly rootDir: string;
+
+  /** Directory holding the entry project's emitted JavaScript. */
+  readonly emitDir: string;
+
+  /**
+   * Selected TypeScript entry coordinate whose preparation created this
+   * manifest.
+   */
+  readonly entrySource?: string;
+
+  /** Exact JavaScript emitted for `entrySource`. */
+  readonly entryFile?: string;
+
+  /**
+   * The build's record of the JavaScript it emitted, relative to `emitDir` with
+   * `/` separators. This lists available outputs; actual source ownership is
+   * established by emittedSources rather than reconstructing source
+   * membership.
+   */
+  readonly outputs?: readonly string[];
+
+  /** Actual absolute native output-to-source observations of this checked emit. */
+  readonly emittedSources: Readonly<Record<string, readonly string[]>>;
+
+  /** Observed output-specific proof refusals; diagnostic context is not proof. */
+  readonly emittedSourceProofFailures?: Readonly<Record<string, string>>;
+
+  /**
+   * The entry tsconfig's `module` and `target`, deciding emit CJS/ESM per file.
+   * `target` is not decoration: an absent `module` makes tsgo derive the module
+   * kind from it.
+   */
+  readonly moduleOptions?: Readonly<OwningModuleOptions>;
+
+  /** Root directory for per-dependency build output. */
+  readonly depCacheDir: string;
+
+  /**
+   * Directory of lowered orphan sources under the resolved cache root, outside
+   * the run's disposable project directory. Cache collection or explicit root
+   * cleanup, rather than this manifest, determines its continued storage.
+   */
+  readonly orphanCacheDir?: string;
+
+  /**
+   * `false` when the run disabled transform plugins (`ttsx --no-plugins`). A
+   * TypeScript root the program reaches outside every checked build is part of
+   * the same run, so it is compiled under the same plugin policy as the entry.
+   */
+  readonly plugins?: false;
+}