ttsc 0.30.3 → 0.31.0

package/lib/index.d.ts

@@ -2,11 +2,16 @@
  * Ttsc — public TypeScript entry.
  *
  * The package root intentionally exposes only the programmatic compiler class
- * and the plugin-author contracts. CLI launcher functions, binary resolution,
- * project parsing helpers, and native build helpers stay internal so the public
- * package surface remains small and stable.
+ * and the plugin-author contracts, including passive failure descriptions. CLI
+ * launcher functions, binary resolution, project parsing helpers, and native
+ * build helpers stay off it so the public package surface remains small and
+ * stable.
  */
+export * from "./plugin/ITtscCapabilityPlugin";
+export * from "./plugin/CapabilityPluginResolver";
 export * from "./plugin/resolveCapabilityPlugins";
 export * from "./TtscCompiler";
+export * from "./TtscServiceRequestOptions";
 export * from "./TtscService";
 export * from "./structures/index";
+export { serializeCompilerError } from "./internal/serializeCompilerError";

package/lib/index.js

@@ -3,9 +3,10 @@
  * Ttsc — public TypeScript entry.
  *
  * The package root intentionally exposes only the programmatic compiler class
- * and the plugin-author contracts. CLI launcher functions, binary resolution,
- * project parsing helpers, and native build helpers stay internal so the public
- * package surface remains small and stable.
+ * and the plugin-author contracts, including passive failure descriptions. CLI
+ * launcher functions, binary resolution, project parsing helpers, and native
+ * build helpers stay off it so the public package surface remains small and
+ * stable.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -22,8 +23,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCompilerError = void 0;
+__exportStar(require("./plugin/ITtscCapabilityPlugin"), exports);
+__exportStar(require("./plugin/CapabilityPluginResolver"), exports);
 __exportStar(require("./plugin/resolveCapabilityPlugins"), exports);
 __exportStar(require("./TtscCompiler"), exports);
+__exportStar(require("./TtscServiceRequestOptions"), exports);
 __exportStar(require("./TtscService"), exports);
 __exportStar(require("./structures/index"), exports);
