node-or-bun 0.0.0-stage → 0.2.1

package/dist/executor.js

@@ -0,0 +1,285 @@
+import { PROCESS_CLEANUP_STEP_MS } from "./contract.js";
+import { ProcessRuntimeError, isProcessRuntimeError, processError, } from "./errors.js";
+import { classifyProcessOutcome, } from "./internal/classification.js";
+import { decodeCapture, drainCapture } from "./internal/capture.js";
+import { snapshotRequest } from "./internal/input.js";
+import { rejectedReasons, settleOperation, withCause, } from "./internal/settlement.js";
+const deferred = () => {
+    let resolve;
+    const promise = new Promise((settle) => {
+        resolve = settle;
+    });
+    return { promise, resolve };
+};
+const wait = async (promise, timeoutMs) => {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ status: "timeout" }), timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            promise.then((value) => ({ status: "settled", value })),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+};
+const captureError = (value, streamName) => {
+    const code = isProcessRuntimeError(value) && value.code === "output-limit"
+        ? "output-limit"
+        : "stream";
+    return new ProcessRuntimeError(code, code === "output-limit" ? "captured output exceeded 4 MiB" : `${streamName} capture failed`, { cause: value });
+};
+const initiatingCause = (cause) => {
+    switch (cause) {
+        case "timeout":
+            return "timeout";
+        case "cancelled":
+            return "cancellation";
+        case "capture":
+            return "capture";
+        case "observation":
+        case "failed":
+            return "observation";
+        case "exited":
+            return "exit";
+    }
+};
+export const createProcessExecutor = (adapter) => {
+    if (adapter === null || typeof adapter !== "object" || typeof adapter.launch !== "function") {
+        throw processError("invalid-input", "adapter must expose launch(request)");
+    }
+    return {
+        run: async (request) => {
+            const snapshot = snapshotRequest(request);
+            const failure = deferred();
+            let initiatingFailure;
+            let observedExit = null;
+            let completionRequestedBeforeExitObservation = false;
+            let lateFailureCodes = [];
+            let captureReads;
+            let outputBounded = false;
+            const addLateFailureCode = (code) => {
+                if (!lateFailureCodes.includes(code)) {
+                    lateFailureCodes = [...lateFailureCodes, code];
+                }
+            };
+            const beginFailure = (error, cause) => {
+                if (initiatingFailure !== undefined) {
+                    if (cause === "capture")
+                        addLateFailureCode(error.code);
+                    return;
+                }
+                const state = {
+                    cause: initiatingCause(cause),
+                    code: error.code,
+                    error,
+                };
+                initiatingFailure = state;
+                completionRequestedBeforeExitObservation = observedExit === null;
+                failure.resolve(state);
+            };
+            if (snapshot.signal !== undefined && Boolean(snapshot.signal.aborted)) {
+                throw new ProcessRuntimeError("cancelled", "process request was already cancelled", {
+                    initiatingError: snapshot.signal.reason,
+                    facts: {
+                        initiatingCause: "cancellation",
+                        completionRequestedBeforeExitObservation: true,
+                    },
+                });
+            }
+            const onAbort = () => {
+                if (observedExit === null && initiatingFailure === undefined) {
+                    beginFailure(processError("cancelled", "process request was cancelled", snapshot.signal?.reason), "cancelled");
+                }
+            };
+            snapshot.signal?.addEventListener("abort", onAbort, { once: true });
+            const timer = snapshot.timeoutMs === undefined
+                ? undefined
+                : setTimeout(() => {
+                    if (observedExit === null && initiatingFailure === undefined) {
+                        beginFailure(processError("timeout", "process deadline elapsed"), "timeout");
+                    }
+                }, snapshot.timeoutMs);
+            if (snapshot.signal !== undefined && Boolean(snapshot.signal.aborted)) {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                snapshot.signal.removeEventListener("abort", onAbort);
+                throw new ProcessRuntimeError("cancelled", "process request was already cancelled", {
+                    initiatingError: snapshot.signal.reason,
+                    facts: {
+                        initiatingCause: "cancellation",
+                        completionRequestedBeforeExitObservation: true,
+                    },
+                });
+            }
+            let running;
+            try {
+                running = await adapter.launch(snapshot.launch);
+            }
+            catch (cause) {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                snapshot.signal?.removeEventListener("abort", onAbort);
+                if (isProcessRuntimeError(cause) && cause.code === "cleanup") {
+                    throw new ProcessRuntimeError("cleanup", "process cleanup did not complete", {
+                        cause: cause.cause,
+                        initiatingError: cause.initiatingError,
+                        facts: {
+                            ...cause.facts,
+                            initiatingCause: cause.facts.initiatingCause ?? "launch",
+                            incompleteCustody: true,
+                        },
+                    });
+                }
+                if (initiatingFailure !== undefined) {
+                    throw new ProcessRuntimeError(initiatingFailure.code, initiatingFailure.error.message, {
+                        cause: initiatingFailure.error.cause,
+                        initiatingError: initiatingFailure.error,
+                        facts: {
+                            initiatingCause: initiatingFailure.cause,
+                            completionRequestedBeforeExitObservation,
+                            lateFailureCodes,
+                        },
+                    });
+                }
+                if (isProcessRuntimeError(cause)) {
+                    throw cause;
+                }
+                throw new ProcessRuntimeError("launch", "process launch failed", {
+                    cause,
+                    initiatingError: cause,
+                    facts: { initiatingCause: "launch" },
+                });
+            }
+            const stdoutRead = drainCapture(running.stdout, (cause) => {
+                beginFailure(captureError(cause, "stdout"), "capture");
+            });
+            const stderrRead = drainCapture(running.stderr, (cause) => {
+                beginFailure(captureError(cause, "stderr"), "capture");
+            });
+            outputBounded = true;
+            // Invariant assertion: the 4 MiB capture limits are in force for this
+            // run; the fact does not report whether truncation occurred (review-v2
+            // R11 disposition, documented invariant).
+            // Contract: drainCapture reports failures through beginFailure and its
+            // promise never rejects, so this chain cannot reject (review-v2 R17
+            // disposition, documented non-rejecting drain contract).
+            const captures = Promise.all([stdoutRead, stderrRead]).then((value) => {
+                captureReads = value;
+                return value;
+            });
+            const exitObservation = running.exited.then((exit) => {
+                observedExit = exit;
+                return { kind: "exit" };
+            }, (cause) => {
+                beginFailure(new ProcessRuntimeError("stream", "process observation failed", { cause }), "observation");
+                return { kind: "failure" };
+            });
+            const failureObservation = failure.promise.then(() => ({ kind: "failure" }));
+            const firstObservation = await Promise.race([exitObservation, failureObservation]);
+            if (firstObservation.kind === "exit" && initiatingFailure === undefined) {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                snapshot.signal?.removeEventListener("abort", onAbort);
+            }
+            const closeAndSettleCapture = async () => {
+                const initiallySettled = await wait(captures, PROCESS_CLEANUP_STEP_MS);
+                if (initiallySettled.status === "settled" &&
+                    initiallySettled.value.every((capture) => capture.normalEof)) {
+                    return;
+                }
+                const forcedAfterEofDeadline = initiallySettled.status === "timeout";
+                let closeSettlement;
+                const close = settleOperation(() => running.closeCapture()).then((settlement) => {
+                    closeSettlement = settlement;
+                    return settlement;
+                });
+                const settled = await wait(Promise.all([close, settleOperation(() => captures)]).then(() => true), PROCESS_CLEANUP_STEP_MS);
+                const closeFailure = closeSettlement !== undefined && closeSettlement.status === "rejected"
+                    ? closeSettlement
+                    : undefined;
+                if (settled.status === "timeout") {
+                    throw closeFailure === undefined
+                        ? new Error("native capture close or reader settlement remained open")
+                        : closeFailure.reason;
+                }
+                if (closeFailure !== undefined) {
+                    throw closeFailure.reason === undefined
+                        ? withCause(new Error("native capture closure failed"), undefined)
+                        : closeFailure.reason;
+                }
+                if (forcedAfterEofDeadline) {
+                    throw new Error("capture EOF deadline elapsed");
+                }
+            };
+            let cleanupFailure;
+            const cleanupSettlement = await settleOperation(() => running.cleanup(initiatingFailure?.cause === "timeout"
+                ? "timeout"
+                : initiatingFailure?.cause === "cancellation"
+                    ? "cancelled"
+                    : firstObservation.kind === "exit"
+                        ? "exited"
+                        : "failed"));
+            const closeSettlement = await settleOperation(() => closeAndSettleCapture());
+            const failures = rejectedReasons([cleanupSettlement, closeSettlement]);
+            if (failures.length > 0) {
+                cleanupFailure = {
+                    reason: failures.length === 1
+                        ? failures[0]
+                        : new AggregateError(failures, "cleanup and capture closure both failed"),
+                };
+            }
+            if (timer !== undefined)
+                clearTimeout(timer);
+            snapshot.signal?.removeEventListener("abort", onAbort);
+            await wait(exitObservation, PROCESS_CLEANUP_STEP_MS);
+            let decodeFailure;
+            let output = null;
+            let stdout = "";
+            let stderr = "";
+            if (captureReads !== undefined) {
+                try {
+                    stdout = decodeCapture(captureReads[0].bytes, snapshot.strictUtf8, "stdout");
+                    stderr = decodeCapture(captureReads[1].bytes, snapshot.strictUtf8, "stderr");
+                    output = { stdout, stderr };
+                }
+                catch (cause) {
+                    decodeFailure = new ProcessRuntimeError("invalid-output", "captured output was not valid UTF-8", { cause });
+                    addLateFailureCode("invalid-output");
+                }
+            }
+            const outcome = classifyProcessOutcome({
+                initiatingFailure,
+                cleanupFailure,
+                decodeFailure,
+                lateFailureCodes,
+                observedExit,
+                completionRequestedBeforeExitObservation,
+                outputBounded,
+                output,
+            });
+            if (outcome.kind === "error") {
+                throw outcome.error;
+            }
+            const finalExit = observedExit;
+            if (finalExit === null) {
+                throw new ProcessRuntimeError("stream", "process exited without an observed result", {
+                    facts: outcome.facts,
+                    output,
+                });
+            }
+            return {
+                ...finalExit,
+                stdout,
+                stderr,
+                facts: outcome.facts,
+            };
+        },
+    };
+};
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { CompletionCause, Exit, Launch, ProcessAdapter, ProcessExecutor, ProcessRunResult, Request, RunningProcess, } from "./contract.js";
+export { PROCESS_CAPTURE_LIMIT_BYTES, PROCESS_CLEANUP_STEP_MS, PROCESS_TIMEOUT_MAX_MS, } from "./contract.js";
+export { ProcessRuntimeError, isProcessRuntimeError, processError, } from "./errors.js";
+export type { ProcessCapturedOutput, ProcessErrorCode, ProcessInitiatingCause, ProcessRuntimeErrorOptions, ProcessRuntimeFacts, } from "./errors.js";
+export { createProcessExecutor } from "./executor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,IAAI,EACJ,MAAM,EACN,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,OAAO,EACP,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PROCESS_CAPTURE_LIMIT_BYTES, PROCESS_CLEANUP_STEP_MS, PROCESS_TIMEOUT_MAX_MS, } from "./contract.js";
+export { ProcessRuntimeError, isProcessRuntimeError, processError, } from "./errors.js";
+export { createProcessExecutor } from "./executor.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/internal/capture.d.ts

