ttsc 0.30.3 → 0.31.0

package/lib/internal/OwnedNativeProcess.d.ts

@@ -0,0 +1,66 @@
+import { type SpawnSyncOptions, type SpawnSyncReturns } from "node:child_process";
+/**
+ * Execute one command under the platform helper's process-tree owner.
+ * Cancellation closes the control pipe; completion is accepted only after the
+ * helper's joined child and empty-boundary receipt, never merely its exit
+ * code.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact command arguments and environment are sent to the selected native owner; its structurally checked completion receipt supplies tree-shutdown authority before callers release build resources. A missing or invalid proof retains private protocol storage and reports unknown retirement.
+ * @evidence contracts/common.md#clear-and-simple-design Node owns asynchronous streams and cancellation while the native helper owns OS containment and wait semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported helper versions and missing cleanup receipts reject; no ordinary uncontained spawn substitutes for cancellation safety.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the pipe and receipt ownership and the absence of a process-exit-only success path.
+ * @evidence contracts/portability.md#os-neutral-implementation The published platform helper resolver selects the executable; exact JSON argv/env avoid a new shell quoting layer, including explicit Windows verbatim command lines.
+ * @evidence contracts/performance.md#efficient-algorithms Output accumulation follows the caller's spawn buffer policy, while file-backed descriptor outputs remain streaming. Encoding and receipt serialization scale with actual payload bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each command has its own containment lifetime and cannot share a result based on matching arguments.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The completion owner waits for helper close and its tree receipt before removing private protocol storage; stream and abort listeners are removed on settlement. Unknown retirement retains the exact reported private path and rejects; qualified closure or external closure verification is required before reclaiming it.
+ */
+export declare namespace OwnedNativeProcess {
+    /**
+     * Run a command with Node's synchronous-result shape after real async
+     * joining. Explicit input bytes and standard output descriptors are
+     * supported. Shell, uid/gid, inherited stdin and additional descriptor modes
+     * are refused. Cancellation and timeout force termination of the owned native
+     * boundary; a custom softer kill signal is therefore refused. TTSC_BINARY
+     * retains its helper authority, so an override must implement this protocol
+     * version. The optional internal observer receives the actual retirement
+     * class even when cancellation or a compiler error rejects the operation.
+     * Unknown retirement preserves protocol inputs and does not certify child
+     * closure. Rejected receipts retain native lifetime fields as diagnostic
+     * causes. Output fields and extra receipt fields are omitted. Diagnostic data
+     * never authorizes release.
+     *
+     * Enabled private tracing may receive a frozen scalar copy of an accepted
+     * receipt through the existing retirement observer. The original helper has
+     * closed before that copy is made. It contains no command or environment
+     * data and cannot grant closure authority. Trace IO can change scheduling.
+     *
+     * @evidence contracts/common.md#principled-implementation A private request carries exact command/options and a structurally checked native receipt is required after helper close; cancellation returns only after joined and empty-boundary proof.
+     * @evidence contracts/common.md#clear-and-simple-design Control stdin is separate from target input, target output streams remain unchanged, and one finally owns listeners and private protocol storage.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported modes and incompatible helper overrides reject explicitly rather than falling back to an uncontained child or asserting cleanup from helper exit alone.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain supported descriptor/input modes, forced retirement, helper override compatibility and the opt-in frozen receipt observation's scheduling and authority limits; the namespace describes the native ownership split.
+     * @evidence contracts/portability.md#os-neutral-implementation The existing native helper resolver owns platform and override precedence; JSON argv/env and explicit Windows verbatim mode preserve the actual command boundary without an added shell layer.
+     * @evidence contracts/performance.md#efficient-algorithms Piped output is accumulated up to maxBuffer per stream and file-backed outputs stream through inherited descriptors. Input encoding processes only the supplied view bytes; protocol serialization and receipts scale with their payloads. Enabled tracing with an observer alone copies and freezes nine validated scalar fields without traversing arbitrary receipt payloads.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Commands can produce external effects and every admitted invocation has its own process boundary and result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Abort closes the control pipe, then helper close and its native retirement receipt are awaited before private storage is removed. Missing or failed cleanup proof rejects and retains the exact protocol path; a classified failed spawn removes unused storage. The observer transfers classification to the source-resource owner rather than manufacturing a joined result from helper exit; its optional frozen receipt copy lives with this invocation and may transfer to the caller without retaining streams or mutable receipt data.
+     */
+    function run(command: string, args: readonly string[], options: SpawnSyncOptions, signal?: AbortSignal, observeRetirement?: (state: "joined" | "not-started" | "unknown", reason?: string, observation?: Readonly<{
+        /** Original supervising child's PID, retained after its close. */
+        helperPid: number | undefined;
+        /** Target PID reported by the accepted native receipt. */
+        targetPid: number;
+        /** Accepted private protocol version. */
+        version: number;
+        /** Native target completion code, when supplied. */
+        status: number | null;
+        /** Native target completion signal, when supplied. */
+        signal: string | null;
+        /** Actual native cancellation classification. */
+        cancelled: boolean;
+        /** Accepted original-child join field. */
+        directChildJoined: boolean;
+        /** Accepted native containment-emptiness field. */
+        boundaryEmpty: boolean;
+        /** Accepted platform reaping mechanism. */
+        orphanReaping: string;
+    }>) => void): Promise<SpawnSyncReturns<string | Buffer>>;
+}

