ttsc 0.30.3 → 0.31.0

package/lib/compiler/internal/build/BuildExecution.js

@@ -0,0 +1,977 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildExecution = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const createCanonicalTempDirectory_1 = require("../../../internal/createCanonicalTempDirectory");
+const resolveNodeBinary_1 = require("../../../internal/resolveNodeBinary");
+const hasProjectPluginEntries_1 = require("../../../plugin/internal/load/hasProjectPluginEntries");
+const loadProjectPlugins_1 = require("../../../plugin/internal/load/loadProjectPlugins");
+const outputText_1 = require("../outputText");
+const readProjectConfig_1 = require("../project/readProjectConfig");
+const CompilerProjectSelection_1 = require("../project/CompilerProjectSelection");
+const readEffectiveCompilerOptions_1 = require("../readEffectiveCompilerOptions");
+const resolveBinary_1 = require("../resolveBinary");
+const resolveTsgo_1 = require("../resolveTsgo");
+const runNativeCheckWithObservations_1 = require("../runNativeCheckWithObservations");
+const SidecarEnvironment_1 = require("../sharedHost/SidecarEnvironment");
+const TSGO_ARGS_CWD_ENV_1 = require("../sharedHost/TSGO_ARGS_CWD_ENV");
+const TSGO_ARGS_ENV_1 = require("../sharedHost/TSGO_ARGS_ENV");
+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");
+const spawnNative_1 = require("../spawnNative");
+const BuildTiming_1 = require("./BuildTiming");
+const CompilerDiagnostics_1 = require("./CompilerDiagnostics");
+const NativePluginArguments_1 = require("./NativePluginArguments");
+const PassthroughFlags_1 = require("./PassthroughFlags");
+const PluginFailureDiagnostics_1 = require("./PluginFailureDiagnostics");
+const TsgoArguments_1 = require("./TsgoArguments");
+const appendBuildOutput_1 = require("./appendBuildOutput");
+const isAbsoluteLocalProjectInputPath_1 = require("./isAbsoluteLocalProjectInputPath");
+const mergeProjectInputSnapshots_1 = require("./mergeProjectInputSnapshots");
+const normalizeBuildOutput_1 = require("./normalizeBuildOutput");
+const parseProjectInputSnapshot_1 = require("./parseProjectInputSnapshot");
+const runExternalEmitProvenance_1 = require("./runExternalEmitProvenance");
+/**
+ * The shared runBuild execution engine: resolve the project and plugins, then
+ * run TypeScript-Go directly or through native plugin hosts.
+ *
+ * {@link runBuild} runs it once per command; {@link ResidentCheckWatchSession}
+ * runs the same phases per watch cycle while keeping a check host resident. The
+ * shared phases centralize plugin/flag and failed-plugin diagnostic policy.
+ * Watch residency and its cycle-specific preparation remain with the watch
+ * owner; sharing these operations is not a guarantee of identical invocation
+ * inputs or outputs across watch and one-shot runs.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolution, preparation and ordered execution share selected project/plugin semantics, with independent failed-plugin diagnostic recovery preserving the original failure.
+ * @evidence contracts/common.md#clear-and-simple-design The grouping owns build phase policy while native argv, flag classification, diagnostic normalization and watch lifetime remain separate responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability-gated host behavior and format-only/terminal lanes follow real supported differences; failure recovery supplements diagnostics without hiding a disproven setup or enabling emission.
+ * @evidence contracts/common.md#meaningful-documentation Namespace prose explains common one-shot/watch phases; public comments document policy precedence, environment ownership and returned versus thrown failures.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This namespace grouping has no independent native representation; selected operations acknowledge environment, filesystem and process boundaries individually.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Each selected phase/command function owns its processing strategy; grouping those operations introduces no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace owns no cached selection; resolved context reuse belongs to its operations and the watch session.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No persistent resource is acquired by this namespace; synchronous commands and resident sessions have separate owners.
+ */
+var BuildExecution;
+(function (BuildExecution) {
+    /**
+     * Merge extra environment variables over `process.env`, always injecting
+     * `TTSC_NODE_BINARY` selected by the runtime capability owner. Explicit
+     * compatible overrides can select a different Node executable; this is not
+     * necessarily the current process binary.
+     */
+    function mergeEnv(extra, cwd = process.cwd(), ...later) {
+        const env = SidecarEnvironment_1.SidecarEnvironment.merge(process.env, extra, ...later);
+        const node = (0, resolveNodeBinary_1.resolveNodeBinary)(env, cwd);
+        SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_NODE_BINARY", node);
+        return env;
+    }
+    /**
+     * Build the environment for a native plugin spawn. Injects `TTSC_TSGO_BINARY`
+     * and `TTSC_TTSX_BINARY` alongside the base env from `mergeEnv`, plus
+     * `TTSC_PLUGIN_CONFIG_DIR` when the caller declared a plugin config anchor
+     * (an embedder compiling through a generated wrapper tsconfig) so config-file
+     * discovery walks the real project instead of the wrapper's temp-dir
+     * ancestry. For transform-stage plugins, also passes
+     * `TTSC_LINKED_PLUGINS_JSON` containing any linked sources so they run inside
+     * the same process as the host plugin.
+     *
+     * Caller-provided values override inherited defaults, except the invocation's
+     * selected compiler remains authoritative. Absent per-invocation payloads
+     * remove stale inherited state rather than leaking an ancestor's project.
+     *
+     * @evidence contracts/common.md#principled-implementation Environment layering preserves caller overrides while the resolved compiler wins last; per-run compiler/config/link payloads are published or cleared according to invocation ownership.
+     * @evidence contracts/common.md#clear-and-simple-design Shared environment helpers own merging and key access; runtime discovery precedes the pure composer that owns invocation payload publication.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported environment channels convey compiler/plugin context without patching strict sidecar parsers; clearing inherited payloads corrects ownership rather than compensating for a stale ancestor selection.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain config anchoring, linked sources, precedence and absent-payload effects without mixing prose into tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Native environment helpers normalize Windows key aliases while retaining POSIX case distinctions; node:path builds the default launcher path and binary values remain native executable selections.
+     * @evidence contracts/performance.md#efficient-algorithms Environment layering copies inherited/caller fields, and Windows channel reads/writes repeatedly scan native-equivalent key names with key-text normalization costs. Linked selection/projection/JSON adds plugin count and payload work. Ordered runtime-candidate probes are delegated before publication and remain native process costs of this call.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Fresh environment composition depends on current invocation and mutable process environment, and coordinates no persistent producer.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The fresh environment and intermediate linked payload have invocation-local ownership and transfer to the spawn caller. Runtime probe acquisition/timeout/cleanup belongs to the capability owner, not a native-release guarantee made here; this function stores no child handle or global payload.
+     */
+    function nativePluginEnv(extra, execution, plugin, tsgoArgs) {
+        const env = mergeEnv({
+            ...(execution.pluginConfigDir === undefined
+                ? {}
+                : { TTSC_PLUGIN_CONFIG_DIR: execution.pluginConfigDir }),
+            TTSC_TTSX_BINARY: process.env.TTSC_TTSX_BINARY ??
+                node_path_1.default.join(__dirname, "..", "..", "..", "launcher", "ttsx.js"),
+        }, execution.projectRoot, extra, 
+        // The invocation's resolved compiler owns the final environment layer.
+        { TTSC_TSGO_BINARY: execution.tsgo.binary });
+        return composeNativePluginEnv(env, extra, execution, SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_NODE_BINARY"), plugin, tsgoArgs);
+    }
+    BuildExecution.nativePluginEnv = nativePluginEnv;
+    /**
+     * Publish this invocation's payloads into its already layered environment.
+     *
+     * The caller owns the fresh environment and the selected Node executable.
+     * Executable capability discovery remains at the native spawn boundary; this
+     * composer only writes protocol values and removes stale payloads.
+     *
+     * @evidence contracts/common.md#principled-implementation The selected compiler and Node executable own their channels; config, forwarded arguments and linked transforms are published or cleared according to this invocation and explicit caller ownership.
+     * @evidence contracts/common.md#clear-and-simple-design A synchronous payload composer consumes the existing merged environment, keeping native executable discovery in nativePluginEnv without copying environment layers again.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied executable selections are preserved without guessing capabilities, launching a substitute producer or mutating the global environment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the required fresh layered environment, caller ownership and the separation of runtime discovery from protocol publication.
+     * @evidence contracts/portability.md#os-neutral-implementation SidecarEnvironment preserves native Windows name identity and POSIX spelling; executable values are supplied native paths rather than shell commands.
+     * @evidence contracts/performance.md#efficient-algorithms Protocol channel reads/writes include Windows environment-name scans and key-text costs. Transform-stage publication also filters P native plugins and projects/JSON-serializes linked config/name/stage values with ordinary JSON conversion/error semantics. No capability subprocess or extra environment-layer merge is performed by this composer.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Invocation-owned writes apply to current mutable caller state rather than a reusable producer computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The supplied environment remains caller-owned and is returned without retaining it or acquiring a child process.
+     */
+    function composeNativePluginEnv(env, extra, execution, nodeBinary, plugin, tsgoArgs) {
+        CompilerProjectSelection_1.CompilerProjectSelection.assertCurrent(execution.compilerSelection);
+        SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_NODE_BINARY", nodeBinary);
+        SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_TSGO_BINARY", execution.tsgo.binary);
+        // Forwarded tsgo argv is per-invocation state this host owns, exactly like
+        // the config anchor below: publish this run's payload, or drop whatever an
+        // ancestor ttsc process left behind when this lane forwards nothing.
+        if (tsgoArgs !== undefined) {
+            SidecarEnvironment_1.SidecarEnvironment.write(env, TSGO_ARGS_ENV_1.TSGO_ARGS_ENV, tsgoArgs);
+            const compilerArgsCwd = execution.compilerSelection.compilerArgsCwd;
+            if (compilerArgsCwd !== execution.projectRoot &&
+                JSON.parse(tsgoArgs).length !== 0) {
+                if (plugin?.capabilities?.compilerArgsCwd !== true)
+                    throw new Error(`ttsc: native host ${plugin?.name ?? "(unselected)"} does not support separate compiler argument cwd`);
+                SidecarEnvironment_1.SidecarEnvironment.write(env, TSGO_ARGS_CWD_ENV_1.TSGO_ARGS_CWD_ENV, compilerArgsCwd);
+            }
+            else {
+                SidecarEnvironment_1.SidecarEnvironment.write(env, TSGO_ARGS_CWD_ENV_1.TSGO_ARGS_CWD_ENV, undefined);
+            }
+        }
+        else {
+            (0, clearInheritedTsgoArgs_1.clearInheritedTsgoArgs)(env, extra);
+        }
+        (0, clearInheritedSemanticConfigPath_1.clearInheritedSemanticConfigPath)(env, extra);
+        // 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.
+        SidecarEnvironment_1.SidecarEnvironment.write(env, "TTSC_PLUGIN_CONFIG_DIR", SidecarEnvironment_1.SidecarEnvironment.read(extra, "TTSC_PLUGIN_CONFIG_DIR") ??
+            execution.pluginConfigDir);
+        (0, publishLinkedTransformPlugins_1.publishLinkedTransformPlugins)(env, extra, plugin?.stage === "transform"
+            ? (0, linkedTransformPlugins_1.linkedTransformPlugins)(execution.nativePlugins)
+            : []);
+        return env;
+    }
+    BuildExecution.composeNativePluginEnv = composeNativePluginEnv;
+    /**
+     * Finish the setup phase of one build: record its timing, apply the project's
+     * own `noEmit`, and report the project's non-TypeScript inputs to a watching
+     * caller.
+     *
+     * Returns a finished `result` alongside effective options when plugin setup
+     * failed, so plugin compilation/emission is skipped. An independent no-emit
+     * compiler pass may still collect TypeScript diagnostics alongside it.
+     * Input-discovery, recovery and caller callback exceptions propagate rather
+     * than being converted to another completed setup result.
+     *
+     * @evidence contracts/common.md#principled-implementation Project noEmit is applied before dispatch; setup failure remains the result while independent diagnostic recovery may supplement it, and successful watch setup reports real dependency snapshots.
+     * @evidence contracts/common.md#clear-and-simple-design Preparation separates setup timing, effective options and dependency reporting from compile execution, returning an explicit finished-result alternative.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Setup failure prevents plugin execution instead of retrying a malformed setup; independent type checking preserves the original failure rather than replacing it.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish skipped plugin emission from permitted independent diagnostics and explain watch-input reporting.
+     * @evidence contracts/portability.md#os-neutral-implementation Native input discovery delegates spawning and identity reconciliation to the established process/filesystem boundaries; selected execution paths are preserved.
+     * @evidence contracts/performance.md#efficient-algorithms Preparation records one optional timing line and applies options, potentially shallow-copying their fields. Applicable recovery/discovery adds argument/env projection, native child/runtime, snapshot or diagnostic text processing; supplied callback work is also part of this call and can throw. Fixed orchestration branches do not bound those inputs or duration.
+     * @evidence contracts/performance.md#reuse-equivalent-work The resolved execution and setup result are reused by the build phase instead of reloading plugins or the project.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Preparation returns build-local state and uses synchronous discovery/check operations; retained watch state belongs to its caller.
+     */
+    function prepareBuildExecution(options, timing, execution, setupStartedAt) {
+        if (execution.nativePlugins.length > 0 ||
+            execution.pluginSetupFailure !== undefined) {
+            BuildTiming_1.BuildTiming.recordTiming(timing, "ttsc plugin setup time", setupStartedAt);
+        }
+        const buildOptions = applyProjectNoEmit(options, execution);
+        if (execution.pluginSetupFailure !== undefined) {
+            return {
+                buildOptions,
+                result: appendTypeScriptDiagnosticsAfterPluginFailure(execution.pluginSetupFailure, buildOptions, execution),
+            };
+        }
+        if (options.onProjectInputs !== undefined) {
+            options.onProjectInputs(discoverNativeProjectInputs(options, execution));
+        }
+        return { buildOptions };
+    }
+    BuildExecution.prepareBuildExecution = prepareBuildExecution;
+    /**
+     * Run the compile phase of a prepared build.
+     *
+     * With native plugins, check-stage hosts run first and a failure stops the
+     * build (with TypeScript diagnostics collected separately when the host did
+     * not report them); transform-stage hosts then emit through one shared host.
+     * Without plugins, TypeScript-Go runs directly.
+     *
+     * The supported format lane supplies emit:false and returns after configured
+     * checks without a later type-check or transform pass; conflicting internal
+     * emit/format selections are not validated here. Launch and compatibility
+     * errors may throw. Required emit provenance keeps the selected producer: an
+     * opted-in native host reports its captured generation, while the direct
+     * compiler adapter admits only a stable observed selection and supported
+     * output layout. Unknown ownership remains explicit for consumers rather than
+     * guessed.
+     *
+     * @evidence contracts/common.md#principled-implementation Ordered checks block emit on failure and retain negotiated same-generation input observations for the actual check verb; effectful fix/format results keep their distinct command contract without fabricated reusable check metadata; transforms use one compatible host. Normally completed native partial emission and supported stable external emission can retain actual-write provenance alongside unchanged nonzero status, while interrupted or unknown generations establish no proof.
+     * @evidence contracts/common.md#clear-and-simple-design This dispatcher owns phase policy while argv, spawning, normalization and fallback comparison remain shared helpers used by one-shot and watch lanes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Format bypass follows its write-only contract; capability-based diagnostics/provenance and failure fallback preserve supported producer semantics without plugin-name shortcuts, foreign mutation or filename-based ownership guesses.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states ordering, format effects and thrown boundary failures; branch comments explain nonobvious emission and display policies.
+     * @evidence contracts/portability.md#os-neutral-implementation Commands preserve native executable/argv/cwd boundaries; provenance uses a canonical unique temporary directory and absolute native wire paths without post-compile realpath reconstruction or OS-derived case folding.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin/stage selection scans the configured population; each command includes argv/env publication and native runtime probes under its helpers. Required proof adds artifact or external inspection/JSON/source-executable observation work, plus association/path processing. Accumulating phase reports can recopy earlier bytes; there is no supplied bound on total reports, proof bytes or child duration.
+     * @evidence contracts/performance.md#reuse-equivalent-work A check host declaring TypeScript diagnostics avoids an equivalent extra successful check, while compatible transform plugins share one host; effectful configured checks still execute in order.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Phase results and command/proof records stay build-local and returned data transfer to the caller, with uncapped report/association bytes. Native proof setup observes ownership before finally, so setup failure can leave allocation unclaimed; accepted artifacts reach identity-checked cleanup attempts. Replaced parents remain untouched. Cleanup aggregates an earlier throw or nonzero result; other cleanup errors propagate without certifying release. Delegated capture/descendant release remains with its owner; no resident history is retained here.
+     */
+    function runPreparedBuild(options, timing, execution, buildOptions) {
+        if (execution.compilerSelection.inspectionError !== undefined) {
+            const diagnosed = runTsgo(execution, [], buildOptions);
+            if (diagnosed.status !== 0)
+                return diagnosed;
+            return {
+                ...diagnosed,
+                status: 2,
+                stderr: diagnosed.stderr +
+                    `ttsc: compiler project selection unavailable: ${String(execution.compilerSelection.inspectionError)}\n`,
+            };
+        }
+        if (execution.nativePlugins.length > 0) {
+            const compilers = execution.nativePlugins.filter((plugin) => plugin.stage === "transform");
+            const checked = runNativeCheckPlugins(buildOptions, execution, timing);
+            if (checked.status !== 0) {
+                return appendTypeScriptDiagnosticsAfterPluginFailure(checked, buildOptions, execution);
+            }
+            if (buildOptions.emit === false) {
+                if (buildOptions.format === true) {
+                    // Format mode is write-only by contract: the lint sidecar
+                    // already rewrote source files and reported nothing. Running
+                    // tsgo --noEmit OR a transform compiler afterwards would either
+                    // surface unrelated type errors as if they were format failures
+                    // (tsgo path) or apply transform-stage rewrites on top of the
+                    // formatted source (transform path), both of which break the
+                    // documented "ttsc format only formats" guarantee. The
+                    // short-circuit fires before either branch so format mode is a
+                    // single concern regardless of how many compilers the project
+                    // configures. Callers that want a recheck or a transform pass
+                    // after format should run `ttsc check` / `ttsc build` as a
+                    // separate invocation.
+                    return checked;
+                }
+                if (compilers.length !== 0) {
+                    (0, assertSharedHostCompatibility_1.assertSharedHostCompatibility)(compilers, "emit");
+                    const compiled = buildWithNativeCompilerPlugins(buildOptions, execution, compilers, timing);
+                    const result = (0, appendBuildOutput_1.appendBuildOutput)(checked, compiled);
+                    return compiled.status === 0
+                        ? result
+                        : appendTypeScriptDiagnosticsAfterPluginFailure(result, buildOptions, execution);
+                }
+                if (checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins)) {
+                    return checked;
+                }
+                return (0, appendBuildOutput_1.appendBuildOutput)(checked, runTsgo(execution, ["--noEmit"], buildOptions));
+            }
+            let result;
+            if (compilers.length !== 0) {
+                (0, assertSharedHostCompatibility_1.assertSharedHostCompatibility)(compilers, "emit");
+                const compiled = buildWithNativeCompilerPlugins(buildOptions, execution, compilers, timing);
+                result = (0, appendBuildOutput_1.appendBuildOutput)(checked, compiled);
+                if (compiled.status !== 0) {
+                    result = appendTypeScriptDiagnosticsAfterPluginFailure(result, buildOptions, execution);
+                }
+            }
+            else {
+                if (buildOptions.skipDiagnosticsCheck !== true &&
+                    !checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins) &&
+                    !PassthroughFlags_1.PassthroughFlags.forwardsTerminalTsgoFlag(buildOptions)) {
+                    const tsgoChecked = runTsgo(execution, ["--noEmit"], buildOptions);
+                    if (tsgoChecked.status !== 0) {
+                        return (0, appendBuildOutput_1.appendBuildOutput)(checked, tsgoChecked);
+                    }
+                }
+                const args = TsgoArguments_1.TsgoArguments.createTsgoBuildArgs(execution, buildOptions, {
+                    listEmittedFiles: buildOptions.forceListEmittedFiles === true,
+                });
+                const emitted = runTsgoBuild(execution, buildOptions, args);
+                result = (0, appendBuildOutput_1.appendBuildOutput)(checked, emitted);
+            }
+            return result;
+        }
+        if (buildOptions.format === true) {
+            // Format mode is write-only by contract — see the matching
+            // short-circuit in the with-native-plugins branch above. When no
+            // native plugin is loaded there is nothing for `ttsc format` to
+            // rewrite, so emit an empty success result rather than falling
+            // through to a tsgo pass that would surface unrelated type errors
+            // as if they were format failures.
+            return {
+                diagnostics: [],
+                status: 0,
+                stdout: "",
+                stderr: "",
+            };
+        }
+        const args = TsgoArguments_1.TsgoArguments.createTsgoBuildArgs(execution, buildOptions, {
+            // `--verbose` promises the emitted-file list on every lane, and the list
+            // only exists if tsgo is asked for it. ttsc adds the flag for itself here
+            // exactly as it does for `forceListEmittedFiles`, and strips the raw
+            // `TSFILE:` lines back out below.
+            listEmittedFiles: buildOptions.emit !== false &&
+                (buildOptions.forceListEmittedFiles === true ||
+                    buildOptions.quiet === false),
+            noEmitOnError: buildOptions.emit !== false &&
+                buildOptions.skipDiagnosticsCheck !== true &&
+                !PassthroughFlags_1.PassthroughFlags.forwardsTerminalTsgoFlag(buildOptions),
+        });
+        return runTsgoBuild(execution, buildOptions, args);
+    }
+    BuildExecution.runPreparedBuild = runPreparedBuild;
+    /**
+     * Answer a forwarded terminal flag whose meaning precedes a project, when no
+     * project can be resolved.
+     *
+     * `ttsc --init` exists to write the starter `tsconfig.json`, and `ttsc --all`
+     * / `ttsc -?` only print tsgo's help: none of them needs a project, so a
+     * project-resolution failure must not stop them. The classification is
+     * `FLAG_SCHEMA`'s (`terminal` + `projectFree`), so marking a further flag
+     * project-free needs no edit here.
+     *
+     * A resolvable project keeps the established lane untouched: the build path
+     * still forwards the flag with `-p <tsconfig>` from the project root, so
+     * `ttsc --init` inside an existing project still reports tsgo's TS5054
+     * instead of writing a second config into the current directory. Returns
+     * `null` when this lane does not apply.
+     *
+     * @evidence contracts/common.md#principled-implementation Schema project-free terminal semantics permit compiler execution after any project resolution failure; an existing selected project returns null so its ordinary compiler answer remains authoritative.
+     * @evidence contracts/common.md#clear-and-simple-design A narrow early lane probes project availability before direct terminal execution and leaves all project-dependent builds to shared preparation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The caught resolution failure is legitimate only for commands not requiring a project; ordinary compilation failures do not enter this bypass.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain project-independent commands, existing-project behavior and null applicability; the catch comment states its deliberate broad premise.
+     * @evidence contracts/portability.md#os-neutral-implementation Invocation cwd is resolved natively and spawnNative receives executable/argv separately with platform-aware environment merging.
+     * @evidence contracts/performance.md#efficient-algorithms Flag selection scans forwarded argument/name text before config IO. An applicable lane includes native cwd/config resolution, binary and runtime capability lookup, argv/env composition, complete captured output and diagnostic normalization; one requested command does not bound its native duration or output bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A project probe and effectful terminal invocation establish no retained or shared cross-request result.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Returned output and diagnostics transfer to the caller without retaining a child handle or config history here. No timeout or output ceiling is supplied; delegated native capture/probe cleanup may be best effort and does not certify descendant release.
+     */
+    function runProjectFreeTerminalFlag(options) {
+        if (!PassthroughFlags_1.PassthroughFlags.forwardsProjectFreeTerminalTsgoFlag(options))
+            return null;
+        if (options.resolvedProject !== undefined)
+            return null;
+        const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
+        try {
+            (0, readProjectConfig_1.readProjectConfig)({
+                cwd,
+                projectRoot: options.projectRoot,
+                tsconfig: options.tsconfig,
+            });
+            return null;
+        }
+        catch {
+            // Any resolution failure takes this branch, not only "not found": a
+            // malformed config and an explicitly named missing `-p` path are equally
+            // 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 = (0, resolveTsgo_1.resolveTsgo)({ ...options, cwd });
+        const res = (0, spawnNative_1.spawnNative)(tsgo.binary, [...(options.passthrough ?? [])], {
+            cwd,
+            env: mergeEnv(options.env, cwd),
+            encoding: "utf8",
+        });
+        if (res.error) {
+            throw new Error(`ttsc: failed to spawn ${tsgo.binary}: ${res.error.message}`);
+        }
+        return (0, normalizeBuildOutput_1.normalizeBuildOutput)({
+            status: res.status ?? 1,
+            stdout: (0, outputText_1.outputText)(res.stdout),
+            stderr: (0, outputText_1.outputText)(res.stderr),
+        }, cwd);
+    }
+    BuildExecution.runProjectFreeTerminalFlag = runProjectFreeTerminalFlag;
+    /**
+     * A tsconfig-level `noEmit: true` is an analysis-only build unless the user
+     * explicitly asks `ttsc --emit` to override it. Treat it like CLI `--noEmit`
+     * before composing tsgo/native-host arguments so ttsc does not add emit-only
+     * guards around projects that cannot emit.
+     *
+     * @evidence contracts/common.md#principled-implementation An explicit emit selection takes precedence; only absent selection combined with project noEmit maps to analysis-only options.
+     * @evidence contracts/common.md#clear-and-simple-design A small shared option adapter applies project policy once before either native or direct argument composition.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts This reflects declared project and caller policy instead of special-casing particular configs or mutating compiler internals.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains explicit override precedence and why application precedes argument composition.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Selecting an emit boolean accesses no native filesystem, path or process boundary.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms Two scalar checks return the original options when possible; only a changed policy requires a shallow copy of option fields.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This policy adapter does not coordinate a repeated producer or persistent result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Option ownership remains with the caller and no retained state or handle is acquired.
+     */
+    function applyProjectNoEmit(options, execution) {
+        if (options.emit !== undefined || execution.projectNoEmit !== true) {
+            return options;
+        }
+        return { ...options, emit: false };
+    }
+    BuildExecution.applyProjectNoEmit = applyProjectNoEmit;
+    /**
+     * Whether a check-stage host declares reporting TypeScript's diagnostics, in
+     * which case another pass can duplicate already-reported diagnostics. This
+     * trusts an explicit descriptor contract; it does not independently measure
+     * the completed host's diagnostic completeness or success.
+     *
+     * @evidence contracts/common.md#principled-implementation Only check-stage descriptors explicitly declaring TypeScript diagnostic reporting satisfy the predicate; transform metadata cannot supply that declaration. The dispatcher owns when it may trust this contract rather than treating a true predicate as observed runtime completeness.
+     * @evidence contracts/common.md#clear-and-simple-design One capability query is shared by both analysis and emission orchestration rather than duplicating plugin classifications.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Descriptor semantics drive diagnostic policy without recognizing particular plugin names or trusting a previous passing example.
+     * @evidence contracts/common.md#meaningful-documentation Native prose gives the declared reporting premise and why a redundant type check should be avoided.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Inspecting stage/reporting metadata does not access native paths or processes.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms A short-circuit scan performs O(plugin count) scalar checks without allocating a filtered population.
+     * @evidence contracts/performance.md#reuse-equivalent-work This predicate identifies the descriptor guarantee that permits a completed check's TypeScript diagnostics to serve the following build phase; the owning dispatcher determines when it applies.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The capability query retains no descriptor history or process handle.
+     */
+    function checkPluginsReportTypeScriptDiagnostics(plugins) {
+        return plugins.some((plugin) => plugin.stage === "check" &&
+            plugin.reportsTypeScriptDiagnostics === true);
+    }
+    BuildExecution.checkPluginsReportTypeScriptDiagnostics = checkPluginsReportTypeScriptDiagnostics;
+    /**
+     * Preserve a failed plugin's output and status while collecting TypeScript
+     * diagnostics through an independent no-emit pass.
+     *
+     * A sidecar can fail before it loads the project Program, including when a Go
+     * panic or another runtime error terminates the process. The plugin failure
+     * must still block emit, but it must not hide unrelated errors in the user's
+     * TypeScript source. The fallback runs only after a plugin failure, skips
+     * modes whose contract intentionally omits diagnostics, and avoids appending
+     * a batch the plugin already reported itself. A returned recovery preserves
+     * the original status; secondary compiler/environment/normalization errors
+     * can propagate before that result merge. NoEmit prevents compiler emission,
+     * not unrelated native/cache effects or incremental metadata writes.
+     *
+     * @evidence contracts/common.md#principled-implementation An independent no-emit pass adds only unreported diagnostics, seeds an otherwise unstructured plugin failure when needed and restores the original failure status after output merging.
+     * @evidence contracts/common.md#clear-and-simple-design Recovery policy, compiler execution and diagnostic identity comparison are separate shared operations, with one result merge preserving the failed producer's ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The second pass addresses a supported failed-sidecar reporting gap; it never retries emission or converts the plugin failure into a successful build.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain independent diagnostics, blocked emission, excluded modes and duplicate suppression; the seeding comment explains structured-consumer visibility.
+     * @evidence contracts/portability.md#os-neutral-implementation Compiler execution uses the selected native binary/cwd; diagnostic filenames normalize against the same project root through the shared parser.
+     * @evidence contracts/performance.md#efficient-algorithms Excluded modes use scalar checks and the delegated forwarded-frame terminal selector. Applicable recovery adds option copy/pretty filtering, one native compiler check, indexed diagnostic/text selection and output merging; argument/environment/path/report bytes and child runtime remain inputs to the work.
+     * @evidence contracts/performance.md#reuse-equivalent-work Existing reported diagnostics suppress equivalent fallback reports, while failed plugin execution cannot guarantee a complete Program check and therefore cannot replace this independent pass.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The fallback runs synchronously without a timeout supplied here. Intermediate failure/check/selected records and text remain live through merge; returned records transfer to the caller and no historical cache is retained. Delegated capture release is best effort, not a certificate that native descendants or failed cleanup resources were released.
+     */
+    function appendTypeScriptDiagnosticsAfterPluginFailure(failure, options, execution) {
+        if (!PluginFailureDiagnostics_1.PluginFailureDiagnostics.shouldCollect(options)) {
+            return failure;
+        }
+        const typechecked = runTsgo(execution, ["--noEmit"], createPluginFailureTypecheckOptions(options));
+        const fallback = CompilerDiagnostics_1.CompilerDiagnostics.filterReportedTypeScriptDiagnostics(failure, typechecked, execution.projectRoot);
+        // Structured consumers (the public API's `IFailure.diagnostics`) never see
+        // stdout/stderr, so a plugin failure that reported no parsable diagnostics
+        // must be seeded as one before recovered TypeScript diagnostics are appended
+        // — otherwise the recovery would replace the plugin error with unrelated
+        // type errors instead of surfacing both.
+        return PluginFailureDiagnostics_1.PluginFailureDiagnostics.append(failure, fallback);
+    }
+    BuildExecution.appendTypeScriptDiagnosticsAfterPluginFailure = appendTypeScriptDiagnosticsAfterPluginFailure;
+    /**
+     * Make the recovery pass parseable regardless of the user's display flags.
+     * This is an internal second pass, so plain output is required to remove only
+     * diagnostics that the failed plugin already printed.
+     */
+    function createPluginFailureTypecheckOptions(options) {
+        return {
+            ...options,
+            passthrough: PassthroughFlags_1.PassthroughFlags.withoutBooleanFlags(options.passthrough ?? [], ["--pretty"]),
+            structuredDiagnostics: true,
+        };
+    }
+    /**
+     * Dispatch a build through the shared-host native plugin. The host plugin is
+     * the one that owns the process (non-linked); all other transform plugins
+     * ride inside it via the `--plugins-json` flag.
+     */
+    function buildWithNativeCompilerPlugins(options, execution, plugins, timing) {
+        const host = (0, selectSharedHostPlugin_1.selectSharedHostPlugin)(plugins);
+        const run = (provenancePath) => runNativePluginCommand(host, NativePluginArguments_1.NativePluginArguments.createNativeBuildArgs(execution, options, plugins, provenancePath), options, execution, "ttsc.build", timing, NativePluginArguments_1.NativePluginArguments.transformHostTimingLabel(plugins), TsgoArguments_1.TsgoArguments.createNativeBuildTsgoArgs(execution, options));
+        if (options.forceEmitProvenance !== true)
+            return run();
+        if (host.capabilities?.emitProvenance !== true) {
+            throw new Error(`ttsc: selected native compiler host ${host.name ?? host.binary} does not support required emit provenance`);
+        }
+        return captureNativeEmitProvenance(run);
+    }
+    /**
+     * Read an opted-in producer's normally completed emit proof through a unique
+     * private artifact, including writes preceding an emit diagnostic. Nonzero
+     * status and diagnostics remain unchanged; missing or invalid failed-run
+     * metadata supplies no proof. Interrupted runs never admit an artifact.
+     * Removal targets only the artifact and its empty, identity-checked
+     * directory; a cleanup failure preserves an earlier thrown error or nonzero
+     * compiler result as its aggregate cause, including the original diagnostics
+     * and text.
+     */
+    function captureNativeEmitProvenance(run) {
+        const directory = (0, createCanonicalTempDirectory_1.createCanonicalTempDirectory)("ttsc-emit-provenance-");
+        const ownership = node_fs_1.default.lstatSync(directory);
+        const provenancePath = node_path_1.default.join(directory, "emitted-sources.json");
+        let completed;
+        let failed = false;
+        let failure;
+        try {
+            const result = run(provenancePath);
+            completed = result;
+            if (result.processCompletedNormally !== true)
+                return result;
+            let value;
+            try {
+                assertEmitProvenanceDirectory(directory, ownership);
+                if (!node_fs_1.default.lstatSync(provenancePath).isFile())
+                    throw new Error("ttsc: native emit provenance is not an ordinary file");
+                value = JSON.parse(node_fs_1.default.readFileSync(provenancePath, "utf8"));
+            }
+            catch (error) {
+                if (result.status !== 0 &&
+                    (error instanceof SyntaxError ||
+                        error.code === "ENOENT"))
+                    return result;
+                throw new Error("ttsc: native emit provenance could not be read", {
+                    cause: new AggregateError([result, error]),
+                });
+            }
+            if (!isEmitProvenance(value)) {
+                if (result.status !== 0)
+                    return result;
+                throw new Error("ttsc: native compiler returned invalid emit provenance", {
+                    cause: result,
+                });
+            }
+            return { ...result, emittedSources: value };
+        }
+        catch (error) {
+            failed = true;
+            failure = error;
+            throw error;
+        }
+        finally {
+            try {
+                assertEmitProvenanceDirectory(directory, ownership);
+                node_fs_1.default.rmSync(provenancePath, { force: true });
+                node_fs_1.default.rmdirSync(directory);
+            }
+            catch (error) {
+                if (failed) {
+                    throw new AggregateError([failure, error], "ttsc: native emit provenance failed and its private artifact could not be released", { cause: failure });
+                }
+                if (completed !== undefined && completed.status !== 0) {
+                    throw new AggregateError([completed, error], `ttsc: native compiler exited with status ${String(completed.status)} and its private emit provenance artifact could not be released`, { cause: completed });
+                }
+                throw error;
+            }
+        }
+    }
+    /** Refuse artifact IO or deletion through a replaced private directory. */
+    function assertEmitProvenanceDirectory(directory, captured) {
+        const current = node_fs_1.default.lstatSync(directory);
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            current.dev !== captured.dev ||
+            current.ino !== captured.ino)
+            throw new Error("ttsc: native emit provenance directory ownership changed");
+    }
+    /**
+     * Validate the native wire representation without re-resolving compile-time
+     * identities against a potentially changed filesystem. Empty and ambiguous
+     * source lists stay intact; they cannot justify unique runtime routing.
+     */
+    function isEmitProvenance(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            Object.entries(value).every(([output, sources]) => (0, isAbsoluteLocalProjectInputPath_1.isAbsoluteLocalProjectInputPath)(output) &&
+                Array.isArray(sources) &&
+                sources.every((source) => typeof source === "string" &&
+                    (0, isAbsoluteLocalProjectInputPath_1.isAbsoluteLocalProjectInputPath)(source))));
+    }
+    /**
+     * Run `tsgo -p <tsconfig> [extraArgs]` and return the normalized result. Used
+     * for the no-emit type-check pass that precedes file emission.
+     *
+     * `extraArgs` follow the forwarded flags: they are this pass's own contract
+     * (`--noEmit`), and a runtime build that re-enables emit after the user's
+     * flags must not turn its check pass into a second emit.
+     *
+     * @evidence contracts/common.md#principled-implementation Pass-owned extra flags follow forwarded flags, so noEmit cannot be overridden into accidental emission; output isolation remains final even for incremental build information.
+     * @evidence contracts/common.md#clear-and-simple-design One synchronous compiler boundary composes diagnostics/threading and delegates normalization, serving all independent check operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported compiler options express the check contract without intercepting writes or replacing compiler APIs; spawn errors remain errors.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains the no-emit use and load-bearing argument precedence.
+     * @evidence contracts/portability.md#os-neutral-implementation spawnNative uses the selected executable, separate argv and project cwd; environment composition handles native variable aliases and output text decoding is explicit UTF-8.
+     * @evidence contracts/performance.md#efficient-algorithms One argv composition includes delegated option-presence classification, threading/isolation text and argument copies. Environment composition can perform native runtime capability probes before the compiler launch; complete capture/decoding and diagnostic normalization follow. Work/storage depend on argument/env/path/report bytes and native child work, without an asserted measured cost ranking.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This executes the requested compiler pass; equivalence with other phases must be established by orchestration rather than caching a result here.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous compiler call has no timeout or output-byte ceiling supplied here. Output/diagnostic records transfer to the caller; delegated file capture attempts cleanup with suppressed errors, so native release and inherited descendants are not certified by returning.
+     */
+    function runTsgo(execution, extraArgs, options) {
+        CompilerProjectSelection_1.CompilerProjectSelection.assertCurrent(execution.compilerSelection);
+        const res = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, [
+            "-p",
+            execution.tsconfig,
+            ...TsgoArguments_1.TsgoArguments.createTsgoDiagnosticArgs(options),
+            ...TsgoArguments_1.TsgoArguments.createTsgoThreadingArgs(options),
+            ...(options.passthrough ?? []),
+            ...extraArgs,
+            ...TsgoArguments_1.TsgoArguments.isolatedTsgoOutputArgs(options, true),
+            ...CompilerProjectSelection_1.CompilerProjectSelection.readGuard(execution.compilerSelection, options.passthrough),
+        ], {
+            cwd: execution.compilerSelection.compilerArgsCwd,
+            env: mergeEnv(options.env, execution.projectRoot),
+            encoding: "utf8",
+        });
+        if (res.error) {
+            throw new Error("ttsc: failed to spawn " +
+                execution.tsgo.binary +
+                ": " +
+                res.error.message);
+        }
+        return (0, normalizeBuildOutput_1.normalizeBuildOutput)({
+            status: res.status ?? 1,
+            stdout: (0, outputText_1.outputText)(res.stdout),
+            stderr: (0, outputText_1.outputText)(res.stderr),
+        }, execution.projectRoot);
+    }
+    BuildExecution.runTsgo = runTsgo;
+    /**
+     * Run `tsgo` with the full emit arguments and parse `TSFILE:` lines from
+     * stdout into `emittedFiles`. Internally requested TSFILE lines are stripped;
+     * a user's own listEmittedFiles selection preserves its displayed listing.
+     * Required provenance observes this same selected executable before and after
+     * its single emitting run; unsupported or unstable relations stay unknown.
+     */
+    function runTsgoBuild(execution, options, args) {
+        const env = mergeEnv(options.env, execution.projectRoot);
+        const userOptions = (0, readEffectiveCompilerOptions_1.readEffectiveCompilerOptions)(execution.project, options.passthrough, execution.tsgo.binary, env, execution.compilerSelection.compilerArgsCwd);
+        const userListedEmitted = userOptions?.("listEmittedFiles") === true;
+        const run = (commandArgs) => {
+            CompilerProjectSelection_1.CompilerProjectSelection.assertCurrent(execution.compilerSelection);
+            const res = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, commandArgs, {
+                cwd: execution.compilerSelection.compilerArgsCwd,
+                env,
+                encoding: "utf8",
+            });
+            if (res.error) {
+                throw new Error("ttsc.build: failed to spawn " +
+                    execution.tsgo.binary +
+                    ": " +
+                    res.error.message);
+            }
+            const captured = {
+                status: res.status ?? 1,
+                stdout: (0, outputText_1.outputText)(res.stdout),
+                stderr: (0, outputText_1.outputText)(res.stderr),
+            };
+            // Collect structured diagnostics now, but keep captured streams in their
+            // producer channels until listing/provenance and display handling finish.
+            return {
+                completedNormally: res.status !== null && res.signal === null,
+                result: {
+                    ...(0, normalizeBuildOutput_1.normalizeBuildOutput)(captured, execution.projectRoot),
+                    stdout: captured.stdout,
+                    stderr: captured.stderr,
+                },
+            };
+        };
+        const result = options.forceEmitProvenance === true
+            ? (0, runExternalEmitProvenance_1.runExternalEmitProvenance)({
+                args,
+                binary: execution.tsgo.binary,
+                cwd: execution.compilerSelection.compilerArgsCwd,
+                env,
+                run,
+            })
+            : run(args).result;
+        const displayed = applyEmittedFileListing(result, userListedEmitted);
+        const emittedFiles = displayed.emittedFiles ?? [];
+        if (options.quiet === false) {
+            // A producer's last stdout line (the tsgo statistics block ends without a
+            // newline) must not swallow the summary's first marker.
+            if (displayed.stdout.length !== 0 && !displayed.stdout.endsWith("\n")) {
+                displayed.stdout += "\n";
+            }
+            displayed.stdout += verboseBuildSummary(execution, options, emittedFiles);
+        }
+        return (0, normalizeBuildOutput_1.normalizeBuildOutput)(displayed, execution.projectRoot);
+    }
+    /**
+     * Retain emitted-file metadata while displaying only user-selected listing.
+     * The caller supplies the original effective option before internally added
+     * reporting flags. Status, diagnostics and other producer facts are
+     * preserved. The supported tsgo producer reports absolute emitted paths. When
+     * listing is hidden, remaining stdout uses LF separators and loses trailing
+     * newlines; this transformation does not preserve every original output
+     * byte.
+     *
+     * @evidence contracts/common.md#principled-implementation TSFILE lines establish reported emitted files, while the original effective boolean alone owns their user-visible display; internal reporting does not enable the user's option.
+     * @evidence contracts/common.md#clear-and-simple-design One pure operation separates metadata collection from display and is shared by the actual direct compiler build path.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No producer status or diagnostic is replaced, and option presence is not substituted for the effective config and ordered assignment value.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains original option ownership, internally added reporting and retained producer facts.
+     * @evidence contracts/portability.md#os-neutral-implementation Reported paths are interpreted with native path.resolve, not URL or inode identity. The supported tsgo TSFILE producer supplies normalized absolute paths from its Program cwd; relative malformed reports would instead use this process cwd and are not certified by that protocol. No filesystem capability or existence is queried here.
+     * @evidence contracts/performance.md#efficient-algorithms Parsing and optional stripping each scan complete captured output, with native path normalization for matched records, result property copying and intermediate line/path arrays. Processing and transient text/path storage follow output and reported path bytes; there is no output-size ceiling here.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each completed producer result has its own bytes and requested display value; no history or shared computation is retained.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The copied result and emitted-file array transfer to the caller without retaining a process or handle.
+     */
+    function applyEmittedFileListing(result, displayListing) {
+        const emittedFiles = parseEmittedFiles(result.stdout);
+        return {
+            ...result,
+            emittedFiles,
+            stdout: displayListing || emittedFiles.length === 0
+                ? result.stdout
+                : stripEmittedFileLines(result.stdout),
+        };
+    }
+    BuildExecution.applyEmittedFileListing = applyEmittedFileListing;
+    /**
+     * The `--verbose` summary for the direct-tsgo lane, in the shape
+     * `cmd/ttsc/build.go` already prints on the native-host lane.
+     *
+     * Verbosity is a launcher-owned presentation concern: which lane `runBuild`
+     * selects is an implementation detail the user cannot see, so a documented
+     * flag must not change meaning with it.
+     *
+     * `sites=0` is a fact about this lane rather than a placeholder: it runs
+     * without a transform-stage host, even if check-stage plugins ran earlier. An
+     * emitting build with no files prints `emitted=0 files`; an analysis-only
+     * build prints no emitted count.
+     */
+    function verboseBuildSummary(execution, options, emittedFiles) {
+        const lines = [
+            `// ttsc: tsconfig=${execution.tsconfig} cwd=${execution.cwd} sites=0 emit=${options.emit !== false}`,
+        ];
+        if (options.emit !== false) {
+            lines.push(`// ttsc: emitted=${emittedFiles.length} files`);
+            for (const file of emittedFiles) {
+                lines.push(`  + ${node_path_1.default.relative(execution.cwd, file) || file}`);
+            }
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    /**
+     * Run every check-stage plugin in order, short-circuiting on the first
+     * non-zero exit. Aggregates diagnostics and output across all check plugins.
+     * Only the actual check verb negotiates its same-generation sidecar. Fix and
+     * format are effectful native verbs even though their descriptor has check
+     * stage; they keep their original streams/status without a check graph.
+     * Undeclared transport leaves the host's original argv and input contract
+     * intact.
+     */
+    function runNativeCheckPlugins(options, execution, timing) {
+        let out = {
+            diagnostics: [],
+            status: 0,
+            stdout: "",
+            stderr: "",
+        };
+        for (const plugin of execution.nativePlugins.filter((plugin) => plugin.stage === "check")) {
+            const args = NativePluginArguments_1.NativePluginArguments.createNativeCheckArgs(execution, options, plugin);
+            const result = (0, runNativeCheckWithObservations_1.runNativeCheckWithObservations)(plugin, (extraArgs) => runNativePluginCommand(plugin, [...args, ...extraArgs], options, execution, "ttsc.check", timing, `ttsc check plugin ${plugin.name} time`, TsgoArguments_1.TsgoArguments.createNativeTsgoArgs(options)), args[0]);
+            out = (0, appendBuildOutput_1.appendBuildOutput)(out, result);
+            if (result.status !== 0) {
+                return out;
+            }
+        }
+        return out;
+    }
+    /**
+     * Ask every check-stage host that declares the `projectInputs` capability for
+     * the files its rules read beyond the TypeScript Program, and merge the
+     * answers into one snapshot for watch and cache invalidation.
+     *
+     * Launch, nonzero query results and invalid snapshots throw instead of
+     * leaving a declared dependency unwatched. The selected project root must
+     * agree with every contributing snapshot after filesystem identity
+     * resolution.
+     *
+     * @evidence contracts/common.md#principled-implementation Only capable check hosts are queried, their JSON and native paths are validated, and identity-based merging rejects contributions anchored at another project.
+     * @evidence contracts/common.md#clear-and-simple-design Discovery owns host selection/execution while parsing and alias-preserving reconciliation remain dedicated operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported hosts are not probed by guessed names, and invalid query output is rejected instead of silently dropping declared dependencies.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain dependency purpose, thrown query/validation failures and shared-root enforcement.
+     * @evidence contracts/portability.md#os-neutral-implementation Native spawning preserves cwd/argv and the path classifier plus identity resolver distinguish valid native spelling from physical filesystem equality.
+     * @evidence contracts/performance.md#efficient-algorithms Selection scans P plugins; each capable check host runs once after argv/env publication and delegated runtime probes. Complete output read/JSON/path validation and identity resolution include native capability/ancestor lookup and path-text costs. Merging indexes identities/aliases and sorts unique plus declared spellings; native duration and report bytes are not capped here.
+     * @evidence contracts/performance.md#reuse-equivalent-work A single merge identity context reuses repeated path resolution across hosts; each host query remains necessary because its rules may contribute distinct effect-dependent inputs.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Snapshots and identity memoization grow with contributed path/alias bytes during synchronous discovery; the result transfers to the watch/cache caller. No process timeout or report ceiling is supplied here. Native capture/probe cleanup remains delegated and may be best effort; returning a snapshot does not certify descendant release.
+     */
+    function discoverNativeProjectInputs(options, execution) {
+        const snapshots = [];
+        for (const plugin of execution.nativePlugins.filter((candidate) => candidate.stage === "check" &&
+            candidate.capabilities?.projectInputs === true)) {
+            const res = (0, spawnNative_1.spawnNative)(plugin.binary, NativePluginArguments_1.NativePluginArguments.createNativeProjectInputsArgs(execution, plugin), {
+                cwd: execution.projectRoot,
+                env: nativePluginEnv(options.env, execution, plugin),
+                encoding: "utf8",
+            });
+            if (res.error) {
+                throw new Error(`ttsc.project-inputs: failed to spawn ${plugin.binary}: ${res.error.message}`);
+            }
+            const stdout = (0, outputText_1.outputText)(res.stdout).trim();
+            if (res.status !== 0) {
+                const detail = (0, outputText_1.outputText)(res.stderr).trim() || stdout;
+                throw new Error(`ttsc.project-inputs: ${plugin.name ?? plugin.binary} failed${detail ? `: ${detail}` : ""}`);
+            }
+            const snapshot = (0, parseProjectInputSnapshot_1.parseProjectInputSnapshot)(stdout, plugin);
+            snapshots.push(snapshot);
+        }
+        return (0, mergeProjectInputSnapshots_1.mergeProjectInputSnapshots)(execution.projectRoot, snapshots);
+    }
+    BuildExecution.discoverNativeProjectInputs = discoverNativeProjectInputs;
+    /**
+     * Spawn a single native plugin binary with the given args and return the
+     * normalized build result. `label` is used in the thrown error message so the
+     * caller's context (e.g. `"ttsc.check"` or `"ttsc.build"`) is preserved.
+     *
+     * Nonzero exits are results; launch failures throw. Timing records the
+     * returned spawn result before its launch error is reported. Environment,
+     * capture/read or other thrown failures can occur before timing is recorded;
+     * the elapsed interval also includes environment preparation, not only
+     * execution of the selected plugin.
+     *
+     * @evidence contracts/common.md#principled-implementation The selected plugin receives the composed invocation context, and actual exit status/output become a normalized result while native launch errors remain thrown failures.
+     * @evidence contracts/common.md#clear-and-simple-design One command boundary owns environment publication, timing and output normalization for native build and check phases.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Execution uses the loaded binary and supported protocol rather than patching its implementation or manufacturing success on launch failure.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes result failures, thrown launch failures and error/timing label attribution.
+     * @evidence contracts/portability.md#os-neutral-implementation spawnNative receives executable and argv separately with native project cwd; platform-aware environment helpers publish compiler/context payloads without shell interpolation.
+     * @evidence contracts/performance.md#efficient-algorithms The interval includes environment key scans, linked payload serialization and delegated runtime capability probes before plugin launch. Argv/native work, complete capture/decode, timing label formatting and diagnostic normalization follow their actual text/record sizes; one wrapper call does not bound native duration or output bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A requested effectful plugin command cannot be reused merely because argv matches; scheduling and shared-host compatibility belong to orchestration.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Timing lines stay in the build-owned ledger and returned diagnostic/output records transfer to the caller. No timeout or output ceiling is supplied here; delegated capture cleanup is best effort and does not certify native descendant release. This wrapper stores no child handle or historical result.
+     */
+    function runNativePluginCommand(plugin, args, options, execution, label, timing, timingLabel, tsgoArgs) {
+        const startedAt = process.hrtime.bigint();
+        const res = (0, spawnNative_1.spawnNative)(plugin.binary, args, {
+            cwd: execution.projectRoot,
+            env: nativePluginEnv(options.env, execution, plugin, tsgoArgs),
+            encoding: "utf8",
+        });
+        BuildTiming_1.BuildTiming.recordTiming(timing, timingLabel, startedAt);
+        if (res.error) {
+            throw new Error(`${label}: failed to spawn ${plugin.binary}: ${res.error.message}`);
+        }
+        return (0, normalizeBuildOutput_1.normalizeBuildOutput)({
+            processCompletedNormally: res.status !== null && res.signal === null,
+            status: res.status ?? 1,
+            stdout: (0, outputText_1.outputText)(res.stdout),
+            stderr: (0, outputText_1.outputText)(res.stderr),
+        }, execution.projectRoot);
+    }
+    BuildExecution.runNativePluginCommand = runNativePluginCommand;
+    /**
+     * Resolve all runtime context needed for a build: cwd, tsconfig path, project
+     * root, tsgo binary location, and the loaded native plugin list. Centralised
+     * here so every code path in `runBuild` shares the same resolution logic.
+     *
+     * A supplied resolvedProject preserves the caller's lexical project identity.
+     * 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.
+     *
+     * @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.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Loader failures remain explicit setup failures rather than empty successful plugin selection; preserving lexical project identity avoids mixed alias assumptions without patching filesystem APIs.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe selected context, supplied-project meaning and the exact returned-versus-thrown failure boundary.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path and binary resolvers select cwd/project/executables; TTSC_CACHE_DIR uses platform-aware environment lookup and already-selected project spelling is not independently canonicalized again.
+     * @evidence contracts/performance.md#efficient-algorithms Initial project resolution (unless supplied) and compiler selection precede plugin admission. Admission and loading can separately resolve entries; config bytes, module/native search, environment-name/path text and delegated source builds/capability probes remain call costs. The no-entry branch avoids loading but can invoke the supplied callback.
+     * @evidence contracts/performance.md#reuse-equivalent-work The supplied project reference and returned selection records serve multiple phases without a second top-level context acquisition. They are not a frozen filesystem or deep immutable snapshot; the build/session owns their continued authority, while source-artifact reuse follows loader validity.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This returns selection metadata rather than resident child handles; persistent plugin build caches are owned by the loader, while context lifetime belongs to the build/session.
+     */
+    function resolveExecutionContext(options) {
+        const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
+        const compilerSelection = CompilerProjectSelection_1.CompilerProjectSelection.read(options);
+        const project = compilerSelection.project;
+        const tsconfig = project.path;
+        const projectRoot = project.root;
+        const tsgo = (0, resolveTsgo_1.resolveTsgo)({ ...options, cwd: projectRoot });
+        let pluginSetupFailure;
+        let nativePlugins = [];
+        try {
+            if (compilerSelection.inspectionError === undefined &&
+                (0, hasProjectPluginEntries_1.hasProjectPluginEntries)(project, options.plugins)) {
+                nativePlugins = (0, loadProjectPlugins_1.loadProjectPlugins)({
+                    binary: (0, resolveBinary_1.resolveBinary)(options) ?? "",
+                    cacheDir: options.cacheDir ??
+                        SidecarEnvironment_1.SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
+                    cwd,
+                    entries: options.plugins,
+                    env: (0, inheritedSidecarEnv_1.inheritedSidecarEnv)(options.env, options.binary),
+                    onWatchInputs: options.onWatchInputs,
+                    pluginConfigDir: options.pluginConfigDir,
+                    projectRoot,
+                    tsconfig,
+                }).nativePlugins;
+            }
+            else {
+                options.onWatchInputs?.([]);
+            }
+        }
+        catch (error) {
+            pluginSetupFailure = {
+                diagnostics: [],
+                status: 2,
+                stdout: "",
+                stderr: `${error instanceof Error ? error.message : String(error)}\n`,
+            };
+        }
+        return {
+            compilerSelection,
+            cwd,
+            nativePlugins,
+            pluginConfigDir: (0, resolvePluginConfigDir_1.resolvePluginConfigDir)({
+                cwd,
+                pluginConfigDir: options.pluginConfigDir,
+            }),
+            pluginSetupFailure,
+            project,
+            projectNoEmit: project.compilerOptions.noEmit === true,
+            projectRoot,
+            rewriteRelativeImportExtensionsForEmit: options.emit === true &&
+                project.compilerOptions.allowImportingTsExtensions === true,
+            tsgo,
+            tsconfig,
+        };
+    }
+    BuildExecution.resolveExecutionContext = resolveExecutionContext;
+    /**
+     * Extract `TSFILE: <path>` lines from tsgo stdout and return the absolute
+     * paths. tsgo emits these when `--listEmittedFiles` is passed.
+     */
+    function parseEmittedFiles(stdout) {
+        const out = [];
+        for (const line of stdout.split(/\r?\n/)) {
+            const match = line.match(/^TSFILE:\s*(.+)$/);
+            if (match?.[1]) {
+                out.push(node_path_1.default.resolve(match[1].trim()));
+            }
+        }
+        return out;
+    }
+    /**
+     * Remove `TSFILE:` lines from tsgo stdout so they do not appear in the
+     * user-facing output after they have been parsed into `emittedFiles`.
+     */
+    function stripEmittedFileLines(stdout) {
+        return stdout
+            .split(/\r?\n/)
+            .filter((line) => !/^TSFILE:\s*/.test(line))
+            .join("\n")
+            .replace(/\n+$/, "");
+    }
+})(BuildExecution || (exports.BuildExecution = BuildExecution = {}));
+//# sourceMappingURL=BuildExecution.js.map