@@ -0,0 +1,9 @@
+export type CaptureRead = {
+    readonly bytes: Uint8Array;
+    readonly overflow: boolean;
+    readonly normalEof: boolean;
+};
+export declare const concatBytes: (chunks: readonly Uint8Array[], length: number) => Uint8Array;
+export declare const decodeCapture: (bytes: Uint8Array, strictUtf8: boolean, streamName: "stdout" | "stderr") => string;
+export declare const drainCapture: (stream: AsyncIterable<Uint8Array>, onProblem: (error: unknown) => void) => Promise<CaptureRead>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/internal/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/internal/capture.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,CAAC;AASF,eAAO,MAAM,WAAW,WAAY,SAAS,UAAU,EAAE,UAAU,MAAM,KAAG,UAQ3E,CAAC;AAEF,eAAO,MAAM,aAAa,UACjB,UAAU,cACL,OAAO,cACP,QAAQ,GAAG,QAAQ,KAC9B,MASF,CAAC;AAEF,eAAO,MAAM,YAAY,WACf,aAAa,CAAC,UAAU,CAAC,aACtB,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAClC,OAAO,CAAC,WAAW,CA2BrB,CAAC"}

package/dist/internal/capture.js

@@ -0,0 +1,58 @@
+import { PROCESS_CAPTURE_LIMIT_BYTES } from "../contract.js";
+import { processError } from "../errors.js";
+const copyChunk = (value) => {
+    if (!(value instanceof Uint8Array)) {
+        throw processError("stream", "capture stream yielded a non-byte chunk");
+    }
+    return new Uint8Array(value);
+};
+export const concatBytes = (chunks, length) => {
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+};
+export const decodeCapture = (bytes, strictUtf8, streamName) => {
+    try {
+        return new TextDecoder("utf-8", {
+            fatal: strictUtf8,
+            ignoreBOM: true,
+        }).decode(bytes);
+    }
+    catch (cause) {
+        throw processError("invalid-output", `${streamName} is not valid UTF-8`, cause);
+    }
+};
+export const drainCapture = async (stream, onProblem) => {
+    const chunks = [];
+    let length = 0;
+    let overflow = false;
+    try {
+        for await (const value of stream) {
+            const chunk = copyChunk(value);
+            if (overflow) {
+                continue;
+            }
+            const remaining = PROCESS_CAPTURE_LIMIT_BYTES - length;
+            const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
+            if (accepted.byteLength > 0) {
+                chunks.push(accepted);
+                length += accepted.byteLength;
+            }
+            if (chunk.byteLength > remaining) {
+                overflow = true;
+                onProblem(processError("output-limit", "captured output exceeded 4 MiB"));
+            }
+        }
+    }
+    catch (cause) {
+        // Preserve the stream-specific reason at the executor boundary.
+        onProblem(cause);
+        return { bytes: concatBytes(chunks, length), overflow, normalEof: false };
+    }
+    return { bytes: concatBytes(chunks, length), overflow, normalEof: true };
+};
+//# sourceMappingURL=capture.js.map