package/lib/internal/OwnedNativeProcess.js

@@ -0,0 +1,317 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OwnedNativeProcess = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const resolveBinary_1 = require("../compiler/internal/resolveBinary");
+/**
+ * Execute one command under the platform helper's process-tree owner.
+ * Cancellation closes the control pipe; completion is accepted only after the
+ * helper's joined child and empty-boundary receipt, never merely its exit
+ * code.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact command arguments and environment are sent to the selected native owner; its structurally checked completion receipt supplies tree-shutdown authority before callers release build resources. A missing or invalid proof retains private protocol storage and reports unknown retirement.
+ * @evidence contracts/common.md#clear-and-simple-design Node owns asynchronous streams and cancellation while the native helper owns OS containment and wait semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported helper versions and missing cleanup receipts reject; no ordinary uncontained spawn substitutes for cancellation safety.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the pipe and receipt ownership and the absence of a process-exit-only success path.
+ * @evidence contracts/portability.md#os-neutral-implementation The published platform helper resolver selects the executable; exact JSON argv/env avoid a new shell quoting layer, including explicit Windows verbatim command lines.
+ * @evidence contracts/performance.md#efficient-algorithms Output accumulation follows the caller's spawn buffer policy, while file-backed descriptor outputs remain streaming. Encoding and receipt serialization scale with actual payload bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each command has its own containment lifetime and cannot share a result based on matching arguments.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The completion owner waits for helper close and its tree receipt before removing private protocol storage; stream and abort listeners are removed on settlement. Unknown retirement retains the exact reported private path and rejects; qualified closure or external closure verification is required before reclaiming it.
+ */
+var OwnedNativeProcess;
+(function (OwnedNativeProcess) {
+    /**
+     * Run a command with Node's synchronous-result shape after real async
+     * joining. Explicit input bytes and standard output descriptors are
+     * supported. Shell, uid/gid, inherited stdin and additional descriptor modes
+     * are refused. Cancellation and timeout force termination of the owned native
+     * boundary; a custom softer kill signal is therefore refused. TTSC_BINARY
+     * retains its helper authority, so an override must implement this protocol
+     * version. The optional internal observer receives the actual retirement
+     * class even when cancellation or a compiler error rejects the operation.
+     * Unknown retirement preserves protocol inputs and does not certify child
+     * closure. Rejected receipts retain native lifetime fields as diagnostic
+     * causes. Output fields and extra receipt fields are omitted. Diagnostic data
+     * never authorizes release.
+     *
+     * Enabled private tracing may receive a frozen scalar copy of an accepted
+     * receipt through the existing retirement observer. The original helper has
+     * closed before that copy is made. It contains no command or environment
+     * data and cannot grant closure authority. Trace IO can change scheduling.
+     *
+     * @evidence contracts/common.md#principled-implementation A private request carries exact command/options and a structurally checked native receipt is required after helper close; cancellation returns only after joined and empty-boundary proof.
+     * @evidence contracts/common.md#clear-and-simple-design Control stdin is separate from target input, target output streams remain unchanged, and one finally owns listeners and private protocol storage.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported modes and incompatible helper overrides reject explicitly rather than falling back to an uncontained child or asserting cleanup from helper exit alone.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain supported descriptor/input modes, forced retirement, helper override compatibility and the opt-in frozen receipt observation's scheduling and authority limits; the namespace describes the native ownership split.
+     * @evidence contracts/portability.md#os-neutral-implementation The existing native helper resolver owns platform and override precedence; JSON argv/env and explicit Windows verbatim mode preserve the actual command boundary without an added shell layer.
+     * @evidence contracts/performance.md#efficient-algorithms Piped output is accumulated up to maxBuffer per stream and file-backed outputs stream through inherited descriptors. Input encoding processes only the supplied view bytes; protocol serialization and receipts scale with their payloads. Enabled tracing with an observer alone copies and freezes nine validated scalar fields without traversing arbitrary receipt payloads.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Commands can produce external effects and every admitted invocation has its own process boundary and result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Abort closes the control pipe, then helper close and its native retirement receipt are awaited before private storage is removed. Missing or failed cleanup proof rejects and retains the exact protocol path; a classified failed spawn removes unused storage. The observer transfers classification to the source-resource owner rather than manufacturing a joined result from helper exit; its optional frozen receipt copy lives with this invocation and may transfer to the caller without retaining streams or mutable receipt data.
+     */
+    async function run(command, args, options, signal, observeRetirement) {
+        signal?.throwIfAborted();
+        if (options.shell || options.uid !== undefined || options.gid !== undefined)
+            throw new Error("ttsc: owned native commands do not support shell, uid or gid overrides");
+        if (options.killSignal !== undefined &&
+            options.killSignal !== "SIGKILL" &&
+            options.killSignal !== 9)
+            throw new Error("ttsc: owned native commands require forced process-tree termination");
+        const inputMode = Array.isArray(options.stdio)
+            ? options.stdio[0]
+            : options.stdio;
+        if (inputMode === "inherit" ||
+            typeof inputMode === "number" ||
+            (Array.isArray(options.stdio) && options.stdio.length > 3))
+            throw new Error("ttsc: owned native commands require explicit input bytes and standard output descriptors");
+        const binary = (0, resolveBinary_1.resolveBinary)({ env: options.env });
+        if (binary === null)
+            throw new Error("ttsc: native process supervisor is unavailable");
+        // Convert all potentially throwing caller data before acquiring a process
+        // or protocol directory. An invalid encoding must not strand a helper.
+        const input = options.input;
+        const bytes = input === undefined
+            ? undefined
+            : typeof input === "string"
+                ? Buffer.from(input, options.encoding && options.encoding !== "buffer"
+                    ? options.encoding
+                    : "utf8")
+                : Buffer.from(new Uint8Array(input.buffer, input.byteOffset, input.byteLength));
+        const env = Object.fromEntries(Object.entries(options.env ?? process.env).filter((entry) => entry[1] !== undefined));
+        const payload = `${JSON.stringify({
+            version: 1,
+            command,
+            args: [...args],
+            cwd: node_path_1.default.resolve(options.cwd === undefined
+                ? process.cwd()
+                : typeof options.cwd === "string"
+                    ? options.cwd
+                    : (0, node_url_1.fileURLToPath)(options.cwd)),
+            env,
+            ...(bytes === undefined ? {} : { inputBase64: bytes.toString("base64") }),
+            windowsVerbatimArguments: options.windowsVerbatimArguments === true,
+            ...(options.argv0 === undefined ? {} : { argv0: options.argv0 }),
+            ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+        })}\n`;
+        const directory = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "ttsc-owned-process-"));
+        const resultFile = node_path_1.default.join(directory, "result.json");
+        let retirement = "not-started";
+        let observation;
+        const stdout = [];
+        const stderr = [];
+        const limit = options.maxBuffer ?? 1024 * 1024;
+        let overflow;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        const stdio = options.stdio;
+        const output = (index) => Array.isArray(stdio)
+            ? (stdio[index] ?? "pipe")
+            : stdio === "inherit" || stdio === "ignore"
+                ? stdio
+                : "pipe";
+        const child = (() => {
+            try {
+                return (0, node_child_process_1.spawn)(binary, ["__source-process", "--result", resultFile], {
+                    cwd: options.cwd,
+                    env: options.env ?? process.env,
+                    windowsHide: true,
+                    stdio: ["pipe", output(1), output(2)],
+                });
+            }
+            catch (error) {
+                node_fs_1.default.rmSync(directory, { recursive: true, force: true });
+                throw error;
+            }
+        })();
+        retirement = "unknown";
+        const cancel = () => child.stdin?.end();
+        child.stdin?.on("error", () => undefined);
+        const collect = (channel, chunk) => {
+            const count = channel === "stdout"
+                ? (stdoutBytes += chunk.length)
+                : (stderrBytes += chunk.length);
+            if (count <= limit)
+                (channel === "stdout" ? stdout : stderr).push(chunk);
+            else if (overflow === undefined) {
+                overflow = Object.assign(new Error("ttsc: owned command output exceeded maxBuffer"), { code: "ENOBUFS" });
+                cancel();
+            }
+        };
+        child.stdout?.on("data", (chunk) => collect("stdout", chunk));
+        child.stderr?.on("data", (chunk) => collect("stderr", chunk));
+        signal?.addEventListener("abort", cancel, { once: true });
+        let spawnError;
+        const closed = new Promise((resolve) => {
+            child.on("error", (error) => {
+                spawnError = error;
+            });
+            child.once("close", () => resolve());
+        });
+        // An abort after listener installation must not authorize target admission.
+        if (signal?.aborted)
+            cancel();
+        else {
+            child.stdin?.write(payload);
+        }
+        let originalFailure;
+        let failed = false;
+        try {
+            await closed;
+            if (spawnError !== undefined) {
+                // Node's failed spawn has no process owner or admitted target.
+                if (child.pid === undefined)
+                    retirement = "not-started";
+                throw spawnError;
+            }
+            let receipt;
+            try {
+                receipt = JSON.parse(node_fs_1.default.readFileSync(resultFile, "utf8"));
+            }
+            catch (cause) {
+                throw new Error("ttsc: native supervisor did not publish a completion receipt", { cause });
+            }
+            if (receipt === null ||
+                typeof receipt !== "object" ||
+                receipt.version !== 1 ||
+                !Number.isSafeInteger(receipt.pid) ||
+                receipt.pid < 0 ||
+                (receipt.status !== null &&
+                    (!Number.isSafeInteger(receipt.status) || receipt.pid === 0)) ||
+                (receipt.signal !== null &&
+                    (typeof receipt.signal !== "string" ||
+                        receipt.signal.length === 0)) ||
+                typeof receipt.cancelled !== "boolean" ||
+                (receipt.error !== undefined &&
+                    (typeof receipt.error?.code !== "string" ||
+                        typeof receipt.error?.message !== "string")) ||
+                receipt.cleanup?.directChildJoined !== true ||
+                receipt.cleanup?.boundaryEmpty !== true ||
+                !["owned", "os", "windows-job"].includes(receipt.cleanup.orphanReaping)) {
+                // The parsed receipt is untrusted diagnostic data, not closure proof.
+                // Project only lifetime fields and never traverse nested payloads.
+                const scalar = (value) => value !== null && typeof value === "object"
+                    ? { $ttscValue: Array.isArray(value) ? "array" : "object" }
+                    : value;
+                const diagnostic = receipt === null ||
+                    typeof receipt !== "object" ||
+                    Array.isArray(receipt)
+                    ? scalar(receipt)
+                    : {
+                        version: scalar(receipt.version),
+                        pid: scalar(receipt.pid),
+                        status: scalar(receipt.status),
+                        signal: scalar(receipt.signal),
+                        cancelled: scalar(receipt.cancelled),
+                        ...(receipt.error === undefined
+                            ? {}
+                            : {
+                                error: receipt.error !== null &&
+                                    typeof receipt.error === "object" &&
+                                    !Array.isArray(receipt.error)
+                                    ? {
+                                        code: scalar(receipt.error.code),
+                                        message: scalar(receipt.error.message),
+                                    }
+                                    : scalar(receipt.error),
+                            }),
+                        ...(receipt.cleanup === undefined
+                            ? {}
+                            : {
+                                cleanup: receipt.cleanup !== null &&
+                                    typeof receipt.cleanup === "object" &&
+                                    !Array.isArray(receipt.cleanup)
+                                    ? {
+                                        directChildJoined: scalar(receipt.cleanup.directChildJoined),
+                                        boundaryEmpty: scalar(receipt.cleanup.boundaryEmpty),
+                                        orphanReaping: scalar(receipt.cleanup.orphanReaping),
+                                    }
+                                    : scalar(receipt.cleanup),
+                            }),
+                    };
+                throw new Error("ttsc: native supervisor did not confirm process-tree retirement", { cause: diagnostic });
+            }
+            retirement = "joined";
+            if (observeRetirement !== undefined && process.env.TTSC_E2E_TRACE) {
+                // Only already-validated scalar receipt fields cross this private
+                // observation boundary. Its allocation cannot replace an outcome.
+                try {
+                    observation = Object.freeze({
+                        helperPid: child.pid,
+                        targetPid: receipt.pid,
+                        version: receipt.version,
+                        status: receipt.status,
+                        signal: receipt.signal,
+                        cancelled: receipt.cancelled,
+                        directChildJoined: receipt.cleanup.directChildJoined,
+                        boundaryEmpty: receipt.cleanup.boundaryEmpty,
+                        orphanReaping: receipt.cleanup.orphanReaping,
+                    });
+                }
+                catch {
+                    // Missing diagnostics do not change native closure authority.
+                }
+            }
+            signal?.throwIfAborted();
+            const encoding = options.encoding;
+            const decode = (chunks) => {
+                const bytes = Buffer.concat(chunks);
+                return encoding && encoding !== "buffer"
+                    ? bytes.toString(encoding)
+                    : bytes;
+            };
+            const out = child.stdout === null ? null : decode(stdout);
+            const err = child.stderr === null ? null : decode(stderr);
+            const failure = overflow ??
+                (receipt.error === undefined
+                    ? undefined
+                    : Object.assign(new Error(receipt.error.message), {
+                        code: receipt.error.code,
+                    }));
+            return {
+                pid: receipt.pid,
+                status: receipt.status,
+                signal: receipt.signal,
+                output: [null, out, err],
+                stdout: out,
+                stderr: err,
+                ...(failure === undefined ? {} : { error: failure }),
+            };
+        }
+        catch (error) {
+            failed = true;
+            originalFailure = error;
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+            child.stdin?.destroy();
+            if (observation === undefined)
+                observeRetirement?.(retirement, failed ? String(originalFailure) : undefined);
+            else
+                observeRetirement?.(retirement, failed ? String(originalFailure) : undefined, observation);
+            // A failed proof does not authorize deleting a native reader's protocol
+            // inputs. The exact retained path is part of the terminal diagnostic.
+            if (retirement === "unknown") {
+                throw new Error(`ttsc: native retirement is unknown; retained protocol ${directory}`, {
+                    cause: originalFailure,
+                });
+            }
+            try {
+                node_fs_1.default.rmSync(directory, { recursive: true, force: true });
+            }
+            catch (error) {
+                throw failed
+                    ? new AggregateError([originalFailure, error], "ttsc: native protocol cleanup failed")
+                    : error;
+            }
+        }
+    }
+    OwnedNativeProcess.run = run;
+})(OwnedNativeProcess || (exports.OwnedNativeProcess = OwnedNativeProcess = {}));
+//# sourceMappingURL=OwnedNativeProcess.js.map

