ttsc 0.30.3 → 0.31.0

package/lib/internal/CompilerResultAdapter.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProject = runProject;
+exports.runTransformation = runTransformation;
+exports.classifyException = classifyException;
+exports.toCompilerTransformation = toCompilerTransformation;
+exports.normalizeError = normalizeError;
+const createProcessDiagnostic_1 = require("../compiler/internal/build/createProcessDiagnostic");
+const serializeCompilerError_1 = require("./serializeCompilerError");
+/**
+ * Run the selected compile task once and adapt its returned or thrown outcome.
+ *
+ * @evidence contracts/common.md#principled-implementation The original task runs once; its output/status/diagnostics or thrown error determine the public result kind.
+ * @evidence contracts/common.md#clear-and-simple-design One try/catch joins the task owner with the existing compile and exception adapters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No native task, output or error is substituted; caught values retain the existing serialization and classification policy.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence states exact invocation and returned/thrown ownership.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The task owner chooses native files/processes; this boundary chooses only result adaptation and no independent platform policy.
+ * @evidence contracts/performance.md#efficient-algorithms Cost includes the arbitrary selected task, diagnostic scan and any process-diagnostic construction or error serialization/classification; the fixed envelope does not bound those costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter coordinates no reusable native producer or cached outcome.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned producer references transfer to the caller; task resources and their lifetime remain with the task owner.
+ */
+function runProject(task) {
+    try {
+        return toCompilerResult(task());
+    }
+    catch (error) {
+        return {
+            error: normalizeError(error),
+            kind: classifyException(error),
+            type: "exception",
+        };
+    }
+}
+/**
+ * Run the selected transform task once, preserving its optional observations.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful and failed build outcomes retain source/advisory values while thrown outcomes use the existing exception policy.
+ * @evidence contracts/common.md#clear-and-simple-design One try/catch invokes the selected task and delegates to the transform result adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter neither reconstructs native observations nor replaces the actual task with a result certificate.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence distinguishes selected execution from its observation adaptation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The task owns its native platform boundaries; this function selects no path, process or filesystem policy.
+ * @evidence contracts/performance.md#efficient-algorithms The task cost is delegated in full, followed by diagnostic scanning, fixed optional-field projection and exceptional serialization/classification when needed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No completed or in-flight transform is cached by this adapter.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned source/advisory references remain caller-owned; the task owns native resource acquisition and retirement.
+ */
+function runTransformation(task) {
+    try {
+        return toCompilerTransformation(task());
+    }
+    catch (error) {
+        return {
+            error: normalizeError(error),
+            kind: classifyException(error),
+            type: "exception",
+        };
+    }
+}
+/**
+ * Best-effort classifier for the `kind` field of `IException`. Pattern- matches
+ * the real prefixes thrown inside this package:
+ *
+ * - Plugin: messages from `loadProjectPlugins.ts` / `buildSourcePlugin.ts` start
+ *   with `ttsc: plugin "..."` or `ttsc: package "..." declares ...`, and
+ *   transform-time spawn failures start with `ttsc.transform:` /
+ *   `ttsc.transform.check:`. The Go-toolchain missing envelope also surfaces
+ *   here.
+ * - Host: everything else under the `ttsc:` umbrella — the bare `ttsc:` strings
+ *   from `packageRootDir.ts`, `ttsc: TypeScript-Go executable not found`
+ *   (`resolveTsgo.ts`), `ttsc: failed to spawn native compiler host`
+ *   (`transformProjectInMemory.ts`), and tsconfig / extended-tsconfig shapes
+ *   from `readProjectConfig.ts`.
+ * - Anything else falls back to `"unknown"` so embedders always see the field set
+ *   per the documented contract.
+ *
+ * Order matters: plugin patterns must run before the generic `ttsc:` test
+ * because every plugin message also starts with `ttsc:`.
+ */
+/**
+ * Classify the observed message using the existing plugin-before-host patterns.
+ *
+ * @evidence contracts/common.md#principled-implementation Original plugin-prefix precedence and host fallback are retained; unreadable message inspection yields unknown.
+ * @evidence contracts/common.md#clear-and-simple-design One guarded message extraction precedes the two existing pattern groups.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification is best-effort message policy, not a certificate of exception origin or native process ownership.
+ * @evidence contracts/common.md#meaningful-documentation The adjacent native paragraphs describe actual prefix shapes, ordering and unknown fallback.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Message matching inspects no filesystem, executable or native platform capability.
+ * @evidence contracts/performance.md#efficient-algorithms Message inspection can invoke existing Error property behavior; pattern work visits selected message text and extraction failures return unknown. Message size is not bounded here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Classification coordinates no reusable operation or outcome cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned kind is retained by callers; this operation acquires no resource or registry.
+ */
+function classifyException(error) {
+    let message;
+    try {
+        const description = error instanceof Error
+            ? error.message
+            : typeof error === "string"
+                ? error
+                : error !== null && typeof error === "object"
+                    ? Object.getOwnPropertyDescriptor(error, "message")?.value
+                    : undefined;
+        message = typeof description === "string" ? description : "";
+    }
+    catch {
+        return "unknown";
+    }
+    if (
+    // Match every plugin-origin shape with verb-anchored patterns so a
+    // host-path containing the literal token `plugin` (e.g.
+    // `TTSC_BINARY=/opt/cache/plugins/ttsc-bin`) does not misclassify
+    // as kind="plugin". Each alternative anchors at the start of the
+    // message to capture the verb, not anywhere later in the line:
+    //
+    //   - `ttsc: plugin "..."` / `ttsc: package "..."` — from
+    //     loadProjectPlugins.ts
+    //   - `ttsc: building plugin "..."` / `ttsc: reading go.mod for
+    //     plugin "..."` — from buildSourcePlugin.ts
+    //   - `ttsc.transform:` / `ttsc.transform.check:` — from
+    //     transformProjectInMemory.ts
+    //   - `ttsc-plugin:` — legacy prefix kept for compatibility
+    //   - `go toolchain` — the goToolchainNotFoundMessage envelope
+    /^ttsc:\s*plugin\b|^ttsc:\s*package\b|^ttsc:\s*building plugin\b|^ttsc:\s*reading go\.mod for plugin\b|^ttsc\.transform[.:]|^ttsc-plugin:|go toolchain/i.test(message)) {
+        return "plugin";
+    }
+    if (/^ttsc:|tsconfig|extended tsconfig|TypeScript-Go|native compiler host/i.test(message)) {
+        return "host";
+    }
+    return "unknown";
+}
+/**
+ * Adapt a compile producer outcome, preserving its output record reference.
+ * Common: Principled implementation: Status zero without error diagnostics
+ * succeeds; every other result fails and an empty diagnostic list receives the
+ * original process diagnostic. Common: Clear and simple design: One
+ * status/diagnostic guard constructs success or failure while preserving output
+ * identity. Common: Prohibited implementation shortcuts: Warning diagnostics
+ * are not converted to errors and nonzero process outcomes are not promoted to
+ * success. Common: Meaningful documentation: The native sentence identifies
+ * output-reference preservation rather than copied or certified output.
+ * Applicability: Native platform boundary: This is result-data policy; the
+ * process diagnostic owner formats already reported outcome values.
+ * Performance: Computation cost: Diagnostic classification scans until an
+ * error; otherwise a fixed envelope retains output/diagnostic references, with
+ * delegated process-diagnostic text work on empty failures. Applicability: Work
+ * reuse: No producer or previous result is reused by this adapter.
+ * Applicability: Resource ownership: Output/diagnostic references transfer
+ * through the return value and no independent cache or resource is acquired.
+ */
+function toCompilerResult(project) {
+    const { output, result } = project;
+    if (result.status === 0 && !hasErrorDiagnostics(result.diagnostics)) {
+        return {
+            ...(result.diagnostics.length === 0
+                ? {}
+                : { diagnostics: result.diagnostics }),
+            output,
+            type: "success",
+        };
+    }
+    return {
+        diagnostics: result.diagnostics.length === 0
+            ? [(0, createProcessDiagnostic_1.createProcessDiagnostic)(result)]
+            : result.diagnostics,
+        output,
+        type: "failure",
+    };
+}
+/**
+ * Adapt source/build outcome and copy optional advisory references only when
+ * present.
+ *
+ * @evidence contracts/common.md#principled-implementation Undefined advisory fields are omitted; present empty/false values and references survive both success and failure, alongside the existing diagnostic decision.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-field projection is shared by the two result branches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter does not manufacture graph, host-read or completeness proof and does not discard it solely because the build failed.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence states omission policy and reference ownership.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Advisory values are passed through without native path normalization or capability inference.
+ * @evidence contracts/performance.md#efficient-algorithms Fixed optional-field checks retain references without scanning map text; diagnostic classification and empty-failure formatting have their delegated data costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adaptation coordinates no reusable compiler/worker or outcome cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned source/advisory objects remain reachable under caller ownership; this operation owns no process, lease or historical registry.
+ */
+function toCompilerTransformation(project) {
+    const { dependencies, dependenciesComplete, graph, hostInputHashes, hostInputProofFailures, hostInputRealpaths, hostInputs, observationsComplete, pluginSources, result, sourceMaps, typescript, volatile, } = project;
+    const advisoryFields = {
+        ...(dependencies === undefined ? {} : { dependencies }),
+        ...(dependenciesComplete === undefined ? {} : { dependenciesComplete }),
+        ...(graph === undefined ? {} : { graph }),
+        ...(hostInputHashes === undefined ? {} : { hostInputHashes }),
+        ...(hostInputProofFailures === undefined ? {} : { hostInputProofFailures }),
+        ...(hostInputRealpaths === undefined ? {} : { hostInputRealpaths }),
+        ...(hostInputs === undefined ? {} : { hostInputs }),
+        ...(observationsComplete === undefined ? {} : { observationsComplete }),
+        ...(pluginSources === undefined ? {} : { pluginSources }),
+        ...(sourceMaps === undefined ? {} : { sourceMaps }),
+        ...(volatile === undefined ? {} : { volatile }),
+    };
+    if (result.status === 0 && !hasErrorDiagnostics(result.diagnostics)) {
+        return {
+            ...(result.diagnostics.length === 0
+                ? {}
+                : { diagnostics: result.diagnostics }),
+            ...advisoryFields,
+            type: "success",
+            typescript,
+        };
+    }
+    return {
+        ...advisoryFields,
+        diagnostics: result.diagnostics.length === 0
+            ? [(0, createProcessDiagnostic_1.createProcessDiagnostic)(result)]
+            : result.diagnostics,
+        type: "failure",
+        typescript,
+    };
+}
+/**
+ * Report whether the supplied diagnostics contain an error category. Common:
+ * Principled implementation: Only the literal error category changes this
+ * outcome; other diagnostic categories remain advisory. Common: Clear and
+ * simple design: A short-circuiting predicate expresses the existing success
+ * guard directly. Common: Prohibited implementation shortcuts: Status and
+ * message text are not guessed as substitutes for diagnostic category. Common:
+ * Meaningful documentation: The native sentence identifies the supplied
+ * diagnostic population and category decision. Applicability: Native platform
+ * boundary: Category comparison accesses no native platform boundary.
+ * Performance: Computation cost: The scan visits at most the supplied
+ * diagnostic count and stops at the first error. Applicability: Work reuse:
+ * This predicate coordinates no cached or in-flight result. Applicability:
+ * Resource ownership: A boolean is returned without retaining diagnostic
+ * history or acquiring a resource.
+ */
+function hasErrorDiagnostics(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.category === "error");
+}
+/**
+ * Serialize the actual thrown value through the existing compiler error owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The original serializer receives the exact thrown value rather than a guessed error message.
+ * @evidence contracts/common.md#clear-and-simple-design One delegation shares the compiler error representation with synchronous and worker result adapters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Serialization does not manufacture a native exception or replace the task that threw it.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence names the actual value and owning serializer.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The error representation owner inspects data rather than native platform capability.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The existing serializer owns value traversal, reference tracking and encoded allocation; this adapter adds no independent serialization algorithm or size bound.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This call coordinates no reusable producer or previous serialized result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned serialized data transfers to the caller; traversal state and exceptional value inspection remain with the serializer owner.
+ */
+function normalizeError(error) {
+    return (0, serializeCompilerError_1.serializeCompilerError)(error);
+}
+//# sourceMappingURL=CompilerResultAdapter.js.map