package/dist/internal/capture.js.map

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

package/dist/internal/classification.d.ts

@@ -0,0 +1,32 @@
+import type { Exit } from "../contract.js";
+import { ProcessRuntimeError, type ProcessCapturedOutput, type ProcessErrorCode, type ProcessInitiatingCause, type ProcessRuntimeFacts } from "../errors.js";
+export type InitiatingFailure = {
+    readonly cause: ProcessInitiatingCause;
+    readonly code: ProcessErrorCode;
+    readonly error: ProcessRuntimeError;
+};
+export type ClassificationInput = {
+    readonly initiatingFailure?: InitiatingFailure | undefined;
+    readonly cleanupFailure?: {
+        readonly reason: unknown;
+    } | undefined;
+    readonly decodeFailure?: ProcessRuntimeError | undefined;
+    readonly lateFailureCodes: readonly ProcessErrorCode[];
+    readonly observedExit: Exit | null;
+    readonly completionRequestedBeforeExitObservation: boolean;
+    readonly outputBounded: boolean;
+    readonly output: ProcessCapturedOutput | null;
+};
+/**
+ * The fixed facts-outside classifier from plan v4 section 3.2. Cleanup/forced
+ * EOF closure wins; otherwise the first initiating failure wins; otherwise a
+ * normal observed exit is a result and strict decode failure is `invalid-output`.
+ */
+export declare const classifyProcessOutcome: ({ initiatingFailure, cleanupFailure, decodeFailure, lateFailureCodes, observedExit, completionRequestedBeforeExitObservation, outputBounded, output, }: ClassificationInput) => {
+    readonly kind: "result";
+    readonly facts: ProcessRuntimeFacts;
+} | {
+    readonly kind: "error";
+    readonly error: ProcessRuntimeError;
+};
+//# sourceMappingURL=classification.d.ts.map

