ttsc 0.32.0 → 0.32.1

package/src/compiler/internal/build/BuildExecution.ts

@@ -39,6 +39,7 @@ import { PassthroughFlags } from "./PassthroughFlags";
 import { PluginFailureDiagnostics } from "./PluginFailureDiagnostics";
 import type { RunBuildOptions } from "./RunBuildOptions";
 import { TsgoArguments } from "./TsgoArguments";
+import { WatchInputPublication } from "./WatchInputPublication";
 import { appendBuildOutput } from "./appendBuildOutput";
 import { isAbsoluteLocalProjectInputPath } from "./isAbsoluteLocalProjectInputPath";
 import { mergeProjectInputSnapshots } from "./mergeProjectInputSnapshots";
@@ -260,6 +261,52 @@ export namespace BuildExecution {
     execution: ReturnType<typeof resolveExecutionContext>,
     setupStartedAt: bigint,
   ): { buildOptions: RunBuildOptions; result?: TtscBuildResult } {
+    return WatchInputPublication.run(
+      prepareBuildExecutionSteps(options, timing, execution, setupStartedAt),
+    );
+  }
+
+  /**
+   * Await project-input publication before handing a prepared build to its
+   * compiler or resident check owner. Publication rejection propagates.
+   *
+   * @evidence contracts/common.md#principled-implementation The asynchronous runner joins the same preparation sequence's project-input handoff before its result becomes available.
+   * @evidence contracts/common.md#clear-and-simple-design The companion changes completion mode while keeping diagnostic recovery, emit policy and discovery in one sequence.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An unsettled or rejected publication cannot become successful preparation.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies the publication barrier and propagated failure.
+   * @evidence contracts/portability.md#os-neutral-implementation Native discovery and selected paths remain with the shared preparation sequence.
+   * @evidence contracts/performance.md#efficient-algorithms One runner advances the preparation handoff once, retaining the shared discovery and diagnostic work costs.
+   * @evidence contracts/performance.md#reuse-equivalent-work The supplied resolved context remains authoritative throughout preparation and its awaited handoff.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The current preparation state survives only until the callback settles or fails; resident handles belong to the caller.
+   */
+  export function prepareBuildExecutionAsync(
+    ...args: Parameters<typeof prepareBuildExecution>
+  ): Promise<ReturnType<typeof prepareBuildExecution>> {
+    return WatchInputPublication.runAsync(prepareBuildExecutionSteps(...args));
+  }
+
+  /**
+   * Prepare one selected execution, yielding its discovered project topology
+   * before the caller may begin compilation.
+   *
+   * @evidence contracts/common.md#principled-implementation Setup failures retain their existing recovery policy; successful discovery suspends at the owning watch handoff before returning build options.
+   * @evidence contracts/common.md#clear-and-simple-design One preparation sequence serves synchronous, asynchronous and composed build entries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The sequence publishes actual native discovery and preserves failure results instead of fabricating completed registration.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states selection ownership and the barrier before compilation.
+   * @evidence contracts/portability.md#os-neutral-implementation Project-input discovery delegates native processes and path reconciliation to their existing boundaries.
+   * @evidence contracts/performance.md#efficient-algorithms Preparation retains one timing update, option projection and optional native discovery; callback completion adds one suspension rather than repeated discovery.
+   * @evidence contracts/performance.md#reuse-equivalent-work The resolved context and setup result are passed to the next phase without another plugin load.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Build-local options and discovered snapshot remain live during publication; the sequence acquires no resident handle.
+   */
+  export function* prepareBuildExecutionSteps(
+    options: RunBuildOptions,
+    timing: BuildTiming.BuildTiming,
+    execution: ReturnType<typeof resolveExecutionContext>,
+    setupStartedAt: bigint,
+  ): WatchInputPublication.Sequence<{
+    buildOptions: RunBuildOptions;
+    result?: TtscBuildResult;
+  }> {
     if (
       execution.nativePlugins.length > 0 ||
       execution.pluginSetupFailure !== undefined
@@ -282,7 +329,9 @@ export namespace BuildExecution {
       };
     }
     if (options.onProjectInputs !== undefined) {
-      options.onProjectInputs(discoverNativeProjectInputs(options, execution));
+      yield options.onProjectInputs(
+        discoverNativeProjectInputs(options, execution),
+      );
     }
     return { buildOptions };
   }
