ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { RuntimeFilesystem } from "./RuntimeFilesystem";
+
+/**
+ * Physical installed-source and owning-project authority for runtime loading.
+ *
+ * @evidence contracts/common.md#principled-implementation A shared native installed-directory predicate governs both project traversal and whether a source root belongs to the user. Physical workspace paths retain their own authority.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns the related decisions and nearest-config cache; compiler module-format precedence remains a separate owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native physical identity proves alternate installed spellings without OS-wide case folding, consumer exceptions or foreign filesystem replacement.
+ * @evidence contracts/common.md#meaningful-documentation Public method prose states physical-path preconditions, nearest own-config priority and current cache validation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups operations; each method documents native path and filesystem authority.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups operations; methods choose their algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cache validity belongs to nearestTsconfig.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Cache retention belongs to nearestTsconfig.
+ */
+export namespace RuntimeProjectOwnership {
+  interface Lookup {
+    candidates: readonly string[];
+    result: string | null;
+    boundary?: string;
+  }
+  const cache = new Map<string, Lookup>();
+
+  /**
+   * Whether a physical source path passes through an installed directory.
+   * A linked workspace physically outside that directory remains user source.
+   * Alternate spellings count only when the native lowercase installed spelling
+   * resolves to the same physical directory; failed identity reads prove none.
+   *
+   * @evidence contracts/common.md#principled-implementation Native dirname traversal applies the same installed-directory identity used by config lookup. Source callers have already resolved links, so installed links to outside workspace targets do not transfer package authority.
+   * @evidence contracts/common.md#clear-and-simple-design One ancestor walk delegates the installed spelling decision to the shared private predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A lowercase candidate routes a native identity query; it never establishes case equivalence on its own. No runtime source or root gate is bypassed.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify the physical-source precondition, workspace behavior and failed identity boundary.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path.dirname preserves platform separators and POSIX backslashes as filename data. realpathSync.native proves actual aliasing without an OS-name casing policy.
+   * @evidence contracts/performance.md#efficient-algorithms The walk visits path ancestors and only possible alternate installed basenames incur two native identity reads. Depth and native resolution cost are input-dependent.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable native alias topology is observed for each call rather than retained as a platform capability.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous walk retains no handles or historical identities.
+   */
+  export function isInstalledPackageSource(real: string): boolean {
+    for (let directory = path.dirname(real);;) {
+      if (isInstalledDirectory(directory)) return true;
+      const parent = path.dirname(directory);
+      if (parent === directory) return false;
+      directory = parent;
+    }
+  }
+
+  /**
+   * The nearest own tsconfig above a physical source, stopping before the
+   * consumer across an installed directory. A package's nearer config wins.
+   *
+   * Cached walks recheck both candidate files and the native boundary topology.
+   * Creating/deleting a config or adding/removing an installed alias therefore
+   * cannot retain an earlier consumer or isolated selection. The observer
+   * brackets config candidates and alternate directory identities for descriptor
+   * dependency recording; it does not pin the filesystem during compilation.
+   *
+   * @evidence contracts/common.md#principled-implementation Upward traversal selects the first existing config before the installed boundary. Cache entries retain ordered candidates and their stopping boundary; current candidate and native topology checks establish whether the old selection still applies.
+   * @evidence contracts/common.md#clear-and-simple-design The same private predicate serves fresh lookup, cached topology validation and installed-source classification. One directory-keyed cache shares the walked suffix without a second casing policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Native file kind and physical alias identity determine selection. Cache invalidation corrects changed inputs directly without caller-specific retries, source gating bypasses or foreign mutation.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs state nearer package-config priority, physical source authority, topology invalidation and the observer's limits.
+   * @evidence contracts/portability.md#os-neutral-implementation path.dirname/join and native realpath/stat preserve actual directory spelling and physical links. Alternate spelling succeeds only through observed native aliasing on that filesystem.
+   * @evidence contracts/performance.md#efficient-algorithms Fresh lookup walks ancestors and stats each candidate until selection or boundary. Warm lookup rechecks its ordered candidates and possible installed-boundary identities; storing candidate suffix arrays can retain quadratic references over a deep newly walked chain, as with the existing cache representation.
+   * @evidence contracts/performance.md#reuse-equivalent-work Directory entries share equivalent suffix walks only while current nearest candidate and stopping-boundary topology agree. Descriptor observations bracket cached candidate liveness and native alias comparisons; no cross-process cache authority is inferred.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources This module-lifetime cache retains one entry per observed directory with no explicit capacity or eviction beyond invalidated entries. Queries retain no native handle/task; the runtime process owns cache lifetime and descriptor recording resources.
+   */
+  export function nearestTsconfig(
+    file: string,
+    observe: (candidates: readonly string[]) => void = () => {},
+  ): string | null {
+    let directory = path.dirname(file);
+    const chain: string[] = [];
+    for (;;) {
+      if (isInstalledDirectory(directory, observe))
+        return remember(chain, null, [], directory);
+      const cached = cache.get(directory);
+      if (cached !== undefined) {
+        observe(cached.candidates);
+        const topologyCurrent =
+          (cached.boundary === undefined || isInstalledDirectory(cached.boundary, observe)) &&
+          cached.candidates.every((candidate) => !isInstalledDirectory(path.dirname(candidate), observe));
+        const current = nearestExisting(cached.candidates);
+        observe(cached.candidates);
+        if (topologyCurrent && current === cached.result)
+          return remember(chain, cached.result, cached.candidates, cached.boundary);
+        cache.delete(directory);
+      }
+      chain.push(directory);
+      const candidate = path.join(directory, "tsconfig.json");
+      observe([candidate]);
+      if (RuntimeFilesystem.isFile(candidate)) return remember(chain, candidate);
+      const parent = path.dirname(directory);
+      if (parent === directory) return remember(chain, null);
+      directory = parent;
+    }
+  }
+
+  function isInstalledDirectory(
+    directory: string,
+    observe: (inputs: readonly string[]) => void = () => {},
+  ): boolean {
+    const basename = path.basename(directory);
+    if (basename === "node_modules") return true;
+    if (basename.toLowerCase() !== "node_modules") return false;
+    const lowercase = path.join(path.dirname(directory), "node_modules");
+    const inputs = [directory, lowercase];
+    observe(inputs);
+    try {
+      return fs.realpathSync.native(directory) === fs.realpathSync.native(lowercase);
+    } catch {
+      return false;
+    } finally {
+      observe(inputs);
+    }
+  }
+
+  function nearestExisting(candidates: readonly string[]): string | null {
+    for (const candidate of candidates)
+      if (RuntimeFilesystem.isFile(candidate)) return path.resolve(candidate);
+    return null;
+  }
+
+  function remember(
+    directories: readonly string[],
+    result: string | null,
+    tail: readonly string[] = [],
+    boundary?: string,
+  ): string | null {
+    let candidates = [...tail];
+    for (let index = directories.length - 1; index >= 0; --index) {
+      const directory = directories[index]!;
+      candidates = [path.join(directory, "tsconfig.json"), ...candidates];
+      cache.set(directory, { candidates, result, boundary });
+    }
+    return result;
+  }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Minimum Node.js API version accepted before loader capability checks. The
+ * synchronous `module.registerHooks` (Node 22.15.0) is the highest floor among
+ * the runtime APIs these hooks depend on — `stripTypeScriptTypes` (22.13.0) and
+ * the child's `--disable-warning` flag (20.11.0) are both lower — so it sets
+ * the effective minimum. Kept in sync with
+ * `packages/ttsc/package.json#engines.node` and the documented requirement in
+ * `website/src/content/docs/development/index.mdx`. Actual hook capabilities
+ * can still reject a release above this API floor.
+ */
+export const TTSX_MINIMUM_NODE_VERSION = "22.15.0";

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

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { isContendedCandidateRename } from "../../../internal/isContendedCandidateRename";
+import { DependencyBuildGeneration } from "./DependencyBuildGeneration";
+import type { DependencyBuildLockLease } from "./DependencyBuildLockLease";
+import { DependencyBuildLockProtocol } from "./DependencyBuildLockProtocol";
+import { RuntimeFilesystem } from "./RuntimeFilesystem";
+
+/**
+ * Atomically acquire the current generation of a dependency build lock, or
+ * `null` when another process already holds it or the candidate loses its
+ * publication race. Unexpected filesystem errors propagate. Publication assumes
+ * a preserved lock namespace and a noncolliding generated candidate identity.
+ * Native failures before/after rename can leave persisted state: finally
+ * attempts candidate removal, and a cleanup error can propagate after current
+ * was published but before a lease reaches the caller.
+ *
+ * @evidence contracts/common.md#principled-implementation A private candidate contains its generation and owner before directory rename publishes current; a nonempty held directory prevents replacement, giving the winner a fully initialized lease.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate preparation, native rename publication and finally removal attempts define one acquisition operation; layout and contention classification use shared owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acquisition uses a real atomic filesystem boundary rather than an empty-owner window, fixture schedule or ignored unexpected error.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents null contention and propagated errors, while the cleanup comment explains why the private candidate cannot select current or another contender.
+ * @evidence contracts/portability.md#os-neutral-implementation Node fs/path supply native directory operations; isContendedCandidateRename owns supported Windows and POSIX contention codes instead of this operation guessing from an OS label.
+ * @evidence contracts/performance.md#efficient-algorithms Fixed operation count still pays path text/parent depth, generation entropy/hex, hostname/pid/timestamp JSON bytes and native create/write/rename/removal. No tombstone-history scan or holder wait is performed here; native latency and cleanup entry work are not constant-time certificates.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Acquisition changes lock ownership and cannot reuse a past lease; the higher-level build coordinator owns shared compilation.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Finally attempts candidate cleanup; returning a successful lease transfers current to its holder. Cleanup failure can leave a candidate or published current before caller lease transfer, and forced termination can strand state. Recovery/container removal own later reclamation; this call has no historical quota or cleanup deadline.
+ */
+export function acquireDependencyBuildLock(
+  lockDir: string,
+): DependencyBuildLockLease | null {
+  ensureDependencyLockRoot(lockDir);
+  const generation = DependencyBuildGeneration.newDependencyGeneration();
+  const candidateDir = path.join(lockDir, `candidate-${generation}`);
+  fs.mkdirSync(candidateDir);
+  try {
+    fs.writeFileSync(
+      path.join(
+        candidateDir,
+        DependencyBuildLockProtocol.DEP_BUILD_LOCK_GENERATION_FILE,
+      ),
+      `${generation}\n`,
+      { encoding: "utf8", flag: "wx" },
+    );
+    writeDependencyLockOwner(candidateDir, generation);
+    const currentDir = path.join(
+      lockDir,
+      DependencyBuildLockProtocol.DEP_BUILD_LOCK_CURRENT_DIR,
+    );
+    try {
+      fs.renameSync(candidateDir, currentDir);
+    } catch (error) {
+      if (
+        RuntimeFilesystem.isMissingPathError(error) ||
+        isContendedCandidateRename(error)
+      ) {
+        return null;
+      }
+      throw error;
+    }
+    return { generation };
+  } finally {
+    // The candidate prefix cannot name `current`; exclusive ownership of this
+    // created candidate and noncolliding generations remain protocol premises.
+    fs.rmSync(candidateDir, { force: true, recursive: true });
+  }
+}
+
+function ensureDependencyLockRoot(lockDir: string): void {
+  fs.mkdirSync(
+    path.join(lockDir, DependencyBuildLockProtocol.DEP_BUILD_LOCK_RETIRED_DIR),
+    {
+      recursive: true,
+    },
+  );
+}
+
+function writeDependencyLockOwner(
+  generationDir: string,
+  generation: string,
+): void {
+  fs.writeFileSync(
+    path.join(
+      generationDir,
+      DependencyBuildLockProtocol.DEP_BUILD_LOCK_OWNER_FILE,
+    ),
+    `${JSON.stringify({
+      generation,
+      hostname: os.hostname(),
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+    })}\n`,
+    "utf8",
+  );
+}

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

@@ -0,0 +1,94 @@
+import { TTSX_MINIMUM_NODE_VERSION } from "./TTSX_MINIMUM_NODE_VERSION";
+
+/**
+ * Report why the running (or a candidate) Node.js version cannot execute the
+ * ttsx source runtime, or `null` when it passes this minimum-version check.
+ * Returning an actionable message — rather than letting the child die with an
+ * internal `TypeError` on the missing `registerHooks`, or Node 18 rejecting
+ * `--disable-warning` with exit 9 — is what turns an opaque internal failure
+ * into a clear version diagnostic.
+ *
+ * Bun/Deno identity markers select the Node-only support policy even when they
+ * also report a compatible-looking Node version. This decision does not probe
+ * their current APIs or certify every other runtime as Node; the separate
+ * loader capability boundary remains responsible for actual hooks.
+ *
+ * A null answer passes only this runtime-identity and minimum-API version
+ * check. Hook installation separately requires the actual public loader
+ * capabilities; a release above the floor can still be unsupported there.
+ *
+ * @param version - The Node version the runtime reports.
+ * @param versions - The runtime's `process.versions`, which names Bun or Deno
+ *   when one of them imitates Node.
+ * @evidence contracts/common.md#principled-implementation Known non-Node runtime markers are rejected before major/minor/patch comparison with the minimum API floor; unknown version syntax alone does not prove incompatibility. Null does not certify the separate public-hook capability gate.
+ * @evidence contracts/common.md#clear-and-simple-design Version parsing and tuple comparison are private helpers under one diagnostic decision; loader behavior probes remain a separate capability owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The minimum release and Bun/Deno markers describe actual supported runtime boundaries, not fixture versions, and no runtime method is replaced to emulate missing hooks.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain checked emit/plugin consequences and the separate capability gate, while parameter docs distinguish reported version from runtime identity markers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This diagnostic keeps no request history or native handle; supplied records remain caller-owned and the returned text belongs to its consumer.
+ * @evidence contracts/performance.md#efficient-algorithms Two marker fields precede trimmed version parsing and at most three numeric comparisons. Text scanning/conversion and diagnostic construction scale with supplied strings; the fixed tuple does not make all text processing constant time.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call compares current supplied identity/version fields; it owns no compilation or native capability memo to reuse.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Reads version strings (process.versions by default) and compares numeric parts; it has no path or platform branch.
+ */
+export function checkNodeRuntimeSupport(
+  version: string,
+  versions: Readonly<Record<string, string | undefined>> = process.versions,
+): string | null {
+  for (const [key, name] of NON_NODE_RUNTIMES) {
+    const imitator = versions[key];
+    if (typeof imitator === "string") {
+      return (
+        `ttsx runs on Node.js, but this process is ${name} ${imitator}. ` +
+        `The ttsx checked-emit/plugin runtime supports Node.js rather than ${name}; ` +
+        `a reported compatibility version does not establish the supported hook boundary ` +
+        `or checked-emit execution. Run it with Node.js instead, for ` +
+        `example \`npx ttsx\` (\`bunx ttsx\` also uses Node.js unless ` +
+        `\`--bun\` is given).`
+      );
+    }
+  }
+  const parts = parseNodeVersion(version);
+  if (parts === null) {
+    // An unrecognizable version string is not proof of an unsupported runtime;
+    // let execution proceed rather than block on a parsing quirk.
+    return null;
+  }
+  if (compareVersionParts(parts, TTSX_MINIMUM_NODE_PARTS) >= 0) {
+    return null;
+  }
+  return (
+    `ttsx requires Node.js ${TTSX_MINIMUM_NODE_VERSION} or later, but this ` +
+    `process is Node.js ${version}. The source runtime installs synchronous ` +
+    `module hooks (module.registerHooks, Node 22.15.0) and strips types with ` +
+    `module.stripTypeScriptTypes (Node 22.13.0). The required synchronous hooks ` +
+    `are unavailable below this floor. Upgrade Node.js to 22.15.0+ (or the current LTS), or ` +
+    `compile the project with \`ttsc\` and run the emitted JavaScript directly.`
+  );
+}
+
+const TTSX_MINIMUM_NODE_PARTS: readonly [number, number, number] = [22, 15, 0];
+
+/** `process.versions` keys of runtimes that report a Node version too. */
+const NON_NODE_RUNTIMES: readonly (readonly [string, string])[] = [
+  ["bun", "Bun"],
+  ["deno", "Deno"],
+];
+
+function parseNodeVersion(version: string): [number, number, number] | null {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (match === null) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareVersionParts(
+  a: readonly [number, number, number],
+  b: readonly [number, number, number],
+): number {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index]! !== b[index]!) {
+      return a[index]! < b[index]! ? -1 : 1;
+    }
+  }
+  return 0;
+}

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

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { SourceBuildCacheLayout } from "../../../plugin/internal/source/SourceBuildCacheLayout";
+import { ProcessOwnedDirectory } from "./ProcessOwnedDirectory";
+import { withRuntimeDirectoryLock } from "./withRuntimeDirectoryLock";
+
+/**
+ * Select the runtime project index and publish one run's owner under clean's
+ * cooperative root lock. The caller supplies a pinned cache-root spelling and a
+ * validated run key whose replacement authority belongs to this execution. The
+ * returned directory carries a record until relinquishment; the record and
+ * realpath spelling are not process-incarnation or directory-handle leases.
+ *
+ * A supplied lock operation owns the same synchronous root transaction as the
+ * default runtime-directory lock. Directory selection, abandoned-run sweeping,
+ * replacement and claim publication all occur before that transaction ends.
+ * Participants must preserve the selected physical namespace and share that
+ * lock identity. Effects are not an atomic filesystem transaction: a failure
+ * can leave created directories or a partially published record, and this
+ * function does not roll them back. Caller cleanup owns those remaining
+ * effects.
+ *
+ * @param runtimeRoot The already-pinned physical runtime cache root.
+ * @param runKey The caller's validated private run identity.
+ * @param withLock The operation that serializes this root against clean.
+ * @evidence contracts/common.md#principled-implementation Project index selection and run-record publication occur inside the cooperative root-lock scope, excluding clean participants using the same stable identity. This does not certify rollback, physical namespace immutability or actual process incarnation.
+ * @evidence contracts/common.md#clear-and-simple-design One operation owns pinning, sweep, replacement and claim; the caller owns virtual emit layout and eventual relinquishment.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native filesystem operations and the default real runtime lock preserve actual ownership; supplied lock operations must serialize the same root rather than bypass coordination.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states validated replacement authority, cooperative lock/namespace premises, absence of rollback and transferred directory lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath selects the currently observed link/junction target before run-path construction. Shared native lock/probe owners coordinate that spelling; stable namespace and caller-owned replacement remain premises rather than handles held here.
+ * @evidence contracts/performance.md#efficient-algorithms Lock acquisition/retirement delegates identity, record IO and contention waits. The index sweep pays entry/path/owner-record/native-probe costs; selected recursive replacement pays its existing tree size, and creation/publication follow path depth/text and JSON/native IO. Fixed effect count does not bound those costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Claims and replacements are distinct lifetime effects that cannot reuse a prior operation result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Finally attempts lock retirement, whose peer-handle release has no independent deadline. Successful directory ownership transfers to the caller; created/deleted/partially published effects are not rolled back on failure, and abandoned/unknown/live or native-failed leftovers have no reclamation deadline here.
+ */
+export function claimRuntimeProjectDirectory(
+  runtimeRoot: string,
+  runKey: string,
+  withLock: typeof withRuntimeDirectoryLock = withRuntimeDirectoryLock,
+): string {
+  return withLock(runtimeRoot, () => {
+    const directory = path.join(
+      runtimeRoot,
+      SourceBuildCacheLayout.RUNTIME_PROJECT_DIRNAME,
+    );
+    fs.mkdirSync(directory, { recursive: true });
+    const runsDir = fs.realpathSync.native(directory);
+    const processDir = path.join(runsDir, runKey);
+    ProcessOwnedDirectory.sweep(runsDir);
+    fs.rmSync(processDir, { recursive: true, force: true });
+    ProcessOwnedDirectory.claim(processDir);
+    return processDir;
+  });
+}

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