package/dist/internal/classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.ts","sourceRoot":"","sources":["../../src/internal/classification.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,wCAAwC,EAAE,OAAO,CAAC;IAC3D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAqBF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2JAShC,mBAAmB,KAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAwDhE,CAAC"}

package/dist/internal/classification.js

@@ -0,0 +1,64 @@
+import { ProcessRuntimeError, } from "../errors.js";
+const facts = ({ initiatingFailure, lateFailureCodes, observedExit, completionRequestedBeforeExitObservation, outputBounded, incompleteCustody, }) => Object.freeze({
+    initiatingCause: initiatingFailure?.cause ?? (observedExit === null ? null : "exit"),
+    completionRequestedBeforeExitObservation,
+    observedExit,
+    lateFailureCodes: Object.freeze([...lateFailureCodes]),
+    outputBounded,
+    incompleteCustody,
+});
+/**
+ * The fixed facts-outside classifier from plan v4 section 3.2. Cleanup/forced
+ * EOF closure wins; otherwise the first initiating failure wins; otherwise a
+ * normal observed exit is a result and strict decode failure is `invalid-output`.
+ */
+export const classifyProcessOutcome = ({ initiatingFailure, cleanupFailure, decodeFailure, lateFailureCodes, observedExit, completionRequestedBeforeExitObservation, outputBounded, output, }) => {
+    const shared = {
+        initiatingFailure,
+        lateFailureCodes,
+        observedExit,
+        completionRequestedBeforeExitObservation,
+        outputBounded,
+    };
+    if (cleanupFailure !== undefined) {
+        return {
+            kind: "error",
+            error: new ProcessRuntimeError("cleanup", "process cleanup did not complete", {
+                output,
+                cause: cleanupFailure.reason,
+                initiatingError: initiatingFailure?.error ?? null,
+                facts: facts({ ...shared, incompleteCustody: true }),
+            }),
+        };
+    }
+    if (initiatingFailure !== undefined) {
+        return {
+            kind: "error",
+            error: new ProcessRuntimeError(initiatingFailure.code, initiatingFailure.error.message, {
+                output,
+                cause: initiatingFailure.error.cause,
+                initiatingError: initiatingFailure.error,
+                facts: facts({ ...shared, incompleteCustody: false }),
+            }),
+        };
+    }
+    if (decodeFailure !== undefined) {
+        return {
+            kind: "error",
+            error: new ProcessRuntimeError("invalid-output", decodeFailure.message, {
+                output,
+                cause: decodeFailure.cause,
+                initiatingError: decodeFailure,
+                facts: {
+                    ...facts({ ...shared, incompleteCustody: false }),
+                    initiatingCause: "decode",
+                },
+            }),
+        };
+    }
+    return {
+        kind: "result",
+        facts: facts({ ...shared, incompleteCustody: false }),
+    };
+};
+//# sourceMappingURL=classification.js.map

