@vibesdotdev/host-bun 0.0.0-stage → 1.0.0-rc.3

package/dist/held-launch/abi.impl.bun.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The execution base's adapter over the native held-launch ABI
+ * (`native/held-launch/src/lib.rs` + `abi-manifest.json`, Codex's contract).
+ *
+ * It turns one opaque native handle into a {@link HeldLaunchHandle}:
+ *
+ * - **Payload.** The workload travels only as the framed control-fd payload
+ *   (`VHLW2\0`, u64BE minimum open-file budget, u32BE-length UTF-8 command and cwd, both absolute, a u32 argc
+ *   plus strings, a u32 env count plus key/value strings; nothing trailing),
+ *   bounded by the provider's declared `maxPayloadBytes` (never per request).
+ * - **Readiness is level-triggered.** Wait for the control fd's declared
+ *   interest through the event reactor, then advance; never a timer. Only
+ *   after a complete READY frame is the canonical identity read from the
+ *   retained child (`vhl_identity`, never a caller-supplied pid) and admitted
+ *   (`vhl_ready`); release takes a fresh identity snapshot.
+ * - **Exit.** The canonical process event precedes the parent's `try_reap`;
+ *   control-fd EOF is not exit, and READY/release is not exec success
+ *   (`vhl_exec_status` keeps exec failure apart from a workload's exit 126).
+ * - **Custody.** `take_fd` is one-shot; `resize` keeps the native PTY master;
+ *   `dispose` alone invalidates the handle, and a refusal keeps it.
+ *
+ * The native library and the host's event owners are ports: this module holds
+ * no timer, no process registry and no identity resolver.
+ */
+import { CapabilityError, type RuntimeLifecycle } from '@vibesdotdev/kernel';
+import { type HeldLaunchFdStreams } from './streams.impl.bun.ts';
+import type { HeldLaunchPort, NativeBirth } from '@vibesdotdev/execution-local/owned-session';
+/** An opaque native handle; valid until a successful dispose. */
+export type NativeLaunchHandle = number & {
+    readonly __nativeLaunchHandle: unique symbol;
+};
+/** An opaque native event-reactor handle; valid until `finish` returns 1. */
+export type NativeEventsHandle = number & {
+    readonly __nativeEventsHandle: unique symbol;
+};
+/**
+ * Mint the opaque handle for a native launch address. The brand is nominal:
+ * only a binding that received `address` from the native library, or a scripted
+ * library standing in for it, may call this.
+ */
+export declare function nativeLaunchHandle(address: number): NativeLaunchHandle;
+/** Mint the opaque handle for a native event-reactor address (same contract as {@link nativeLaunchHandle}). */
+export declare function nativeEventsHandle(address: number): NativeEventsHandle;
+/** The reactor's callback events (`vibes_native_core::process_events`). */
+export declare const REACTOR_EVENT: {
+    readonly fdReady: 1;
+    readonly childExited: 2;
+    readonly cancelAck: 3;
+    readonly disposeAck: 4;
+    readonly watchError: 5;
+};
+/** The ABI's stream numbers for `take_fd`. */
+export type NativeStream = 0 | 1 | 2 | 3;
+/**
+ * The raw ABI, one method per exported symbol. Integers are the ABI's own
+ * return codes; this module interprets them. A binding (bun:ffi) implements it.
+ */
+export interface HeldLaunchLibrary {
+    spawn(helperPath: string, helperCwd: string, payload: Uint8Array, maxPayloadBytes: number, stdin: number, stdout: number, stderr: number, cols: number, rows: number): NativeLaunchHandle | null;
+    pid(handle: NativeLaunchHandle): number;
+    /** The retained child's canonical identity, or null on failure (see `lastError`). */
+    identity(handle: NativeLaunchHandle): NativeBirth | null;
+    controlFd(handle: NativeLaunchHandle): number;
+    /** 1 readable, 2 writable, negative on failure. */
+    controlInterest(handle: NativeLaunchHandle): number;
+    /** 0 pending, 1 complete READY frame, -1 failure. */
+    advanceReady(handle: NativeLaunchHandle): number;
+    /** 0 pending, 1 READY admitted, -1 failure. */
+    ready(handle: NativeLaunchHandle, pid: number, sessionId: number, startToken: Uint8Array): number;
+    /** 1 released, -1 failure. */
+    release(handle: NativeLaunchHandle, pid: number, sessionId: number, startToken: Uint8Array): number;
+    /** An owned fd, -2 undeclared or already transferred, -1 failure. */
+    takeFd(handle: NativeLaunchHandle, stream: NativeStream): number;
+    resize(handle: NativeLaunchHandle, cols: number, rows: number): number;
+    terminate(handle: NativeLaunchHandle): number;
+    /** status 0 pending, 1 reaped, -1 failure; code -1 absent; signal 0 absent. */
+    reap(handle: NativeLaunchHandle): {
+        status: number;
+        code: number;
+        signal: number;
+    };
+    /** status 0 pending, 1 control closed (not exit), 2 exec failure with errno, -1 failure. */
+    execStatus(handle: NativeLaunchHandle): {
+        status: number;
+        errno: number;
+    };
+    /** 1 disposed (handle invalid), -1 refused (handle and child retained). */
+    dispose(handle: NativeLaunchHandle): number;
+    /** The last failure on this thread: `<phase>:errno=<n>`, or null. */
+    lastError(): string | null;
+    /**
+     * Create the event reactor. `onEvent` is called on the JS thread for every
+     * native callback `(id, event, detail)`; the binding keeps it alive until
+     * `releaseCallback` runs, which the owner calls only after `eventsFinish`
+     * returned 1. The caps are the provider's declared resource inputs.
+     */
+    eventsCreate(onEvent: (id: number, event: number, detail: number) => void, maxWatches: number, maxPendingCommands: number): {
+        owner: NativeEventsHandle;
+        releaseCallback(): void;
+    } | null;
+    /** 1 accepted, -1 failure. `interest` 1 readable, 2 writable. */
+    eventsWatchFd(owner: NativeEventsHandle, fd: number, interest: 1 | 2, id: number): number;
+    /** 1 accepted, -1 failure; an already-exited child is delivered at once. */
+    eventsWatchChild(owner: NativeEventsHandle, handle: NativeLaunchHandle, id: number): number;
+    /** 1 pending (a cancel ACK follows), 2 already terminal (no new ACK), -1 failure. */
+    eventsCancel(owner: NativeEventsHandle, id: number): number;
+    /** 1 accepted (memoized; the pointer stays valid; event 4 follows), -1 failure. */
+    eventsDispose(owner: NativeEventsHandle): number;
+    /** 0 thread still running, 1 joined (pointer invalid), -1 failure (pointer retained). */
+    eventsFinish(owner: NativeEventsHandle): number;
+}
+/**
+ * The event owner around the ABI (the held-launch reactor, see
+ * {@link createHeldLaunchReactor}): one-shot,
+ * level-triggered watches that honour `signal` and settle only after the
+ * reactor acknowledged a cancel. None is a timer.
+ */
+export interface HeldLaunchEvents {
+    /** Resolve once `fd` has the level-triggered `interest`; reject when `signal` aborts. */
+    controlReady(fd: number, interest: 'readable' | 'writable', signal: AbortSignal): Promise<void>;
+    /**
+     * Resolve when the retained child of `handle` has an exit to reap, including
+     * one that already happened; reject when `signal` aborts.
+     */
+    childExited(handle: NativeLaunchHandle, signal: AbortSignal): Promise<void>;
+}
+/**
+ * The {@link HeldLaunchPort} over a native held-launch library. `helperPath`
+ * is the installed trusted helper the host's manifest names; `maxPayloadBytes`
+ * is the provider's declared input budget (never a per-request override); the
+ * helper starts in the workload's cwd, which the payload also carries.
+ */
+export declare function createHeldLaunchPort(options: {
+    readonly library: HeldLaunchLibrary;
+    readonly helperPath: string;
+    readonly maxPayloadBytes: number;
+    readonly events: HeldLaunchEvents;
+    readonly streams?: HeldLaunchFdStreams;
+}): HeldLaunchPort;
+/** The provider's declared reactor resource caps. */
+export interface HeldLaunchReactorCaps {
+    readonly maxWatches: number;
+    readonly maxPendingCommands: number;
+}
+/** A runtime's one reactor: the {@link HeldLaunchEvents} plus its two-step shutdown. */
+export interface HeldLaunchReactor extends HeldLaunchEvents {
+    /**
+     * Close every watch and join the reactor thread within `signal`/the
+     * finalization budget: dispose (memoized), await the dispose ACK, then
+     * `finish` until it joins; only then is the JS callback released. Resolves
+     * `joined: false` when the budget ran out before the join: the callback and
+     * library stay alive, and cleanup is unconfirmed, never claimed.
+     */
+    shutdown(lifecycle: Pick<RuntimeLifecycle, 'wait' | 'delay'>, budgetMs: number): Promise<HeldLaunchReactorShutdown>;
+}
+/**
+ * How a reactor shutdown ended. `joined: false` carries the typed failure
+ * (the finalization budget ran out, or the wait was cancelled) that left the
+ * join unconfirmed.
+ */
+export type HeldLaunchReactorShutdown = {
+    readonly joined: true;
+} | {
+    readonly joined: false;
+    readonly unconfirmed: CapabilityError;
+};
+/**
+ * The held-launch reactor over the native ABI. One per runtime, created on the
+ * first held launch. Watches are one-shot and level-triggered; a watch whose
+ * signal aborts is cancelled and settles only on its cancel ACK (or its
+ * already-in-flight terminal event), so an id is never retired early and never
+ * reused.
+ */
+export declare function createHeldLaunchReactor(library: HeldLaunchLibrary, caps: HeldLaunchReactorCaps): HeldLaunchReactor;
+//# sourceMappingURL=abi.impl.bun.d.ts.map

package/dist/held-launch/abi.impl.bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.impl.bun.d.ts","sourceRoot":"","sources":["../../src/held-launch/abi.impl.bun.ts"],"names":[],"mappings":"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"}

package/dist/held-launch/abi.impl.bun.js

@@ -0,0 +1,476 @@
+/**
+ * The execution base's adapter over the native held-launch ABI
+ * (`native/held-launch/src/lib.rs` + `abi-manifest.json`, Codex's contract).
+ *
+ * It turns one opaque native handle into a {@link HeldLaunchHandle}:
+ *
+ * - **Payload.** The workload travels only as the framed control-fd payload
+ *   (`VHLW2\0`, u64BE minimum open-file budget, u32BE-length UTF-8 command and cwd, both absolute, a u32 argc
+ *   plus strings, a u32 env count plus key/value strings; nothing trailing),
+ *   bounded by the provider's declared `maxPayloadBytes` (never per request).
+ * - **Readiness is level-triggered.** Wait for the control fd's declared
+ *   interest through the event reactor, then advance; never a timer. Only
+ *   after a complete READY frame is the canonical identity read from the
+ *   retained child (`vhl_identity`, never a caller-supplied pid) and admitted
+ *   (`vhl_ready`); release takes a fresh identity snapshot.
+ * - **Exit.** The canonical process event precedes the parent's `try_reap`;
+ *   control-fd EOF is not exit, and READY/release is not exec success
+ *   (`vhl_exec_status` keeps exec failure apart from a workload's exit 126).
+ * - **Custody.** `take_fd` is one-shot; `resize` keeps the native PTY master;
+ *   `dispose` alone invalidates the handle, and a refusal keeps it.
+ *
+ * The native library and the host's event owners are ports: this module holds
+ * no timer, no process registry and no identity resolver.
+ */
+import { closeSync } from 'node:fs';
+import { constants as osConstants } from 'node:os';
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { encodeHeldLaunchPayload, heldLaunchPayloadInvalid, isHeldLaunchAbsolutePath } from '@vibesdotdev/execution-local';
+import { createReactorFdStreams } from "./streams.impl.bun.js";
+/**
+ * Mint the opaque handle for a native launch address. The brand is nominal:
+ * only a binding that received `address` from the native library, or a scripted
+ * library standing in for it, may call this.
+ */
+export function nativeLaunchHandle(address) {
+    // SAFETY: `NativeLaunchHandle` is a nominal brand over the native address; the number is unchanged and the brand has no runtime representation.
+    return address;
+}
+/** Mint the opaque handle for a native event-reactor address (same contract as {@link nativeLaunchHandle}). */
+export function nativeEventsHandle(address) {
+    // SAFETY: `NativeEventsHandle` is a nominal brand over the native address; the number is unchanged and the brand has no runtime representation.
+    return address;
+}
+/** The reactor's callback events (`vibes_native_core::process_events`). */
+export const REACTOR_EVENT = { fdReady: 1, childExited: 2, cancelAck: 3, disposeAck: 4, watchError: 5 };
+const STDIO_CODE = { pipe: 0, inherit: 1, ignore: 2 };
+function nativeFailureDetails(library, operation) {
+    const raw = library.lastError() ?? '';
+    const match = /^([a-z0-9-]+):errno=(-?\d+)$/.exec(raw);
+    return {
+        operation,
+        phase: match?.[1] ?? 'unknown',
+        errno: match ? Number(match[2]) : null
+    };
+}
+/** A native failure, with the ABI's fixed phase and errno only (never workload values). */
+function nativeFailure(library, operation) {
+    return new CapabilityError(`The native held launch failed during ${operation}.`, 'UNAVAILABLE', {
+        reason: 'held-launch-failed',
+        retryable: false,
+        details: nativeFailureDetails(library, operation)
+    });
+}
+const SIGNAL_NAMES = new Map(Object.entries(osConstants.signals).map(([name, number]) => [number, name]));
+/** Close `fd`; a failed close is returned for the caller to report, never dropped. */
+function closeOnce(fd) {
+    try {
+        closeSync(fd);
+        return null;
+    }
+    catch (cause) {
+        return new CapabilityError('A transferred held-launch descriptor could not be closed.', 'UNAVAILABLE', {
+            reason: 'held-launch-fd-close-failed',
+            retryable: false,
+            details: { fd },
+            cause
+        });
+    }
+}
+/** Take the declared descriptors and give each to exactly one stream owner. */
+function adoptIo(library, streams, handle, request, live) {
+    const taken = [];
+    const take = (stream) => {
+        const fd = library.takeFd(handle, stream);
+        if (fd === -2)
+            return null;
+        if (fd < 0)
+            throw nativeFailure(library, 'take-fd');
+        taken.push(fd);
+        return fd;
+    };
+    try {
+        if (request.pty !== undefined) {
+            const master = take(3);
+            if (master === null)
+                throw nativeFailure(library, 'take-pty-master');
+            return {
+                io: {
+                    kind: 'pty',
+                    // One owner for the one master fd: read and written, closed once.
+                    master: streams.duplex(master),
+                    resize(cols, rows) {
+                        if (library.resize(live('resize'), cols, rows) !== 1)
+                            throw nativeFailure(library, 'resize');
+                    }
+                },
+                failure: undefined
+            };
+        }
+        const stdio = request.stdio;
+        const stdin = stdio.stdin === 'pipe' ? take(0) : null;
+        const stdout = stdio.stdout === 'pipe' ? take(1) : null;
+        const stderr = stdio.stderr === 'pipe' ? take(2) : null;
+        return {
+            io: {
+                kind: 'pipes',
+                stdin: stdin === null ? null : streams.writer(stdin),
+                stdout: stdout === null ? null : streams.reader(stdout),
+                stderr: stderr === null ? null : streams.reader(stderr)
+            },
+            failure: undefined
+        };
+    }
+    catch (error) {
+        // Every take precedes stream construction, so no stream owns these fds yet:
+        // this failed adoption closes each exactly once, and reports a close that fails.
+        const closeFailures = taken.map(closeOnce).filter((failure) => failure !== null);
+        const adoption = error instanceof CapabilityError
+            ? error
+            : new CapabilityError('The native held launch failed during adopt.', 'UNAVAILABLE', {
+                reason: 'held-launch-failed',
+                retryable: false,
+                details: nativeFailureDetails(library, 'adopt'),
+                cause: error
+            });
+        const failure = closeFailures.length === 0
+            ? adoption
+            : new CapabilityError('The held launch failed during adopt, and a transferred descriptor could not be closed.', 'UNAVAILABLE', {
+                reason: 'held-launch-adoption-cleanup-failed',
+                retryable: false,
+                cause: new AggregateError([adoption, ...closeFailures])
+            });
+        return { io: { kind: 'pipes', stdin: null, stdout: null, stderr: null }, failure };
+    }
+}
+function tokenBytes(birth) {
+    return new TextEncoder().encode(birth.startToken);
+}
+function adoptHandle(library, events, streams, handle, request) {
+    let disposed = false;
+    const live = (operation) => {
+        if (disposed) {
+            throw new CapabilityError(`The held launch was disposed; ${operation} has no handle.`, 'CONFLICT', {
+                reason: 'held-launch-disposed',
+                retryable: false
+            });
+        }
+        return handle;
+    };
+    // Custody first: nothing below may drop this handle. A failure while
+    // adopting it surfaces from `ready()`, so the owner's one cleanup still
+    // terminates, reaps and disposes the retained child.
+    let adoptionFailure;
+    if (library.pid(handle) <= 0)
+        adoptionFailure = nativeFailure(library, 'pid');
+    /** The canonical identity of the retained child, read natively. */
+    const identify = (operation) => {
+        const birth = library.identity(live(operation));
+        if (birth === null)
+            throw nativeFailure(library, `${operation}-identity`);
+        return birth;
+    };
+    // The streams exist from birth: the workload runs only after release.
+    const adopted = adoptIo(library, streams, handle, request, live);
+    adoptionFailure ??= adopted.failure;
+    const { io } = adopted;
+    const awaitControl = (signal) => {
+        const current = live('ready');
+        const interest = library.controlInterest(current);
+        if (interest !== 1 && interest !== 2)
+            throw nativeFailure(library, 'control-interest');
+        return events.controlReady(library.controlFd(current), interest === 1 ? 'readable' : 'writable', signal);
+    };
+    return {
+        io,
+        async ready(signal) {
+            if (adoptionFailure)
+                throw adoptionFailure;
+            // Level-triggered: advance; on "pending", wait for the declared interest and advance again.
+            for (;;) {
+                const advanced = library.advanceReady(live('ready'));
+                if (advanced === 1)
+                    break;
+                if (advanced < 0)
+                    throw nativeFailure(library, 'advance-ready');
+                await awaitControl(signal);
+            }
+            // Only after a complete READY frame: the canonical identity, then admission.
+            for (;;) {
+                const birth = identify('ready');
+                const admitted = library.ready(live('ready'), birth.pid, birth.sessionId, tokenBytes(birth));
+                if (admitted === 1)
+                    return birth;
+                if (admitted < 0)
+                    throw nativeFailure(library, 'ready');
+                await awaitControl(signal);
+            }
+        },
+        async release() {
+            // A fresh identity snapshot: release checks the held child is still that birth.
+            const birth = identify('release');
+            if (library.release(live('release'), birth.pid, birth.sessionId, tokenBytes(birth)) !== 1) {
+                throw nativeFailure(library, 'release');
+            }
+        },
+        async terminateChild() {
+            if (library.terminate(live('terminate')) !== 1)
+                throw nativeFailure(library, 'terminate');
+        },
+        async exited(signal) {
+            await events.childExited(live('exited'), signal);
+        },
+        async reaped(signal) {
+            // The canonical exit event precedes the parent's reap; a pending reap waits for it.
+            for (;;) {
+                const result = library.reap(live('reap'));
+                if (result.status === 1) {
+                    return {
+                        code: result.code === -1 ? null : result.code,
+                        signal: result.signal === 0 ? null : (SIGNAL_NAMES.get(result.signal) ?? `SIG${result.signal}`)
+                    };
+                }
+                if (result.status < 0)
+                    throw nativeFailure(library, 'reap');
+                await events.childExited(live('reap'), signal);
+            }
+        },
+        execStatus() {
+            const result = library.execStatus(live('exec-status'));
+            if (result.status === 0)
+                return { status: 'pending' };
+            if (result.status === 1)
+                return { status: 'control-closed' };
+            if (result.status === 2)
+                return { status: 'exec-failed', errno: result.errno };
+            throw nativeFailure(library, 'exec-status');
+        },
+        async dispose() {
+            if (disposed)
+                return { disposed: true };
+            if (library.dispose(handle) === 1) {
+                disposed = true;
+                return { disposed: true };
+            }
+            // Refused: the native handle and its child stay in custody.
+            const failure = nativeFailure(library, 'dispose');
+            return { disposed: false, reason: `${failure.details?.phase ?? 'unknown'}` };
+        }
+    };
+}
+function budgetInvalid(value) {
+    return new CapabilityError('A held-launch provider declares a positive whole-byte payload budget.', 'INVALID_INPUT', {
+        reason: 'held-launch-payload-budget-invalid',
+        retryable: false,
+        details: { maxPayloadBytes: value }
+    });
+}
+/**
+ * The {@link HeldLaunchPort} over a native held-launch library. `helperPath`
+ * is the installed trusted helper the host's manifest names; `maxPayloadBytes`
+ * is the provider's declared input budget (never a per-request override); the
+ * helper starts in the workload's cwd, which the payload also carries.
+ */
+export function createHeldLaunchPort(options) {
+    const { library, helperPath, maxPayloadBytes, events } = options;
+    // Default: the descriptors are read and written on the same reactor's readiness.
+    const streams = options.streams ?? createReactorFdStreams(events);
+    if (!isHeldLaunchAbsolutePath(helperPath))
+        throw heldLaunchPayloadInvalid('helperPath');
+    if (!Number.isSafeInteger(maxPayloadBytes) || maxPayloadBytes <= 0)
+        throw budgetInvalid(maxPayloadBytes);
+    return {
+        spawn(request) {
+            const payload = encodeHeldLaunchPayload(request);
+            if (payload.length > maxPayloadBytes) {
+                throw new CapabilityError('The held launch workload exceeds the provider\'s declared payload budget.', 'INVALID_INPUT', {
+                    reason: 'held-launch-payload-too-large',
+                    retryable: false,
+                    details: { bytes: payload.length, maxPayloadBytes }
+                });
+            }
+            const stdio = request.stdio ?? { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' };
+            const handle = library.spawn(helperPath, request.cwd, payload, maxPayloadBytes, STDIO_CODE[stdio.stdin], STDIO_CODE[stdio.stdout], STDIO_CODE[stdio.stderr], request.pty?.cols ?? 0, request.pty?.rows ?? 0);
+            if (handle === null)
+                throw nativeFailure(library, 'spawn');
+            return adoptHandle(library, events, streams, handle, request);
+        }
+    };
+}
+function reactorFailure(library, operation) {
+    return nativeFailure(library, operation);
+}
+/**
+ * The held-launch reactor over the native ABI. One per runtime, created on the
+ * first held launch. Watches are one-shot and level-triggered; a watch whose
+ * signal aborts is cancelled and settles only on its cancel ACK (or its
+ * already-in-flight terminal event), so an id is never retired early and never
+ * reused.
+ */
+export function createHeldLaunchReactor(library, caps) {
+    for (const [name, value] of Object.entries(caps)) {
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new CapabilityError(`The held-launch reactor's ${name} must be a positive whole number.`, 'INVALID_INPUT', {
+                reason: 'held-launch-reactor-caps-invalid',
+                retryable: false,
+                details: { [name]: value }
+            });
+        }
+    }
+    const pending = new Map();
+    let nextId = 1;
+    let fatalError;
+    let disposeAck;
+    const disposeAcked = new Promise((resolve) => {
+        disposeAck = resolve;
+    });
+    let shuttingDown = false;
+    const onEvent = (id, event, detail) => {
+        if (id === 0 && event === REACTOR_EVENT.watchError) {
+            fatalError = new CapabilityError('A held-launch global reactor error occurred.', 'UNAVAILABLE', {
+                reason: 'held-launch-reactor-failed',
+                retryable: false,
+                details: { errno: detail }
+            });
+            shuttingDown = true;
+            for (const [watchId, watch] of pending) {
+                pending.delete(watchId);
+                watch.reject(fatalError);
+            }
+            return;
+        }
+        if (event === REACTOR_EVENT.disposeAck) {
+            // Every watch is closed now; any still pending never receives its event.
+            for (const [watchId, watch] of pending) {
+                pending.delete(watchId);
+                watch.reject(watch.cancelError ??
+                    watch.aborted ??
+                    new CapabilityError('The held-launch reactor was disposed before this watch fired.', 'CANCELLED', {
+                        reason: 'held-launch-reactor-disposed',
+                        retryable: false
+                    }));
+            }
+            disposeAck();
+            return;
+        }
+        const watch = pending.get(id);
+        if (!watch)
+            return;
+        pending.delete(id);
+        if (watch.cancelError !== undefined) {
+            watch.reject(watch.cancelError);
+            return;
+        }
+        if (watch.aborted !== undefined) {
+            watch.reject(watch.aborted);
+            return;
+        }
+        if (event === REACTOR_EVENT.fdReady || event === REACTOR_EVENT.childExited)
+            watch.resolve();
+        else if (event === REACTOR_EVENT.watchError) {
+            watch.reject(new CapabilityError('A held-launch watch failed natively.', 'UNAVAILABLE', {
+                reason: 'held-launch-watch-failed',
+                retryable: false,
+                details: { errno: detail }
+            }));
+        }
+        else {
+            watch.reject(new CapabilityError('The held-launch watch was cancelled.', 'CANCELLED', { reason: 'held-launch-watch-cancelled', retryable: false }));
+        }
+    };
+    const created = library.eventsCreate(onEvent, caps.maxWatches, caps.maxPendingCommands);
+    if (created === null)
+        throw reactorFailure(library, 'events-create');
+    const { owner, releaseCallback } = created;
+    const watch = (arm, operation, signal) => {
+        if (fatalError)
+            return Promise.reject(fatalError);
+        if (shuttingDown) {
+            return Promise.reject(new CapabilityError('The held-launch reactor is shutting down.', 'UNAVAILABLE', { reason: 'held-launch-reactor-disposed', retryable: false }));
+        }
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            const entry = { resolve, reject, cancelSent: false };
+            pending.set(id, entry);
+            if (arm(id) !== 1) {
+                pending.delete(id);
+                reject(reactorFailure(library, operation));
+                return;
+            }
+            const onAbort = () => {
+                if (!pending.has(id) || entry.cancelSent)
+                    return;
+                entry.aborted = signal.reason;
+                entry.cancelSent = true;
+                // 1: an ACK follows; 2: the terminal event is in flight. Either way the entry settles on it.
+                // A cancel returning < 0 keeps pending custody until a terminal event, cancel ACK, or disposeAck.
+                if (library.eventsCancel(owner, id) < 0) {
+                    entry.cancelError = reactorFailure(library, 'events-cancel');
+                }
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            const settle = () => signal.removeEventListener('abort', onAbort);
+            entry.resolve = () => {
+                settle();
+                resolve();
+            };
+            entry.reject = (error) => {
+                settle();
+                reject(error);
+            };
+        });
+    };
+    let shutdownResult;
+    return {
+        controlReady(fd, interest, signal) {
+            return watch((id) => library.eventsWatchFd(owner, fd, interest === 'readable' ? 1 : 2, id), 'events-watch-fd', signal);
+        },
+        childExited(handle, signal) {
+            return watch((id) => library.eventsWatchChild(owner, handle, id), 'events-watch-child', signal);
+        },
+        shutdown(lifecycle, budgetMs) {
+            shutdownResult ??= (async () => {
+                shuttingDown = true;
+                let disposeError = null;
+                if (library.eventsDispose(owner) !== 1) {
+                    disposeError = reactorFailure(library, 'events-dispose');
+                }
+                try {
+                    await lifecycle.wait(async (signal) => {
+                        if (!disposeError) {
+                            // The dispose ACK arrives before the thread exits: it closes watches, not the join.
+                            await Promise.race([
+                                disposeAcked,
+                                new Promise((_, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true }))
+                            ]);
+                        }
+                        // The native thread offers no join event: finish is polled, bounded by this wait.
+                        for (;;) {
+                            const finished = library.eventsFinish(owner);
+                            if (finished === 1)
+                                return;
+                            if (finished < 0)
+                                throw reactorFailure(library, 'events-finish');
+                            await lifecycle.delay(5, signal);
+                        }
+                    }, { timeoutMs: Math.max(1, budgetMs), reason: 'held-launch-reactor-finish' });
+                }
+                catch (error) {
+                    if (error instanceof CapabilityError && (error.code === 'TIMEOUT' || error.code === 'CANCELLED')) {
+                        // Not joined: keep the callback and library alive; cleanup is unconfirmed.
+                        return { joined: false, unconfirmed: error };
+                    }
+                    throw error;
+                }
+                releaseCallback();
+                if (disposeError)
+                    throw disposeError;
+                return { joined: true };
+            })();
+            return shutdownResult;
+        }
+    };
+}
+//# sourceMappingURL=abi.impl.bun.js.map