@@ -506,7 +555,11 @@ export namespace BuildExecution {
       // beside the point for a flag whose meaning does not presuppose a project.
       // Forward it to tsgo from the invocation directory instead of failing.
     }
-    const tsgo = resolveTsgo({ ...options, cwd });
+    const tsgo = resolveTsgo({
+      ...options,
+      cwd,
+      env: compilerEnv(options.env),
+    });
     const res = spawnNative(tsgo.binary, [...(options.passthrough ?? [])], {
       cwd,
       env: compilerEnv(options.env),
@@ -1212,7 +1265,8 @@ export namespace BuildExecution {
    * Plugin admission, loading and watch-input callbacks inside the guarded
    * acquisition branch become setup-failure results on error. Initial project/
    * compiler resolution and final config-anchor resolution outside it may
-   * throw.
+   * throw. A synchronous call requires synchronous watch-input handlers; use
+   * resolveExecutionContextAsync when registration returns a promise.
    *
    * @evidence contracts/common.md#principled-implementation One selected project supplies root, config and compiler policy; explicit resolvedProject preserves prior selection, and the guarded plugin admission/loading/watch-input callback branch is converted to a setup failure.
    * @evidence contracts/common.md#clear-and-simple-design A single context carries compiler/project/plugin selection to all phases, with plugin acquisition isolated from project and executable resolution.
@@ -1231,13 +1285,64 @@ export namespace BuildExecution {
       resolvedProject?: ITtscParsedProjectConfig;
       tsconfig?: string;
     },
+  ) {
+    return WatchInputPublication.run(resolveExecutionContextSteps(options));
+  }
+
+  /**
+   * Resolve the selected execution after its plugin watch owner completes every
+   * source-baseline handoff. Rejection keeps the setup-failure policy.
+   *
+   * @evidence contracts/common.md#principled-implementation Awaited stepping shares project/compiler selection and the guarded acquisition branch while retaining each pre-read publication barrier.
+   * @evidence contracts/common.md#clear-and-simple-design The companion delegates to the same resolution sequence as the synchronous entry.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin or watch publication failure remains an explicit setup failure rather than successful empty selection.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes awaited source baselines and the existing returned setup-failure boundary.
+   * @evidence contracts/portability.md#os-neutral-implementation Selected native paths, compiler executable and effective environment retain the resolution sequence's platform boundaries.
+   * @evidence contracts/performance.md#efficient-algorithms Each publication is advanced once without repeating project resolution, plugin selection or source builds.
+   * @evidence contracts/performance.md#reuse-equivalent-work One returned selected context serves all following phases; loader records retain their own validity conditions.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The current selection and loader generation remain retained until a handoff settles; resident children remain separately owned.
+   */
+  export function resolveExecutionContextAsync(
+    options: Parameters<typeof resolveExecutionContext>[0],
+  ): Promise<ReturnType<typeof resolveExecutionContext>> {
+    return WatchInputPublication.runAsync(
+      resolveExecutionContextSteps(options),
+    );
+  }
+
+  /**
+   * Select one execution and suspend its plugin producer at watch handoffs. The
+   * no-plugin path also publishes its empty selection before returning.
+   *
+   * @evidence contracts/common.md#principled-implementation The existing guarded acquisition sequence yields the loader's pre-read barriers and converts thrown handoff failures into the same setup-failure result as loading errors.
+   * @evidence contracts/common.md#clear-and-simple-design Selection and final context assembly remain in one sequence for both completion modes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty plugin selection is published explicitly; rejected acquisition never becomes successful empty admission.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states suspension and empty-selection behavior; the synchronous entry documents context and error ownership.
+   * @evidence contracts/portability.md#os-neutral-implementation Native resolution, effective environment identity and config-anchor selection use their existing owners without changing path spellings.
+   * @evidence contracts/performance.md#efficient-algorithms Initial project/compiler selection precedes optional plugin loading once; suspension does not add another discovery or source scan.
+   * @evidence contracts/performance.md#reuse-equivalent-work The resolved project, opened record store and acquired plugin list stay in the same invocation across publication.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Selection metadata is build-owned and loader caches keep their existing ownership; a suspended handoff retains only the current acquisition generation here.
+   */
+  export function* resolveExecutionContextSteps(
+    options: TtscCommonOptions & {
+      emit?: boolean;
+      onWatchInputs?: TtscPluginSourceInputsHandler;
+      resolvedProject?: ITtscParsedProjectConfig;
+      tsconfig?: string;
+    },
   ) {
     const cwd = path.resolve(options.cwd ?? process.cwd());
     const compilerSelection = CompilerProjectSelection.read(options);
     const project = compilerSelection.project;
     const tsconfig = project.path;
     const projectRoot = project.root;
-    const tsgo = resolveTsgo({ ...options, cwd: projectRoot });
+    const tsgo = resolveTsgo({
+      ...options,
+      cwd: projectRoot,
+      // Public options carry overrides; resolver env is a complete snapshot.
+      // Keep the original overrides for per-invocation channel ownership.
+      env: compilerEnv(options.env),
+    });
     let pluginSetupFailure: TtscBuildResult | undefined;
     let nativePlugins: ITtscLoadedNativePlugin[] = [];
     // Opened only for an invocation that loads plugins, so a project without
@@ -1247,7 +1352,11 @@ export namespace BuildExecution {
     try {
       if (
         compilerSelection.inspectionError === undefined &&
-        hasProjectPluginEntries(project, options.plugins)
+        hasProjectPluginEntries(
+          project,
+          options.plugins,
+          options.pluginConfigDir,
+        )
       ) {
         const cacheDir =
           options.cacheDir ??
@@ -1258,8 +1367,8 @@ export namespace BuildExecution {
           cacheDir,
           env,
         });
-        nativePlugins = loadProjectPlugins({
-          binary: resolveBinary(options) ?? "",
+        nativePlugins = (yield* loadProjectPlugins.steps({
+          binary: resolveBinary({ env }) ?? "",
           cacheDir,
           cwd,
           entries: options.plugins,
@@ -1269,9 +1378,9 @@ export namespace BuildExecution {
           pluginConfigDir: options.pluginConfigDir,
           projectRoot,
           tsconfig,
-        }).nativePlugins;
+        })).nativePlugins;
       } else {
-        options.onWatchInputs?.([]);
+        yield options.onWatchInputs?.([]);
       }
     } catch (error) {
       pluginSetupFailure = {

package/src/compiler/internal/build/ResidentCheckWatchSession.ts

@@ -34,14 +34,14 @@ import { takeResidentCheckEntryRequest } from "./takeResidentCheckEntryRequest";
  * `TTSC_WATCH_DEBUG_INPUTS` reports why selection is reset and the active
  * sidecar count being retired, and distinguishes a failed resident transport.
  *
- * @evidence contracts/common.md#principled-implementation Stable invocation selection and serialized cycles let compatible analysis-only checks retain their Program; explicit reload and observed input-topology changes reset selection before another cycle.
- * @evidence contracts/common.md#clear-and-simple-design The session owns selected execution, dependency snapshot, process identities and per-entry delivery buffers while shared BuildExecution owns one-shot phase and failure policy.
- * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability-aware residency has an actual transport-failure one-shot path, not a successful-result substitution; configuration positions remain distinct even when processes share a key.
- * @evidence contracts/common.md#meaningful-documentation Native paragraphs state supported lanes, reset causes and the caller's serialization/stable-invocation premise; run and dispose document lifecycle effects.
- * @evidence contracts/portability.md#os-neutral-implementation Native filesystem checks and cache touch helpers use selected binary paths; child creation delegates native executable/argv/environment handling to ResidentCheckProcess and BuildExecution.
- * @evidence contracts/performance.md#efficient-algorithms Per-cycle command planning, key serialization and buffer unions process configured checks and pending path text; sorting/comparison bytes, native cache observations, subscribed input discovery and delegated checks add work. Snapshot comparison visits normalized strings and accumulated output can repeatedly copy earlier phase text.
- * @evidence contracts/performance.md#reuse-equivalent-work Process keys include binary/name/argv/compiler payload, while stable invocation context and reload guard the remaining startup inputs; current input snapshots and change requests determine warm Program updates.
- * @evidence contracts/performance.md#bound-retention-and-release-resources Reset clears active maps, execution and snapshots while retiring children and join promises remain separately retained. Unknown joins remain retained rejection and prevent replacement; delegated termination is not descendant settlement. Stable options bound active process keys by configured checks, but pending unique paths and repeated disposal promise chains have no independent historical ceiling.
+ * @evidence contracts/common.md#principled-implementation Stable invocation selection and serialized cycles let compatible analysis-only checks retain their Program; explicit reload and observed input-topology changes reset selection before another cycle. Initial capture and warm refresh await the watch owner's publication before retaining topology; warm refresh compares physical dependency identity while publishing every declared-alias update.
+ * @evidence contracts/common.md#clear-and-simple-design The session owns selected execution, dependency snapshot, process identities and per-entry delivery buffers while shared BuildExecution owns one-shot phase and failure policy. Initial capture wraps the existing discovery callback, and warm refresh joins discovery, comparison and watch registration without another topology owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability-aware residency retains the actual transport-failure one-shot path and distinct configured check positions. Pending or rejected registration cannot restamp topology, and unchanged physical dependencies cannot bypass declared-alias publication.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state supported lanes, reset causes and the caller's serialization/stable-invocation premise; private capture and refresh prose distinguish committed topology, physical comparison and declared-alias publication, while run and dispose document lifecycle effects.
+ * @evidence contracts/portability.md#os-neutral-implementation Native filesystem checks, cache touch helpers and child creation retain selected binary paths and delegated executable/argv/environment handling. BuildExecution owns native discovery and path normalization; initial capture forwards its snapshot without native operations and warm comparison preserves physical and declared representations.
+ * @evidence contracts/performance.md#efficient-algorithms Per-cycle command planning, key serialization and buffer unions process configured checks and pending path text; sorting/comparison bytes, native cache observations, subscribed input discovery and delegated checks add work. Initial capture adds one shallow options copy and one awaited callback; warm refresh adds one native discovery, linear normalized comparison and callback, avoiding reset when topology is unchanged. Accumulated output can repeatedly copy earlier phase text.
+ * @evidence contracts/performance.md#reuse-equivalent-work Process keys include binary/name/argv/compiler payload, while stable invocation context and reload guard the remaining startup inputs. Accepted snapshots serve warm topology comparison only after watch registration completes; execution reuse also requires equal physical dependency topology.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Initial capture closes over the session and caller for its build; warm handoff retains the previous and next snapshots until successful registration replaces the accepted population, while rejection preserves it. Reset clears active maps, execution and snapshots while retiring children and join promises remain separately retained. Unknown joins retain rejection and prevent replacement; delegated termination is not descendant settlement. Stable options bound active process keys by configured checks, but pending unique paths and repeated disposal chains have no independent historical ceiling.
  */
 export class ResidentCheckWatchSession {
   private execution:
@@ -70,7 +70,9 @@ export class ResidentCheckWatchSession {
    * and plugins and starts resident check processes for compatible entries.
    * Later cycles reuse them and forward `change` as an incremental request. A
    * resident process that fails is retired and its entry falls back to the
-   * one-shot check for that cycle.
+   * one-shot check for that cycle. Plugin and project watch handoffs complete
+   * before checks begin; reused topology is republished through the same
+   * completion boundary.
    *
    * @evidence contracts/common.md#principled-implementation Compatible no-emit check-only selection uses the same diagnostic/failure policy as one-shot execution; reload, missing binaries and changed normalized dependency topology cold-resolve the next execution.
    * @evidence contracts/common.md#clear-and-simple-design The cycle separates setup/reuse, topology refresh, ordered checks and final diagnostics/timing, delegating each phase to its owning shared operation.
@@ -103,14 +105,16 @@ export class ResidentCheckWatchSession {
     let buildOptions: RunBuildOptions;
     if (execution === undefined) {
       const setupStartedAt = process.hrtime.bigint();
-      execution = BuildExecution.resolveExecutionContext(options);
+      execution = await BuildExecution.resolveExecutionContextAsync(options);
+      this.assertOpen(generation);
       const discoveryOptions = this.captureProjectInputs(options);
-      const prepared = BuildExecution.prepareBuildExecution(
+      const prepared = await BuildExecution.prepareBuildExecutionAsync(
         discoveryOptions,
         timing,
         execution,
         setupStartedAt,
       );
+      this.assertOpen(generation);
       buildOptions = prepared.buildOptions;
       if (prepared.result !== undefined) {
         await this.resetForRun("preparation-result");
@@ -145,12 +149,16 @@ export class ResidentCheckWatchSession {
         touchPluginCacheEntryInUse(plugin.binary);
       buildOptions = BuildExecution.applyProjectNoEmit(options, execution);
     }
-    if (
-      reusedExecution &&
-      this.refreshProjectInputTopology(options, execution)
-    ) {
-      await this.resetForRun("project-input-topology");
-      return this.run(options);
+    if (reusedExecution) {
+      const topologyChanged = await this.refreshProjectInputTopology(
+        options,
+        execution,
+      );
+      this.assertOpen(generation);
+      if (topologyChanged) {
+        await this.resetForRun("project-input-topology");
+        return this.run(options);
+      }
     }
 
     const checked = await this.runCheckPlugins(
@@ -294,15 +302,20 @@ export class ResidentCheckWatchSession {
     return joined;
   }
 
-  /** Capture discoveries only when the caller actually subscribes to them. */
+  /**
+   * Retain discovered project topology after its watch owner confirms the
+   * publication; rejected registration leaves the previous snapshot intact.
+   */
   private captureProjectInputs(options: RunBuildOptions): RunBuildOptions {
     const onProjectInputs = options.onProjectInputs;
     if (onProjectInputs === undefined) return options;
+    const generation = this.generation;
     return {
       ...options,
-      onProjectInputs: (snapshot) => {
+      onProjectInputs: async (snapshot) => {
+        await onProjectInputs(snapshot);
+        this.assertOpen(generation);
         this.projectInputs = snapshot;
-        onProjectInputs(snapshot);
       },
     };
   }
@@ -310,19 +323,23 @@ export class ResidentCheckWatchSession {
   /**
    * Refresh normalized Program topology while always publishing declared alias
    * updates to the watcher, even when physical dependency identity is
-   * unchanged.
+   * unchanged. Await registration before checks reuse the selected execution.
    */
-  private refreshProjectInputTopology(
+  private async refreshProjectInputTopology(
     options: RunBuildOptions,
     execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
-  ): boolean {
+  ): Promise<boolean> {
     if (options.onProjectInputs === undefined) return false;
+    const generation = this.generation;
     const next = BuildExecution.discoverNativeProjectInputs(options, execution);
     const changed =
       this.projectInputs !== undefined &&
       !projectInputSnapshotsEqual(this.projectInputs, next);
+    // Replaying an unchanged population still crosses the worker's publication
+    // barrier. Starting checks first would accept edits before registration.
+    await options.onProjectInputs(next);
+    this.assertOpen(generation);
     this.projectInputs = next;
-    options.onProjectInputs(next);
     return changed;
   }
 

package/src/compiler/internal/build/RunBuildOptions.ts

@@ -1,7 +1,9 @@
 import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
-import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
 import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOptions";
-import type { TtscPluginSourceInputsHandler } from "../../../structures/internal/TtscSingleFileEmitOptions";
+import type {
+  TtscPluginSourceInputsHandler,
+  TtscProjectInputsHandler,
+} from "../../../structures/internal/TtscSingleFileEmitOptions";
 
 /**
  * Options of one {@link runBuild} call: the public build options plus the knobs
@@ -119,7 +121,8 @@ export type RunBuildOptions = TtscBuildOptions & {
   /**
    * Receives selected native-plugin source roots after the project resolves.
    * The watch launcher uses these roots to invalidate a sidecar when its Go
-   * implementation changes between rebuilds.
+   * implementation changes between rebuilds. Asynchronous entries await a
+   * returned promise; synchronous entries require a synchronous handler.
    */
   onWatchInputs?: TtscPluginSourceInputsHandler;
 
@@ -127,9 +130,10 @@ export type RunBuildOptions = TtscBuildOptions & {
    * Receives the reconciled project-rule filesystem dependency snapshot. Called
    * when this internal callback is supplied, normally by watch launchers;
    * ordinary calls without the callback do not probe the optional sidecar
-   * command.
+   * command. Asynchronous entries await a returned promise before compilation;
+   * synchronous entries require a synchronous handler.
    */
-  onProjectInputs?: (inputs: ITtscProjectInputSnapshot) => void;
+  onProjectInputs?: TtscProjectInputsHandler;
 
   /**
    * Request an external source map in an emitting direct tsgo lane even when

package/src/compiler/internal/build/WatchInputPublication.ts

@@ -0,0 +1,106 @@
+/**
+ * Complete each watch-input handoff before resuming its producer.
+ *
+ * Synchronous compiler APIs retain their return types and require synchronous
+ * handlers. Watch callers use the asynchronous runner so a worker establishes
+ * its baseline before the producer reads or builds the reported inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation Generator suspension preserves ordered publication checkpoints; rejected handoffs return to the producer's failure policy and finally blocks. The synchronous guard recognizes callable then members across realms and observes an already-started promise's rejection before refusing asynchronous completion.
+ * @evidence contracts/common.md#clear-and-simple-design Two runners share one producer sequence; the synchronous guard owns promise recognition and refusal, and its caller delivers that failure to the producer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A synchronous entry refuses asynchronous work instead of reporting completion or blocking; neither runner changes watcher or filesystem internals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies publication ordering, synchronous restrictions, cross-realm recognition and already-started handler ownership; each runner documents failure delivery.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Promise recognition and publication stepping introduce no native filesystem, path identity or process boundary.
+ * @evidence contracts/performance.md#efficient-algorithms Each runner advances each handoff once with constant state; the synchronous guard adds one then-member observation and one rejection observer. Callback work and retained producer state remain owner costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Publication and completion validation belong to each current producer handoff and are never memoized or shared away.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One suspended sequence remains until completion or failure, and rejected handoffs enter its cleanup path. The rejection observer lasts until the already-started handler settles; the synchronous runner cannot join or cancel it. Handler duration and retained producer bytes have no independent bound.
+ */
+export namespace WatchInputPublication {
+  /**
+   * A producer suspends only at a watch owner's completion boundary.
+   *
+   * @evidence contracts/common.md#principled-implementation Yielded values describe handler completion, and the final return preserves the producer's result type.
+   * @evidence contracts/common.md#clear-and-simple-design One generator shape serves both completion runners without changing the producer's return contract.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The type models real callback completion without injecting watcher or filesystem behavior.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies the suspension boundary.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This type has no native representation or process boundary.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes no reusable work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires no resource.
+   */
+  export type Sequence<Result> = Generator<void | Promise<void>, Result, void>;
+
+  /**
+   * Finish a synchronous producer, refusing a handler that returns a promise.
+   * The refusal enters the producer's ordinary exception and cleanup path.
+   *
+   * @evidence contracts/common.md#principled-implementation Each yielded completion is checked before advancing; asynchronous completion becomes an exception delivered into the producer.
+   * @evidence contracts/common.md#clear-and-simple-design The runner owns synchronous completion while the sequence owns operation policy and cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Promise rejection is observed and synchronous success cannot precede its completion.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states promise refusal and the producer-owned exception path.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Sequence stepping performs no native operation.
+   * @evidence contracts/performance.md#efficient-algorithms The runner visits each handoff once and retains one iterator result at a time.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Ordered effectful publications are not cached or shared.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Refusal enters generator cleanup and observes the already-started promise's rejection; its unfinished handler remains handler-owned rather than joined by this synchronous API.
+   */
+  export function run<Result>(sequence: Sequence<Result>): Result {
+    let step = sequence.next();
+    while (!step.done) {
+      try {
+        assertSynchronous(step.value);
+      } catch (error) {
+        step = sequence.throw(error);
+        continue;
+      }
+      step = sequence.next();
+    }
+    return step.value;
+  }
+
+  /**
+   * Join every handoff before continuing, delivering rejection to the producer
+   * rather than bypassing its error handling or temporary-resource cleanup.
+   *
+   * @evidence contracts/common.md#principled-implementation Await settles each yielded handoff and throws rejection back into the same suspended generator before advancing.
+   * @evidence contracts/common.md#clear-and-simple-design The runner owns asynchronous completion while producer policy remains inside the shared sequence.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No pending or rejected publication is silently treated as completed registration.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states ordered joining, rejection delivery and cleanup ownership.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Promise and generator stepping introduce no native boundary.
+   * @evidence contracts/performance.md#efficient-algorithms Each yielded handoff is awaited once with constant runner state.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each effectful publication belongs to its current producer and is not cached.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One suspended sequence remains live until the handler settles; rejection enters its cleanup path, with no independent callback deadline imposed here.
+   */
+  export async function runAsync<Result>(
+    sequence: Sequence<Result>,
+  ): Promise<Result> {
+    let step = sequence.next();
+    while (!step.done) {
+      try {
+        await step.value;
+      } catch (error) {
+        step = sequence.throw(error);
+        continue;
+      }
+      step = sequence.next();
+    }
+    return step.value;
+  }
+
+  /**
+   * Refuse cross-realm promises and thenables through the producer's failure
+   * path, observing rejection from a handler that has already started.
+   */
+  function assertSynchronous(value: unknown): void {
+    if (
+      value !== null &&
+      (typeof value === "object" || typeof value === "function") &&
+      typeof (value as { then?: unknown }).then === "function"
+    ) {
+      // The handler has already started; observe its rejection even though
+      // this synchronous caller cannot join it and must fail the operation.
+      void Promise.resolve(value).catch(() => {});
+      throw new TypeError(
+        "ttsc: asynchronous watch input publication requires an asynchronous build entry",
+      );
+    }
+  }
+}

package/src/compiler/internal/build/runBuild.ts

@@ -2,6 +2,7 @@ import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResu
 import { BuildExecution } from "./BuildExecution";
 import { BuildTiming } from "./BuildTiming";
 import type { RunBuildOptions } from "./RunBuildOptions";
+import { WatchInputPublication } from "./WatchInputPublication";
 
 /**
  * Run `ttsc` against a tsconfig. Returns once the binary exits so the CLI can
@@ -10,8 +11,9 @@ import type { RunBuildOptions } from "./RunBuildOptions";
  *
  * Project-free terminal flags bypass project/plugin setup when applicable.
  * Required emit provenance preserves compiler selection and exposes unknown
- * ownership when the selected producer cannot establish the requested
- * relation.
+ * ownership when the selected producer cannot establish the requested relation.
+ * Watch-input handlers must complete synchronously; use {@link runBuild.async}
+ * when a handler returns a promise.
  *
  * @evidence contracts/common.md#principled-implementation Shared preparation selects project and plugins before execution, while project-free terminal requests take their supported direct compiler path; timing is appended after the resulting build phase.
  * @evidence contracts/common.md#clear-and-simple-design The public synchronous entry owns timing and delegates setup/execution to BuildExecution, keeping the same build policy available to watch sessions.
@@ -23,39 +25,61 @@ import type { RunBuildOptions } from "./RunBuildOptions";
  * @evidence contracts/performance.md#bound-retention-and-release-resources The ledger and execution state are build-owned, while returned output/proof/diagnostic records transfer to the caller; no resident handle or historical build is stored here. Delegated native/probe/artifact acquisition and cleanup may be best effort, and thrown setup can precede some cleanup boundaries. This wrapper supplies no duration/output bound or descendant-release certification.
  */
 export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
-  const timing = BuildTiming.createBuildTiming(options);
-  const result = runBuildTimed(options, timing);
-  return BuildTiming.appendTimingOutput(result, timing);
+  return WatchInputPublication.run(runBuild.steps(options));
 }
 
-function runBuildTimed(
-  options: RunBuildOptions,
-  timing: BuildTiming.BuildTiming,
-): TtscBuildResult {
-  const projectFree = BuildExecution.runProjectFreeTerminalFlag(options);
-  if (projectFree !== null) return projectFree;
-  const setupStartedAt = process.hrtime.bigint();
-  const execution = BuildExecution.resolveExecutionContext(options);
-  return runBuildWithExecution(options, timing, execution, setupStartedAt);
-}
+/**
+ * Share one build sequence between synchronous APIs and awaited watch cycles.
+ *
+ * @evidence contracts/common.md#principled-implementation Both completion modes use the same timed terminal selection, context acquisition, preparation and compile sequence. The asynchronous runner joins every plugin and project publication before native compilation; composing callers must deliver callback rejection into that sequence.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace keeps awaited completion beside its synchronous entry and exposes one timing and phase sequence to single-file orchestration; BuildExecution retains build policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Awaiting changes only publication completion, preserves compiler/plugin selection and project-free terminal behavior, and sends publication failure through existing setup and cleanup rather than bypassing a pending baseline.
+ * @evidence contracts/common.md#meaningful-documentation Entry prose states the publication barrier, order before compilation and internal callers' obligation to complete the sequence and deliver rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation BuildExecution retains native cwd, path identity and argument-array ownership across suspension; the namespace adds no independent native boundary.
+ * @evidence contracts/performance.md#efficient-algorithms Each selected terminal, context, discovery, preparation and compile phase runs once; each publication adds one await and constant sequence state.
+ * @evidence contracts/performance.md#reuse-equivalent-work One resolved execution context serves preparation and compilation without reloading plugins; the namespace retains no completed build or in-flight cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The invocation owns its sequence, ledger, context and current handoff while callbacks settle. Selected results transfer to the caller, delegated resource ownership and cleanup stay unchanged, and no resident history is retained.
+ */
+export namespace runBuild {
+  /**
+   * Run a build after each watch-input handler's returned promise settles.
+   * Compilation starts only after both plugin and project baselines complete.
+   */
+  export function async(
+    options: RunBuildOptions = {},
+  ): Promise<TtscBuildResult> {
+    return WatchInputPublication.runAsync(steps(options));
+  }
 
-function runBuildWithExecution(
-  options: RunBuildOptions,
-  timing: BuildTiming.BuildTiming,
-  execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
-  setupStartedAt: bigint,
-): TtscBuildResult {
-  const prepared = BuildExecution.prepareBuildExecution(
-    options,
-    timing,
-    execution,
-    setupStartedAt,
-  );
-  if (prepared.result !== undefined) return prepared.result;
-  return BuildExecution.runPreparedBuild(
-    options,
-    timing,
-    execution,
-    prepared.buildOptions,
-  );
+  /**
+   * Produce one timed build, yielding watch handoffs before native work.
+   * Composing owners must complete the sequence and deliver callback rejection
+   * back into it so the existing setup and cleanup policies apply.
+   */
+  export function* steps(
+    options: RunBuildOptions,
+  ): WatchInputPublication.Sequence<TtscBuildResult> {
+    const timing = BuildTiming.createBuildTiming(options);
+    const projectFree = BuildExecution.runProjectFreeTerminalFlag(options);
+    if (projectFree !== null)
+      return BuildTiming.appendTimingOutput(projectFree, timing);
+    const setupStartedAt = process.hrtime.bigint();
+    const execution =
+      yield* BuildExecution.resolveExecutionContextSteps(options);
+    const prepared = yield* BuildExecution.prepareBuildExecutionSteps(
+      options,
+      timing,
+      execution,
+      setupStartedAt,
+    );
+    const result =
+      prepared.result ??
+      BuildExecution.runPreparedBuild(
+        options,
+        timing,
+        execution,
+        prepared.buildOptions,
+      );
+    return BuildTiming.appendTimingOutput(result, timing);
+  }
 }

package/src/compiler/internal/buildNativeCompiler.ts

@@ -33,12 +33,16 @@ export function buildNativeCompiler(options: {
   /** Optional explicit cache directory, interpreted by the artifact builder. */
   cacheDir?: string;
 
+  /** Complete environment used to select and key the native host build. */
+  env?: NodeJS.ProcessEnv;
+
   /** Installed ttsc package containing cmd/ttsc and its module metadata. */
   packageRoot: string;
 }): string {
   return buildSourcePlugin({
     baseDir: options.cacheBaseDir,
     cacheDir: options.cacheDir,
+    env: options.env,
     label: "compiler host",
     overlayDirs: [],
     pluginName: "ttsc",

package/src/compiler/internal/compileProjectInMemory.ts

@@ -68,11 +68,13 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     return compileProjectWithPlugins(options, cwd, project);
   }
   const tsconfig = project.path;
+  const env = inheritedSidecarEnv(options.env, options.binary);
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
     cacheDir:
       options.cacheDir ??
       SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
+    env,
     packageRoot: packageRootDir(),
   });
   const res = spawnNative(
@@ -80,7 +82,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     ["api-compile", "--cwd", project.root, "--tsconfig", tsconfig],
     {
       cwd: project.root,
-      env: inheritedSidecarEnv(options.env, options.binary),
+      env,
     },
   );
   if (res.error) {
@@ -110,7 +112,11 @@ function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
 ): boolean {
-  return hasProjectPluginEntries(project, options.plugins);
+  return hasProjectPluginEntries(
+    project,
+    options.plugins,
+    options.pluginConfigDir,
+  );
 }
 
 /**