package/lib/internal/CompilerResultAdapter.js.map

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

package/lib/internal/E2ETrace.d.ts

@@ -0,0 +1,219 @@
+import type { ChildProcess, SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
+/**
+ * Private opt-in observations of maintained process primitives and separately
+ * classified runtime source preparation inputs, watch-shutdown phases and
+ * computed capability cache gates.
+ *
+ * TTSC_E2E_TRACE selects coordinator-owned scratch. Each writer owns one JSONL
+ * and its raw returned-buffer payloads. Returned strings are recorded as text,
+ * without claiming their encoding reconstructs original process bytes. Missing
+ * or invalid evidence is a measurement failure, never permission to change a
+ * product result. Times are call bounds; a synchronous return does not reveal
+ * an exact OS start time or descendant close. No trace output is written to
+ * product streams.
+ *
+ * @evidence contracts/common.md#principled-implementation Actual primitive call bounds and returned PID/status/signal/error/output remain separate from source-preparation inputs and caller-observed shutdown phases; failed admission or sink writes do not synthesize success or replace product results.
+ * @evidence contracts/common.md#clear-and-simple-design A private token connects one attempt and returned result; per-process writer state owns serialization, payload budget and append-close IO.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The helper neither patches child_process nor infers launches from wrapper call counts; no tests/utils or public product API is introduced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates observation from lifecycle ownership and documents opt-in failure and time-bound limitations.
+ * @evidence contracts/portability.md#os-neutral-implementation Native Node path and filesystem APIs admit an absolute scratch root; argv/cwd retain selected representations and returned PID/signal are native observations, not shell syntax or OS defaults.
+ * @evidence contracts/performance.md#efficient-algorithms Each event serializes its actual metadata and returned payload bytes. JSON encoding and string-to-byte conversion temporarily precede budget admission; encoded metadata and payload IO scale with those inputs and add synchronous latency.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each primitive invocation has independent effects; matching command/argv cannot share its observation as a new execution.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One writer retains root/nonce/counters until process exit. Each sink write closes in finally; payloads are capped at 64MiB each and writer output at 256MiB including reserved integrity metadata. Coordinator owns scratch reclamation and writer/child settlement; IO failure can leave partial files and missing evidence.
+ */
+export declare namespace E2ETrace {
+    /**
+     * Observe one runtime cleanup without repeating ownership or filesystem work.
+     *
+     * The returned observer shares an invocation across actual lock, ownership,
+     * removal and failure phases. It records caller-computed values only.
+     * Disabled tracing allocates no writer; observer errors never replace cleanup
+     * results.
+     *
+     * @evidence contracts/common.md#principled-implementation One token binds the caller's actual cleanup phases and computed classification; an event does not establish an unobserved owner incarnation or successful deletion.
+     * @evidence contracts/common.md#clear-and-simple-design A private optional callback reuses the existing writer, metadata schema and error absorption; owner observations preserve the existing scan's values without changing its policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No ownership scan, liveness probe, file observation, policy decision or retry is performed by tracing.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes computed phases from OS ownership proof and documents disabled and failed-sink behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation The caller's native directory coordinates and error code are recorded without path rewriting, shell commands or OS-name inference.
+     * @evidence contracts/performance.md#efficient-algorithms Enabled metadata encoding and synchronous sink IO scale with actual field/error text; disabled mode returns before copying argv or creating writer state.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each cleanup occurrence owns its effect and observer token; previous classifications cannot certify a later cleanup.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One callback/token lives with the cleanup call and retains no history. Existing writer budgets, append-close lifecycle and coordinator scratch ownership remain unchanged.
+     */
+    function runtimeCleanup(directory: string, runtimeCacheDir: string, origin?: "ttsx-runtime-cleanup" | "runtime-clean-selection"): ((phase: string, ownership?: string, error?: unknown, ownerObservation?: {
+        record: string;
+        owner?: {
+            hostname: string;
+            pid: number;
+        };
+        result: string;
+        errorCode?: string;
+    }) => void) | undefined;
+    /**
+     * Record already-computed capability cache gates as non-process observations.
+     * Disabled tracing performs no sink IO. Writer admission, budgets and failed
+     * sink handling are shared with the other private observations; no gate is
+     * recomputed and no product result is replaced by an observer failure.
+     *
+     * @evidence contracts/common.md#principled-implementation Caller-supplied gate values and actual publication branches are observations, not fabricated producer proof or process outcomes.
+     * @evidence contracts/common.md#clear-and-simple-design One capability event uses the existing private writer and schema without changing capability response fields.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No process, hash probe, public API or environment selector is added; observer failure remains inside the trace owner.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes computed gates from product evidence and states disabled and failed-sink behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Actual Node argv, cwd and writer identity retain their native representations under the existing absolute scratch admission.
+     * @evidence contracts/performance.md#efficient-algorithms Enabled metadata copying, serialization and synchronous sink IO scale with actual text sizes; disabled mode returns before those operations.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each occurrence reports its own decision and cannot substitute an earlier gate outcome.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This call retains no history or resource; the existing bounded writer owns append-close IO and coordinator-owned scratch lifetime.
+     */
+    function capabilityResolution(phase: string, data: Readonly<Record<string, string | number | boolean | null | undefined>>): void;
+    /**
+     * Record a watch-shutdown phase as a non-process observation. Callers report
+     * actual promise/callback outcomes and the received stop ID; observation time
+     * is not an OS exit time or proof of descendant termination. Disabled tracing
+     * performs no sink IO or metadata copying. Sink failures never replace the
+     * caller's promise, result, exception or protocol message.
+     *
+     * @evidence contracts/common.md#principled-implementation Actual caller-supplied phase metadata is recorded without treating observation as a join authority or synthesizing settlement.
+     * @evidence contracts/common.md#clear-and-simple-design One non-process event uses the existing private writer, invocation schema, budget and integrity path.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No promise or foreign process method is replaced; no product stream, public API, flag, configuration or test dependency is introduced.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes observed phase time and received stop ID from native lifecycle authority.
+     * @evidence contracts/portability.md#os-neutral-implementation Node supplies actual writer PID, argv, cwd and UTC metadata; the existing absolute native scratch admission owns path handling.
+     * @evidence contracts/performance.md#efficient-algorithms Enabled argv/metadata copying, JSON encoding and synchronous native sink IO scale with their text sizes and add latency; disabled mode returns before copying.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each phase occurrence describes a distinct caller observation; another occurrence cannot reuse an earlier outcome.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This call keeps no phase history or handle; the existing writer owns its 256MiB output limit, append-close writes and coordinator-owned scratch cleanup.
+     */
+    function watchShutdown(phase: string, data: Readonly<Record<string, string | number | boolean | null | undefined>>): void;
+    /**
+     * Observe the actual source string before runtime preparation, not a launch.
+     * UTF-16LE preserves JavaScript code units, including unpaired surrogates;
+     * these bytes represent the consumed string, not original disk or emit bytes.
+     * Optional served-emit coordinates report the caller's selected ownership
+     * metadata, not current artifact identity or successful preparation. Disabled
+     * An empty project build may instead report its actual returned failure
+     * envelope; that distinct event contains no consumed source or emit claim.
+     * Disabled tracing performs no sink IO or source conversion. Observer failure
+     * leaves the caller's preparation and exception behavior untouched.
+     *
+     * @evidence contracts/common.md#principled-implementation The caller supplies its already-read source, filename and selected format; the observation precedes unchanged preparation without certifying parsing success or executable identity. An empty project emit reports only its actual returned build envelope in a distinct failed event, preserving the original fallback and exception.
+     * @evidence contracts/common.md#clear-and-simple-design One non-process event and bounded raw-string payload use the existing private writer, invocation schema and integrity policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No source is reconstructed, product result replaced, syntax admitted, or launch inferred from this observation; no public product API or test dependency is introduced.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes consumed UTF-16 code units from disk bytes, process starts and preparation success.
+     * @evidence contracts/portability.md#os-neutral-implementation Native filenames and selected format remain caller metadata; Node's explicit utf16le encoding preserves source code units without filesystem case or module-format guessing.
+     * @evidence contracts/performance.md#efficient-algorithms Enabled source conversion and payload IO scale with twice the source code-unit count; returned build text is budget-checked and serialized by its actual size. Metadata encoding and synchronous sink IO add latency. Disabled tracing returns before conversion, and oversized source is rejected before allocation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each preparation observation concerns its actual caller input, not a shared compilation or historical execution answer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation retains no source history or handle; the existing writer owns bounded payload writes, failure metadata and coordinator-owned scratch cleanup.
+     */
+    function runtimePreparation(source: string, filename: string, selectedFormat: string, origin: string, emitAttribution?: {
+        emittedFile?: string;
+        moduleOptions: {
+            module?: string;
+            target?: string;
+        } | null;
+        sourceFile?: string;
+        selectedTsconfig?: string;
+        buildScope?: string;
+        /** Actual already-computed orphan cache gates or failed native write. */
+        orphanCache?: {
+            file?: string;
+            sourceHeld?: boolean;
+            expectedCompiler?: string;
+            currentCompiler?: string;
+            lowered?: boolean;
+            cacheKeyAvailable?: boolean;
+            error?: string;
+        };
+        nativeBuildFailure?: {
+            status: number;
+            stdout: string;
+            stderr: string;
+        };
+    }): void;
+    /**
+     * Observe supported child events without taking transport or kill ownership.
+     * Error monitoring preserves Node's ordinary unhandled-error behavior. Close
+     * releases these listeners; an unclosed child can retain them indefinitely.
+     *
+     * @evidence contracts/common.md#principled-implementation Actual spawn, exit and close events remain distinct; native child PID and code/signal are observations, not inferred wrapper counts or descendant joins.
+     * @evidence contracts/common.md#clear-and-simple-design One token owns four observation callbacks on the actual maintained ChildProcess and removes remaining callbacks at close.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported event listeners and errorMonitor neither replace foreign methods nor convert an unhandled error into handled success; process streams are not consumed here.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states event ownership, error behavior and unclosed-listener retention.
+     * @evidence contracts/portability.md#os-neutral-implementation Node's spawn/exit/close events and returned native PID/code/signal supply platform observations without guessed Unix state or exact OS start time.
+     * @evidence contracts/performance.md#efficient-algorithms Four listener registrations and bounded event count add actual metadata/error-byte serialization and native sink IO; caller event-loop scheduling and child runtime remain delegated.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work One actual child's lifecycle cannot certify an equivalent second launch.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Observation callbacks retain the token/child until actual close and then remove remaining listeners. No deadline or child termination is introduced; a caller's release of event-loop reference does not prove close.
+     */
+    function asynchronous(token: Token | undefined, child: ChildProcess): void;
+    /**
+     * Observe exactly one caller-owned synchronous primitive, preserving its
+     * returned object and any thrown exception. A thrown call leaves an attempt
+     * without a result, which cannot certify completed process observation.
+     *
+     * @evidence contracts/common.md#principled-implementation The operation is called once and its same result is returned; observer failure cannot substitute a command outcome.
+     * @evidence contracts/common.md#clear-and-simple-design This boundary pairs the shared before/after observer around a maintained actual primitive.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No foreign spawn method is replaced; maintained owners supply their unchanged actual call rather than reconstructed source.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states result identity, exception preservation and incomplete-attempt scope.
+     * @evidence contracts/portability.md#os-neutral-implementation Selected native command/argv/cwd accompany the actual returned Node PID/status/signal; the observer does not reinterpret the platform.
+     * @evidence contracts/performance.md#efficient-algorithms One primitive call delegates observer metadata/output-byte and native IO cost before returning; no retries or output traversals beyond the trace sink are added here.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work An independent effectful primitive call cannot be replaced with a matching historical result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The actual call owner retains process/output authority; the namespace sink owns trace-file writes and coordinator cleanup.
+     */
+    function synchronous<Result extends SpawnSyncReturns<string | Buffer>>(command: string, args: readonly string[], options: Pick<SpawnSyncOptions, "cwd" | "argv0">, origin: string, operation: () => Result, coordinatorRoot?: string | undefined): Result;
+    /**
+     * Observation metadata, not a process handle or execution authority.
+     *
+     * @evidence contracts/common.md#principled-implementation One invocation identity pairs selected arguments with honest before/after call bounds; no PID is claimed before native return.
+     * @evidence contracts/common.md#clear-and-simple-design A token holds only invocation metadata while module state owns the sink.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Fields do not substitute for a ChildProcess or certify start/close.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes observation metadata from execution ownership.
+     * @evidence contracts/portability.md#os-neutral-implementation Command/argv and optional cwd retain the native spawn inputs; inherited cwd is represented separately from explicit selection.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This token declares fields, not the observer algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This value coordinates no equivalent execution reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This value owns no process or file handle; writer and caller own their lifetimes.
+     */
+    interface Token {
+        /** Writer-local ordinal; writer pid and nonce complete its identity. */
+        invocation: string;
+        /**
+         * Selected process inputs, or actual writer argv for a non-process
+         * observation.
+         */
+        argv: string[];
+        /** Explicit cwd representation, or null for inherited cwd intent. */
+        cwd: string | null;
+        /** UTC bound before the owning primitive or non-process observation. */
+        lower: string;
+        /** Maintained observation owner, not an inferred child phase. */
+        origin: string;
+        /** Explicit argv[0] override, or null for the primitive's default. */
+        argv0: string | null;
+    }
+    /**
+     * Observe before one actual synchronous primitive, with disabled sink IO
+     * zero. The generated private broker can pass the same coordinator root
+     * through its internal arguments without changing the target's supplied
+     * environment.
+     *
+     * @evidence contracts/common.md#principled-implementation Empty opt-in returns undefined before sink work; native call execution remains entirely with the caller.
+     * @evidence contracts/common.md#clear-and-simple-design Admission and one attempt event return a small token for the same call.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Observation failures return no token rather than changing command execution or printing to its streams.
+     * @evidence contracts/common.md#meaningful-documentation Purpose and timing are explicit in native prose and token fields.
+     * @evidence contracts/portability.md#os-neutral-implementation Node validates an absolute coordinator root; cwd preserves supplied path/URL spelling or records inherited intent.
+     * @evidence contracts/performance.md#efficient-algorithms Argument copying and cwd text plus delegated sink encoding/native IO scale with input bytes; disabled mode returns before copying.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This observes an independent effectful call, not a reusable completed computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned metadata token owns no handle; namespace writer and actual spawn owner control resource lifetimes.
+     */
+    function begin(command: string, args: readonly string[], options: Pick<SpawnSyncOptions, "cwd" | "argv0">, origin: string, coordinatorRoot?: string | undefined): Token | undefined;
+    /**
+     * Record a returned primitive result without claiming a child close event.
+     * Native failures may return undefined streams; both null and undefined mean
+     * absent payload, without invalidating the writer or replacing the result.
+     *
+     * @evidence contracts/common.md#principled-implementation Native returned PID/status/signal/error and original returned buffers/string values remain distinct from attempt metadata and product outcomes; null or undefined streams retain absent payload references, and encoded returned text is not certified original child bytes.
+     * @evidence contracts/common.md#clear-and-simple-design One result event connects the token to optional raw stdout/stderr payload references.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed or missing PID is not counted as a launch, and absent output is not fabricated as empty bytes; genuine payload or sink failure still invalidates the writer without replacing the result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states returned-result scope, native absent-stream meaning and absence of descendant-close proof.
+     * @evidence contracts/portability.md#os-neutral-implementation Status and signal are used as returned by Node; there is no POSIX interpretation of Windows status or guessed start timestamp.
+     * @evidence contracts/performance.md#efficient-algorithms Actual returned text/buffer conversion, payload writes and metadata/error serialization scale with their bytes; budget admission does not bound prior conversion allocation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every returned result belongs to its own observed call and cannot stand in for another invocation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Result observation acquires no child ownership; namespace sink closes writes and coordinator retains/reclaims files after settlement.
+     */
+    function result(token: Token | undefined, returned: SpawnSyncReturns<string | Buffer>): void;
+}