ttsc 0.30.4 → 0.31.0

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

@@ -0,0 +1,38 @@
+/**
+ * Validate the serialized source ownership supplied by a completed compiler
+ * emit.
+ *
+ * Keys name absolute native output files; each value names the absolute native
+ * sources that actually contributed to that written output. Validation checks
+ * representation, not whether the compiler observations themselves are
+ * trusted.
+ *
+ * @evidence contracts/common.md#principled-implementation One record grammar preserves actual output-to-source observations across manifest and cache-marker JSON instead of reconstructing ownership from stems or optional source maps.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace owns shared transport validation for both runtime readers; producer observation and unique physical ownership stay with the compiler and ownership index.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Representation checks do not fabricate missing provenance or accept a known output filename as proof of which source compiled it.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs define absolute output/source spelling and the distinction between syntactic validation and trusted producer observations.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute validates transported filesystem filenames; it does not lower-case them or confuse slash-separated output-list keys with native absolute paths.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups transport validation; isRecord owns the traversal strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no request cache or shared completed emit.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no record, descriptor or task.
+ */
+export declare namespace RuntimeEmitProvenance {
+    /**
+     * Whether a decoded value has the compiler's absolute output-to-sources
+     * shape. An empty record is valid transport shape, distinct from absent
+     * provenance; the predicate does not authenticate a producer's observation
+     * that no output owns a source.
+     *
+     * @evidence contracts/common.md#principled-implementation A nonarray object with absolute native output keys and arrays of absolute native source names preserves each recorded mapping; an empty object remains distinct from absent provenance.
+     * @evidence contracts/common.md#clear-and-simple-design One type predicate validates the same nested record for manifest inheritance and generation reuse without adding a runtime wrapper around the observed data.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or malformed provenance is rejected rather than rebuilt from filename extensions or a source-map guess.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies decoded transport scope and valid empty-record shape without certifying producer completeness or ownership observations.
+     * @evidence contracts/portability.md#os-neutral-implementation path.isAbsolute applies the consuming host's native filename grammar; filesystem identity and alias equivalence remain the ownership index's responsibility.
+     * @evidence contracts/performance.md#efficient-algorithms One visit per output and contributing source costs O(O + S) entries plus path characters; Object.entries temporarily stores O(O) pairs, with early rejection and no filesystem reads or recursive source-tree enumeration.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate owns no cross-reader computation coordinator, independent cache or invalidation identity for mutable caller records; readers choose when to revalidate transported values.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous predicate retains no mapping history or native resource; validated data remains reader-owned.
+     */
+    function isRecord(value: unknown): value is Readonly<Record<string, readonly string[]>>;
+}

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

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeEmitProvenance = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Validate the serialized source ownership supplied by a completed compiler
+ * emit.
+ *
+ * Keys name absolute native output files; each value names the absolute native
+ * sources that actually contributed to that written output. Validation checks
+ * representation, not whether the compiler observations themselves are
+ * trusted.
+ *
+ * @evidence contracts/common.md#principled-implementation One record grammar preserves actual output-to-source observations across manifest and cache-marker JSON instead of reconstructing ownership from stems or optional source maps.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace owns shared transport validation for both runtime readers; producer observation and unique physical ownership stay with the compiler and ownership index.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Representation checks do not fabricate missing provenance or accept a known output filename as proof of which source compiled it.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs define absolute output/source spelling and the distinction between syntactic validation and trusted producer observations.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute validates transported filesystem filenames; it does not lower-case them or confuse slash-separated output-list keys with native absolute paths.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups transport validation; isRecord owns the traversal strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no request cache or shared completed emit.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no record, descriptor or task.
+ */
+var RuntimeEmitProvenance;
+(function (RuntimeEmitProvenance) {
+    /**
+     * Whether a decoded value has the compiler's absolute output-to-sources
+     * shape. An empty record is valid transport shape, distinct from absent
+     * provenance; the predicate does not authenticate a producer's observation
+     * that no output owns a source.
+     *
+     * @evidence contracts/common.md#principled-implementation A nonarray object with absolute native output keys and arrays of absolute native source names preserves each recorded mapping; an empty object remains distinct from absent provenance.
+     * @evidence contracts/common.md#clear-and-simple-design One type predicate validates the same nested record for manifest inheritance and generation reuse without adding a runtime wrapper around the observed data.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or malformed provenance is rejected rather than rebuilt from filename extensions or a source-map guess.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies decoded transport scope and valid empty-record shape without certifying producer completeness or ownership observations.
+     * @evidence contracts/portability.md#os-neutral-implementation path.isAbsolute applies the consuming host's native filename grammar; filesystem identity and alias equivalence remain the ownership index's responsibility.
+     * @evidence contracts/performance.md#efficient-algorithms One visit per output and contributing source costs O(O + S) entries plus path characters; Object.entries temporarily stores O(O) pairs, with early rejection and no filesystem reads or recursive source-tree enumeration.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate owns no cross-reader computation coordinator, independent cache or invalidation identity for mutable caller records; readers choose when to revalidate transported values.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous predicate retains no mapping history or native resource; validated data remains reader-owned.
+     */
+    function isRecord(value) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            return false;
+        }
+        for (const [output, sources] of Object.entries(value)) {
+            if (!node_path_1.default.isAbsolute(output) ||
+                !Array.isArray(sources) ||
+                !sources.every((source) => typeof source === "string" && node_path_1.default.isAbsolute(source))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    RuntimeEmitProvenance.isRecord = isRecord;
+})(RuntimeEmitProvenance || (exports.RuntimeEmitProvenance = RuntimeEmitProvenance = {}));
+//# sourceMappingURL=RuntimeEmitProvenance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeEmitProvenance.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeEmitProvenance.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,IAAiB,qBAAqB,CAoCrC;AApCD,WAAiB,qBAAqB;IACpC;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,QAAQ,CACtB,KAAc;QAEd,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACtD,IACE,CAAC,mBAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBACxB,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;gBACvB,CAAC,OAAO,CAAC,KAAK,CACZ,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,mBAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAClE,EACD,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAlBe,sBAAA,QAAQ,WAkBvB,CAAA;AACH,CAAC,EApCgB,qBAAqB,aAArB,qBAAqB,GAArB,qBAAqB,QAoCrC"}

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

@@ -0,0 +1,22 @@
+import type { RuntimeManifest } from "./RuntimeManifest";
+/**
+ * Synchronously prepare and type-check a TypeScript root discovered by a host.
+ *
+ * The input is the resolved native filename supplied by the runtime hook. The
+ * returned manifest records the checked emit used for that root and its
+ * imports; artifact cleanup remains with the preparation owner. Preparation
+ * errors propagate to the requesting import, and the registry copies successful
+ * supported metadata without eviction while its module instance remains alive.
+ * The structural callback type itself does not authenticate checked
+ * preparation.
+ *
+ * @evidence contracts/common.md#principled-implementation This callback contract requests synchronous checked preparation; the hook admits its returned metadata and requires an owning entry emit before serving. The signature is not a completion certificate, and thrown preparation errors remain import failures.
+ * @evidence contracts/common.md#clear-and-simple-design One named callback separates the preparation contract from optional hook configuration without adding a wrapper or changing the callback's parameter variance.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The callback describes the host's supported preparation boundary and introduces no fixture branch, foreign mutation or fallback implementation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish the requested preparation contract from structural authentication, artifact ownership, propagated errors and instance-owned copied metadata lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation The argument is a native filesystem filename rather than a URL; the returned manifest carries the owning build's resolved directories instead of assuming a separator or case policy.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type RuntimeEntryPreparer = (filename: string) => RuntimeManifest;

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RuntimeEntryPreparer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeEntryPreparer.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeEntryPreparer.ts"],"names":[],"mappings":""}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeFilesystem.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeFilesystem.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AAEzB;;;;;;;;;;;;;;;;;GAiBG;AACH,IAAiB,iBAAiB,CA2CjC;AA3CD,WAAiB,iBAAiB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,kBAAkB,CAAC,KAAc;QAC/C,MAAM,IAAI,GAAI,KAAsC,EAAE,IAAI,CAAC;QAC3D,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC;IACjD,CAAC;IAHe,kBAAA,kBAAkB,qBAGjC,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,MAAM,CAAC,SAAiB;QACtC,IAAI,CAAC;YACH,OAAO,iBAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IANe,kBAAA,MAAM,SAMrB,CAAA;AACH,CAAC,EA3CgB,iBAAiB,aAAjB,iBAAiB,GAAjB,iBAAiB,QA2CjC"}

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

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

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RuntimeHookOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeHookOptions.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeHookOptions.ts"],"names":[],"mappings":""}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeIsolatedEmit.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeIsolatedEmit.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,IAAiB,mBAAmB,CAoDnC;AApDD,WAAiB,mBAAmB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,SAAgB,YAAY,CAC1B,KAAa,EACb,MAAc,EACd,MAA6B,EAC7B,OAAoC;QAEpC,OAAO;YACL,KAAK;YACL,UAAU;YACV,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;YAC7C,GAAG,kBAAkB;YACrB,GAAG,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,UAAU;YACV,MAAM;SACP,CAAC;IACJ,CAAC;IAfe,oBAAA,YAAY,eAe3B,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,SAAS;QACvB,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAFe,oBAAA,SAAS,YAExB,CAAA;AACH,CAAC,EApDgB,mBAAmB,aAAnB,mBAAmB,GAAnB,mBAAmB,QAoDnC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAAG;IACzB,gBAAgB;IAChB,UAAU;IACV,QAAQ;IACR,OAAO;IACP,WAAW;IACX,WAAW;IACX,gBAAgB;IAChB,aAAa;IACb,mBAAmB;CACX,CAAC"}

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

@@ -0,0 +1,78 @@
+/**
+ * What this runtime's module loader does on its own, read by asking it rather
+ * than by its version.
+ *
+ * The ttsx runtime serves TypeScript through `module.registerHooks`, the
+ * supported customization API. How far that API reaches, and how the loader
+ * shapes a CommonJS module imported from ESM, differ between Node releases in
+ * both directions, so this helper instance memoizes actual public-API probes.
+ * Main-thread temporary hooks deregister afterwards; the separate worker owns
+ * its hooks until termination. The runtime installer invokes these before its
+ * own hooks exist, so nothing they load is recorded as an input of the
+ * program.
+ *
+ * @evidence contracts/common.md#principled-implementation Public loader probes observe the actual require.resolve, namespace and hooked-import behavior instead of deriving it from a release number; each boolean selects the runtime path matching that observed capability.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns three independent lazy capability answers and their private probes, keeping loader adaptation choices with the hook consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Temporary registerHooks/deregister boundaries are supported customization, not private-loader mutation; the worker tests a real ESM-to-CommonJS path rather than a fixture version table.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why loader differences require observation and describe each affected behavior; worker comments distinguish synchronous require from the probed import path.
+ * @evidence contracts/portability.md#os-neutral-implementation Native filenames become URLs through pathToFileURL and workers use Node APIs; no shell quoting, separator substitution or OS-name case rule implements the probes.
+ * @evidence contracts/performance.md#efficient-algorithms Three memoized probe paths delegate native resolution/module loading or Worker initialization; input path text, loader work and startup latency are not bounded by the fixed probe count. Atomics waits at most ten seconds after worker construction; that wait is not a bound on constructor or teardown latency.
+ * @evidence contracts/performance.md#reuse-equivalent-work Completed booleans serve this helper instance under the installer's stable native-loader premise; arbitrary later external hook changes are not re-probed. Propagated exceptions leave initialization unset; worker construction/failure/no-answer paths can instead memoize conservative false.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Three booleans remain with this helper instance. Main-thread temporary hooks deregister in finally; the probe namespace/cache belongs to Node. Worker termination is requested asynchronously after the answer wait, so completed teardown and release of its hooks/streams are not certified by return.
+ */
+export declare namespace RuntimeLoaderCapabilities {
+    /**
+     * Whether `require.resolve` consults resolve hooks registered with
+     * `module.registerHooks`.
+     *
+     * A runtime whose `require.resolve` does consult them resolves a TypeScript
+     * source through ttsx's own resolve hook; one that does not answers from
+     * Node's resolver alone, which knows no TypeScript source.
+     *
+     * @evidence contracts/common.md#principled-implementation A sentinel request through require.resolve observes whether the public resolve hook was actually consulted, giving the consumer grounds for its corresponding resolution lane.
+     * @evidence contracts/common.md#clear-and-simple-design The public accessor exposes one cached capability while a private probe owns registration and cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No private Node resolver is patched and no version-specific expected answer replaces the actual supported-hook observation.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish hook-aware and native-only resolution and explain why the distinction affects TypeScript sources.
+     * @evidence contracts/portability.md#os-neutral-implementation The probe uses a native filename converted with pathToFileURL; Node supplies synchronous module resolution on each supported host.
+     * @evidence contracts/performance.md#efficient-algorithms One sentinel request through temporary public hooks initializes the boolean; path text and delegated native resolution are initialization costs. Later calls read the helper-instance memo without another registration.
+     * @evidence contracts/performance.md#reuse-equivalent-work requireResolve stores the running loader's stable capability for subsequent consumers; a thrown probe does not store an invented answer.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally; this helper instance retains the boolean. Node and the surrounding installed runtime own any delegated module/cache state.
+     */
+    function requireResolveConsultsHooks(): boolean;
+    /**
+     * Whether the namespace of a CommonJS module imported from ESM carries a
+     * `module.exports` export beside `default` and the statically detected
+     * names.
+     *
+     * @evidence contracts/common.md#principled-implementation Importing the side-effect-free CommonJS probe through public hooks observes whether the actual ESM namespace contains module.exports, so facade shape follows the running loader.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor exposes only the namespace capability, with source construction and temporary hooks isolated in its private probe.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A real namespace is inspected rather than fabricating the export from a Node version or modifying CommonJS globals.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module.exports from default and static names, which is the fact facade callers need.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join and pathToFileURL preserve native probe filenames and URL spelling; no hand-built file URL assumes drive or separator syntax.
+     * @evidence contracts/performance.md#efficient-algorithms One hooked importer delegates native CommonJS/ESM loading and namespace-key enumeration, including native path text and loader work; later calls read this helper-instance memo.
+     * @evidence contracts/performance.md#reuse-equivalent-work The namespace convention is stable for the running loader, so the cached boolean is shared by all facades; failed probing propagates rather than guessing the convention.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally. The helper retains its boolean; Node owns the probe CommonJS/ESM cache entries, which are not explicitly evicted here.
+     */
+    function commonJsNamespaceCarriesModuleExports(): boolean;
+    /**
+     * Whether a CommonJS module the ESM loader evaluates from source a load hook
+     * returned exposes `require.cache` and `require.extensions` as objects.
+     *
+     * A runtime that does not (Node 22) evaluates it with a narrower `require`:
+     * no `cache`, `extensions`, or `resolve.paths`, whose calls go through the
+     * ESM loader and cannot load a module Node's CommonJS loader would load.
+     * Whenever any load hook is registered, every CommonJS module an `import`
+     * reaches takes that path there, the ones the hook passes to `nextLoad`
+     * included.
+     *
+     * @evidence contracts/common.md#principled-implementation A worker runs an actual ESM import whose hooked CommonJS body observes cache/extensions object properties; only that positive result permits the caller's unadapted lane. This does not independently test every require method or arbitrary CommonJS dependency.
+     * @evidence contracts/common.md#clear-and-simple-design The synchronous accessor hides worker coordination and returns one cached loader capability rather than exposing timing or worker state to hook consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The probe registers supported hooks in its own worker and preserves public createRequire adaptation on uncertain results instead of replacing Node internals.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain narrowed require and why passthrough CommonJS imports are affected; private prose identifies the required asynchronous import path.
+     * @evidence contracts/portability.md#os-neutral-implementation Node workers and pathToFileURL handle the native execution boundary without process shell commands or platform-specific loader guesses.
+     * @evidence contracts/performance.md#efficient-algorithms Worker construction delegates native thread/startup work; one four-byte shared answer and a bounded Atomics wait coordinate this attempt. Repeated accessor calls read the helper-instance memo, including cached conservative negatives, without another worker.
+     * @evidence contracts/performance.md#reuse-equivalent-work The running Node loader's require behavior is shared across imports; a conservative negative result after failure consistently selects the facade that supplies ordinary require.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One worker belongs to initialization and receives terminate in finally; one boolean remains afterwards. The synchronous accessor does not await termination, so completion of teardown is not independently bounded here. Opt-in observations distinguish its actual creation, termination request returning a Promise, and exit event under one probe id. No await, rejection handler or error listener changes the existing termination/unhandled-error behavior. Exit reports this worker lifecycle only and cannot establish an OS executable-lock owner.
+     */
+    function hookedCommonJsImportKeepsRequire(): boolean;
+}