ttsc 0.30.3 → 0.31.0

package/lib/compiler/internal/spawnNative.js

@@ -1,42 +1,44 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.spawnNative = spawnNative;
-exports.ensureExecutable = ensureExecutable;
-exports.outputText = outputText;
-const node_child_process_1 = require("node:child_process");
-const node_fs_1 = __importDefault(require("node:fs"));
+const spawnSyncResilient_1 = require("../../internal/spawnSyncResilient");
 const captureProcessOutput_1 = require("./captureProcessOutput");
+const ensureExecutable_1 = require("./ensureExecutable");
 /**
  * Spawn a native binary (or a Node.js script when the path has a JS/TS
- * extension) and return its result with `stdout` and `stderr` as text.
+ * extension) and return its result with decoded or raw-buffer output streams.
  *
- * The child's streams are written to files rather than piped, and the files are
- * read once it exits. `spawnSync` buffers a _piped_ stream in this process's
- * memory and refuses to hold more than `maxBuffer` bytes, so a piped capture
- * has to name a ceiling — and any ceiling is a number nobody chose for this
- * machine, deciding that a large but legitimate compile said too much. A file
- * has no such limit: the bytes never pass through this heap on their way out of
- * the child, and how many there may be is the filesystem's business.
+ * Streams go to private files and are materialized after exit, avoiding the
+ * piped maxBuffer ceiling while retaining filesystem and runtime allocation
+ * limits. Filesystem read failures propagate after capture cleanup.
  *
  * When `options.encoding` is omitted it defaults to `"utf8"`. Pass `"buffer"`
  * when the caller needs raw bytes.
+ *
+ * @evidence contracts/common.md#principled-implementation Executable plus argv are passed directly to Node spawning; script candidates instead pass their path to process.execPath, and file-backed output reconstructs the normal stdout/stderr/output result fields.
+ * @evidence contracts/common.md#clear-and-simple-design This operation owns synchronous execution and capture lifetime; permission preparation, low-descriptor recovery and byte decoding remain explicit delegated boundaries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No shell parses argv or foreign process API is replaced. Descriptor recovery is selected by the real resource-exhaustion contract in spawnSyncResilient rather than a fixture outcome.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain executable routing, capture limits, read errors and encoding ownership following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node receives native executable and argument arrays, Windows hiding is an explicit process option, and POSIX permission preparation remains in ensureExecutable rather than shell-specific commands.
+ * @evidence contracts/performance.md#efficient-algorithms Argument-reference copying costs O(A); native argv/environment launch work, permission checks, capture acquisition and any broker retry/report costs are delegated but remain part of this call. Reads/decoding allocate complete output proportional to B child bytes. Each stream is read once after synchronous completion; neither output size nor child duration is capped here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A child execution may have effects and depend on arbitrary filesystem state; this wrapper has no equivalence or invalidation contract permitting reuse of a previous process result.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources An acquired capture reaches finally on spawn, recovery and read failures; acquisition has its own rollback attempts. Disposal attempts closure/removal with suppressed failures, so native release is not certified. Materialized output transfers to the caller, and capture/returned bytes grow without a configured ceiling; no timeout or descendant-join policy is supplied here.
  */
 function spawnNative(binary, args, options) {
     const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
     if (!viaNode) {
-        ensureExecutable(binary);
+        (0, ensureExecutable_1.ensureExecutable)(binary);
     }
     const capture = (0, captureProcessOutput_1.captureProcessOutput)();
     try {
-        const result = (0, node_child_process_1.spawnSync)(viaNode ? process.execPath : binary, viaNode ? [binary, ...args] : [...args], {
+        const result = (0, spawnSyncResilient_1.spawnSyncResilient)(viaNode ? process.execPath : binary, viaNode ? [binary, ...args] : [...args], {
             cwd: options.cwd,
             env: options.env,
             stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
             windowsHide: true,
-        });
+        }, { stderr: capture.stderrPath, stdout: capture.stdoutPath });
         const stdout = capture.read("stdout", options.encoding);
         const stderr = capture.read("stderr", options.encoding);
         return {
@@ -50,34 +52,4 @@ function spawnNative(binary, args, options) {
         capture.dispose();
     }
 }
-/**
- * Ensure the binary has the executable bit set on POSIX systems. Silently skips
- * on Windows and swallows `chmod` errors to let the original spawn error
- * surface instead of masking it with a permission error.
- */
-function ensureExecutable(binary) {
-    if (process.platform === "win32") {
-        return;
-    }
-    try {
-        node_fs_1.default.accessSync(binary, node_fs_1.default.constants.X_OK);
-        return;
-    }
-    catch {
-        try {
-            const mode = node_fs_1.default.statSync(binary).mode & 0o777;
-            node_fs_1.default.chmodSync(binary, mode | 0o755);
-        }
-        catch {
-            /* keep the original spawn error path */
-        }
-    }
-}
-/** Coerce a `spawnSync` output value to a plain string, defaulting to `""`. */
-function outputText(value) {
-    if (value == null) {
-        return "";
-    }
-    return typeof value === "string" ? value : value.toString("utf8");
-}
 //# sourceMappingURL=spawnNative.js.map

package/lib/compiler/internal/spawnNative.js.map

@@ -1 +1 @@
-{"version":3,"file":"spawnNative.js","sourceRoot":"","sources":["../../../src/compiler/internal/spawnNative.ts"],"names":[],"mappings":";;;;;;;;AAAA,2DAAsE;AACtE,sDAAyB;AAEzB,iEAA8D;AAE9D;;;;;;;;;;;;;;GAcG;AACH,qBACE,MAAc,EACd,IAAuB,EACvB,OAIC;IAED,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,2CAAoB,GAAE,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,8BAAS,EACtB,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EACnC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EACvC;YACE,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YACrD,WAAW,EAAE,IAAI;SAClB,CACF,CAAC;QACF,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,OAAO;YACL,GAAG,MAAM;YACT,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;YAC9B,MAAM;YACN,MAAM;SAC8B,CAAC;IACzC,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,0BAAiC,MAAc;IAC7C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,iBAAE,CAAC,UAAU,CAAC,MAAM,EAAE,iBAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,iBAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;YAC9C,iBAAE,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,wCAAwC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,oBAA2B,KAAyC;IAClE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"spawnNative.js","sourceRoot":"","sources":["../../../src/compiler/internal/spawnNative.ts"],"names":[],"mappings":";;;AAEA,0EAAuE;AACvE,iEAA8D;AAC9D,yDAAsD;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACE,MAAc,EACd,IAAuB,EACvB,OAIC;IAED,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,IAAA,mCAAgB,EAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,2CAAoB,GAAE,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,uCAAkB,EAC/B,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EACnC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EACvC;YACE,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YACrD,WAAW,EAAE,IAAI;SAClB,EACD,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,CAC3D,CAAC;QACF,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,OAAO;YACL,GAAG,MAAM;YACT,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;YAC9B,MAAM;YACN,MAAM;SAC8B,CAAC;IACzC,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC;AACH,CAAC"}

package/lib/compiler/internal/startResidentTransform.d.ts

@@ -1,26 +1,35 @@
 import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
-import { ResidentTransformProcess } from "./residentTransformProcess";
-/**
- * A started resident transform host plus the project root its keys are relative
- * to.
- */
-export interface StartedResidentTransform {
-    process: ResidentTransformProcess;
-    projectRoot: string;
-}
+import type { StartedResidentTransform } from "./StartedResidentTransform";
 /**
  * Start a resident `serve` host for the configured project.
  *
  * Mirrors the plugin spawn of `transformProjectInMemory`, but launches the
  * shared host's `serve` subcommand as one long-lived process instead of a
- * per-call `transform` subprocess. The host compiles the whole project once at
- * startup and then answers per-file requests, so one caller pays the project
- * compile once and reuses it across its own per-file requests.
+ * per-call `transform` subprocess. The serve protocol lets the host load a
+ * project and answer repeated per-file requests within one process. This
+ * function returns the client after spawning; it does not wait for successful
+ * initial compilation or certify the custom host's internal caching strategy.
+ *
+ * The project must contain a transform-stage plugin. Linked-only projects use
+ * the generated `cmd/utility-host`, which implements `serve`; a selected custom
+ * executable transform owner must implement that same protocol. Check-stage
+ * plugins are not run by this resident lane.
+ *
+ * The returned process transfers to the caller, which must dispose it. Startup
+ * fixes the project and plugins; replacing that configuration requires a new
+ * host rather than reusing a process built for the previous selection.
  *
- * Resident mode runs through the linked-plugin shared host
- * (`cmd/utility-host`), which is the only binary that exposes `serve`. It
- * therefore requires at least one transform-stage plugin; executable transform
- * hosts that own their own process are not served and must use the per-call
- * transform path. Check-stage plugins are not run by the resident host.
+ * @param context Project/plugin selection, environment and executable anchors.
+ * @returns A resident client and the project root passed to its native host.
+ * @throws On synchronous setup failures or an unsupported plugin population.
+ *   Asynchronous spawn, compilation and transport failures reach the client.
+ * @evidence contracts/common.md#principled-implementation The configured transform population selects one compatible compiler owner, and its serve protocol owns project-relative replies; linked libraries execute within that owner's Program, while custom executable owners must supply the same protocol.
+ * @evidence contracts/common.md#clear-and-simple-design Startup resolves project, plugin ownership, compiler and environment before acquiring the child, then returns the process together with its project anchor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing transforms and conflicting executable owners are setup errors; the selected host is not guessed from a plugin name or rescued through a different compiler after an incompatible selection.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs document startup reuse, host protocol requirements, ignored check plugins and mandatory caller disposal following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution anchors cwd and config, environment composition uses native name identity, and process startup passes argv separately without shell quoting.
+ * @evidence contracts/performance.md#efficient-algorithms Filtering and plugin projection visit P entries and JSON encoding costs their data bytes. Project reads, loader discovery/source builds, compiler package lookup and Node capability resolution have delegated native costs; environment merge/encoding costs its key/value bytes. One resident child serves later requests without this adapter spawning a new transform per file, but initial readiness and host work remain protocol-owned.
+ * @evidence contracts/performance.md#reuse-equivalent-work The returned fixed-project process is shared across requests rather than caching responses in this adapter; the serve producer owns transformed-text state and update semantics. A changed startup selection requires a new host, and custom host correctness is a protocol requirement rather than an observed guarantee here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Configuration/environment preparation precedes resident child acquisition; the caller receives the cleanup obligation. Client retirement closes pipes, rejects pending calls and attempts signals with a grace timer, but does not await child close or guarantee termination when OS signaling fails. Pending calls, line data and active host duration have no configured ceiling here; delegated preparatory child/artifact lifetimes remain with their owners.
  */
 export declare function startResidentTransform(context: ITtscCompilerContext): StartedResidentTransform;

package/lib/compiler/internal/startResidentTransform.js

@@ -6,26 +6,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.startResidentTransform = startResidentTransform;
 const node_path_1 = __importDefault(require("node:path"));
 const resolveNodeBinary_1 = require("../../internal/resolveNodeBinary");
-const loadProjectPlugins_1 = require("../../plugin/internal/loadProjectPlugins");
+const loadProjectPlugins_1 = require("../../plugin/internal/load/loadProjectPlugins");
+const ResidentTransformProcess_1 = require("./ResidentTransformProcess");
 const readProjectConfig_1 = require("./project/readProjectConfig");
-const residentTransformProcess_1 = require("./residentTransformProcess");
 const resolveBinary_1 = require("./resolveBinary");
 const resolveTsgo_1 = require("./resolveTsgo");
-const sharedHostHelpers_1 = require("./sharedHostHelpers");
+const SidecarEnvironment_1 = require("./sharedHost/SidecarEnvironment");
+const assertSharedHostCompatibility_1 = require("./sharedHost/assertSharedHostCompatibility");
+const clearInheritedSemanticConfigPath_1 = require("./sharedHost/clearInheritedSemanticConfigPath");
+const clearInheritedTsgoArgs_1 = require("./sharedHost/clearInheritedTsgoArgs");
+const inheritedSidecarEnv_1 = require("./sharedHost/inheritedSidecarEnv");
+const linkedTransformPlugins_1 = require("./sharedHost/linkedTransformPlugins");
+const publishLinkedTransformPlugins_1 = require("./sharedHost/publishLinkedTransformPlugins");
+const resolvePluginConfigDir_1 = require("./sharedHost/resolvePluginConfigDir");
+const selectSharedHostPlugin_1 = require("./sharedHost/selectSharedHostPlugin");
 /**
  * Start a resident `serve` host for the configured project.
  *
  * Mirrors the plugin spawn of `transformProjectInMemory`, but launches the
  * shared host's `serve` subcommand as one long-lived process instead of a
- * per-call `transform` subprocess. The host compiles the whole project once at
- * startup and then answers per-file requests, so one caller pays the project
- * compile once and reuses it across its own per-file requests.
+ * per-call `transform` subprocess. The serve protocol lets the host load a
+ * project and answer repeated per-file requests within one process. This
+ * function returns the client after spawning; it does not wait for successful
+ * initial compilation or certify the custom host's internal caching strategy.
  *
- * Resident mode runs through the linked-plugin shared host
- * (`cmd/utility-host`), which is the only binary that exposes `serve`. It
- * therefore requires at least one transform-stage plugin; executable transform
- * hosts that own their own process are not served and must use the per-call
- * transform path. Check-stage plugins are not run by the resident host.
+ * The project must contain a transform-stage plugin. Linked-only projects use
+ * the generated `cmd/utility-host`, which implements `serve`; a selected custom
+ * executable transform owner must implement that same protocol. Check-stage
+ * plugins are not run by this resident lane.
+ *
+ * The returned process transfers to the caller, which must dispose it. Startup
+ * fixes the project and plugins; replacing that configuration requires a new
+ * host rather than reusing a process built for the previous selection.
+ *
+ * @param context Project/plugin selection, environment and executable anchors.
+ * @returns A resident client and the project root passed to its native host.
+ * @throws On synchronous setup failures or an unsupported plugin population.
+ *   Asynchronous spawn, compilation and transport failures reach the client.
+ * @evidence contracts/common.md#principled-implementation The configured transform population selects one compatible compiler owner, and its serve protocol owns project-relative replies; linked libraries execute within that owner's Program, while custom executable owners must supply the same protocol.
+ * @evidence contracts/common.md#clear-and-simple-design Startup resolves project, plugin ownership, compiler and environment before acquiring the child, then returns the process together with its project anchor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing transforms and conflicting executable owners are setup errors; the selected host is not guessed from a plugin name or rescued through a different compiler after an incompatible selection.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs document startup reuse, host protocol requirements, ignored check plugins and mandatory caller disposal following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution anchors cwd and config, environment composition uses native name identity, and process startup passes argv separately without shell quoting.
+ * @evidence contracts/performance.md#efficient-algorithms Filtering and plugin projection visit P entries and JSON encoding costs their data bytes. Project reads, loader discovery/source builds, compiler package lookup and Node capability resolution have delegated native costs; environment merge/encoding costs its key/value bytes. One resident child serves later requests without this adapter spawning a new transform per file, but initial readiness and host work remain protocol-owned.
+ * @evidence contracts/performance.md#reuse-equivalent-work The returned fixed-project process is shared across requests rather than caching responses in this adapter; the serve producer owns transformed-text state and update semantics. A changed startup selection requires a new host, and custom host correctness is a protocol requirement rather than an observed guarantee here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Configuration/environment preparation precedes resident child acquisition; the caller receives the cleanup obligation. Client retirement closes pipes, rejects pending calls and attempts signals with a grace timer, but does not await child close or guarantee termination when OS signaling fails. Pending calls, line data and active host duration have no configured ceiling here; delegated preparatory child/artifact lifetimes remain with their owners.
  */
 function startResidentTransform(context) {
     const cwd = node_path_1.default.resolve(context.cwd ?? process.cwd());
@@ -36,10 +61,11 @@ function startResidentTransform(context) {
     });
     const loaded = (0, loadProjectPlugins_1.loadProjectPlugins)({
         binary: (0, resolveBinary_1.resolveBinary)(context) ?? "",
-        cacheDir: context.cacheDir ?? context.env?.TTSC_CACHE_DIR,
+        cacheDir: context.cacheDir ??
+            SidecarEnvironment_1.SidecarEnvironment.read(context.env, "TTSC_CACHE_DIR"),
         cwd,
         entries: context.plugins,
-        env: (0, sharedHostHelpers_1.inheritedSidecarEnv)(context.env),
+        env: (0, inheritedSidecarEnv_1.inheritedSidecarEnv)(context.env, context.binary),
         pluginConfigDir: context.pluginConfigDir,
         projectRoot: context.projectRoot,
         tsconfig: project.path,
@@ -49,10 +75,10 @@ function startResidentTransform(context) {
         throw new Error("ttsc: TtscService resident mode requires at least one transform-stage plugin; " +
             "use TtscCompiler.transform for projects with only check-stage plugins or none");
     }
-    (0, sharedHostHelpers_1.assertSharedHostCompatibility)(transformers, "source-to-source");
-    const host = (0, sharedHostHelpers_1.selectSharedHostPlugin)(transformers);
+    (0, assertSharedHostCompatibility_1.assertSharedHostCompatibility)(transformers, "source-to-source");
+    const host = (0, selectSharedHostPlugin_1.selectSharedHostPlugin)(transformers);
     const tsgoBinary = (0, resolveTsgo_1.resolveTsgo)({ ...context, cwd: project.root }).binary;
-    const resident = new residentTransformProcess_1.ResidentTransformProcess({
+    const resident = new ResidentTransformProcess_1.ResidentTransformProcess({
         args: [
             "serve",
             `--tsconfig=${project.path}`,
@@ -75,38 +101,27 @@ function startResidentTransform(context) {
  * `TTSC_LINKED_PLUGINS_JSON`.
  */
 function residentEnv(context, projectRoot, tsgoBinary, nativePlugins) {
-    const pluginConfigDir = (0, sharedHostHelpers_1.resolvePluginConfigDir)(context);
-    const env = {
-        ...process.env,
+    const pluginConfigDir = (0, resolvePluginConfigDir_1.resolvePluginConfigDir)(context);
+    const env = SidecarEnvironment_1.SidecarEnvironment.merge(process.env, {
         ...(pluginConfigDir === undefined
             ? {}
             : { TTSC_PLUGIN_CONFIG_DIR: pluginConfigDir }),
-        TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? tsgoBinary,
         TTSC_TTSX_BINARY: process.env.TTSC_TTSX_BINARY ??
             node_path_1.default.join(__dirname, "..", "..", "launcher", "ttsx.js"),
-        ...context.env,
-    };
+    }, context.env, { TTSC_TSGO_BINARY: tsgoBinary });
     const node = (0, resolveNodeBinary_1.resolveNodeBinary)(env, projectRoot);
-    if (node === undefined)
-        delete env.TTSC_NODE_BINARY;
-    else
-        env.TTSC_NODE_BINARY = node;
+    SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_NODE_BINARY", node);
     // The anchor is per-invocation state owned by this host: when this run
     // declared none (and the caller's env does not name one), drop any value
     // inherited from an ancestor ttsc process so a nested build never
     // mis-anchors its plugins at the outer project.
-    if (pluginConfigDir === undefined &&
-        context.env?.TTSC_PLUGIN_CONFIG_DIR === undefined) {
-        delete env.TTSC_PLUGIN_CONFIG_DIR;
-    }
+    SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_PLUGIN_CONFIG_DIR", SidecarEnvironment_1.SidecarEnvironment.read(context.env, "TTSC_PLUGIN_CONFIG_DIR") ??
+        pluginConfigDir);
     // This lane forwards no tsgo argv of its own, so anything inherited belongs
     // to an outer ttsc run and must not reach the resident sidecar.
-    (0, sharedHostHelpers_1.clearInheritedTsgoArgs)(env, context.env);
-    (0, sharedHostHelpers_1.clearInheritedSemanticConfigPath)(env, context.env);
-    const linked = (0, sharedHostHelpers_1.linkedTransformPlugins)(nativePlugins);
-    if (linked.length !== 0) {
-        env.TTSC_LINKED_PLUGINS_JSON = serializeNativePlugins(linked);
-    }
+    (0, clearInheritedTsgoArgs_1.clearInheritedTsgoArgs)(env, context.env);
+    (0, clearInheritedSemanticConfigPath_1.clearInheritedSemanticConfigPath)(env, context.env);
+    (0, publishLinkedTransformPlugins_1.publishLinkedTransformPlugins)(env, context.env, (0, linkedTransformPlugins_1.linkedTransformPlugins)(nativePlugins));
     return env;
 }
 /**

package/lib/compiler/internal/startResidentTransform.js.map

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

package/lib/compiler/internal/transformProjectInMemory.d.ts

@@ -4,26 +4,63 @@ import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult"
 /**
  * Transform a project and capture TypeScript source output in memory.
  *
- * When no plugins are configured the fast path spawns the native ttsc compiler
- * host (`cmd/ttsc api-transform`) which returns a JSON map of transformed
- * TypeScript sources. When plugins are present:
+ * When no plugins are configured the native path spawns the native ttsc
+ * compiler host (`cmd/ttsc api-transform`) which returns a JSON map of
+ * transformed TypeScript sources. When plugins are present:
  *
- * 1. Check-stage plugins run first and abort on failure.
+ * 1. Check-stage plugins run first and stop on a nonzero accumulated status.
  * 2. If there are no transform-stage plugins the host is used as the transformer.
  * 3. If transform plugins exist they are dispatched through the shared-host binary
  *    with linked plugins passed via `TTSC_LINKED_PLUGINS_JSON`.
  *
+ * Explicit unavailable-observation reports survive every lane so consumers can
+ * use a fresh successful result while withholding reuse. They cannot excuse a
+ * content or physical witness that changed or conflicted across stages.
+ * Opted-in checks supply their same-generation observations through a private
+ * sidecar on failure as well as success. A later transform cannot restore a
+ * check's rejected proof or replace it with an unavailable-input exemption.
+ * Other check hosts retain their existing descriptor and declared-input
+ * observation contract rather than inheriting the driver's protocol.
+ *
  * @returns A `{ result, typescript }` pair where `typescript` maps output paths
- *   to their transformed TypeScript source text.
+ *   to their transformed TypeScript source text, and `pluginSources` the state
+ *   of every Go source directory the plugins supplied to their binaries.
+ * @evidence contracts/common.md#principled-implementation Discovery and check/transform stages use their owning native binaries; evaluation-time witnesses are revalidated, explicit observation limits survive every lane, and changed or conflicting proven inputs lose their unavailable exemption rather than gaining admission.
+ * @evidence contracts/common.md#clear-and-simple-design One router composes built-in and plugin-backed transforms; envelope parsers, environment construction, proof merging and negative-only observation limits have separate shared helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing input proof cannot be repaired by a postcompile baseline; conventional deferred config reads accept only the actual native consumer's proof, while malformed required TypeScript output is a protocol error.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe transform lanes and stage ordering; separated result members distinguish output, advisory graph/dependency data, evaluation witnesses and unstable source markers under documentation guidance.
+ * @evidence contracts/performance.md#efficient-algorithms Stage filtering, declared-input Sets and proof maps scale with plugin/input counts; merged paths are sorted with path-text comparison costs. Each stage can rehash/re-realpath declared inputs, serialize plugin/config records and parse complete output; discovery, native capability probes, source builds and child execution remain delegated costs of this call. No byte/work ceiling or measured dominant-cost ranking is asserted.
+ * @evidence contracts/performance.md#reuse-equivalent-work Source-plugin artifacts are shared by their owning loader; this transform intentionally produces a current generation and gives downstream consumers the graph, source states and host witnesses required to qualify reuse.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This router retains discovery records, per-stage proof maps and accumulated diagnostics/output until synchronous stage completion, then transfers the returned envelope. Native capture/observation owners attempt their own cleanup; suppressed cleanup failures and descendant release remain unconfirmed where those owners do not join them. Artifact-cache retention belongs to the builder, and no stage timeout or input/output byte ceiling is supplied here.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths remain filesystem coordinates, child argv are arrays, and environment helpers preserve Windows key equivalence and explicit Node/tsgo/config anchors without shell parsing or native method patching.
  */
 export declare function transformProjectInMemory(options: ITtscCompilerContext): {
+    /** Optional plugin-reported per-file dependencies used as advisory inputs. */
     dependencies?: Record<string, string[]>;
+    /** Files for which the producer declares dependency reporting complete. */
     dependenciesComplete?: string[];
+    /** Compiler reference graph with its independently recorded input proof. */
     graph?: ITtscCompilerTransformation.IReferenceGraph;
+    /** Evaluation-time raw-content or unavailable-state host witnesses. */
     hostInputHashes?: Record<string, string | null>;
+    /** Evaluation-time native targets under exact host-input spellings. */
     hostInputRealpaths?: Record<string, string | null>;
+    /** Explicitly unavailable observations; changed proven inputs are not excused. */
+    hostInputProofFailures?: Record<string, "observation-unavailable">;
+    /** Universal host paths whose proof downstream reuse must validate. */
     hostInputs?: string[];
+    /** Source states of Go plugins that produced this generation. */
+    pluginSources?: Record<string, string>;
+    /** False withdraws complete observation authority; absence asserts nothing. */
+    observationsComplete?: false;
+    /** Compiler diagnostics and native process outcome. */
     result: TtscBuildResult;
+    /** Optional per-output maps that refer only to returned TypeScript texts. */
+    sourceMaps?: Record<string, ITtscCompilerTransformation.ISourceMap>;
+    /** Required transformed TypeScript text under compiler output keys. */
     typescript: Record<string, string>;
+    /** Sources the producer identifies as unsuitable for stable reuse. */
     volatile?: string[];
 };