package/dist/internal/classification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.js","sourceRoot":"","sources":["../../src/internal/classification.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,GAKpB,MAAM,cAAc,CAAC;AAmBtB,MAAM,KAAK,GAAG,CAAC,EACb,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,wCAAwC,EACxC,aAAa,EACb,iBAAiB,GAGlB,EAAuB,EAAE,CACxB,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,iBAAiB,EAAE,KAAK,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACpF,wCAAwC;IACxC,YAAY;IACZ,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC;IACtD,aAAa;IACb,iBAAiB;CAClB,CAAC,CAAC;AAEL;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,EACrC,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,wCAAwC,EACxC,aAAa,EACb,MAAM,GACc,EAE8C,EAAE;IACpE,MAAM,MAAM,GAAG;QACb,iBAAiB;QACjB,gBAAgB;QAChB,YAAY;QACZ,wCAAwC;QACxC,aAAa;KACd,CAAC;IAEF,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,IAAI,mBAAmB,CAAC,SAAS,EAAE,kCAAkC,EAAE;gBAC5E,MAAM;gBACN,KAAK,EAAE,cAAc,CAAC,MAAM;gBAC5B,eAAe,EAAE,iBAAiB,EAAE,KAAK,IAAI,IAAI;gBACjD,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;aACrD,CAAC;SACH,CAAC;IACJ,CAAC;IAED,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,IAAI,mBAAmB,CAC5B,iBAAiB,CAAC,IAAI,EACtB,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAC/B;gBACE,MAAM;gBACN,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,KAAK;gBACpC,eAAe,EAAE,iBAAiB,CAAC,KAAK;gBACxC,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;aACtD,CACF;SACF,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,IAAI,mBAAmB,CAAC,gBAAgB,EAAE,aAAa,CAAC,OAAO,EAAE;gBACtE,MAAM;gBACN,KAAK,EAAE,aAAa,CAAC,KAAK;gBAC1B,eAAe,EAAE,aAAa;gBAC9B,KAAK,EAAE;oBACL,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;oBACjD,eAAe,EAAE,QAAQ;iBAC1B;aACF,CAAC;SACH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC,CAAC"}

