ttsc 0.30.3 → 0.31.0

package/lib/launcher/internal/runtime/RuntimeProjectOwnership.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare namespace RuntimeProjectOwnership {
+    /**
+     * 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.
+     */
+    function isInstalledPackageSource(real: string): boolean;
+    /**
+     * 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.
+     */
+    function nearestTsconfig(file: string, observe?: (candidates: readonly string[]) => void): string | null;
+}

package/lib/launcher/internal/runtime/RuntimeProjectOwnership.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeProjectOwnership = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const RuntimeFilesystem_1 = require("./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.
+ */
+var RuntimeProjectOwnership;
+(function (RuntimeProjectOwnership) {
+    const cache = new Map();
+    /**
+     * 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.
+     */
+    function isInstalledPackageSource(real) {
+        for (let directory = node_path_1.default.dirname(real);;) {
+            if (isInstalledDirectory(directory))
+                return true;
+            const parent = node_path_1.default.dirname(directory);
+            if (parent === directory)
+                return false;
+            directory = parent;
+        }
+    }
+    RuntimeProjectOwnership.isInstalledPackageSource = isInstalledPackageSource;
+    /**
+     * 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.
+     */
+    function nearestTsconfig(file, observe = () => { }) {
+        let directory = node_path_1.default.dirname(file);
+        const chain = [];
+        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(node_path_1.default.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 = node_path_1.default.join(directory, "tsconfig.json");
+            observe([candidate]);
+            if (RuntimeFilesystem_1.RuntimeFilesystem.isFile(candidate))
+                return remember(chain, candidate);
+            const parent = node_path_1.default.dirname(directory);
+            if (parent === directory)
+                return remember(chain, null);
+            directory = parent;
+        }
+    }
+    RuntimeProjectOwnership.nearestTsconfig = nearestTsconfig;
+    function isInstalledDirectory(directory, observe = () => { }) {
+        const basename = node_path_1.default.basename(directory);
+        if (basename === "node_modules")
+            return true;
+        if (basename.toLowerCase() !== "node_modules")
+            return false;
+        const lowercase = node_path_1.default.join(node_path_1.default.dirname(directory), "node_modules");
+        const inputs = [directory, lowercase];
+        observe(inputs);
+        try {
+            return node_fs_1.default.realpathSync.native(directory) === node_fs_1.default.realpathSync.native(lowercase);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            observe(inputs);
+        }
+    }
+    function nearestExisting(candidates) {
+        for (const candidate of candidates)
+            if (RuntimeFilesystem_1.RuntimeFilesystem.isFile(candidate))
+                return node_path_1.default.resolve(candidate);
+        return null;
+    }
+    function remember(directories, result, tail = [], boundary) {
+        let candidates = [...tail];
+        for (let index = directories.length - 1; index >= 0; --index) {
+            const directory = directories[index];
+            candidates = [node_path_1.default.join(directory, "tsconfig.json"), ...candidates];
+            cache.set(directory, { candidates, result, boundary });
+        }
+        return result;
+    }
+})(RuntimeProjectOwnership || (exports.RuntimeProjectOwnership = RuntimeProjectOwnership = {}));
+//# sourceMappingURL=RuntimeProjectOwnership.js.map

package/lib/launcher/internal/runtime/RuntimeProjectOwnership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeProjectOwnership.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeProjectOwnership.ts"],"names":[],"mappings":"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"}

package/lib/launcher/internal/runtime/TTSX_MINIMUM_NODE_VERSION.d.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 declare const TTSX_MINIMUM_NODE_VERSION = "22.15.0";

package/lib/launcher/internal/runtime/TTSX_MINIMUM_NODE_VERSION.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTSX_MINIMUM_NODE_VERSION = void 0;
+/**
+ * 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.
+ */
+exports.TTSX_MINIMUM_NODE_VERSION = "22.15.0";
+//# sourceMappingURL=TTSX_MINIMUM_NODE_VERSION.js.map

package/lib/launcher/internal/runtime/TTSX_MINIMUM_NODE_VERSION.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TTSX_MINIMUM_NODE_VERSION.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/TTSX_MINIMUM_NODE_VERSION.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACU,QAAA,yBAAyB,GAAG,SAAS,CAAC"}

package/lib/launcher/internal/runtime/acquireDependencyBuildLock.d.ts

@@ -0,0 +1,22 @@
+import type { DependencyBuildLockLease } from "./DependencyBuildLockLease";
+/**
+ * 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 declare function acquireDependencyBuildLock(lockDir: string): DependencyBuildLockLease | null;

package/lib/launcher/internal/runtime/acquireDependencyBuildLock.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireDependencyBuildLock = acquireDependencyBuildLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const isContendedCandidateRename_1 = require("../../../internal/isContendedCandidateRename");
+const DependencyBuildGeneration_1 = require("./DependencyBuildGeneration");
+const DependencyBuildLockProtocol_1 = require("./DependencyBuildLockProtocol");
+const RuntimeFilesystem_1 = require("./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.
+ */
+function acquireDependencyBuildLock(lockDir) {
+    ensureDependencyLockRoot(lockDir);
+    const generation = DependencyBuildGeneration_1.DependencyBuildGeneration.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, DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_GENERATION_FILE), `${generation}\n`, { encoding: "utf8", flag: "wx" });
+        writeDependencyLockOwner(candidateDir, generation);
+        const currentDir = node_path_1.default.join(lockDir, DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_CURRENT_DIR);
+        try {
+            node_fs_1.default.renameSync(candidateDir, currentDir);
+        }
+        catch (error) {
+            if (RuntimeFilesystem_1.RuntimeFilesystem.isMissingPathError(error) ||
+                (0, isContendedCandidateRename_1.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.
+        node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+    }
+}
+function ensureDependencyLockRoot(lockDir) {
+    node_fs_1.default.mkdirSync(node_path_1.default.join(lockDir, DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_RETIRED_DIR), {
+        recursive: true,
+    });
+}
+function writeDependencyLockOwner(generationDir, generation) {
+    node_fs_1.default.writeFileSync(node_path_1.default.join(generationDir, DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_OWNER_FILE), `${JSON.stringify({
+        generation,
+        hostname: node_os_1.default.hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    })}\n`, "utf8");
+}
+//# sourceMappingURL=acquireDependencyBuildLock.js.map

package/lib/launcher/internal/runtime/acquireDependencyBuildLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquireDependencyBuildLock.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/acquireDependencyBuildLock.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,sDAAyB;AACzB,0DAA6B;AAE7B,6FAA0F;AAC1F,2EAAwE;AAExE,+EAA4E;AAC5E,2DAAwD;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oCACE,OAAe;IAEf,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,qDAAyB,CAAC,uBAAuB,EAAE,CAAC;IACvE,MAAM,YAAY,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,UAAU,EAAE,CAAC,CAAC;IACnE,iBAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC3B,IAAI,CAAC;QACH,iBAAE,CAAC,aAAa,CACd,mBAAI,CAAC,IAAI,CACP,YAAY,EACZ,yDAA2B,CAAC,8BAA8B,CAC3D,EACD,GAAG,UAAU,IAAI,EACjB,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CACjC,CAAC;QACF,wBAAwB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QACnD,MAAM,UAAU,GAAG,mBAAI,CAAC,IAAI,CAC1B,OAAO,EACP,yDAA2B,CAAC,0BAA0B,CACvD,CAAC;QACF,IAAI,CAAC;YACH,iBAAE,CAAC,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,qCAAiB,CAAC,kBAAkB,CAAC,KAAK,CAAC;gBAC3C,IAAA,uDAA0B,EAAC,KAAK,CAAC,EACjC,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,0EAA0E;QAC1E,2EAA2E;QAC3E,iBAAE,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAAC,OAAe;IAC/C,iBAAE,CAAC,SAAS,CACV,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,yDAA2B,CAAC,0BAA0B,CAAC,EAC1E;QACE,SAAS,EAAE,IAAI;KAChB,CACF,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB,CAC/B,aAAqB,EACrB,UAAkB;IAElB,iBAAE,CAAC,aAAa,CACd,mBAAI,CAAC,IAAI,CACP,aAAa,EACb,yDAA2B,CAAC,yBAAyB,CACtD,EACD,GAAG,IAAI,CAAC,SAAS,CAAC;QAChB,UAAU;QACV,QAAQ,EAAE,iBAAE,CAAC,QAAQ,EAAE;QACvB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC,IAAI,EACN,MAAM,CACP,CAAC;AACJ,CAAC"}

package/lib/launcher/internal/runtime/checkNodeRuntimeSupport.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function checkNodeRuntimeSupport(version: string, versions?: Readonly<Record<string, string | undefined>>): string | null;

package/lib/launcher/internal/runtime/checkNodeRuntimeSupport.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkNodeRuntimeSupport = checkNodeRuntimeSupport;
+const TTSX_MINIMUM_NODE_VERSION_1 = require("./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.
+ */
+function checkNodeRuntimeSupport(version, versions = process.versions) {
+    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_1.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 = [22, 15, 0];
+/** `process.versions` keys of runtimes that report a Node version too. */
+const NON_NODE_RUNTIMES = [
+    ["bun", "Bun"],
+    ["deno", "Deno"],
+];
+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;
+}
+//# sourceMappingURL=checkNodeRuntimeSupport.js.map

package/lib/launcher/internal/runtime/checkNodeRuntimeSupport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkNodeRuntimeSupport.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/checkNodeRuntimeSupport.ts"],"names":[],"mappings":";;;AAAA,2EAAwE;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iCACE,OAAe,EACf,QAAQ,GAAiD,OAAO,CAAC,QAAQ;IAEzE,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,CACL,6CAA6C,IAAI,IAAI,QAAQ,IAAI;gBACjE,qEAAqE,IAAI,IAAI;gBAC7E,kFAAkF;gBAClF,8DAA8D;gBAC9D,+DAA+D;gBAC/D,sBAAsB,CACvB,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,2EAA2E;QAC3E,8DAA8D;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CACL,yBAAyB,qDAAyB,sBAAsB;QACxE,sBAAsB,OAAO,4CAA4C;QACzE,0EAA0E;QAC1E,6EAA6E;QAC7E,yFAAyF;QACzF,4EAA4E,CAC7E,CAAC;AACJ,CAAC;AAED,MAAM,uBAAuB,GAAsC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAE/E,0EAA0E;AAC1E,MAAM,iBAAiB,GAA2C;IAChE,CAAC,KAAK,EAAE,KAAK,CAAC;IACd,CAAC,MAAM,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,KAAK,GAAG,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,mBAAmB,CAC1B,CAAoC,EACpC,CAAoC;IAEpC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,CAAC,KAAK,CAAE,KAAK,CAAC,CAAC,KAAK,CAAE,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,KAAK,CAAE,GAAG,CAAC,CAAC,KAAK,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/lib/launcher/internal/runtime/claimRuntimeProjectDirectory.d.ts

@@ -0,0 +1,30 @@
+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 declare function claimRuntimeProjectDirectory(runtimeRoot: string, runKey: string, withLock?: typeof withRuntimeDirectoryLock): string;

package/lib/launcher/internal/runtime/claimRuntimeProjectDirectory.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimRuntimeProjectDirectory = claimRuntimeProjectDirectory;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceBuildCacheLayout_1 = require("../../../plugin/internal/source/SourceBuildCacheLayout");
+const ProcessOwnedDirectory_1 = require("./ProcessOwnedDirectory");
+const withRuntimeDirectoryLock_1 = require("./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.
+ */
+function claimRuntimeProjectDirectory(runtimeRoot, runKey, withLock = withRuntimeDirectoryLock_1.withRuntimeDirectoryLock) {
+    return withLock(runtimeRoot, () => {
+        const directory = node_path_1.default.join(runtimeRoot, SourceBuildCacheLayout_1.SourceBuildCacheLayout.RUNTIME_PROJECT_DIRNAME);
+        node_fs_1.default.mkdirSync(directory, { recursive: true });
+        const runsDir = node_fs_1.default.realpathSync.native(directory);
+        const processDir = node_path_1.default.join(runsDir, runKey);
+        ProcessOwnedDirectory_1.ProcessOwnedDirectory.sweep(runsDir);
+        node_fs_1.default.rmSync(processDir, { recursive: true, force: true });
+        ProcessOwnedDirectory_1.ProcessOwnedDirectory.claim(processDir);
+        return processDir;
+    });
+}
+//# sourceMappingURL=claimRuntimeProjectDirectory.js.map

package/lib/launcher/internal/runtime/claimRuntimeProjectDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimRuntimeProjectDirectory.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/claimRuntimeProjectDirectory.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,mGAAgG;AAChG,mEAAgE;AAChE,yEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,sCACE,WAAmB,EACnB,MAAc,EACd,QAAQ,GAAoC,mDAAwB;IAEpE,OAAO,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;QAChC,MAAM,SAAS,GAAG,mBAAI,CAAC,IAAI,CACzB,WAAW,EACX,+CAAsB,CAAC,uBAAuB,CAC/C,CAAC;QACF,iBAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,iBAAE,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,MAAM,UAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,6CAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrC,iBAAE,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,6CAAqB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACxC,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/launcher/internal/runtime/commonJsExportNames.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function commonJsExportNames(source: string, filename: string, readSource: (file: string) => string | null, resolve?: (parent: string, specifier: string) => string): string[];