package/lib/internal/OwnedNativeProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OwnedNativeProcess.js","sourceRoot":"","sources":["../../src/internal/OwnedNativeProcess.ts"],"names":[],"mappings":";;;;;;AAAA,2DAI4B;AAC5B,sDAAyB;AACzB,sDAAyB;AACzB,0DAA6B;AAC7B,uCAAyC;AAEzC,sEAAmE;AAEnE;;;;;;;;;;;;;;GAcG;AACH,IAAiB,kBAAkB,CAuXlC;AAvXD,WAAiB,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,KAAK,UAAU,GAAG,CACvB,OAAe,EACf,IAAuB,EACvB,OAAyB,EACzB,MAAoB,EACpB,iBA+BS;QAET,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS;YACzE,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;QACJ,IACE,OAAO,CAAC,UAAU,KAAK,SAAS;YAChC,OAAO,CAAC,UAAU,KAAK,SAAS;YAChC,OAAO,CAAC,UAAU,KAAK,CAAC;YAExB,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;QACJ,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;YAC5C,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QAClB,IACE,SAAS,KAAK,SAAS;YACvB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YAE1D,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;QACJ,MAAM,MAAM,GAAG,IAAA,6BAAa,EAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,IAAI;YACjB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,0EAA0E;QAC1E,uEAAuE;QACvE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,MAAM,KAAK,GACT,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ;gBACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CACT,KAAK,EACL,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;oBAC/C,CAAC,CAAC,OAAO,CAAC,QAAQ;oBAClB,CAAC,CAAC,MAAM,CACX;gBACH,CAAC,CAAC,MAAM,CAAC,IAAI,CACT,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CACjE,CAAC;QACV,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAC5B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAC/C,CAAC,KAAK,EAA6B,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAC7D,CACF,CAAC;QACF,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;YAChC,OAAO,EAAE,CAAC;YACV,OAAO;YACP,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,GAAG,EAAE,mBAAI,CAAC,OAAO,CACf,OAAO,CAAC,GAAG,KAAK,SAAS;gBACvB,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;gBACf,CAAC,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;oBAC/B,CAAC,CAAC,OAAO,CAAC,GAAG;oBACb,CAAC,CAAC,IAAA,wBAAa,EAAC,OAAO,CAAC,GAAG,CAAC,CACjC;YACD,GAAG;YACH,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzE,wBAAwB,EAAE,OAAO,CAAC,wBAAwB,KAAK,IAAI;YACnE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAChE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;SACzE,CAAC,IAAI,CAAC;QACP,MAAM,SAAS,GAAG,iBAAE,CAAC,WAAW,CAC9B,mBAAI,CAAC,IAAI,CAAC,iBAAE,CAAC,MAAM,EAAE,EAAE,qBAAqB,CAAC,CAC9C,CAAC;QACF,MAAM,UAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,UAAU,GAAyC,aAAa,CAAC;QACrE,IAAI,WAAiE,CAAC;QACtE,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,GAAG,IAAI,CAAC;QAC/C,IAAI,QAA2B,CAAC;QAChC,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,KAAY,EAAE,EAAE,CAC9B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAClB,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;YAC1B,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ;gBACzC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,MAAM,CAAC;QACf,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE;YAClB,IAAI,CAAC;gBACH,OAAO,IAAA,0BAAK,EAAC,MAAM,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE;oBACjE,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG;oBAC/B,WAAW,EAAE,IAAI;oBACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;iBACtC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,iBAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,UAAU,GAAG,SAAS,CAAC;QACvB,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QACxC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,CAAC,OAA4B,EAAE,KAAa,EAAE,EAAE;YAC9D,MAAM,KAAK,GACT,OAAO,KAAK,QAAQ;gBAClB,CAAC,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC;gBAC/B,CAAC,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,KAAK,IAAI,KAAK;gBAAE,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;iBACpE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChC,QAAQ,GAAG,MAAM,CAAC,MAAM,CACtB,IAAI,KAAK,CAAC,+CAA+C,CAAC,EAC1D,EAAE,IAAI,EAAE,SAAS,EAAE,CACpB,CAAC;gBACF,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC,CAAC;QACF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QACtE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QACtE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,IAAI,UAA6B,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC3C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC1B,UAAU,GAAG,KAAK,CAAC;YACrB,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QACH,4EAA4E;QAC5E,IAAI,MAAM,EAAE,OAAO;YAAE,MAAM,EAAE,CAAC;aACzB,CAAC;YACJ,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,eAAwB,CAAC;QAC7B,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC;YACb,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,+DAA+D;gBAC/D,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;oBAAE,UAAU,GAAG,aAAa,CAAC;gBACxD,MAAM,UAAU,CAAC;YACnB,CAAC;YACD,IAAI,OAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAY,CAAC;YACvE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,8DAA8D,EAC9D,EAAE,KAAK,EAAE,CACV,CAAC;YACJ,CAAC;YACD,IACE,OAAO,KAAK,IAAI;gBAChB,OAAO,OAAO,KAAK,QAAQ;gBAC3B,OAAO,CAAC,OAAO,KAAK,CAAC;gBACrB,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC;gBAClC,OAAO,CAAC,GAAG,GAAG,CAAC;gBACf,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI;oBACtB,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;gBAC/D,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI;oBACtB,CAAC,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;wBACjC,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;gBACjC,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS;gBACtC,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;oBAC1B,CAAC,OAAO,OAAO,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ;wBACtC,OAAO,OAAO,CAAC,KAAK,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC;gBAChD,OAAO,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI;gBAC3C,OAAO,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;gBACvC,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,EACvE,CAAC;gBACD,sEAAsE;gBACtE,mEAAmE;gBACnE,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,EAAE,CAChC,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;oBACzC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;oBAC3D,CAAC,CAAC,KAAK,CAAC;gBACZ,MAAM,UAAU,GACd,OAAO,KAAK,IAAI;oBAChB,OAAO,OAAO,KAAK,QAAQ;oBAC3B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;oBACpB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;oBACjB,CAAC,CAAC;wBACE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;wBAChC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;wBACxB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;wBAC9B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;wBAC9B,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;wBACpC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;4BAC7B,CAAC,CAAC,EAAE;4BACJ,CAAC,CAAC;gCACE,KAAK,EACH,OAAO,CAAC,KAAK,KAAK,IAAI;oCACtB,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;oCACjC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;oCAC3B,CAAC,CAAC;wCACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;wCAChC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;qCACvC;oCACH,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;6BAC5B,CAAC;wBACN,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS;4BAC/B,CAAC,CAAC,EAAE;4BACJ,CAAC,CAAC;gCACE,OAAO,EACL,OAAO,CAAC,OAAO,KAAK,IAAI;oCACxB,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;oCACnC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;oCAC7B,CAAC,CAAC;wCACE,iBAAiB,EAAE,MAAM,CACvB,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAClC;wCACD,aAAa,EAAE,MAAM,CACnB,OAAO,CAAC,OAAO,CAAC,aAAa,CAC9B;wCACD,aAAa,EAAE,MAAM,CACnB,OAAO,CAAC,OAAO,CAAC,aAAa,CAC9B;qCACF;oCACH,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;6BAC9B,CAAC;qBACP,CAAC;gBACR,MAAM,IAAI,KAAK,CACb,iEAAiE,EACjE,EAAE,KAAK,EAAE,UAAU,EAAE,CACtB,CAAC;YACJ,CAAC;YACD,UAAU,GAAG,QAAQ,CAAC;YACtB,IAAI,iBAAiB,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;gBAClE,kEAAkE;gBAClE,kEAAkE;gBAClE,IAAI,CAAC;oBACH,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;wBAC1B,SAAS,EAAE,KAAK,CAAC,GAAG;wBACpB,SAAS,EAAE,OAAO,CAAC,GAAG;wBACtB,OAAO,EAAE,OAAO,CAAC,OAAO;wBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,iBAAiB,EAAE,OAAO,CAAC,OAAO,CAAC,iBAAiB;wBACpD,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,aAAa;wBAC5C,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,aAAa;qBAC7C,CAAC,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACP,8DAA8D;gBAChE,CAAC;YACH,CAAC;YACD,MAAM,EAAE,cAAc,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAClC,MAAM,MAAM,GAAG,CAAC,MAAgB,EAAE,EAAE;gBAClC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACpC,OAAO,QAAQ,IAAI,QAAQ,KAAK,QAAQ;oBACtC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;oBAC1B,CAAC,CAAC,KAAK,CAAC;YACZ,CAAC,CAAC;YACF,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC1D,MAAM,OAAO,GACX,QAAQ;gBACR,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;oBAC1B,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;wBAC9C,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI;qBACzB,CAAC,CAAC,CAAC;YACV,OAAO;gBACL,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM,EAAE,OAAO,CAAC,MAA+B;gBAC/C,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;gBACxB,MAAM,EAAE,GAAsB;gBAC9B,MAAM,EAAE,GAAsB;gBAC9B,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;aACrD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,IAAI,CAAC;YACd,eAAe,GAAG,KAAK,CAAC;YACxB,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7C,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;YACvB,IAAI,WAAW,KAAK,SAAS;gBAC3B,iBAAiB,EAAE,CACjB,UAAU,EACV,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAC7C,CAAC;;gBAEF,iBAAiB,EAAE,CACjB,UAAU,EACV,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,EAC5C,WAAW,CACZ,CAAC;YACJ,wEAAwE;YACxE,sEAAsE;YACtE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACb,yDAAyD,SAAS,EAAE,EACpE;oBACE,KAAK,EAAE,eAAe;iBACvB,CACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,iBAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM;oBACV,CAAC,CAAC,IAAI,cAAc,CAChB,CAAC,eAAe,EAAE,KAAK,CAAC,EACxB,sCAAsC,CACvC;oBACH,CAAC,CAAC,KAAK,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAzVqB,mBAAA,GAAG,MAyVxB,CAAA;AACH,CAAC,EAvXgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAuXlC"}