package/dist/internal/input.d.ts

@@ -0,0 +1,9 @@
+import type { Launch, Request } from "../contract.js";
+export type RequestSnapshot = {
+    readonly launch: Launch;
+    readonly signal: AbortSignal | undefined;
+    readonly timeoutMs: number | undefined;
+    readonly strictUtf8: boolean;
+};
+export declare const snapshotRequest: (request: Request) => RequestSnapshot;
+//# sourceMappingURL=input.d.ts.map

package/dist/internal/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/internal/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAItD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CAAC;AA4BF,eAAO,MAAM,eAAe,YAAa,OAAO,KAAG,eAuClD,CAAC"}

package/dist/internal/input.js

@@ -0,0 +1,62 @@
+import { PROCESS_TIMEOUT_MAX_MS } from "../contract.js";
+import { processError } from "../errors.js";
+const hasNul = (value) => value.includes("\u0000");
+const validateString = (value, field) => {
+    if (typeof value !== "string" || value.length === 0 || hasNul(value)) {
+        throw processError("invalid-input", `${field} must be a non-empty string without NUL`);
+    }
+    return value;
+};
+const snapshotEnvironment = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const entries = Object.entries(value);
+    const validated = [];
+    for (const [key, entryValue] of entries) {
+        if (typeof key !== "string" || typeof entryValue !== "string" || hasNul(key) || hasNul(entryValue)) {
+            throw processError("invalid-input", "environment entries must be strings without NUL");
+        }
+        validated.push([key, entryValue]);
+    }
+    return Object.freeze(Object.fromEntries(validated));
+};
+export const snapshotRequest = (request) => {
+    if (request === null || typeof request !== "object") {
+        throw processError("invalid-input", "request must be an object");
+    }
+    const command = validateString(request.command, "command");
+    if (!Array.isArray(request.args)) {
+        throw processError("invalid-input", "args must be an array");
+    }
+    const args = [];
+    for (let index = 0; index < request.args.length; index += 1) {
+        const arg = request.args[index];
+        if (typeof arg !== "string" || hasNul(arg)) {
+            throw processError("invalid-input", `args[${index}] must be a string without NUL`);
+        }
+        args.push(arg);
+    }
+    const cwd = validateString(request.cwd, "cwd");
+    const environment = snapshotEnvironment(request.environment);
+    const timeoutMs = request.timeoutMs;
+    if (timeoutMs !== undefined &&
+        (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > PROCESS_TIMEOUT_MAX_MS)) {
+        throw processError("invalid-input", "timeoutMs must be an integer in 1..2147483647");
+    }
+    if (request.strictUtf8 !== undefined && typeof request.strictUtf8 !== "boolean") {
+        throw processError("invalid-input", "strictUtf8 must be a boolean");
+    }
+    return Object.freeze({
+        launch: Object.freeze({
+            command,
+            args: Object.freeze(args),
+            cwd,
+            ...(environment === undefined ? {} : { environment }),
+        }),
+        signal: request.signal,
+        timeoutMs,
+        strictUtf8: request.strictUtf8 ?? false,
+    });
+};
+//# sourceMappingURL=input.js.map

