ttsc 0.18.4 → 0.19.1

package/lib/launcher/internal/runtimeHooks.js

@@ -3,9 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTSX_MINIMUM_NODE_VERSION = void 0;
+exports.checkNodeRuntimeSupport = checkNodeRuntimeSupport;
 exports.installRuntimeHooks = installRuntimeHooks;
 exports.entryModuleFormat = entryModuleFormat;
 exports.isWithin = isWithin;
+exports.readDependencyCache = readDependencyCache;
+exports.acquireDependencyBuildLock = acquireDependencyBuildLock;
+exports.releaseDependencyBuildLock = releaseDependencyBuildLock;
+exports.reclaimDependencyBuildLock = reclaimDependencyBuildLock;
+exports.inspectDependencyBuildLock = inspectDependencyBuildLock;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_module_1 = require("node:module");
@@ -17,6 +24,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 servedSourceMap_1 = require("./servedSourceMap");
 /**
  * Synchronous Node module hooks installed (via `module.registerHooks`) in the
  * child process `ttsx` spawns to run a TypeScript entry _from source_.
@@ -75,6 +83,72 @@ function manifest() {
     }
     return manifestCache;
 }
+/**
+ * Lowest Node.js the ttsx source runtime supports. 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`.
+ */
+exports.TTSX_MINIMUM_NODE_VERSION = "22.15.0";
+const TTSX_MINIMUM_NODE_PARTS = [22, 15, 0];
+/**
+ * Report why the running (or a candidate) Node.js version cannot execute the
+ * ttsx source runtime, or `null` when it can. 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.
+ *
+ * Exported for direct exercise by the ttsx e2e suite: the built launcher can
+ * only be spawned under the Node version running the tests, so the boundary
+ * around the floor cannot otherwise be pinned on CI.
+ */
+function checkNodeRuntimeSupport(version) {
+    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 ${exports.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), neither of which exists on ` +
+        `earlier releases. Upgrade Node.js to 22.15.0+ (or the current LTS), or ` +
+        `compile the project with \`ttsc\` and run the emitted JavaScript directly.`);
+}
+function parseNodeVersion(version) {
+    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, b) {
+    for (let index = 0; index < 3; index += 1) {
+        if (a[index] !== b[index]) {
+            return a[index] < b[index] ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/**
+ * Throw an actionable version error when the current Node.js cannot run the
+ * ttsx source runtime. Guards the hook-installation boundary directly (a child
+ * or grandchild that inherits the runtime preload under an unsupported Node) so
+ * the failure is diagnosed here instead of surfacing as a bare `TypeError:
+ * registerHooks is not a function`.
+ */
+function assertNodeRuntimeSupport() {
+    const message = checkNodeRuntimeSupport(process.versions.node);
+    if (message !== null) {
+        throw new Error(message);
+    }
+}
 let installed = false;
 /**
  * Install the source-loading hooks on the current (main) thread. Idempotent:
@@ -93,7 +167,15 @@ function installRuntimeHooks() {
     if (installed) {
         return;
     }
+    assertNodeRuntimeSupport();
     installed = true;
+    // Map error stacks through the source maps the serve path now inlines, so a
+    // thrown frame reports the true `.ts` line:col out of the box (no
+    // `--enable-source-maps` needed). Applied before the entry loads; user code
+    // that later toggles it wins, since this is a plain runtime switch.
+    if (typeof process.setSourceMapsEnabled === "function") {
+        process.setSourceMapsEnabled(true);
+    }
     (0, node_module_1.registerHooks)({ load, resolve });
     installCommonJsHook();
 }
@@ -233,11 +315,14 @@ function resolveServedSource(filename, url = (0, node_url_1.pathToFileURL)(filen
     const real = realPath(filename);
     const served = serveEntryEmit(real);
     if (served !== null) {
-        return { moduleOption: manifest()?.moduleOption, ...served };
+        return withInlineSourceMap({
+            moduleOption: manifest()?.moduleOption,
+            ...served,
+        });
     }
     const built = serveDependencyEmit(real);
     if (built !== null) {
-        return built;
+        return withInlineSourceMap(built);
     }
     return {
         moduleOption: undefined,
@@ -245,6 +330,17 @@ function resolveServedSource(filename, url = (0, node_url_1.pathToFileURL)(filen
         source: transformOrphanSource(filename, url),
     };
 }
+/**
+ * Inline a served emit's external source map into its text and absolutize the
+ * map's `sources`, so the JavaScript executed under the `.ts` source URL stays
+ * self-describing after the per-run emit directory is deleted. Applied to both
+ * the entry lane (`serveEntryEmit`) and the dependency lane
+ * (`serveBuiltDependency`); the orphan type-strip lane carries no emitted map.
+ */
+function withInlineSourceMap(served) {
+    const source = (0, servedSourceMap_1.inlineServedSourceMap)(served.source, served.emittedFile, served.sourceFile);
+    return source === served.source ? served : { ...served, source };
+}
 /**
  * Transform a TypeScript source file that no tsconfig owns (a published or
  * vendored package that ships raw `.ts`/`.cts`/`.mts` straight under
@@ -551,14 +647,152 @@ function collectCommonJsExportNames(emittedFile, seen) {
     return names;
 }
 function collectStaticCommonJsExportNames(source) {
+    // Scan executable syntax only. Text that merely resembles an assignment —
+    // `exports.x =` inside a comment, string, or template-literal text — must not
+    // become an ESM-visible export name, or a named import of it would link to
+    // `undefined` for a property the CommonJS module never defines. Masking the
+    // inert lexical spans before matching keeps genuine top-level assignments
+    // (and executable `${ ... }` template substitutions) while dropping the
+    // decoys.
+    const scannable = maskCommentsAndStrings(source);
     const names = new Set();
     const pattern = /(?:^|[^\w$])(?:exports|module\.exports)\.([A-Za-z_$][\w$]*)\s*=/g;
     let match;
-    while ((match = pattern.exec(source)) !== null) {
+    while ((match = pattern.exec(scannable)) !== null) {
         names.add(match[1]);
     }
     return names;
 }
+/**
+ * Blank out the interior of line comments, block comments, string literals, and
+ * template-literal text in emitted JavaScript, replacing each masked character
+ * with a space while preserving newlines, code, and template `${ ... }`
+ * substitutions verbatim. Positions and length are preserved so an offset in
+ * the masked text maps back to the same offset in the source.
+ *
+ * The input is tsgo's CommonJS emit (well-formed JavaScript), so a character
+ * scanner that tracks the standard comment/string/template states is sufficient
+ * to separate executable tokens from inert text. Regular-expression literals
+ * are intentionally not masked: distinguishing `/`-division from a regex
+ * literal needs full tokenization, and tsgo's CommonJS emit never wraps an
+ * `exports.<name> =` assignment inside a regex literal.
+ */
+function maskCommentsAndStrings(source) {
+    const out = source.split("");
+    const n = out.length;
+    const blank = (index) => {
+        const ch = out[index];
+        if (ch !== "\n" && ch !== "\r") {
+            out[index] = " ";
+        }
+    };
+    const stack = [{ kind: "code", braceDepth: 0 }];
+    let i = 0;
+    while (i < n) {
+        const top = stack[stack.length - 1];
+        const ch = out[i];
+        if (top.kind === "template") {
+            if (ch === "\\") {
+                blank(i);
+                blank(i + 1);
+                i += 2;
+                continue;
+            }
+            if (ch === "`") {
+                blank(i);
+                stack.pop();
+                i += 1;
+                continue;
+            }
+            if (ch === "$" && out[i + 1] === "{") {
+                // Enter a code substitution: `${` and its contents stay executable.
+                stack.push({ kind: "code", braceDepth: 0 });
+                i += 2;
+                continue;
+            }
+            blank(i);
+            i += 1;
+            continue;
+        }
+        // Code context.
+        if (ch === "/" && out[i + 1] === "/") {
+            blank(i);
+            blank(i + 1);
+            i += 2;
+            while (i < n && out[i] !== "\n") {
+                blank(i);
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === "/" && out[i + 1] === "*") {
+            blank(i);
+            blank(i + 1);
+            i += 2;
+            while (i < n && !(out[i] === "*" && out[i + 1] === "/")) {
+                blank(i);
+                i += 1;
+            }
+            if (i < n) {
+                blank(i);
+                blank(i + 1);
+                i += 2;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            blank(i);
+            i += 1;
+            while (i < n && out[i] !== ch) {
+                if (out[i] === "\\") {
+                    blank(i);
+                    blank(i + 1);
+                    i += 2;
+                    continue;
+                }
+                // A bare newline ends an unterminated string; stop masking so the rest
+                // of the line is still scanned as code (defensive — tsgo never emits
+                // one).
+                if (out[i] === "\n") {
+                    break;
+                }
+                blank(i);
+                i += 1;
+            }
+            if (i < n && out[i] === ch) {
+                blank(i);
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === "`") {
+            blank(i);
+            stack.push({ kind: "template", braceDepth: 0 });
+            i += 1;
+            continue;
+        }
+        if (ch === "{") {
+            top.braceDepth += 1;
+            i += 1;
+            continue;
+        }
+        if (ch === "}") {
+            if (top.braceDepth === 0 && stack.length > 1) {
+                // Close the enclosing template `${ ... }` and resume template text.
+                stack.pop();
+                i += 1;
+                continue;
+            }
+            if (top.braceDepth > 0) {
+                top.braceDepth -= 1;
+            }
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return out.join("");
+}
 function collectSourceCommonJsExportNames(sourceFile, seen) {
     const real = realPath(sourceFile);
     if (seen.has(real)) {
@@ -761,14 +995,14 @@ function ensureProjectBuilt(tsconfig) {
     if (cached !== undefined) {
         return cached;
     }
-    const { emitDir, lockDir, metaPath, root } = dependencyCachePaths(tsconfig);
-    const reuse = readDependencyCache(emitDir, metaPath);
+    const { cacheDir, lockDir, metaPath, root } = dependencyCachePaths(tsconfig);
+    const reuse = readDependencyCache(cacheDir, metaPath);
     if (reuse !== null) {
         builtProjects.set(tsconfig, reuse);
         return reuse;
     }
     node_fs_1.default.mkdirSync(root, { recursive: true });
-    const built = withBuildLock(lockDir, metaPath, emitDir, () => buildDependency(tsconfig, emitDir, metaPath));
+    const built = withBuildLock(cacheDir, metaPath, lockDir, () => buildDependency(tsconfig, cacheDir, metaPath));
     builtProjects.set(tsconfig, built);
     return built;
 }
@@ -780,14 +1014,38 @@ function dependencyCachePaths(tsconfig) {
         .slice(0, 16);
     const root = dependencyCacheRoot();
     return {
-        emitDir: node_path_1.default.join(root, key),
+        cacheDir: node_path_1.default.join(root, key),
         lockDir: node_path_1.default.join(root, `${key}.lock`),
         metaPath: node_path_1.default.join(root, `${key}.json`),
         root,
     };
 }
-/** Reuse a dependency another process (or an earlier import) already built. */
-function readDependencyCache(emitDir, metaPath) {
+/** The immutable emit directory of one build generation under `cacheDir`. */
+function dependencyGenerationDir(cacheDir, generation) {
+    return node_path_1.default.join(cacheDir, `gen-${generation}`);
+}
+/** A fresh 128-bit build-generation identifier. */
+function newDependencyGeneration() {
+    return node_crypto_1.default.randomBytes(16).toString("hex");
+}
+/** True for a well-formed 128-bit hex build generation. */
+function isDependencyGeneration(value) {
+    return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+}
+/**
+ * Reuse a dependency another process (or an earlier import) already built.
+ *
+ * The completion marker names the exact emit generation, so this reads metadata
+ * and emit as one unit: it returns a hit only when the marker parses to a valid
+ * generation AND that generation's directory holds emitted JavaScript. A reader
+ * that runs while a replacement build is populating a DIFFERENT generation
+ * directory keeps returning the previous complete generation until the atomic
+ * marker swap points at the new one — never a mix of old metadata and a partial
+ * new emit.
+ *
+ * Exported for the ttsx dependency-cache regressions.
+ */
+function readDependencyCache(cacheDir, metaPath) {
     let meta;
     try {
         meta = JSON.parse(node_fs_1.default.readFileSync(metaPath, "utf8"));
@@ -795,73 +1053,102 @@ function readDependencyCache(emitDir, metaPath) {
     catch {
         return null;
     }
+    if (!isDependencyGeneration(meta.generation) ||
+        typeof meta.rootDir !== "string") {
+        return null;
+    }
+    const emitDir = dependencyGenerationDir(cacheDir, meta.generation);
     if (!emittedAnything(emitDir)) {
         return null;
     }
     return {
         emitDir,
         emittedFiles: undefined,
-        moduleOption: meta.moduleOption,
+        moduleOption: typeof meta.moduleOption === "string" ? meta.moduleOption : undefined,
         rootDir: meta.rootDir,
     };
 }
 /**
- * Run `build` while holding an exclusive lock for this dependency, re-checking
+ * Run `build` while holding the fenced lock for this dependency, re-checking
  * the cache once the lock is held (a concurrent builder may have just
- * finished). A waiter polls for the winner's meta marker, and steals an
- * abandoned lock (a builder that crashed) after a generous timeout so the run
- * never wedges.
+ * finished). A loser polls for the winner's completion marker and, only when
+ * the holding generation is provably abandoned (dead owner or the steal budget
+ * elapsed), retires precisely that generation before retrying — never a
+ * successor's.
  */
-function withBuildLock(lockDir, metaPath, emitDir, build) {
-    const stealAfterMs = 600_000;
+function withBuildLock(cacheDir, metaPath, lockDir, build) {
     for (;;) {
+        const reuse = readDependencyCache(cacheDir, metaPath);
+        if (reuse !== null) {
+            return reuse;
+        }
+        let lease;
         try {
-            node_fs_1.default.mkdirSync(lockDir);
+            lease = acquireDependencyBuildLock(lockDir);
         }
         catch {
-            const waited = waitForDependencyCache(emitDir, metaPath, stealAfterMs);
-            if (waited !== null) {
-                return waited;
+            // An unusable coordination directory must not silently skip the build.
+            // Generation-stamped emit and the atomic marker swap still keep every
+            // reader's view of publication consistent without the lock.
+            return build();
+        }
+        if (lease === null) {
+            const waited = waitForDependencyBuild(cacheDir, metaPath, lockDir, DEP_BUILD_LOCK_STEAL_MS);
+            if (waited.outcome === "built") {
+                return waited.built;
+            }
+            if (waited.outcome === "abandoned") {
+                // Retire only the generation this observation named. Losing the rename
+                // race means the holder's own release (or another waiter) already made
+                // progress, so a stale result never removes a live successor.
+                reclaimDependencyBuildLock(lockDir, waited.fence);
             }
-            node_fs_1.default.rmSync(lockDir, { force: true, recursive: true });
+            // "released" needs no repair: the holder freed the lock normally, so
+            // retry the ordinary acquisition.
             continue;
         }
         try {
-            const reuse = readDependencyCache(emitDir, metaPath);
-            return reuse ?? build();
+            const reuseUnderLock = readDependencyCache(cacheDir, metaPath);
+            return reuseUnderLock ?? build();
         }
         finally {
-            node_fs_1.default.rmSync(lockDir, { force: true, recursive: true });
-        }
-    }
-}
-/** Poll for a concurrent builder's completion, up to `timeoutMs`. */
-function waitForDependencyCache(emitDir, metaPath, timeoutMs) {
-    const startedAt = Date.now();
-    for (;;) {
-        const reuse = readDependencyCache(emitDir, metaPath);
-        if (reuse !== null) {
-            return reuse;
-        }
-        if (Date.now() - startedAt > timeoutMs) {
-            return null;
+            releaseDependencyBuildLock(lockDir, lease);
         }
-        sleepSync(50);
     }
 }
 /** Block the current (synchronous) thread for `ms` without busy-spinning. */
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-/** Compile a dependency project to `emitDir` and write its completion marker. */
-function buildDependency(tsconfig, emitDir, metaPath) {
+/**
+ * Compile a dependency project into a fresh generation directory and publish
+ * its completion marker atomically.
+ *
+ * The emit lands in `<cacheDir>/gen-<generation>`, a directory no other
+ * generation or process shares, so it is never mutated in place while a reader
+ * looks at it. Only after the emit is proven non-empty is the marker written by
+ * temp-and-rename, binding metadata to that exact generation. A build that
+ * produced no output drops its partial directory so a failed generation can
+ * never be reused.
+ */
+function buildDependency(tsconfig, cacheDir, metaPath) {
     const project = (0, readProjectConfig_1.readProjectConfig)({ cwd: node_path_1.default.dirname(tsconfig), tsconfig });
+    const generation = newDependencyGeneration();
+    const emitDir = dependencyGenerationDir(cacheDir, generation);
     node_fs_1.default.rmSync(emitDir, { force: true, recursive: true });
+    node_fs_1.default.mkdirSync(emitDir, { recursive: true });
     const result = (0, runBuild_1.runBuild)({
         cwd: project.root,
         emit: true,
         forceListEmittedFiles: true,
         outDir: emitDir,
+        // Emit a source map on the transient dependency emit (it never reaches the
+        // dependency's published `lib/`) so the serve path can inline it under the
+        // source URL, but only when the dependency configures none itself. Routed
+        // as a dedicated build option, not a forwarded tsgo flag, so it never
+        // reaches a native plugin host's argument parser (issue #353).
+        forceRuntimeSourceMap: project.compilerOptions.sourceMap !== true &&
+            project.compilerOptions.inlineSourceMap !== true,
         // Honour the dependency's own transform plugins: a source-shipping package
         // can itself depend on a transform (e.g. a fixture whose values are built
         // with `typia.createRandom`), and its runtime behaviour is wrong without it.
@@ -872,6 +1159,7 @@ function buildDependency(tsconfig, emitDir, metaPath) {
         // deadlocks, so every dependency in that graph builds with plugins off.
         plugins: process.env.TTSC_PLUGIN_DESCRIPTOR_LOAD === "1" ? false : undefined,
         quiet: true,
+        resolvedProject: project,
         // Emit only: the entry project's up-front check is the type gate. A
         // dependency build pulls its own transitive sources into the program and
         // would otherwise fail on type diagnostics that belong to those packages
@@ -887,6 +1175,9 @@ function buildDependency(tsconfig, emitDir, metaPath) {
     // even on a clean build. A genuinely empty output directory is the real
     // failure; the caller then falls back to type-stripping the one file.
     if (!emittedAnything(emitDir)) {
+        // Drop the failed generation so its partial directory can never be mistaken
+        // for a reusable build.
+        node_fs_1.default.rmSync(emitDir, { force: true, recursive: true });
         throw new Error([
             `ttsx: dependency build produced no output for ${tsconfig}`,
             result.stderr || result.stdout,
@@ -900,11 +1191,30 @@ function buildDependency(tsconfig, emitDir, metaPath) {
     const moduleOption = typeof project.compilerOptions.module === "string"
         ? project.compilerOptions.module
         : undefined;
-    writeDependencyMeta(metaPath, { moduleOption, rootDir });
+    publishDependencyMeta(metaPath, { generation, moduleOption, rootDir });
     return { emitDir, emittedFiles: undefined, moduleOption, rootDir };
 }
-function writeDependencyMeta(metaPath, meta) {
-    node_fs_1.default.writeFileSync(metaPath, JSON.stringify(meta), "utf8");
+/**
+ * Publish the completion marker atomically: write it to a private temp name in
+ * the same directory, then rename onto `metaPath`. Node's rename replaces an
+ * existing file atomically on POSIX and Windows alike, so a concurrent reader
+ * sees either the whole previous marker or the whole new one, never a
+ * half-written file. The marker is the LAST artifact a build writes, after its
+ * generation's emit is complete, so observing the new marker guarantees the new
+ * generation is complete.
+ */
+function publishDependencyMeta(metaPath, meta) {
+    const tmp = `${metaPath}.${process.pid}.${Date.now()}.${node_crypto_1.default
+        .randomBytes(6)
+        .toString("hex")}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, JSON.stringify(meta), "utf8");
+    try {
+        node_fs_1.default.renameSync(tmp, metaPath);
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(tmp, { force: true });
+        throw error;
+    }
 }
 function dependencyCacheRoot() {
     const m = manifest();
@@ -912,6 +1222,285 @@ function dependencyCacheRoot() {
         ? m.depCacheDir
         : node_path_1.default.join(node_os_1.default.tmpdir(), "ttsx-dep");
 }
+// -----------------------------------------------------------------------------
+// Fenced dependency-build lock.
+//
+// The lock serialises concurrent first-builders of one dependency so the
+// expensive `runBuild` runs once per key while the rest wait and reuse the
+// published generation. It is generation-fenced so a stale observer or a former
+// owner can never release a successor's lock:
+//
+//   * `<lockDir>/current` is the held generation — a directory carrying a
+//     `generation` id and an `owner.json` (pid + hostname). A contender writes a
+//     private candidate and atomically renames it onto `current`; a directory
+//     rename cannot replace a non-empty `current`, so exactly one contender wins
+//     with no empty-owner publication window.
+//   * Release and reclaim both retire a generation by renaming `current` to its
+//     deterministic tombstone `<lockDir>/retired/<generation>`. The only way to
+//     free `current` is to create that tombstone, so a successor can acquire only
+//     after its predecessor's tombstone exists. A late or duplicate retire of an
+//     already-retired generation therefore finds the tombstone occupied and
+//     fails atomically, and a reclaim that named an old generation can never move
+//     a different successor into that old tombstone.
+//
+// This mirrors the source-plugin v2 protocol (`buildSourcePlugin.ts`) proven by
+// issue #452 / PR #460, minus the legacy-compatibility layer: the ttsx
+// dependency cache lives under a per-run directory with no shipped on-disk
+// format to stay compatible with.
+// -----------------------------------------------------------------------------
+const DEP_BUILD_LOCK_STEAL_MS = 600_000;
+const DEP_BUILD_LOCK_POLL_MS = 50;
+const DEP_BUILD_LOCK_STALE_MS = 30_000;
+const DEP_BUILD_LOCK_CURRENT_DIR = "current";
+const DEP_BUILD_LOCK_RETIRED_DIR = "retired";
+const DEP_BUILD_LOCK_GENERATION_FILE = "generation";
+const DEP_BUILD_LOCK_OWNER_FILE = "owner.json";
+/**
+ * Atomically acquire the current generation of a dependency build lock, or
+ * `null` when another process already holds it. Exported for the deterministic
+ * multi-process cache regressions.
+ */
+function acquireDependencyBuildLock(lockDir) {
+    ensureDependencyLockRoot(lockDir);
+    const generation = newDependencyGeneration();
+    const candidateDir = node_path_1.default.join(lockDir, `candidate-${generation}`);
+    node_fs_1.default.mkdirSync(candidateDir);
+    try {
+        node_fs_1.default.writeFileSync(node_path_1.default.join(candidateDir, DEP_BUILD_LOCK_GENERATION_FILE), `${generation}\n`, { encoding: "utf8", flag: "wx" });
+        writeDependencyLockOwner(candidateDir, generation);
+        const currentDir = node_path_1.default.join(lockDir, DEP_BUILD_LOCK_CURRENT_DIR);
+        try {
+            node_fs_1.default.renameSync(candidateDir, currentDir);
+        }
+        catch (error) {
+            if (isMissingPathError(error) ||
+                isRenameDestinationOccupied(error, currentDir)) {
+                return null;
+            }
+            throw error;
+        }
+        return { generation };
+    }
+    finally {
+        // The candidate name carries this process's random generation and can never
+        // alias `current` or another contender's candidate.
+        node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+    }
+}
+/** Retire a held generation during the holder's `finally`. */
+function releaseDependencyBuildLock(lockDir, lease) {
+    return retireDependencyBuildLock(lockDir, lease.generation);
+}
+/**
+ * Retire exactly the generation carried by an abandoned observation. Exported
+ * for the deterministic multi-process cache regressions.
+ */
+function reclaimDependencyBuildLock(lockDir, fence) {
+    return retireDependencyBuildLock(lockDir, fence.generation);
+}
+function retireDependencyBuildLock(lockDir, generation) {
+    if (!isDependencyGeneration(generation)) {
+        return false;
+    }
+    const retiredDir = node_path_1.default.join(lockDir, DEP_BUILD_LOCK_RETIRED_DIR);
+    try {
+        node_fs_1.default.mkdirSync(retiredDir);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            if (isMissingPathError(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    const destination = node_path_1.default.join(retiredDir, generation);
+    try {
+        node_fs_1.default.renameSync(node_path_1.default.join(lockDir, DEP_BUILD_LOCK_CURRENT_DIR), destination);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPathError(error) ||
+            isRenameDestinationOccupied(error, destination)) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Classify the current state of a dependency build lock directory. Exported for
+ * the deterministic multi-process cache regressions.
+ */
+function inspectDependencyBuildLock(lockDir, now) {
+    const currentDir = node_path_1.default.join(lockDir, DEP_BUILD_LOCK_CURRENT_DIR);
+    const generation = readDependencyLockGeneration(currentDir);
+    if (generation === null) {
+        if (dependencyLockAgeMs(currentDir, now) === null) {
+            return { state: "released" };
+        }
+        // `current` exists without a readable generation id. Acquisition writes the
+        // id into the candidate BEFORE the atomic rename, so this is a transient or
+        // corrupt state; keep waiting rather than steal on ambiguous evidence.
+        return {
+            state: "active",
+            owner: "lock generation without a readable id",
+            fence: { generation: "" },
+        };
+    }
+    const fence = { generation };
+    const owner = readDependencyLockOwner(currentDir);
+    if (owner !== null) {
+        const label = describeDependencyLockOwner(owner);
+        if (isLocalHostName(owner.hostname) && !isProcessAlive(owner.pid)) {
+            return {
+                state: "abandoned",
+                reason: `${label} is no longer running`,
+                fence,
+            };
+        }
+        return { state: "active", owner: label, fence };
+    }
+    const ageMs = dependencyLockAgeMs(currentDir, now);
+    if (ageMs === null) {
+        return { state: "released" };
+    }
+    if (ageMs > DEP_BUILD_LOCK_STALE_MS) {
+        return {
+            state: "abandoned",
+            reason: `lock generation has no ${DEP_BUILD_LOCK_OWNER_FILE} and is ${formatDuration(ageMs)} old`,
+            fence,
+        };
+    }
+    return {
+        state: "active",
+        owner: `lock generation with no ${DEP_BUILD_LOCK_OWNER_FILE}`,
+        fence,
+    };
+}
+/** Poll for the locked builder to publish, up to `timeoutMs`. */
+function waitForDependencyBuild(cacheDir, metaPath, lockDir, timeoutMs) {
+    const startedAt = Date.now();
+    for (;;) {
+        const reuse = readDependencyCache(cacheDir, metaPath);
+        if (reuse !== null) {
+            return { outcome: "built", built: reuse };
+        }
+        const now = Date.now();
+        const lock = inspectDependencyBuildLock(lockDir, now);
+        if (lock.state === "released") {
+            // The holder retired its generation between the cache check above and this
+            // observation: prefer the marker if it landed in that window, otherwise
+            // hand the free lock back to the caller to re-acquire.
+            const built = readDependencyCache(cacheDir, metaPath);
+            return built !== null
+                ? { outcome: "built", built }
+                : { outcome: "released" };
+        }
+        if (lock.state === "abandoned") {
+            return { outcome: "abandoned", reason: lock.reason, fence: lock.fence };
+        }
+        if (now - startedAt > timeoutMs) {
+            return {
+                outcome: "abandoned",
+                reason: `timed out after ${formatDuration(now - startedAt)}`,
+                fence: lock.fence,
+            };
+        }
+        sleepSync(DEP_BUILD_LOCK_POLL_MS);
+    }
+}
+function ensureDependencyLockRoot(lockDir) {
+    node_fs_1.default.mkdirSync(node_path_1.default.join(lockDir, DEP_BUILD_LOCK_RETIRED_DIR), {
+        recursive: true,
+    });
+}
+function writeDependencyLockOwner(generationDir, generation) {
+    node_fs_1.default.writeFileSync(node_path_1.default.join(generationDir, DEP_BUILD_LOCK_OWNER_FILE), `${JSON.stringify({
+        generation,
+        hostname: node_os_1.default.hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    })}\n`, "utf8");
+}
+function readDependencyLockOwner(generationDir) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(generationDir, DEP_BUILD_LOCK_OWNER_FILE), "utf8"));
+        if (typeof parsed.hostname !== "string" ||
+            typeof parsed.pid !== "number" ||
+            !Number.isInteger(parsed.pid) ||
+            parsed.pid <= 0) {
+            return null;
+        }
+        return {
+            hostname: parsed.hostname,
+            pid: parsed.pid,
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readDependencyLockGeneration(generationDir) {
+    try {
+        const generation = node_fs_1.default
+            .readFileSync(node_path_1.default.join(generationDir, DEP_BUILD_LOCK_GENERATION_FILE), "utf8")
+            .trim();
+        return isDependencyGeneration(generation) ? generation : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Age of an observed lock directory, or `null` when it no longer exists. */
+function dependencyLockAgeMs(generationDir, now) {
+    try {
+        return Math.max(0, now - node_fs_1.default.statSync(generationDir).mtimeMs);
+    }
+    catch (error) {
+        return isMissingPathError(error) ? null : 0;
+    }
+}
+function describeDependencyLockOwner(owner) {
+    const started = owner.startedAt === undefined ? "" : ` started at ${owner.startedAt}`;
+    return `pid ${owner.pid} on ${owner.hostname}${started}`;
+}
+function isLocalHostName(hostname) {
+    return hostname.toLowerCase() === node_os_1.default.hostname().toLowerCase();
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function isMissingPathError(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+function isRenameDestinationOccupied(error, destination) {
+    const code = error.code;
+    if (code === "EEXIST" || code === "ENOTEMPTY") {
+        return true;
+    }
+    return (code === "EACCES" || code === "EPERM") && node_fs_1.default.existsSync(destination);
+}
+/** Render a millisecond duration for lock diagnostics (`137ms`, `42s`, `9m 3s`). */
+function formatDuration(ms) {
+    if (!Number.isFinite(ms)) {
+        return "an unknown time";
+    }
+    if (ms < 1_000) {
+        return `${Math.max(0, Math.round(ms))}ms`;
+    }
+    const seconds = Math.floor(ms / 1_000);
+    const minutes = Math.floor(seconds / 60);
+    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 moduleOptionCache = new Map();