package/lib/internal/OwnedSynchronousProcess.d.ts

@@ -0,0 +1,158 @@
+import type { SpawnSyncOptions, SpawnSyncReturns, spawnSync } from "node:child_process";
+/**
+ * A synchronous resolver task's explicit cancellation and native-command seam.
+ * Ordinary compiler callers retain their established synchronous execution.
+ * Worker owners supply a relay which joins native process containment before
+ * returning, allowing cancellation to unwind normal lock and scratch cleanup.
+ *
+ * @evidence contracts/common.md#principled-implementation Scope installation is lexical and restored in finally; only an explicitly owned task delegates commands and observes its shared cancellation cell.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace owns scoped checkpoints and synchronous delegation; the parent relay owns process launch, containment and joining.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No child-process monkeypatch or inferred empty result substitutes for real command completion; cancellation throws outside the resolver's outcome conversion.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes opt-in worker execution from unchanged synchronous consumers and preserves cleanup responsibilities.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared memory and explicit argv/options cross the Node worker boundary; native process differences remain in the supervisor.
+ * @evidence contracts/performance.md#efficient-algorithms Checkpoints inspect one atomic cell; sleeps wait on that same cell so cancellation wakes them without polling. Native execution costs remain delegated.
+ * @evidence contracts/performance.md#reuse-equivalent-work A scope conveys task ownership only and never caches command results or authorizes reuse of a discovery proof.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Scope state is restored after the synchronous callback; tracked retirement promises remain with the worker request owner until joined.
+ */
+export declare namespace OwnedSynchronousProcess {
+    /**
+     * One synchronous task's cancellation, command relay and retirement records.
+     * The asynchronous owner supplies these collections and joins/reports them
+     * after the synchronous scope restores its predecessor.
+     *
+     * @evidence contracts/common.md#principled-implementation One scope binds cancellation and native command ownership to the same task; caller-owned collections preserve retirement and cleanup failures after scope restoration.
+     * @evidence contracts/common.md#clear-and-simple-design Four fields express admission, command delegation, pending closure and ownership failure without placing process containment in this type.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit ownership carries actual promises and errors rather than inferring closure from a kill request or an unavailable result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the owner's post-scope responsibility; field comments specify cancellation-cell encoding and optional collection behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Shared memory and Node spawn options represent the worker/native boundary; the relay owns platform process containment.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This type declares task capabilities and collections, without executing a command or selecting an algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Scope identity authorizes no reusable computation or cache hit.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The type allocates no task or handle; runtime members and the asynchronous owner govern collection lifetime and joining.
+     */
+    interface Scope {
+        /** First Int32 cell: zero admits work; any nonzero value cancels it. */
+        cancel: SharedArrayBuffer;
+        /**
+         * Synchronous relay whose owner contains and joins the actual command. The
+         * returned spawn result describes that command's real completion; callers
+         * do not transfer closure authority merely by requesting a kill.
+         *
+         * @evidence contracts/common.md#principled-implementation This capability supplies actual synchronous command completion to the same task that owns cancellation and post-task retirement.
+         * @evidence contracts/common.md#clear-and-simple-design Command, argv and Node options form one explicit relay boundary; the owning supervisor retains native process containment policy.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts A real spawn result is required; no patched child-process API, cached success or empty output stands in for command execution.
+         * @evidence contracts/common.md#meaningful-documentation Native prose defines synchronous completion and distinguishes a termination request from closure authority.
+         * @evidence contracts/portability.md#os-neutral-implementation Native Node spawn arguments/options and return types cross the seam without shell assembly; the supplied supervisor handles platform containment.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms The function field declares the command capability; its concrete relay owns launch, output and joining algorithms.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work Declaring a relay authorizes no equivalent-result reuse or deduplication of effectful commands.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This signature acquires no process or handle; the concrete synchronous relay must contain and join its command before returning.
+         */
+        launch?: (command: string, args: readonly string[], options: SpawnSyncOptions) => ReturnType<typeof spawnSync>;
+        /** Optional original retirement promises, awaited after synchronous work. */
+        retirements?: Set<Promise<unknown>>;
+        /** Optional original cleanup failures that legacy catches must not erase. */
+        failures?: unknown[];
+    }
+    /**
+     * Run one synchronous payload, restoring a prior scope even on failure.
+     * Returning a Promise does not extend this lexical scope until settlement.
+     *
+     * @evidence contracts/common.md#principled-implementation Entry and successful completion check cancellation; finally restores the previous scope even when admission, callback or completion throws.
+     * @evidence contracts/common.md#clear-and-simple-design One saved predecessor supports nesting without an asynchronous context registry.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual callback runs under explicit scope; no monkeypatch or unavailable result represents cancellation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states restoration and the synchronous lifetime limit for returned Promises.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Scope installation sequences opaque callbacks and cancellation checks; command and filesystem representation remain with the supplied owner.
+     * @evidence contracts/performance.md#efficient-algorithms A saved reference and two delegated checks surround the callback; callback costs and native blocking remain its owner's responsibility.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every invocation runs its own effectful callback and establishes no equivalent-result reuse.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Finally restores the previous reference; task-created promises and failures stay in caller-owned collections for later joining rather than being silently discarded.
+     */
+    function run<T>(scope: Scope, callback: () => T): T;
+    /**
+     * Reject cancelled payload work with AbortError. Cleanup must instead finish
+     * its ownership transitions, optionally observing cancelled without
+     * throwing.
+     *
+     * @evidence contracts/common.md#principled-implementation The shared admission state determines cancellation and produces the documented AbortError rather than a degraded plugin result.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate and one exception separate admission from cleanup policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Real cancellation is thrown; no success value or empty result impersonates completed work.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the error and explains why cleanup must not use this throwing guard.
+     * @evidence contracts/portability.md#os-neutral-implementation Atomics and DOMException provide the same shared-cell and AbortError contract across supported Node platforms.
+     * @evidence contracts/performance.md#efficient-algorithms One delegated atomic observation and at most one exception allocation perform the guard.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cancellation is mutable admission state and is observed anew rather than cached.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The guard opens no resource and retains no error after throwing; lexical cleanup remains with callers.
+     */
+    function checkpoint(): void;
+    /**
+     * Identify withdrawn payload admission without interrupting cleanup. No
+     * installed scope means ordinary synchronous work remains admitted.
+     *
+     * @evidence contracts/common.md#principled-implementation Only an installed scope's first shared Int32 cell determines this task's cancellation; nonzero values uniformly withdraw admission.
+     * @evidence contracts/common.md#clear-and-simple-design A boolean observation allows cleanup to choose its own grace without throwing midway through release.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An atomic shared value is cancellation authority; elapsed time or process-name guesses are not substituted.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes nonthrowing cleanup observation from ordinary unscoped admission.
+     * @evidence contracts/portability.md#os-neutral-implementation SharedArrayBuffer and Atomics.load avoid platform-specific worker signaling conventions.
+     * @evidence contracts/performance.md#efficient-algorithms Each scoped call creates one short typed view and loads one cell; it scans no task collection.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A cancellation cell may change between calls, so prior observations cannot be reused.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The temporary view retains no independent handle or asynchronous work after return.
+     */
+    function cancelled(): boolean;
+    /**
+     * Sleep between payload attempts; a cancelling owner stores the cell and
+     * notifies it to wake the wait. Native scheduling can delay resumed
+     * execution.
+     *
+     * @evidence contracts/common.md#principled-implementation Checks before and after Atomics.wait cover cancellation before admission, during the wait and before subsequent work.
+     * @evidence contracts/common.md#clear-and-simple-design The cancellation cell doubles as the wait address; ordinary callers use a fresh zero cell.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared-cell notification interrupts the actual wait instead of substituting a delayed cancellation result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states store-plus-notify ownership and avoids claiming a hard scheduling deadline.
+     * @evidence contracts/portability.md#os-neutral-implementation Node shared-memory waits replace shell sleeps and preserve the ordinary synchronous wait behavior.
+     * @evidence contracts/performance.md#efficient-algorithms One blocking wait avoids active polling; timeout and native scheduling govern the suspension's duration.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each sleep sequences its own payload attempts and produces no reusable result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources No timer or child is installed; the synchronous wait and temporary view end on notification, value mismatch or timeout before the final guard.
+     */
+    function sleep(milliseconds: number): void;
+    /**
+     * Delegate a command only through the installed owner's synchronous relay.
+     * Undefined means no relay is installed; callers retain their native path.
+     *
+     * @evidence contracts/common.md#principled-implementation The explicit relay receives the original command, argv and options, with cancellation guards before and after real completion.
+     * @evidence contracts/common.md#clear-and-simple-design Optional delegation preserves ordinary synchronous callers without importing supervisor policy here.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined denotes absent delegation, never fabricated command success; the relay must return the actual joined command result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies optional delegation and the ordinary caller's fallback responsibility.
+     * @evidence contracts/portability.md#os-neutral-implementation Node spawn argument/options types cross the seam without shell string assembly; native containment remains the relay owner's responsibility.
+     * @evidence contracts/performance.md#efficient-algorithms A relay lookup and two guards surround one opaque synchronous launch; command execution, output buffers and joining are delegated costs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Effectful commands are never cached or deduplicated by this seam.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources This function retains no child itself; the supplied relay owns actual containment and completion before returning, while scope restoration belongs to run.
+     */
+    function launch<T extends string | Buffer = Buffer<ArrayBuffer>>(command: string, args: readonly string[], options: SpawnSyncOptions): SpawnSyncReturns<T> | undefined;
+    /**
+     * Register an original retirement promise for the asynchronous owner to join.
+     * True means registration occurred, so a producer must keep that work
+     * referenced until closure; this function neither awaits nor removes
+     * entries.
+     *
+     * @evidence contracts/common.md#principled-implementation The original promise is retained, including rejection, while an attached rejection handler prevents an unhandled notification before the owner joins it.
+     * @evidence contracts/common.md#clear-and-simple-design The registration boolean lets producers preserve ordinary unref behavior while scoped work remains alive through joining.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Registering actual exit/close promises never certifies closure merely from a termination request; rejection remains in the original promise.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states registration, keepalive ownership and the absence of awaiting or collection removal here.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Promise registration interprets no native process or filesystem representation; producers supply actual native closure promises.
+     * @evidence contracts/performance.md#efficient-algorithms One Set insertion and rejection-handler attachment avoid scanning previously registered work; costs scale with distinct promise registrations.
+     * @evidence contracts/performance.md#reuse-equivalent-work Set identity prevents duplicate references to the same promise; no result equivalence or shared command execution is inferred.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Caller-owned entries remain for the request lifetime until its asynchronous owner joins and releases the collection; this registration operation schedules no collection cleanup.
+     */
+    function track(retirement: Promise<unknown>): boolean;
+    /**
+     * Preserve original ownership failures across legacy unavailable conversion.
+     * The asynchronous owner reports the collected failures after joining work;
+     * absent scope or collection means this reporting seam does nothing.
+     *
+     * @evidence contracts/common.md#principled-implementation The original error is appended before a cleanup caller throws, so a legacy catch cannot erase the asynchronous owner's failure record.
+     * @evidence contracts/common.md#clear-and-simple-design One optional caller-owned array separates failure recording from later aggregate publication.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Recording preserves the actual failure rather than treating an unavailable outcome as successful cleanup.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states deferred reporting and the ordinary unscoped no-op behavior.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Appending an opaque failure interprets no platform-specific errno or native ownership state.
+     * @evidence contracts/performance.md#efficient-algorithms One append retains a reference per reported failure without formatting errors or traversing prior records.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each occurrence is preserved as reported; error identity does not authorize skipping a distinct failed ownership transition.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller's request collection retains original errors until aggregate reporting and request release; this seam owns no independent handle or asynchronous task.
+     */
+    function reportFailure(error: unknown): void;
+}