ttsc 0.30.4 → 0.31.0

package/src/compiler/internal/runNativeCheckWithObservations.ts

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import { parseReferenceGraph } from "./parseNativeTransformOutput";
+
+/**
+ * Execute a check with its same-generation input observations, preserving the
+ * selected host, original diagnostics, streams and status.
+ *
+ * The selected native verb must be check before negotiating this check-only
+ * channel. A check-stage descriptor can also serve effectful fix/format verbs;
+ * those retain their original result and never acquire an invented check graph.
+ * An opted-in host writes a private sidecar even when its check fails. Hosts
+ * without that transport run their original command under their existing
+ * descriptor and declared-input contract; omission does not assert complete
+ * driver observations. No check is rerun to infer what the earlier generation
+ * read. Missing metadata after an interrupted failed opted-in check likewise
+ * withholds reuse; missing or malformed successful metadata is a protocol
+ * error, not an empty proof.
+ *
+ * The callback receives only additional transport arguments. This operation
+ * owns their accepted canonical private directory and attempts file and empty
+ * directory removal without recursive deletion. Setup observes ownership before
+ * entering the cleanup boundary, so a setup observation failure can leave the
+ * allocation unclaimed. Cleanup failures retain the original thrown failure or
+ * completed result as their cause. Before reading and removing the artifact,
+ * the parent must still have its captured native identity; a replaced directory
+ * is left untouched and reported as failure. These observations do not provide
+ * an atomic descriptor or ABA guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation Only an actual check verb with the declared capability negotiates same-generation observations; effectful write verbs retain their own result without being projected as reusable check generations. The selected check generation's sidecar carries driver-observed input states; hosts with a different observation contract keep their original command and declared-input authority without fabricating driver completeness or incompleteness.
+ * @evidence contracts/common.md#clear-and-simple-design The actual verb and descriptor opt-in jointly select one adapter for strict wire decoding and private artifact lifetime; its callback retains command and diagnostic normalization ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Neither a later project-input query nor a separate transform can reconstruct check observations; unknown hosts receive no guessed flag and malformed metadata cannot become a complete empty observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish failed-check metadata, unavailable transport, protocol errors and cleanup ownership, with body and tags separated according to the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native absolute paths locate the canonical private artifact, and an additional argv element conveys it without shell quoting or platform-specific filename guesses.
+ * @evidence contracts/performance.md#efficient-algorithms One original check callback runs; this adapter adds canonical temp acquisition/native ownership observations, complete sidecar read/JSON decoding and indexed input membership/witness validation. Work and temporary storage follow wire/path bytes and declared inputs plus delegated check runtime; it does not add a second compiler generation or source-content rehash, and supplies no callback timeout or metadata-byte ceiling.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter supplies the generation's proof to its cache owner rather than retaining or sharing a completed check itself.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources An accepted post-setup directory/artifact reaches ownership-checked cleanup attempts on success and failure; setup ownership observation occurs before this try/finally and can leave the allocation unclaimed. A replaced parent stays untouched, and ownership/removal failures preserve the primary outcome without certifying release. Wire text and parsed/witness records grow without a metadata-byte ceiling; accepted records transfer to the caller.
+ */
+export function runNativeCheckWithObservations(
+  plugin: Pick<ITtscLoadedNativePlugin, "capabilities">,
+  run: (extraArgs: readonly string[]) => TtscBuildResult,
+  /** Actual argv verb; legacy direct callers already represent a check. */
+  command: string = "check",
+): TtscBuildResult {
+  if (command !== "check" || plugin.capabilities?.checkObservations !== true)
+    return run([]);
+
+  const directory = createCanonicalTempDirectory("ttsc-check-observations-");
+  const ownership = fs.lstatSync(directory);
+  const file = path.join(directory, "observations.json");
+  let completed: TtscBuildResult | undefined;
+  let failed = false;
+  let failure: unknown;
+  try {
+    completed = run(["--check-observations-json=" + file]);
+    if (completed.processCompletedNormally !== true)
+      return { ...completed, observationsComplete: false };
+    let text: string;
+    try {
+      assertDirectoryOwnership(directory, ownership);
+      if (!fs.lstatSync(file).isFile())
+        throw new Error("check observation artifact is not an ordinary file");
+      text = fs.readFileSync(file, "utf8");
+    } catch (error) {
+      if (
+        completed.status !== 0 &&
+        (error as NodeJS.ErrnoException).code === "ENOENT"
+      )
+        return { ...completed, observationsComplete: false };
+      throw new Error("ttsc: check observation metadata is unavailable", {
+        cause: new AggregateError([completed, error]),
+      });
+    }
+    try {
+      return { ...completed, ...parseObservations(JSON.parse(text)) };
+    } catch (error) {
+      throw new Error("ttsc: invalid check observation metadata", {
+        cause: new AggregateError([completed, error]),
+      });
+    }
+  } catch (error) {
+    failed = true;
+    failure = error;
+    throw error;
+  } finally {
+    const errors: unknown[] = [];
+    try {
+      assertDirectoryOwnership(directory, ownership);
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length === 0) {
+      try {
+        fs.rmSync(file, { force: true });
+      } catch (error) {
+        errors.push(error);
+      }
+      try {
+        fs.rmdirSync(directory);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length !== 0) {
+      const primary = failed ? failure : completed;
+      throw new AggregateError(
+        [primary, ...errors],
+        "ttsc: check observation artifact cleanup failed",
+        { cause: primary },
+      );
+    }
+  }
+}
+
+/** Refuse artifact IO or removal through a replaced private directory. */
+function assertDirectoryOwnership(directory: string, captured: fs.Stats): void {
+  const current = fs.lstatSync(directory);
+  if (
+    !current.isDirectory() ||
+    current.isSymbolicLink() ||
+    current.dev !== captured.dev ||
+    current.ino !== captured.ino
+  )
+    throw new Error("ttsc: check observation directory ownership changed");
+}
+
+/** Decode declared native inputs without refreshing producer observations. */
+function parseObservations(
+  value: unknown,
+): Pick<
+  TtscBuildResult,
+  | "hostInputs"
+  | "hostInputHashes"
+  | "hostInputRealpaths"
+  | "observationsComplete"
+  | "graph"
+> {
+  if (!isRecord(value) || !Array.isArray(value.hostInputs))
+    throw new Error("expected an observation record and input list");
+  if (
+    value.observationsComplete !== undefined &&
+    value.observationsComplete !== false
+  )
+    throw new Error("observation completeness must be absent or false");
+  const inputs = new Set<string>();
+  for (const input of value.hostInputs) {
+    if (typeof input !== "string" || !path.isAbsolute(input))
+      throw new Error("expected absolute native input paths");
+    inputs.add(path.resolve(input));
+  }
+  const graph = parseReferenceGraph(value.graph);
+  const graphUnavailable =
+    graph === undefined ||
+    (graph.inputHashes === undefined &&
+      graph.inputObservations === undefined &&
+      graph.inputRealpaths === undefined &&
+      graph.inputProofFailures === undefined);
+  return {
+    ...(graph === undefined ? {} : { graph }),
+    ...(graphUnavailable ? { observationsComplete: false as const } : {}),
+    hostInputs: [...inputs],
+    hostInputHashes: parseWitnesses(value.hostInputHashes, inputs, false),
+    hostInputRealpaths: parseWitnesses(value.hostInputRealpaths, inputs, true),
+    ...(value.observationsComplete === false
+      ? { observationsComplete: false as const }
+      : {}),
+  };
+}
+
+/** Retain null witnesses and missing conflicting proofs as distinct states. */
+function parseWitnesses(
+  value: unknown,
+  inputs: ReadonlySet<string>,
+  physical: boolean,
+): Record<string, string | null> {
+  if (!isRecord(value)) throw new Error("expected an input witness record");
+  const output: Record<string, string | null> = {};
+  for (const [file, witness] of Object.entries(value)) {
+    if (!path.isAbsolute(file) || !inputs.has(path.resolve(file)))
+      throw new Error("witness key must identify a declared native input");
+    if (
+      witness !== null &&
+      (typeof witness !== "string" ||
+        (physical
+          ? !path.isAbsolute(witness)
+          : !/^[0-9a-f]{64}$/.test(witness)))
+    )
+      throw new Error("invalid input witness");
+    const key = path.resolve(file);
+    const normalized =
+      physical && typeof witness === "string" ? path.resolve(witness) : witness;
+    if (
+      Object.prototype.hasOwnProperty.call(output, key) &&
+      output[key] !== normalized
+    )
+      throw new Error("conflicting native input coordinates");
+    output[key] = normalized as string | null;
+  }
+  return output;
+}
+
+/** JSON object records exclude scalar and array payloads. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/compiler/internal/runSingleFileEmit.ts

@@ -3,50 +3,97 @@ import path from "node:path";
 
 import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
 import type { TtscSingleFileEmitOptions } from "../../structures/internal/TtscSingleFileEmitOptions";
+import { EmitOwnershipIndex } from "./EmitOwnershipIndex";
+import { runBuild } from "./build/runBuild";
+import { CompilerProjectSelection } from "./project/CompilerProjectSelection";
 import { readProjectConfig } from "./project/readProjectConfig";
-import { resolveEmittedJavaScript } from "./resolveEmittedJavaScript";
-import { runBuild } from "./runBuild";
+import { readEffectiveCompilerOptions } from "./readEffectiveCompilerOptions";
 
 /**
  * Emit one source file by building its project into a temporary directory.
  *
- * The full project is compiled with `forceListEmittedFiles` so that the emitted
- * file list is available for `resolveEmittedJavaScript`. The temp directory is
- * always cleaned up in the `finally` block, even on error.
+ * The full project is compiled with its `rootDir` pinned, and the output is
+ * selected through the producing build's emitted-source provenance and current
+ * physical source identity. Missing or ambiguous ownership is refused without
+ * source-map or filename-precedence inference. Temp-directory removal in
+ * `finally` is attempted after acquisition, including failure paths. Removal
+ * failure propagates on success and is aggregated with an earlier operation
+ * failure rather than replacing it.
+ *
+ * A launcher-supplied selection shares its project and original compiler argument
+ * cwd with public output planning. Response freshness is checked before native
+ * work and publication; these sequential checks do not pin bytes atomically.
+ * Callers without that record retain explicit config/nearest-file discovery.
  *
  * @returns The transformed JavaScript source text.
- * @throws When the build exits non-zero or no output is produced for the file.
+ * @throws When the build exits non-zero, proves no JavaScript for the requested
+ *   source or cannot establish unique ownership.
+ * @evidence contracts/common.md#principled-implementation The supplied invocation selection or legacy locator establishes one project and compiler argument base; current response observations, effective rootDir precedence and isolated emission preserve that producing invocation; its emitted-source provenance and current physical source identity select the actual written output before optional caller-directed writing.
+ * @evidence contracts/common.md#clear-and-simple-design One operation owns project emission, optional public copy and returned text. A supplied existing selection replaces repeated discovery; delegated option interpretation and provenance retain their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or ambiguous provenance cannot become ownership through basename, source-map presence or extension precedence; inferred-root pinning addresses the compiler's injected-outDir requirement.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain exact-source selection, missing owned output and temporary lifetime; the private realpath helper describes unavailable identity without a test-specific premise.
+ * @evidence contracts/performance.md#efficient-algorithms A supplied project avoids another discovery; otherwise legacy discovery remains. Sequential response freshness checks and effective-option inspection precede one full project build, followed by publication reobservation. Output enumeration visits directory entries and sorts output paths; provenance indexing resolves native output identities and processes source associations. Only selected output content is read here, with optional caller output writing; path/association/output bytes and delegated native/build costs remain part of this call.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation observes the project's current compiler/plugin effects and owns no valid-generation cache; equivalent build sharing belongs to higher-level runtime owners.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted private output directory reaches removal in finally after success, build failure, lookup failure or output writing; acquisition has its own failure limitations. The index and selected text live until return/throw and transfer text to the caller, without an output-byte ceiling or timeout supplied here. Cleanup failure propagates after success and aggregates with the original failure and cause after an unsuccessful operation, so neither outcome is hidden.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths and filesystem identities use Node APIs, child execution uses argument arrays, and optional output targets resolve from the invocation cwd on each supported host.
  */
-export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
+export function runSingleFileEmit(
+  options: TtscSingleFileEmitOptions,
+  selection?: ReturnType<typeof CompilerProjectSelection.read>,
+): string {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const sourceFile = realpathIfExists(
     path.isAbsolute(options.file)
       ? options.file
       : path.resolve(cwd, options.file),
   );
-  const project = readProjectConfig({
-    cwd,
-    file: options.file,
-    projectRoot: options.projectRoot,
-    tsconfig: options.tsconfig,
-  });
+  const project =
+    selection?.project ??
+    readProjectConfig({
+      cwd,
+      file: options.file,
+      projectRoot: options.projectRoot,
+      tsconfig: options.tsconfig,
+    });
   const tsconfig = project.path;
-  const projectRoot = project.root;
+  const compilerArgsCwd = selection?.compilerArgsCwd ?? project.root;
+  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
+  // The root tsgo lays the outputs against: a `--rootDir` forwarded on the
+  // command line, which reaches it after the config; otherwise the declared
+  // one, which `readProjectConfig` already absolutized; otherwise the project's
+  // own directory, which `pinInferredRootDir` hands it below.
+  const effective = readEffectiveCompilerOptions(
+    project,
+    options.passthrough,
+    options.binary,
+    options.env,
+    compilerArgsCwd,
+  )?.("rootDir");
+  const rootDir =
+    typeof effective === "string"
+      ? path.resolve(compilerArgsCwd, effective)
+      : project.root;
+  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
   const outDir = createCanonicalTempDirectory("ttsc-single-file-");
+  let failed = false;
+  let failure: unknown;
   try {
     const result = runBuild({
       ...options,
       cwd,
+      compilerArgsCwd,
       emit: true,
-      forceListEmittedFiles: true,
+      forceEmitProvenance: true,
       isolateOutputsTo: outDir,
       outDir,
       // The private temp directory above is an `outDir` this lane injected, not
       // one the project declared, and tsgo answers an inferred common source
       // directory with TS5011 as soon as any `outDir` is in play. Pinning the
       // root tsgo would infer keeps `ttsc <file.ts>` working on a project that
-      // declares no output at all, and it is the same root
-      // `resolveEmittedJavaScript` mirrors below (issue #1172).
+      // declares no output at all, while the producing invocation reports its
+      // actual source/output ownership separately.
       pinInferredRootDir: true,
       resolvedProject: project,
       tsconfig,
@@ -59,18 +106,20 @@ export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
           (result.stderr || result.stdout),
       );
     }
-    const emitted = resolveEmittedJavaScript({
-      emittedFiles: result.emittedFiles,
-      outDir,
-      projectRoot,
-      sourceFile,
-    });
+    const emitted = new EmitOwnershipIndex({
+      emitDir: outDir,
+      rootDir,
+      emittedSources: result.emittedSources,
+      emittedSourceProofFailures: result.emittedSourceProofFailures,
+      outputs: EmitOwnershipIndex.listOutputs(outDir),
+    }).find(sourceFile);
     if (emitted === null) {
       throw new Error(
-        `ttsc single-file emit: no output produced for ${sourceFile}`,
+        `ttsc single-file emit: ${tsconfig} emitted no JavaScript owned by ${sourceFile}; check that the project includes the source and its options permit JavaScript emission`,
       );
     }
     const transformed = fs.readFileSync(emitted, "utf8");
+    if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
     if (options.out) {
       const target = path.isAbsolute(options.out)
         ? options.out
@@ -79,14 +128,30 @@ export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
       fs.writeFileSync(target, transformed, "utf8");
     }
     return transformed;
+  } catch (error) {
+    failed = true;
+    failure = error;
+    throw error;
   } finally {
-    fs.rmSync(outDir, { recursive: true, force: true });
+    try {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    } catch (cleanupError) {
+      if (failed) {
+        throw new AggregateError(
+          [failure, cleanupError],
+          "ttsc: single-file emission and temporary output cleanup failed",
+          { cause: failure },
+        );
+      }
+      throw cleanupError;
+    }
   }
 }
 
 /**
- * Resolve symlinks on `file` when it exists; return the original path when the
- * file is not yet on disk (e.g. a synthetic path used in tests).
+ * Resolve a physical target when native realpath succeeds; otherwise preserve
+ * the requested lexical spelling so project diagnostics and ownership lookup
+ * decide its actual outcome.
  */
 function realpathIfExists(file: string): string {
   try {

package/src/compiler/internal/sharedHost/SEMANTIC_CONFIG_PATH_ENV.ts

@@ -0,0 +1,2 @@
+/** Internal channel preserving a generated wrapper's user-authored config owner. */
+export const SEMANTIC_CONFIG_PATH_ENV = "TTSC_SEMANTIC_CONFIG_PATH";

package/src/compiler/internal/sharedHost/SidecarEnvironment.ts

@@ -0,0 +1,151 @@
+/**
+ * Native environment-name identity for child and isolated-worker environments.
+ * Construction and Windows scans use own enumerable string names; they do not
+ * reproduce Node's inclusion of inherited enumerable environment entries.
+ *
+ * Merge establishes layer precedence; read and write use that same identity for
+ * invocation-owned channels. Replace lets an isolated worker adopt a complete
+ * request snapshot without inheriting stale names from its preceding request.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace groups child-environment operations under one native name policy, so precedence and channel presence cannot disagree about Windows aliases.
+ * @evidence contracts/common.md#clear-and-simple-design Construction, observation, channel mutation and complete replacement share one native name policy; the single public identity avoids separate environment policies in sidecar consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Members use supplied-object operations without replacing process.env or child-process APIs; a worker explicitly owns the mutable process.env target it adopts.
+ * @evidence contracts/common.md#meaningful-documentation The namespace explains its plain-object boundary and each member documents precedence, undefined and native alias behavior according to the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Each member uses Windows case-insensitive name identity only on Windows; POSIX spelling remains exact throughout merge, lookup and removal.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups declarations; the member functions own and describe the actual environment scans and temporary indexes.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace holds no coordinator or cached request result; supplied environments remain mutable and member calls observe current data.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no environment objects, native resources or historical entries between calls.
+ */
+export namespace SidecarEnvironment {
+  /**
+   * Replace an owned environment with a complete native-name snapshot.
+   *
+   * Worker process.env is case-sensitive even on Windows. Canonicalizing the
+   * snapshot restores native name identity before existing SDK readers run.
+   * Missing and undefined-valued entries are removed, including stale aliases;
+   * POSIX retains distinct spellings. The caller must own the mutable target.
+   *
+   * @evidence contracts/common.md#principled-implementation Merge selects each native name's authoritative value before target mutation; clearing old own names then assigning defined values makes sequential worker requests independent of prior spelling or presence.
+   * @evidence contracts/common.md#clear-and-simple-design The worker delegates complete environment adoption to the same namespace that owns native merge and lookup instead of duplicating Windows alias rules.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the caller-owned target is mutated through supported environment property operations; no foreign method or global environment object is replaced.
+   * @evidence contracts/common.md#meaningful-documentation The comment states worker case behavior, full replacement, undefined removal and target ownership with descriptive prose separated from acknowledgments.
+   * @evidence contracts/portability.md#os-neutral-implementation Windows native names are canonicalized through merge while POSIX spellings remain independent; deletion precedes assignment so case-sensitive worker copies cannot retain an old alias.
+   * @evidence contracts/performance.md#efficient-algorithms Merge scans the incoming E names once; target deletion and defined-value assignment visit T and E names respectively, with temporary snapshot storage proportional to distinct incoming names. No per-name nested scan or sorting is added.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each snapshot is mutable invocation authority and must be applied anew; previous requests cannot authorize its environment.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller retains its target, while the normalized temporary snapshot ends with this synchronous call; no history or native resource is acquired.
+   */
+  export function replace(
+    target: NodeJS.ProcessEnv,
+    snapshot: NodeJS.ProcessEnv,
+  ): void {
+    const selected = merge(snapshot);
+    for (const key of Object.keys(target)) delete target[key];
+    for (const [key, value] of Object.entries(selected))
+      if (value !== undefined) target[key] = value;
+  }
+
+  /**
+   * Merge plain environment layers in precedence order, preserving native
+   * names.
+   *
+   * Windows names are case-insensitive. Within one layer the lexicographically
+   * first own spelling wins, matching Node spawn's duplicate selection for this
+   * own-entry boundary; later layers override earlier layers independently of
+   * spelling. POSIX names remain case-sensitive.
+   *
+   * @evidence contracts/common.md#principled-implementation Layer order expresses caller authority; Windows folds name identity while selecting each layer's lexicographically first spelling, matching Node's duplicate-name rule without allowing an inherited alias to defeat an override.
+   * @evidence contracts/common.md#clear-and-simple-design One environment merge owns native name identity for every sidecar constructor; callers supply distinct default, caller and resolved-value layers instead of embedding precedence in object spreads.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported plain-object operations prepare an explicit child environment without replacing process.env or the spawning API.
+   * @evidence contracts/common.md#meaningful-documentation Purpose and precedence paragraphs define Windows duplicate handling and POSIX spelling preservation following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Windows case-insensitive environment identity is isolated here; POSIX keys retain exact spelling, and the returned object contains no ambiguous Windows aliases.
+   * @evidence contracts/performance.md#efficient-algorithms E entries across supplied layers require name enumeration/copying plus uppercase and comparison text costs on Windows. A per-layer map selects minimum spellings without sorting; its distinct names coexist with Object.keys arrays and the accumulated returned environment. Plain-object property reads remain part of the supplied-data boundary.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Environment layers can change between child runs and the result is independently mutable; this operation owns no equivalent-request coordinator or stable invalidation identity.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Temporary name indexes end with the call, and the merged object transfers to its caller; no historical environment, handle or task is retained.
+   */
+  export function merge(
+    ...layers: readonly (NodeJS.ProcessEnv | undefined)[]
+  ): NodeJS.ProcessEnv {
+    const result: NodeJS.ProcessEnv = Object.create(null);
+    for (const layer of layers) {
+      if (layer === undefined) continue;
+      if (process.platform !== "win32") {
+        Object.assign(result, layer);
+        continue;
+      }
+      const names = new Map<string, string>();
+      for (const key of Object.keys(layer)) {
+        const identity = key.toUpperCase();
+        const previous = names.get(identity);
+        if (previous === undefined || key < previous) names.set(identity, key);
+      }
+      for (const [identity, key] of names) result[identity] = layer[key];
+    }
+    return result;
+  }
+
+  /**
+   * Read a plain child-environment name using the host's native identity rule.
+   * Undefined includes an absent layer or a selected undefined-valued
+   * spelling.
+   *
+   * @evidence contracts/common.md#principled-implementation Exact lookup serves POSIX names; the minimum matching spelling serves Windows aliases using the same selection Node applies to plain spawn environments.
+   * @evidence contracts/common.md#clear-and-simple-design One accessor supplies channel-presence decisions without duplicating Windows alias handling in every cleanup helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor inspects supplied data rather than modifying a global environment or guessing an expected channel value.
+   * @evidence contracts/common.md#meaningful-documentation The comment states native name semantics and the meaning of undefined, separated from tags according to the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Case folding occurs only for Windows environment identity; POSIX variables with different case remain distinct.
+   * @evidence contracts/performance.md#efficient-algorithms POSIX performs one supplied-object property lookup, including its name/data access costs. Windows allocates an Object.keys array and scans E own names with uppercase/comparison text costs to select the minimum spelling, without a full sort or historical index.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The caller owns a mutable environment, so previous reads have no stable validity identity or coordinated reuse boundary.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This synchronous accessor retains no environment history, descriptor or task.
+   */
+  export function read(
+    env: NodeJS.ProcessEnv | undefined,
+    name: string,
+  ): string | undefined {
+    if (env === undefined) return undefined;
+    if (process.platform !== "win32") return env[name];
+    const identity = name.toUpperCase();
+    let selected: string | undefined;
+    for (const key of Object.keys(env)) {
+      if (
+        key.toUpperCase() === identity &&
+        (selected === undefined || key < selected)
+      ) {
+        selected = key;
+      }
+    }
+    return selected === undefined ? undefined : env[selected];
+  }
+
+  /**
+   * Set or remove an invocation-owned channel on a plain child environment.
+   * Removing a Windows name also removes every differently cased alias.
+   *
+   * @evidence contracts/common.md#principled-implementation All spellings of a Windows channel share one native identity; removing aliases before a write or deletion establishes one authoritative value, while POSIX changes only the requested exact name.
+   * @evidence contracts/common.md#clear-and-simple-design One write boundary owns channel replacement and removal, avoiding partial deletion rules scattered through sidecar constructors.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The operation mutates only the explicitly supplied child environment; it neither replaces foreign methods nor changes process.env.
+   * @evidence contracts/common.md#meaningful-documentation The native comment explains undefined-driven removal and Windows alias cleanup following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native environment identity determines the deletion set; Windows emits one uppercase spelling and POSIX preserves exact names.
+   * @evidence contracts/performance.md#efficient-algorithms Windows deletion allocates an Object.keys array and visits E names with uppercase/text and property-deletion costs; POSIX deletes one supplied key directly. The optional value assignment remains caller-data work; neither branch sorts names or launches a child.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Channel writes are invocation effects on mutable caller data and cannot be replaced by a previous result.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The mutated environment remains caller-owned; this helper retains no additional state or native resources.
+   */
+  export function write(
+    env: NodeJS.ProcessEnv,
+    name: string,
+    value: string | undefined,
+  ): void {
+    const identity = process.platform === "win32" ? name.toUpperCase() : name;
+    if (process.platform === "win32") {
+      for (const key of Object.keys(env)) {
+        if (key.toUpperCase() === identity) delete env[key];
+      }
+    } else {
+      delete env[name];
+    }
+    if (value !== undefined) env[identity] = value;
+  }
+}

package/src/compiler/internal/sharedHost/TSGO_ARGS_CWD_ENV.ts

@@ -0,0 +1,7 @@
+/**
+ * Native argument base paired with TTSC_TSGO_ARGS. It anchors upstream option
+ * and response parsing while the Program and plugin root remain independent.
+ * Absence retains the ordinary Program cwd; hosts declare compilerArgsCwd
+ * support before the launcher publishes a distinct base.
+ */
+export const TSGO_ARGS_CWD_ENV = "TTSC_TSGO_ARGS_CWD";

package/src/compiler/internal/sharedHost/TSGO_ARGS_ENV.ts

@@ -0,0 +1,7 @@
+/**
+ * Environment channel carrying the JSON-encoded tsgo argv ttsc forwards to a
+ * native sidecar. Mirrors `driver.TsgoArgsEnv` on the Go side; see
+ * `TsgoArguments.ts::createNativeTsgoArgs` for why the payload is not a CLI
+ * flag.
+ */
+export const TSGO_ARGS_ENV = "TTSC_TSGO_ARGS";

package/src/compiler/internal/sharedHost/assertSharedHostCompatibility.ts

@@ -0,0 +1,48 @@
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+import { isLinkedTransform } from "./isLinkedTransform";
+
+/**
+ * Requires equal loader-supplied binary strings for all entries other than
+ * linked transform libraries. Compiler callers supply transform-stage subsets;
+ * a linked check-stage entry is not excluded by this function.
+ *
+ * BuildExecution uses the emit diagnostic; in-memory and resident transform
+ * setup use the source-to-source diagnostic. The pass argument selects that
+ * wording. Equal strings here do not authenticate executable bytes or physical
+ * equivalence of differently spelled paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Linked transform libraries are excluded; every other supplied entry constrains the common binary string. Transform-stage filtering and physical executable identity remain caller/loader responsibilities.
+ * @evidence contracts/common.md#clear-and-simple-design One owner-path comparison handles both pass kinds, with diagnostic wording chosen only when a conflicting owner is encountered.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Compatibility follows loaded plugin stage and ownership discriminants, without special-casing plugin names or retrying an incompatible emit through another backend.
+ * @evidence contracts/common.md#meaningful-documentation The comment states linked-library exclusion and explains the pass argument's diagnostic purpose in separate paragraphs following the documentation skill.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This predicate compares loader-provided owner identities without filesystem or process access; native binary resolution and identity normalization remain the loader's boundary.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms One scan performs up to P discriminant and binary-string comparisons with one remembered string reference. Work also depends on compared path lengths and conflict-message construction; no secondary population-sized sets are built.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each supplied plugin population belongs to its current pass; this predicate owns no stable cross-request producer identity or shared computation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The remembered owner is local to this check; no plugin table, descriptor or running host is retained.
+ */
+export function assertSharedHostCompatibility(
+  plugins: readonly ITtscLoadedNativePlugin[],
+  pass: "emit" | "source-to-source",
+): void {
+  let owner: string | undefined;
+  for (const plugin of plugins) {
+    if (isLinkedTransform(plugin)) continue;
+    if (owner === undefined) {
+      owner = plugin.binary;
+      continue;
+    }
+    if (owner === plugin.binary) continue;
+    const phrase =
+      pass === "emit"
+        ? "multiple compiler native backends cannot share one emit pass"
+        : "multiple transform native backends cannot share one source-to-source pass";
+    throw new Error(
+      "ttsc: " +
+        phrase +
+        "; compose transform libraries through one aggregate native host",
+    );
+  }
+}

package/src/compiler/internal/sharedHost/clearInheritedSemanticConfigPath.ts

@@ -0,0 +1,27 @@
+import { SEMANTIC_CONFIG_PATH_ENV } from "./SEMANTIC_CONFIG_PATH_ENV";
+import { SidecarEnvironment } from "./SidecarEnvironment";
+
+/**
+ * Remove an outer wrapper's config owner, retaining only a caller-named value.
+ * Native environment-name identity also applies to differently cased names.
+ *
+ * @evidence contracts/common.md#principled-implementation Only the caller's explicit channel value establishes this invocation's semantic owner; absence removes inherited authority rather than anchoring a nested build to an unrelated wrapper.
+ * @evidence contracts/common.md#clear-and-simple-design This helper owns semantic-config inheritance policy and delegates native name identity to the shared environment boundary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Channel cleanup changes only the supplied child environment and does not alter the global process environment or invent a config path.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained caller authority and alias handling, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared reader and writer preserve POSIX case distinctions and clear every Windows alias of the invocation channel.
+ * @evidence contracts/performance.md#efficient-algorithms The shared boundary performs at most one scan of each supplied environment on Windows, with Object.keys allocation and uppercase/comparison/deletion text costs. POSIX uses direct supplied-object key operations; the selected path text is transferred rather than parsed or resolved here.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Environment mutation is this invocation's ownership effect and cannot be replaced by a prior cleanup result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Both environment objects remain caller-owned; no historical wrapper authority or native handle is retained here.
+ */
+export function clearInheritedSemanticConfigPath(
+  env: NodeJS.ProcessEnv,
+  callerEnv: NodeJS.ProcessEnv | undefined,
+): void {
+  SidecarEnvironment.write(
+    env,
+    SEMANTIC_CONFIG_PATH_ENV,
+    SidecarEnvironment.read(callerEnv, SEMANTIC_CONFIG_PATH_ENV),
+  );
+}