@@ -0,0 +1,57 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { parseCommonJsExports } from "../parseCommonJsExports";
+import { realPath } from "./realPath";
+
+/**
+ * Static CommonJS names under the served module's source identity.
+ *
+ * Every re-export resolves through that source's CommonJS require authority,
+ * including package conditions. The reader supplies JavaScript bytes or the
+ * target TypeScript source's own compiler emit; private output paths never
+ * become resolution origins. Targets are not evaluated. Failed resolution adds
+ * no names and leaves the eventual native load to report its error, whereas a
+ * reader's ownership error propagates. Root default metadata is retained for
+ * the facade's native own-property ordering; nested default is not re-exported.
+ *
+ * @evidence contracts/common.md#principled-implementation Node createRequire resolves each edge from the physical source module using require conditions; the runtime supplies its existing source-rescue resolver on supported hook variants. Owned compiler bytes retain TypeScript elision and lowering. Static parsing discovers possible names, while the original loaded helper and facade own values and property semantics.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal serves both JavaScript and TypeScript facades. A call-scoped physical seen set prevents mixed-source cycles and duplicate reads without separate emitted/source resolution policies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native package resolution and the runtime's existing relative-source policy decide targets. No package-specific exception, foreign loader replacement or target evaluation supplies names.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states source-origin and owned-reader authority, unresolved versus reader failure, static-only discovery and direct versus nested default semantics.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native require/path resolution and realPath preserve actual filesystem identity, package maps and platform paths without separator rewriting or OS-based casing assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms Each reachable physical target is read and parsed at most once per scan; edges incur native resolution and set insertion. Source bytes, metadata, names and a DFS stack scale with the reachable graph; no configured graph/depth cap bounds parser or reader work.
+ * @evidence contracts/performance.md#reuse-equivalent-work The traversal shares equivalent physical targets within one scan. Compiler-owned emission reuse belongs to the supplied reader; mutable package resolution and source results are not cached across scans here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Names and visited identities are call-local; only the returned array escapes. The reader and native resolver own their synchronous resources and compiler lifetimes; this scanner retains no historical graph or native handle.
+ */
+export function commonJsExportNames(
+  source: string,
+  filename: string,
+  readSource: (file: string) => string | null,
+  resolve: (parent: string, specifier: string) => string = (parent, specifier) =>
+    createRequire(parent).resolve(specifier),
+): string[] {
+  const names = new Set<string>();
+  const seen = new Set<string>();
+  const visit = (file: string, text: string, root: boolean): void => {
+    const real = realPath(file);
+    if (seen.has(real)) return;
+    seen.add(real);
+    const parsed = parseCommonJsExports(text);
+    for (const name of parsed.exports)
+      if (root || name !== "default") names.add(name);
+    for (const specifier of parsed.reexports) {
+      let target: string;
+      try { target = resolve(real, specifier); } catch { continue; }
+      if (!path.isAbsolute(target)) continue;
+      if ([".json", ".node", ".mjs"].includes(path.extname(target))) continue;
+      const physical = realPath(target);
+      if (seen.has(physical)) continue;
+      const nested = readSource(physical);
+      if (nested === null) seen.add(physical);
+      else visit(physical, nested, false);
+    }
+  };
+  visit(filename, source, true);
+  return [...names];
+}

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