package/dist/internal/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/internal/input.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5C,MAAM,MAAM,GAAG,CAAC,KAAa,EAAW,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAEpE,MAAM,cAAc,GAAG,CAAC,KAAc,EAAE,KAAa,EAAU,EAAE;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACrE,MAAM,YAAY,CAAC,eAAe,EAAE,GAAG,KAAK,yCAAyC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAC1B,KAAmD,EACL,EAAE;IAChD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,SAAS,GAAuB,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,OAAO,EAAE,CAAC;QACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACnG,MAAM,YAAY,CAAC,eAAe,EAAE,iDAAiD,CAAC,CAAC;QACzF,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAgB,EAAmB,EAAE;IACnE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,YAAY,CAAC,eAAe,EAAE,2BAA2B,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,YAAY,CAAC,eAAe,EAAE,uBAAuB,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC5D,MAAM,GAAG,GAAY,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,YAAY,CAAC,eAAe,EAAE,QAAQ,KAAK,gCAAgC,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,IACE,SAAS,KAAK,SAAS;QACvB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,GAAG,sBAAsB,CAAC,EACrF,CAAC;QACD,MAAM,YAAY,CAAC,eAAe,EAAE,+CAA+C,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAChF,MAAM,YAAY,CAAC,eAAe,EAAE,8BAA8B,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,OAAO;YACP,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;YACzB,GAAG;YACH,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;SACtD,CAAC;QACF,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS;QACT,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,KAAK;KACxC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/internal/settlement.d.ts

@@ -0,0 +1,15 @@
+export type Settlement<T> = {
+    readonly status: "fulfilled";
+    readonly value: T;
+} | {
+    readonly status: "rejected";
+    readonly reason: unknown;
+};
+export type BoundedSettlement<T> = Settlement<T> | {
+    readonly status: "timeout";
+};
+export declare const settleOperation: <T>(operation: () => T | PromiseLike<T>) => Promise<Settlement<Awaited<T>>>;
+export declare const settleWithin: <T>(operation: () => T | PromiseLike<T>, timeoutMs: number) => Promise<BoundedSettlement<Awaited<T>>>;
+export declare const rejectedReasons: (settlements: readonly Settlement<unknown>[]) => unknown[];
+export declare const withCause: <T extends object>(error: T, cause: unknown) => T;
+//# sourceMappingURL=settlement.d.ts.map

package/dist/internal/settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../src/internal/settlement.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B,UAAU,CAAC,CAAC,CAAC,GACb;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAEnC,eAAO,MAAM,eAAe,GAAU,CAAC,aAC1B,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAClC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAMhC,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,CAAC,aACvB,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,aACxB,MAAM,KAChB,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAmBvC,CAAC;AAEF,eAAO,MAAM,eAAe,gBACb,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,KAC1C,OAAO,EAGP,CAAC;AAEJ,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,SAAS,CAAC,SAAS,OAAO,KAAG,CAOtE,CAAC"}