+var serializeCompilerError_1 = require("./internal/serializeCompilerError");
+Object.defineProperty(exports, "serializeCompilerError", { enumerable: true, get: function () { return serializeCompilerError_1.serializeCompilerError; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,oEAAkD;AAClD,iDAA+B;AAC/B,gDAA8B;AAC9B,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;AAEH,iEAA+C;AAC/C,oEAAkD;AAClD,oEAAkD;AAClD,iDAA+B;AAC/B,8DAA4C;AAC5C,gDAA8B;AAC9B,qDAAmC;AAEnC,4EAA2E;AAAlE,gIAAA,sBAAsB,OAAA"}

package/lib/internal/CanonicalTempDirectoryOperations.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The filesystem primitives {@link createCanonicalTempDirectory} uses.
+ *
+ * The creator uses these synchronous observations to pin a physical parent,
+ * allocate a child and check its resulting path. Injected implementations must
+ * describe the same native filesystem and propagate operation errors; this
+ * interface does not provide an atomic snapshot or held-directory guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation Link-preserving stat, unique allocation and physical resolution expose the distinct facts needed to validate one temporary directory; their signatures describe synchronous operations and do not claim atomicity between observations.
+ * @evidence contracts/common.md#clear-and-simple-design Three required primitives form the creator's filesystem boundary without embedding cleanup policy, a retry mechanism or unrelated directory traversal in the interface.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit primitive injection is the supported boundary; implementations must report actual native results instead of replacing foreign globals or fabricating a child that matches the postflight.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states caller semantics, consistent-filesystem and error premises and the atomicity limit; documented method blocks and type acknowledgments remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Physical resolution must expand native aliases including symlinks, junctions and Windows short names, while link-preserving stat distinguishes the actual entry instead of relying on path spelling or OS-name guesses.
+ * @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 CanonicalTempDirectoryOperations {
+    /**
+     * Link-preserving stat. Used twice: to prove the physical parent is a real
+     * directory before creation, and to prove the created child is one too.
+     *
+     * Errors propagate to the creator; an unresolved entry must not be reported
+     * as a valid directory.
+     *
+     * @evidence contracts/common.md#principled-implementation A link-preserving observation exposes the entry's directory kind, so the creator can reject a terminal link rather than accepting the kind of its target.
+     * @evidence contracts/common.md#clear-and-simple-design The returned isDirectory predicate supplies exactly the kind check the preflight and postflight need; path resolution remains the separate realpath operation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Injected stat must describe the actual entry and propagate failure rather than supplying a synthetic positive directory result to satisfy validation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose names both checks, link preservation and error effects, with a blank line before method acknowledgments under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Implementations use native link-preserving stat semantics, including junction/reparse entries, rather than inferring directory kind from separators or filename suffixes.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lstat declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lstat declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lstat declares a signature only; the implementation owns any shared work.
+     */
+    lstat(location: string): {
+        isDirectory(): boolean;
+    };
+    /**
+     * Create a unique directory whose native path starts with `prefix`.
+     *
+     * The prefix already includes the pinned physical parent. Return the created
+     * path and propagate allocation failure; the creator checks containment and
+     * directory kind before authorizing its use.
+     *
+     * @evidence contracts/common.md#principled-implementation Unique-directory allocation appends a distinguishing suffix to the supplied native prefix; returning the created path gives postflight validation its actual subject.
+     * @evidence contracts/common.md#clear-and-simple-design This primitive owns allocation only; parent identity, allowed prefix shape and postflight checks remain with the creator.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A successful call must allocate an actual unique directory rather than return a fixed known path or fabricate success after an allocation error.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the parent-bearing prefix, returned path, failure propagation and postflight ownership, with separate method tags under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation The prefix is a native path assembled by the creator and consumed by a filesystem allocation API; no shell syntax, fixed temporary root or OS-specific suffix is required by the signature.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources mkdtemp declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms mkdtemp declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work mkdtemp declares a signature only; the implementation owns any shared work.
+     */
+    mkdtemp(prefix: string): string;
+    /**
+     * Physical path of an existing entry. Must expand every alias (symlinks,
+     * junctions, Windows 8.3 names), because the returned spelling is what later
+     * writes and recursive cleanup are anchored to.
+     *
+     * Missing or inaccessible paths must fail instead of returning a guessed
+     * physical spelling.
+     *
+     * @evidence contracts/common.md#principled-implementation Resolving an existing entry to its physical path removes mutable lexical aliases before the creator compares parent and child locations; the returned spelling must correspond to the observed filesystem entry.
+     * @evidence contracts/common.md#clear-and-simple-design Physical spelling is one primitive result; the creator owns when to resolve and how to compare containment instead of asking this operation to enforce temporary-directory policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts All aliases must be resolved through supported native semantics, not replaced with an assumed parent or fixture-specific canonical name when resolution fails.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains alias expansion, later write/cleanup anchoring and failure meaning, with separated method acknowledgments under the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native physical resolution includes Windows short-name and junction aliases as well as symlinks; manual separator normalization or lowercase conversion cannot substitute for this boundary.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources realpath declares a signature only; the implementation owns acquisition and release of resources.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms realpath declares a signature only; the implementation owns the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work realpath declares a signature only; the implementation owns any shared work.
+     */
+    realpath(location: string): string;
+}

package/lib/internal/CanonicalTempDirectoryOperations.js

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

package/lib/internal/CanonicalTempDirectoryOperations.js.map

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

package/lib/internal/CompilerContextSnapshot.d.ts

@@ -0,0 +1,66 @@
+import type { ITtscCompilerContext } from "../structures/ITtscCompilerContext";
+/**
+ * Own compiler options while preserving host selectors and JSON plugin input.
+ *
+ * Construction evaluates each entry's JSON serialization once. Date and custom
+ * toJSON behavior is preserved in that captured payload; cycles and BigInt fail
+ * at capture rather than during a later plugin launch. Each adapter conversion
+ * parses defined captured JSON anew; an undefined payload stays omitted. A
+ * parsed result cannot mutate the retained string.
+ *
+ * Worker transfer sends selectors and serialized payload separately because
+ * structured cloning cannot carry the local JSON adapter method.
+ *
+ * @evidence contracts/common.md#principled-implementation Native plugin and descriptor inputs are JSON, whereas parent-side loading reads raw transform/enabled/configFile selectors; storing both preserves those distinct meanings even when custom toJSON changes the wire representation.
+ * @evidence contracts/common.md#clear-and-simple-design One snapshot owner supplies local copying and worker transfer; the extra payload channel is required because structured cloning omits local behavior while the loader still needs the original selectors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The toJSON method belongs to a newly owned adapter, not a foreign object or global patch; unsupported cyclic/BigInt payloads fail instead of being replaced with invented defaults.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain capture timing, supported JSON conversion, failure timing, private ownership and the worker distinction, following documentation paragraph and tag separation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Context path strings and environment overrides remain native inputs; own undefined environment overrides are preserved rather than being lost through JSON serialization of the whole context.
+ * @evidence contracts/performance.md#efficient-algorithms Local copies traverse context/environment fields and plugin entries, including their key text. First capture also traverses JSON input and invokes its conversion/property behavior, whose work is not bounded by output bytes alone; captured copies share immutable strings and consumers parse only requested payloads. This avoids a custom recursive object copier without asserting constant callback or conversion cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work Captured JSON strings reuse the constructor's conversion result independently of later original-input mutation. Host selectors are copied into owned, mutable adapters rather than frozen; internal consumers must preserve them. Caller-visible parsed payloads are newly allocated and do not change retained strings.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap associations do not strongly retain owned adapters. Payload strings scale with captured plugin bytes and remain reachable through adapter closures or copied transfer channels until their holders release them; no global strong history, forced reclamation deadline or payload-size cap is imposed.
+ */
+export declare class CompilerContextSnapshot {
+    /**
+     * Capture options or copy a captured context without reevaluating conversion.
+     *
+     * @evidence contracts/common.md#principled-implementation Host selectors are read before first JSON conversion and retained independently; captured entries copy the retained payload rather than executing custom conversion again.
+     * @evidence contracts/common.md#clear-and-simple-design Context spreading retains scalar options, environment copying preserves own undefined overrides, and one entry adapter owns the selector/payload distinction.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only newly owned objects receive adapters; arbitrary plugin payload remains governed by actual JSON serialization, without foreign patches or invented fallback config.
+     * @evidence contracts/common.md#meaningful-documentation The method states capture versus copying, while the enclosing native paragraphs explain JSON conversion timing and ownership consequences.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path fields remain unchanged and environment entries are copied without JSON omission; downstream native owners interpret their respective bases and name semantics.
+     * @evidence contracts/performance.md#efficient-algorithms Copying traverses context/environment own fields and plugin entries with their key text and property reads. An uncaptured entry additionally runs JSON.stringify, including input traversal and user conversion behavior; subsequent captured clones share immutable payload strings rather than repeat conversion.
+     * @evidence contracts/performance.md#reuse-equivalent-work Existing adapters reuse their WeakMap-captured payload strings without reevaluating user conversion. Selectors are copied from the supplied adapter at this call, so preserving internal adapter selectors is a consumer premise rather than an enforced freeze.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned context initially owns new adapter references; an independently retained adapter or payload channel can extend its string lifetime. Weak associations impose no strong historical retention, and reclamation depends on holders dropping their references rather than a disposal hook here.
+     */
+    static clone(context: ITtscCompilerContext): ITtscCompilerContext;
+    /**
+     * JSON payload channel paired by index with worker context selectors.
+     *
+     * @evidence contracts/common.md#principled-implementation Index-preserving mapping keeps each captured JSON payload paired with the same entry whose host selectors the worker clones.
+     * @evidence contracts/common.md#clear-and-simple-design Only payload strings cross this channel; compiler options remain in the ordinary context channel and local behavior is restored by one owner.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual captured JSON is transmitted, without fabricating clone-compatible substitutes for plugin values.
+     * @evidence contracts/common.md#meaningful-documentation The native description explains pairing and worker transfer purpose; the enclosing comment documents why structured cloning needs a separate channel.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This maps captured JSON strings and performs no native path, environment or process interpretation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms Mapping captured entries costs O(N) reference operations for N entries. Uncaptured entries run JSON.stringify with input traversal, output bytes and user conversion work; only captured strings avoid that serialization traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Retained payload strings preserve the constructor's conversion outcome across worker calls; uncaptured direct internal inputs are serialized once for this transfer.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned string array transfers to the caller; this method acquires no independent retained population or native resource.
+     */
+    static serializePlugins(context: ITtscCompilerContext): (string | undefined)[] | undefined;
+    /**
+     * Restore local adapters after the worker cloned selectors and payloads.
+     *
+     * @evidence contracts/common.md#principled-implementation Equal-length arrays establish one payload per selector entry; restored adapters expose the captured JSON result without reevaluating user conversion in the worker.
+     * @evidence contracts/common.md#clear-and-simple-design Restoration owns only the transfer seam and delegates ordinary uncaptured contexts to clone; malformed pairing fails at that boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Pairing failures throw a protocol error rather than inventing defaults; adapter methods belong solely to newly owned objects.
+     * @evidence contracts/common.md#meaningful-documentation Native wording identifies worker restoration and links it to the class's capture and transfer semantics, with prose and tags separated.
+     * @evidence contracts/portability.md#os-neutral-implementation Native option spellings and own undefined environment entries survive restoration unchanged; the worker's separate environment adoption remains the native-name owner.
+     * @evidence contracts/performance.md#efficient-algorithms With a supplied paired channel, one indexed pass builds N adapters and copies context/environment fields plus their key text; payload bytes are parsed when consumers request JSON. Without a channel, clone may capture uncaptured entries and incur their JSON traversal/conversion work.
+     * @evidence contracts/performance.md#reuse-equivalent-work Rehydration reuses the caller's captured conversion rather than recomputing custom behavior in another environment.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Restored contexts and any separately retained adapters hold their configured payload strings while reachable. Weak associations do not globally keep completed contexts alive; this method enforces no request-end reclamation or payload-size bound.
+     */
+    static restorePlugins(context: ITtscCompilerContext, serializedPlugins: readonly (string | undefined)[] | undefined): ITtscCompilerContext;
+}

package/lib/internal/CompilerContextSnapshot.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompilerContextSnapshot = void 0;
+/**
+ * Own compiler options while preserving host selectors and JSON plugin input.
+ *
+ * Construction evaluates each entry's JSON serialization once. Date and custom
+ * toJSON behavior is preserved in that captured payload; cycles and BigInt fail
+ * at capture rather than during a later plugin launch. Each adapter conversion
+ * parses defined captured JSON anew; an undefined payload stays omitted. A
+ * parsed result cannot mutate the retained string.
+ *
+ * Worker transfer sends selectors and serialized payload separately because
+ * structured cloning cannot carry the local JSON adapter method.
+ *
+ * @evidence contracts/common.md#principled-implementation Native plugin and descriptor inputs are JSON, whereas parent-side loading reads raw transform/enabled/configFile selectors; storing both preserves those distinct meanings even when custom toJSON changes the wire representation.
+ * @evidence contracts/common.md#clear-and-simple-design One snapshot owner supplies local copying and worker transfer; the extra payload channel is required because structured cloning omits local behavior while the loader still needs the original selectors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The toJSON method belongs to a newly owned adapter, not a foreign object or global patch; unsupported cyclic/BigInt payloads fail instead of being replaced with invented defaults.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain capture timing, supported JSON conversion, failure timing, private ownership and the worker distinction, following documentation paragraph and tag separation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Context path strings and environment overrides remain native inputs; own undefined environment overrides are preserved rather than being lost through JSON serialization of the whole context.
+ * @evidence contracts/performance.md#efficient-algorithms Local copies traverse context/environment fields and plugin entries, including their key text. First capture also traverses JSON input and invokes its conversion/property behavior, whose work is not bounded by output bytes alone; captured copies share immutable strings and consumers parse only requested payloads. This avoids a custom recursive object copier without asserting constant callback or conversion cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work Captured JSON strings reuse the constructor's conversion result independently of later original-input mutation. Host selectors are copied into owned, mutable adapters rather than frozen; internal consumers must preserve them. Caller-visible parsed payloads are newly allocated and do not change retained strings.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap associations do not strongly retain owned adapters. Payload strings scale with captured plugin bytes and remain reachable through adapter closures or copied transfer channels until their holders release them; no global strong history, forced reclamation deadline or payload-size cap is imposed.
+ */
+class CompilerContextSnapshot {
+    /**
+     * Capture options or copy a captured context without reevaluating conversion.
+     *
+     * @evidence contracts/common.md#principled-implementation Host selectors are read before first JSON conversion and retained independently; captured entries copy the retained payload rather than executing custom conversion again.
+     * @evidence contracts/common.md#clear-and-simple-design Context spreading retains scalar options, environment copying preserves own undefined overrides, and one entry adapter owns the selector/payload distinction.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only newly owned objects receive adapters; arbitrary plugin payload remains governed by actual JSON serialization, without foreign patches or invented fallback config.
+     * @evidence contracts/common.md#meaningful-documentation The method states capture versus copying, while the enclosing native paragraphs explain JSON conversion timing and ownership consequences.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path fields remain unchanged and environment entries are copied without JSON omission; downstream native owners interpret their respective bases and name semantics.
+     * @evidence contracts/performance.md#efficient-algorithms Copying traverses context/environment own fields and plugin entries with their key text and property reads. An uncaptured entry additionally runs JSON.stringify, including input traversal and user conversion behavior; subsequent captured clones share immutable payload strings rather than repeat conversion.
+     * @evidence contracts/performance.md#reuse-equivalent-work Existing adapters reuse their WeakMap-captured payload strings without reevaluating user conversion. Selectors are copied from the supplied adapter at this call, so preserving internal adapter selectors is a consumer premise rather than an enforced freeze.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned context initially owns new adapter references; an independently retained adapter or payload channel can extend its string lifetime. Weak associations impose no strong historical retention, and reclamation depends on holders dropping their references rather than a disposal hook here.
+     */
+    static clone(context) {
+        return {
+            ...context,
+            env: context.env ? { ...context.env } : undefined,
+            plugins: Array.isArray(context.plugins)
+                ? context.plugins.map((entry) => {
+                    const selectors = {
+                        enabled: entry.enabled,
+                        transform: entry.transform,
+                        ...(typeof entry.configFile === "string"
+                            ? { configFile: entry.configFile }
+                            : {}),
+                    };
+                    const payload = payloads.has(entry)
+                        ? payloads.get(entry)
+                        : JSON.stringify(entry);
+                    return ownedPlugin(selectors, payload);
+                })
+                : context.plugins,
+        };
+    }
+    /**
+     * JSON payload channel paired by index with worker context selectors.
+     *
+     * @evidence contracts/common.md#principled-implementation Index-preserving mapping keeps each captured JSON payload paired with the same entry whose host selectors the worker clones.
+     * @evidence contracts/common.md#clear-and-simple-design Only payload strings cross this channel; compiler options remain in the ordinary context channel and local behavior is restored by one owner.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual captured JSON is transmitted, without fabricating clone-compatible substitutes for plugin values.
+     * @evidence contracts/common.md#meaningful-documentation The native description explains pairing and worker transfer purpose; the enclosing comment documents why structured cloning needs a separate channel.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This maps captured JSON strings and performs no native path, environment or process interpretation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms Mapping captured entries costs O(N) reference operations for N entries. Uncaptured entries run JSON.stringify with input traversal, output bytes and user conversion work; only captured strings avoid that serialization traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Retained payload strings preserve the constructor's conversion outcome across worker calls; uncaptured direct internal inputs are serialized once for this transfer.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned string array transfers to the caller; this method acquires no independent retained population or native resource.
+     */
+    static serializePlugins(context) {
+        return Array.isArray(context.plugins)
+            ? context.plugins.map((entry) => payloads.has(entry) ? payloads.get(entry) : JSON.stringify(entry))
+            : undefined;
+    }
+    /**
+     * Restore local adapters after the worker cloned selectors and payloads.
+     *
+     * @evidence contracts/common.md#principled-implementation Equal-length arrays establish one payload per selector entry; restored adapters expose the captured JSON result without reevaluating user conversion in the worker.
+     * @evidence contracts/common.md#clear-and-simple-design Restoration owns only the transfer seam and delegates ordinary uncaptured contexts to clone; malformed pairing fails at that boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Pairing failures throw a protocol error rather than inventing defaults; adapter methods belong solely to newly owned objects.
+     * @evidence contracts/common.md#meaningful-documentation Native wording identifies worker restoration and links it to the class's capture and transfer semantics, with prose and tags separated.
+     * @evidence contracts/portability.md#os-neutral-implementation Native option spellings and own undefined environment entries survive restoration unchanged; the worker's separate environment adoption remains the native-name owner.
+     * @evidence contracts/performance.md#efficient-algorithms With a supplied paired channel, one indexed pass builds N adapters and copies context/environment fields plus their key text; payload bytes are parsed when consumers request JSON. Without a channel, clone may capture uncaptured entries and incur their JSON traversal/conversion work.
+     * @evidence contracts/performance.md#reuse-equivalent-work Rehydration reuses the caller's captured conversion rather than recomputing custom behavior in another environment.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Restored contexts and any separately retained adapters hold their configured payload strings while reachable. Weak associations do not globally keep completed contexts alive; this method enforces no request-end reclamation or payload-size bound.
+     */
+    static restorePlugins(context, serializedPlugins) {
+        if (serializedPlugins === undefined)
+            return this.clone(context);
+        if (!Array.isArray(context.plugins) ||
+            context.plugins.length !== serializedPlugins.length)
+            throw new Error("ttsc: compiler plugin snapshot transfer is inconsistent");
+        return {
+            ...context,
+            env: context.env ? { ...context.env } : undefined,
+            plugins: context.plugins.map((entry, index) => ownedPlugin(entry, serializedPlugins[index])),
+        };
+    }
+}
+exports.CompilerContextSnapshot = CompilerContextSnapshot;
+const payloads = new WeakMap();
+/** Parent-side selectors stay separate from plugin-owned JSON representation. */
+function ownedPlugin(entry, payload) {
+    const owned = {
+        enabled: entry.enabled,
+        transform: entry.transform,
+        ...(typeof entry.configFile === "string"
+            ? { configFile: entry.configFile }
+            : {}),
+    };
+    Object.defineProperty(owned, "toJSON", {
+        value: () => (payload === undefined ? undefined : JSON.parse(payload)),
+    });
+    payloads.set(owned, payload);
+    return owned;
+}
+//# sourceMappingURL=CompilerContextSnapshot.js.map

package/lib/internal/CompilerContextSnapshot.js.map

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

package/lib/internal/CompilerResultAdapter.d.ts

@@ -0,0 +1,129 @@
+import type { ITtscCompilerResult } from "../structures/ITtscCompilerResult";
+import type { ITtscCompilerTransformation } from "../structures/ITtscCompilerTransformation";
+import type { TtscBuildResult } from "../structures/internal/TtscBuildResult";
+/**
+ * The compile producer's actual output and build outcome, before API
+ * adaptation. Common: Principled implementation: This input retains output and
+ * build outcome as separate producer-owned values. Common: Clear and simple
+ * design: Two named fields carry the existing compile adapter boundary without
+ * a second output representation. Common: Prohibited implementation shortcuts:
+ * The type does not supply native output or certify an authored record as a
+ * compiler product. Common: Meaningful documentation: The native sentence
+ * distinguishes the producer boundary from API result adaptation.
+ */
+interface ProjectResult {
+    output: Record<string, string>;
+    result: TtscBuildResult;
+}
+/**
+ * The transform producer's source records and optional advisory observations.
+ * Common: Principled implementation: Optional fields retain the producer's
+ * absent-versus-present observations independently of build status. Common:
+ * Clear and simple design: One input shape carries source, build and advisory
+ * values to the same result adapter. Common: Prohibited implementation
+ * shortcuts: The representation does not invent host reads, graph membership or
+ * compiler completeness. Common: Meaningful documentation: The native sentence
+ * identifies the actual producer-owned fields and optionality.
+ */
+interface ProjectTransformation {
+    dependencies?: Record<string, string[]>;
+    dependenciesComplete?: string[];
+    graph?: ITtscCompilerTransformation.IReferenceGraph;
+    hostInputHashes?: Record<string, string | null>;
+    hostInputProofFailures?: Record<string, "observation-unavailable">;
+    hostInputRealpaths?: Record<string, string | null>;
+    hostInputs?: string[];
+    observationsComplete?: false;
+    pluginSources?: Record<string, string>;
+    result: TtscBuildResult;
+    sourceMaps?: Record<string, ITtscCompilerTransformation.ISourceMap>;
+    typescript: Record<string, string>;
+    volatile?: string[];
+}
+/**
+ * Run the selected compile task once and adapt its returned or thrown outcome.
+ *
+ * @evidence contracts/common.md#principled-implementation The original task runs once; its output/status/diagnostics or thrown error determine the public result kind.
+ * @evidence contracts/common.md#clear-and-simple-design One try/catch joins the task owner with the existing compile and exception adapters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No native task, output or error is substituted; caught values retain the existing serialization and classification policy.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence states exact invocation and returned/thrown ownership.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The task owner chooses native files/processes; this boundary chooses only result adaptation and no independent platform policy.
+ * @evidence contracts/performance.md#efficient-algorithms Cost includes the arbitrary selected task, diagnostic scan and any process-diagnostic construction or error serialization/classification; the fixed envelope does not bound those costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter coordinates no reusable native producer or cached outcome.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned producer references transfer to the caller; task resources and their lifetime remain with the task owner.
+ */
+export declare function runProject(task: () => ProjectResult): ITtscCompilerResult;
+/**
+ * Run the selected transform task once, preserving its optional observations.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful and failed build outcomes retain source/advisory values while thrown outcomes use the existing exception policy.
+ * @evidence contracts/common.md#clear-and-simple-design One try/catch invokes the selected task and delegates to the transform result adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter neither reconstructs native observations nor replaces the actual task with a result certificate.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence distinguishes selected execution from its observation adaptation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The task owns its native platform boundaries; this function selects no path, process or filesystem policy.
+ * @evidence contracts/performance.md#efficient-algorithms The task cost is delegated in full, followed by diagnostic scanning, fixed optional-field projection and exceptional serialization/classification when needed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No completed or in-flight transform is cached by this adapter.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned source/advisory references remain caller-owned; the task owns native resource acquisition and retirement.
+ */
+export declare function runTransformation(task: () => ProjectTransformation): ITtscCompilerTransformation;
+/**
+ * Best-effort classifier for the `kind` field of `IException`. Pattern- matches
+ * the real prefixes thrown inside this package:
+ *
+ * - Plugin: messages from `loadProjectPlugins.ts` / `buildSourcePlugin.ts` start
+ *   with `ttsc: plugin "..."` or `ttsc: package "..." declares ...`, and
+ *   transform-time spawn failures start with `ttsc.transform:` /
+ *   `ttsc.transform.check:`. The Go-toolchain missing envelope also surfaces
+ *   here.
+ * - Host: everything else under the `ttsc:` umbrella — the bare `ttsc:` strings
+ *   from `packageRootDir.ts`, `ttsc: TypeScript-Go executable not found`
+ *   (`resolveTsgo.ts`), `ttsc: failed to spawn native compiler host`
+ *   (`transformProjectInMemory.ts`), and tsconfig / extended-tsconfig shapes
+ *   from `readProjectConfig.ts`.
+ * - Anything else falls back to `"unknown"` so embedders always see the field set
+ *   per the documented contract.
+ *
+ * Order matters: plugin patterns must run before the generic `ttsc:` test
+ * because every plugin message also starts with `ttsc:`.
+ */
+/**
+ * Classify the observed message using the existing plugin-before-host patterns.
+ *
+ * @evidence contracts/common.md#principled-implementation Original plugin-prefix precedence and host fallback are retained; unreadable message inspection yields unknown.
+ * @evidence contracts/common.md#clear-and-simple-design One guarded message extraction precedes the two existing pattern groups.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification is best-effort message policy, not a certificate of exception origin or native process ownership.
+ * @evidence contracts/common.md#meaningful-documentation The adjacent native paragraphs describe actual prefix shapes, ordering and unknown fallback.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Message matching inspects no filesystem, executable or native platform capability.
+ * @evidence contracts/performance.md#efficient-algorithms Message inspection can invoke existing Error property behavior; pattern work visits selected message text and extraction failures return unknown. Message size is not bounded here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Classification coordinates no reusable operation or outcome cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned kind is retained by callers; this operation acquires no resource or registry.
+ */
+export declare function classifyException(error: unknown): "plugin" | "host" | "unknown";
+/**
+ * Adapt source/build outcome and copy optional advisory references only when
+ * present.
+ *
+ * @evidence contracts/common.md#principled-implementation Undefined advisory fields are omitted; present empty/false values and references survive both success and failure, alongside the existing diagnostic decision.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-field projection is shared by the two result branches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter does not manufacture graph, host-read or completeness proof and does not discard it solely because the build failed.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence states omission policy and reference ownership.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Advisory values are passed through without native path normalization or capability inference.
+ * @evidence contracts/performance.md#efficient-algorithms Fixed optional-field checks retain references without scanning map text; diagnostic classification and empty-failure formatting have their delegated data costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adaptation coordinates no reusable compiler/worker or outcome cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned source/advisory objects remain reachable under caller ownership; this operation owns no process, lease or historical registry.
+ */
+export declare function toCompilerTransformation(project: ProjectTransformation): ITtscCompilerTransformation;
+/**
+ * Serialize the actual thrown value through the existing compiler error owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The original serializer receives the exact thrown value rather than a guessed error message.
+ * @evidence contracts/common.md#clear-and-simple-design One delegation shares the compiler error representation with synchronous and worker result adapters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Serialization does not manufacture a native exception or replace the task that threw it.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence names the actual value and owning serializer.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The error representation owner inspects data rather than native platform capability.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The existing serializer owns value traversal, reference tracking and encoded allocation; this adapter adds no independent serialization algorithm or size bound.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This call coordinates no reusable producer or previous serialized result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned serialized data transfers to the caller; traversal state and exceptional value inspection remain with the serializer owner.
+ */
+export declare function normalizeError(error: unknown): unknown;
+export {};