@@ -0,0 +1,62 @@
+/**
+ * The ESM source that stands in for a CommonJS module an ESM `import` reaches.
+ *
+ * The caller selects this adaptation when hook-served CommonJS source needs the
+ * ordinary CommonJS loading lane rather than an ESM loader's narrower
+ * module-local require. The generated source uses public `createRequire` and
+ * the caller's source-aware load boundary, sharing Node's CommonJS cache.
+ * Evaluation occurs with the importer; native load failures still propagate.
+ *
+ * `default` captures `module.exports`. Detected named exports read only own
+ * properties, once after loading; missing/inherited properties and throwing
+ * getters yield undefined, as Node's translator does. Own-property inspection
+ * errors propagate. The supplied marker capability selects either a namespace
+ * `module.exports` alias or the older ordinary named-property behavior,
+ * including its own-property check for a detected `default` name.
+ *
+ * @param url The module's URL, which its `require` resolves from.
+ * @param filename The module's path, which the CommonJS loader loads.
+ * @param names The names Node's static export detection finds for it.
+ * @param moduleExportsKey Whether the runtime's namespace carries
+ *   `module.exports`.
+ * @evidence contracts/common.md#principled-implementation Public createRequire routes loading through the shared CommonJS cache; deduplicated detected names preserve Node's own-only projection, getter-error suppression and capability-selected marker behavior without guessing dynamic exports.
+ * @evidence contracts/common.md#clear-and-simple-design One source builder isolates the ESM-to-CommonJS adaptation; callers supply actual detected names and loader capability rather than embedding another compatibility policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported createRequire and generated ESM adapt the selected public loader lane. JSON quoting protects caller text; only named-property getter errors are suppressed by the specified Node policy, while native load and own-inspection failures propagate.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish caller-selected loader adaptation, captured default, own-only names, getter errors and marker/version behavior; parameters identify URL, native filename and supplied capability.
+ * @evidence contracts/performance.md#efficient-algorithms Set deduplication processes N names and their text; temporary arrays/lines and joining scale with generated bytes. Execution separately delegates native module resolution/evaluation/cache work and own-property/getter observations whose cost is not bounded by generation size.
+ * @evidence contracts/performance.md#reuse-equivalent-work The generated facade invokes createRequire so imports and ordinary require share Node's CommonJS evaluation cache; source generation itself remains caller-owned and does not cache mutable name inputs.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Temporary names and source lines end with the call; the returned source and Node's module cache belong to the runtime loader.
+ * @evidence contracts/portability.md#os-neutral-implementation Generated public createRequire receives the caller's module URL and native filename as independently JSON-quoted values, leaving native resolution and filesystem spelling to Node and the caller's source boundary. Supplied marker capability selects namespace representation without OS-name guessing or path rewriting.
+ */
+export function commonJsImportFacade(
+  url: string,
+  filename: string,
+  names: readonly string[],
+  moduleExportsKey: boolean,
+): string {
+  const lines = [
+    `import { createRequire as __ttscCreateRequire } from "node:module";`,
+    `const __ttscHasOwn = Object.hasOwn;`,
+    `const __ttscModule = __ttscCreateRequire(${JSON.stringify(url)})(${JSON.stringify(filename)});`,
+    `export default __ttscModule;`,
+  ];
+  if (moduleExportsKey)
+    lines.push(`export { __ttscModule as "module.exports" };`);
+  [...new Set(names)].forEach((name, index) => {
+    if (name === "default") {
+      if (!moduleExportsKey)
+        lines.push(`__ttscHasOwn(__ttscModule, "default");`);
+      return;
+    }
+    if (name === "module.exports" && moduleExportsKey) return;
+    lines.push(
+      `let __ttscExport${index};`,
+      `if (__ttscHasOwn(__ttscModule, ${JSON.stringify(name)})) {`,
+      `  try { __ttscExport${index} = __ttscModule[${JSON.stringify(name)}]; } catch {}`,
+      `}`,
+      `export { __ttscExport${index} as ${JSON.stringify(name)} };`,
+    );
+  });
+  return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,82 @@
+import crypto from "node:crypto";
+
+/**
+ * Derive a dependency build address within its owning run or process cache.
+ *
+ * A key addresses one build context: a dependency project's whole file set, or
+ * with `options.root` one TypeScript root that project's file set does not
+ * contain, compiled alone through its options. Their encodings differ, but the
+ * returned 64-bit truncated digest is not a collision-free generation
+ * identity.
+ *
+ * Compiler identity is supplied by the build coordinator after inspecting the
+ * actual executable; an unavailable proof uses a fresh identity there.
+ *
+ * @evidence contracts/common.md#principled-implementation SHA-256 separates project, isolated-root content, plugin loading policy, emit policy, compiler proof and descriptor process identity with explicit delimiters, so distinct supported build contexts do not intentionally share an address.
+ * @evidence contracts/common.md#clear-and-simple-design One key function combines caller-established identity inputs; executable observation and build memo validity remain with the coordinator that knows when a build is requested.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Default descriptor evaluation uses a module-instance random nonce rather than a recycled pid or shared path-only address; a supplied nonce remains the coordinator's evaluator-identity responsibility.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish project and isolated-root context encoding, compiler proof ownership and truncated-digest limits; nonce comments distinguish probabilistic evaluator separation from guaranteed uniqueness.
+ * @evidence contracts/performance.md#efficient-algorithms Hashing processes B input bytes with fixed digest state; interpolated text and UTF-8 conversion also scale with supplied strings. Module initialization draws the default 16-byte native nonce, whose latency/failure is not bounded by output width. The 16-hex address is a 64-bit truncation, not a collision-free or security identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work Run/process containers scope ordinary module snapshots; the coordinator supplies selected plugin policy, current compiler proof and isolated-root content. The supplied or module-instance random nonce separates evaluator encodings probabilistically, not with an absolute noncollision guarantee; a key alone does not validate edited project dependencies.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Module initialization retains one default descriptor nonce while this module instance remains reachable, even when a caller supplies an override. Digest objects and intermediate strings are call-local; generated directory storage remains with the cache owner.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Caller-established filename and option coordinates are opaque text identity inputs here; hashing makes no native path-equivalence, case, alias or process-liveness decision. Native coordinate selection and cache ownership belong to the coordinator.
+ */
+export function dependencyCacheKey(
+  tsconfig: string,
+  options: {
+    /** Current executable content proof, or a fresh non-reusable identity. */
+    compilerIdentity?: string;
+
+    /** Whether this build belongs to descriptor evaluation. */
+    descriptorLoad?: boolean;
+
+    /** Evaluator identity; absent selects this module instance's random nonce. */
+    descriptorNonce?: string;
+
+    /** Effective false-only plugin loading policy captured for this build. */
+    plugins?: false;
+
+    /**
+     * The single root a root build compiles, with the digest of its content;
+     * absent for a project build.
+     */
+    root?: string;
+  } = {},
+): string {
+  const descriptorLoad =
+    options.descriptorLoad ?? process.env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1";
+  return (
+    crypto
+      .createHash("sha256")
+      .update(tsconfig)
+      .update("\0runtime-es2025")
+      .update("\0private-output-volume-root-v1")
+      .update(`\0compiler:${options.compilerIdentity ?? ""}`)
+      .update(
+        options.plugins === false ? "\0plugins:disabled" : "\0plugins:discover",
+      )
+      .update(options.root === undefined ? "" : `\0root:${options.root}`)
+      // 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
+      // probabilistically distinct evaluator nonce; the registry instance's
+      // `builtProjects` map still shares an owning project's result.
+      .update(
+        descriptorLoad
+          ? `\0descriptor-process:${
+              options.descriptorNonce ?? descriptorProcessCacheNonce
+            }`
+          : "",
+      )
+      .digest("hex")
+      .slice(0, 16)
+  );
+}
+
+// Descriptor evaluation needs its own input-bound dependency context. Recycled
+// pids are not a sufficient key while disk storage persists. One default random
+// nonce per module instance reduces accidental evaluator sharing; finite nonce
+// and truncated hash widths do not certify collision-free generation identity.
+// `builtProjects` still shares repeated imports within its registry instance.
+const descriptorProcessCacheNonce = crypto.randomBytes(16).toString("hex");