reactor-effect-native 0.2.0 → 0.3.0-rc.0

package/dist/_internal/peer.js

@@ -1,9 +1,13 @@
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import * as Queue from "effect/Queue";
+import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
-import { ReactorError, ErrorCode } from "reactor-effect-client";
+import { IceFailed, Mapping, ReactorError, TransportFailed } from "reactor-effect-client";
 import { Observations, errorOf } from "reactor-effect-client/host";
-import { encodeNativeJson, encodeNativeText, NativeBridge, NativeCall, } from "./bridge.js";
+import { encodeNativeJson, encodeNativeText, NativeBridge, NativeCall, nativeFailure, Ready, } from "./bridge.js";
 const stateValues = new Set([
     "new",
     "connecting",
@@ -12,7 +16,6 @@ const stateValues = new Set([
     "failed",
     "closed",
 ]);
-const isErrorCode = Schema.is(ErrorCode);
 const statsBigInts = new Set([
     "bytesSent",
     "bytesReceived",
@@ -21,61 +24,66 @@ const statsBigInts = new Set([
     "retransmittedPacketsSent",
     "priority",
 ]);
-const validateNativeTracks = (tracks) => {
+// Bound on reading statistics to classify a failed connection.
+const CLASSIFY_TIMEOUT_MS = 2000;
+/**
+ * How long closing a peer waits for its native owner join. A healthy join under
+ * real libwebrtc took 13-62 ms in the media load tests on Node and Bun, which
+ * require it under 2 s; the default leaves five times that bound.
+ */
+export const defaultShutdownTimeout = Duration.seconds(10);
+export const validateNativeTracks = (tracks) => {
     const incomingVideo = tracks.filter((track) => track.direction === "recvonly" && track.kind === "video").length;
     const incomingAudio = tracks.filter((track) => track.direction === "recvonly" && track.kind === "audio").length;
     if (incomingVideo > 1 || incomingAudio > 1) {
-        throw new ReactorError("UnsupportedCapability", "native WebRTC currently supports at most one incoming video and one incoming audio track because reactor-webrtc does not expose the remote track MID to its observer", { outcome: "not-submitted" });
+        throw ReactorError.fromCode("UnsupportedCapability", "native WebRTC currently supports at most one incoming video and one incoming audio track because reactor-webrtc does not expose the remote track MID to its observer", { outcome: "not-submitted" });
     }
 };
 const record = (value, what) => {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        throw new ReactorError("Protocol", `native ${what} is not an object`);
+    if (!Predicate.isObject(value))
+        throw ReactorError.fromCode("Protocol", `native ${what} is not an object`);
     return value;
 };
 const string = (value, what) => {
     if (typeof value !== "string")
-        throw new ReactorError("Protocol", `native ${what} is not a string`);
+        throw ReactorError.fromCode("Protocol", `native ${what} is not a string`);
     return value;
 };
 const integer = (value, what) => {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
-        throw new ReactorError("Protocol", `native ${what} is not a nonnegative safe integer`);
+        throw ReactorError.fromCode("Protocol", `native ${what} is not a nonnegative safe integer`);
     return value;
 };
 const bigint = (value, what) => {
     if (typeof value !== "string" || !/^[0-9]+$/.test(value))
-        throw new ReactorError("Protocol", `native ${what} is not an unsigned integer string`);
+        throw ReactorError.fromCode("Protocol", `native ${what} is not an unsigned integer string`);
     return BigInt(value);
 };
-const nativeError = (cause, operation) => cause instanceof ReactorError ? cause : errorOf(cause, "Native", operation);
+const nativeError = (cause, operation) => ReactorError.is(cause) ? cause : errorOf(cause, "Native", operation);
+const decodeMappings = Schema.decodeUnknownResult(Schema.Array(Mapping).check(Schema.isMaxLength(64)));
+/** The client's own `Mapping` schema, so the host and the session agree on every rule. */
 const parseMapping = (value) => {
-    if (!Array.isArray(value) || value.length > 64)
-        throw new ReactorError("Protocol", "native prepare returned an invalid mapping list");
-    return Object.freeze(value.map((item) => {
-        const entry = record(item, "mapping");
-        const name = string(entry.name, "mapping.name"), kind = string(entry.kind, "mapping.kind"), direction = string(entry.direction, "mapping.direction"), mid = string(entry.mid, "mapping.mid");
-        if (kind !== "audio" && kind !== "video")
-            throw new ReactorError("Protocol", "native mapping has an unknown track kind");
-        if (direction !== "recvonly" && direction !== "sendonly")
-            throw new ReactorError("Protocol", "native mapping has an unknown direction");
-        return Object.freeze({ name, kind, direction, mid });
-    }));
+    const decoded = decodeMappings(value);
+    if (Result.isFailure(decoded))
+        throw ReactorError.fromCode("Protocol", "native prepare returned an invalid mapping list", {
+            detail: decoded.failure,
+        });
+    return Object.freeze(decoded.success.map((entry) => Object.freeze({ ...entry })));
 };
 const parsePrepared = (value) => {
     const response = record(value, "prepare response"), sdp = string(response.sdp, "prepare.sdp"), mapping = parseMapping(response.mapping);
     if (sdp.length === 0)
-        throw new ReactorError("Protocol", "native prepare returned an empty SDP offer");
+        throw ReactorError.fromCode("Protocol", "native prepare returned an empty SDP offer");
     return Object.freeze({ sdp, mapping });
 };
-const iceServers = (servers) => servers.map((server) => {
+export const iceServers = (servers) => servers.map((server) => {
     const urls = typeof server.urls === "string" ? [server.urls] : [...server.urls];
     if (urls.length === 0 || urls.some((url) => typeof url !== "string" || url.length === 0))
-        throw new ReactorError("InvalidInput", "native ICE server has no usable URL", {
+        throw ReactorError.fromCode("InvalidInput", "native ICE server has no usable URL", {
             outcome: "not-submitted",
         });
     if (server.credential !== undefined && typeof server.credential !== "string")
-        throw new ReactorError("UnsupportedCapability", "native ICE supports password credentials, not OAuth credential objects", { outcome: "not-submitted" });
+        throw ReactorError.fromCode("UnsupportedCapability", "native ICE supports password credentials, not OAuth credential objects", { outcome: "not-submitted" });
     return Object.freeze({
         urls: Object.freeze(urls),
         username: server.username ?? "",
@@ -89,21 +97,21 @@ const parseEvent = (packet) => {
         case "state": {
             const state = string(header.state, "state");
             if (!stateValues.has(state))
-                throw new ReactorError("Protocol", `native peer reported unknown state ${state}`);
+                throw ReactorError.fromCode("Protocol", `native peer reported unknown state ${state}`);
             return { type: "state", state: state };
         }
         case "channel": {
             const channel = string(header.channel, "channel");
             if (channel !== "control" && channel !== "data")
-                throw new ReactorError("Protocol", "native peer reported an unknown data channel");
+                throw ReactorError.fromCode("Protocol", "native peer reported an unknown data channel");
             if (typeof header.open !== "boolean")
-                throw new ReactorError("Protocol", "native channel event omitted its open state");
+                throw ReactorError.fromCode("Protocol", "native channel event omitted its open state");
             return { type: "channel", channel, open: header.open };
         }
         case "message": {
             const channel = string(header.channel, "message.channel");
             if (channel !== "control" && channel !== "data")
-                throw new ReactorError("Protocol", "native peer message named an unknown channel");
+                throw ReactorError.fromCode("Protocol", "native peer message named an unknown channel");
             return { type: "message", channel, bytes: packet.payload };
         }
         case "ice": {
@@ -127,7 +135,7 @@ const parseEvent = (packet) => {
         case "decoded": {
             const kind = string(header.kind, "decoded.kind");
             if (kind !== "video" && kind !== "audio")
-                throw new ReactorError("Protocol", "native decoded event has unknown media kind");
+                throw ReactorError.fromCode("Protocol", "native decoded event has unknown media kind");
             return {
                 type: "decoded",
                 kind,
@@ -136,63 +144,62 @@ const parseEvent = (packet) => {
             };
         }
         case "error": {
-            const rawCode = string(header.code, "error.code"), code = isErrorCode(rawCode) ? rawCode : "Native";
-            string(header.message, "error.message");
+            const status = header.status;
+            if (typeof status !== "number" || !Number.isSafeInteger(status))
+                throw ReactorError.fromCode("Protocol", "native error event omitted its failure class");
             return {
                 type: "error",
-                error: new ReactorError(code, `native peer failed (${code})`, { detail: header }),
+                error: nativeFailure(status, string(header.message, "error.message"), (code) => `native peer failed (${code})`, {}),
             };
         }
         default:
-            throw new ReactorError("Protocol", `native peer emitted unknown event type ${type}`);
+            throw ReactorError.fromCode("Protocol", `native peer emitted unknown event type ${type}`);
     }
 };
-const parseVideo = (packet) => {
-    const h = packet.header;
-    if (h.type !== "video" || h.format !== "BGRA")
-        throw new ReactorError("Protocol", "native video packet has an unsupported format");
-    const width = integer(h.width, "video.width"), height = integer(h.height, "video.height"), dataLength = integer(h.dataLength, "video.dataLength"), metadataLength = integer(h.metadataLength, "video.metadataLength");
-    if (width === 0 ||
-        height === 0 ||
-        dataLength !== width * height * 4 ||
-        dataLength + metadataLength !== packet.payload.length)
-        throw new ReactorError("Protocol", "native BGRA frame dimensions do not match its payload");
+/** The native track index is the position of the track in the prepare request. */
+const receiving = (tracks, index, kind) => {
+    const track = tracks[index];
+    if (track?.direction !== "recvonly" || track.kind !== kind)
+        throw ReactorError.fromCode("Protocol", `native ${kind} was delivered without its declared receive mapping`);
+    return track.name;
+};
+const videoFrame = (tracks, taken) => {
+    const track = receiving(tracks, taken.track, "video");
+    if (taken.width === 0 ||
+        taken.height === 0 ||
+        taken.data.byteLength !== taken.width * taken.height * 4)
+        throw ReactorError.fromCode("Protocol", "native BGRA frame dimensions do not match its payload");
     return Object.freeze({
         _tag: "VideoFrame",
-        track: string(h.track, "video.track"),
-        width,
-        height,
-        frameId: bigint(h.frameId, "video.frameId"),
-        timestampMicros: bigint(h.timestampMicros, "video.timestampMicros"),
-        data: Uint8Array.from(packet.payload.subarray(0, dataLength)),
-        metadata: Uint8Array.from(packet.payload.subarray(dataLength)),
+        track,
+        format: "BGRA",
+        width: taken.width,
+        height: taken.height,
+        frameId: taken.frameId,
+        timestampMicros: taken.timestampMicros,
+        sequence: taken.sequence,
+        data: taken.data,
+        metadata: taken.metadata,
     });
 };
-const parseAudio = (packet) => {
-    const h = packet.header;
-    if (h.type !== "audio" || h.format !== "s16le")
-        throw new ReactorError("Protocol", "native audio packet has an unsupported format");
-    const sampleRate = integer(h.sampleRate, "audio.sampleRate"), channels = integer(h.channels, "audio.channels"), samples = integer(h.samples, "audio.samples");
-    if (sampleRate === 0 ||
-        channels === 0 ||
-        samples % channels !== 0 ||
-        packet.payload.length !== samples * 2)
-        throw new ReactorError("Protocol", "native PCM format does not match its payload");
-    const view = new DataView(packet.payload.buffer, packet.payload.byteOffset, packet.payload.byteLength), pcm = new Int16Array(samples);
-    for (let index = 0; index < samples; index++)
-        pcm[index] = view.getInt16(index * 2, true);
+const audioFrame = (tracks, taken) => {
+    const track = receiving(tracks, taken.track, "audio");
+    if (taken.sampleRate === 0 || taken.channels === 0 || taken.samples.length % taken.channels)
+        throw ReactorError.fromCode("Protocol", "native PCM format does not match its payload");
     return Object.freeze({
         _tag: "AudioFrame",
-        track: string(h.track, "audio.track"),
-        sampleRate,
-        channels,
-        samples: pcm,
+        track,
+        sampleRate: taken.sampleRate,
+        channels: taken.channels,
+        sequence: taken.sequence,
+        samples: taken.samples,
     });
 };
+/** The native snapshot's transport counters; the host adds its own reader overflows. */
 const parseSnapshot = (value) => {
     const s = record(value, "media snapshot");
     if (typeof s.closed !== "boolean")
-        throw new ReactorError("Protocol", "native media snapshot omitted closed state");
+        throw ReactorError.fromCode("Protocol", "native media snapshot omitted closed state");
     return Object.freeze({
         closed: s.closed,
         queuedControl: integer(s.queuedControl, "snapshot.queuedControl"),
@@ -219,23 +226,57 @@ const statsValue = (value) => {
                 : statsValue(entry);
     return output;
 };
-const pollPacket = (poll) => bridgeEffect("poll native WebRTC", async () => {
-    const result = await poll();
-    return result._tag === "Packet" ? result.packet : result._tag === "Closed" ? null : undefined;
-});
+/**
+ * Classify a failed connection from its candidate pairs. reactor-webrtc does
+ * not report ICE connection state, but a pair that succeeded or was nominated
+ * shows ICE worked and the DTLS/SCTP transport above it failed.
+ */
+const connectionFailure = (stats) => {
+    const entries = stats.filter(Predicate.isObject);
+    const pairs = entries.filter((entry) => entry.type === "candidate-pair");
+    if (pairs.some((pair) => pair.state === "succeeded" || pair.nominated === true))
+        return new ReactorError({
+            reason: new TransportFailed({
+                message: "native peer failed after ICE connectivity succeeded",
+                pairs: pairs.length,
+            }),
+        });
+    const candidateTypes = [
+        ...new Set(entries
+            .filter((entry) => entry.type === "local-candidate")
+            .map((entry) => entry.candidateType)
+            .filter((type) => typeof type === "string")),
+    ];
+    return new ReactorError({
+        reason: new IceFailed({
+            message: "native peer found no working ICE candidate pair",
+            pairs: pairs.length,
+            candidateTypes,
+        }),
+    });
+};
+/** One synchronous, nonblocking take from a native queue, as a pump step. */
+const drain = (step) => Effect.try({ try: step, catch: (cause) => nativeError(cause, "drain native WebRTC") });
 export class NativePeer {
+    shutdownTimeout;
     nativeTracks = false;
     rawMedia;
     bridge;
     video = new Map();
     audio = new Map();
     incoming = new Map();
+    tracks = [];
+    // Readiness wakes one pump per native queue; a pending wake coalesces.
+    wakeEvents = Effect.runSync(Queue.dropping(1));
+    wakeVideo = Effect.runSync(Queue.dropping(1));
+    wakeAudio = Effect.runSync(Queue.dropping(1));
     emit;
     closed = false;
     failureEmitted = false;
     failure;
-    constructor(libraryPath) {
-        this.bridge = new NativeBridge(libraryPath);
+    constructor(libraryPath, shutdownTimeout = defaultShutdownTimeout) {
+        this.shutdownTimeout = shutdownTimeout;
+        this.bridge = new NativeBridge(libraryPath, (ready) => this.wake(ready));
         this.rawMedia = Object.freeze({
             video: (name) => Stream.unwrap(Effect.try({
                 try: () => {
@@ -256,7 +297,16 @@ export class NativePeer {
     }
     requireIncoming(name, kind) {
         if (this.incoming.get(name) !== kind)
-            throw new ReactorError("InvalidInput", "native media requires a declared receive track of the requested kind", { outcome: "not-submitted" });
+            throw ReactorError.fromCode("InvalidInput", "native media requires a declared receive track of the requested kind", { outcome: "not-submitted" });
+    }
+    /** Readers failed for falling behind, across this peer's video and audio tracks. */
+    readerOverflows() {
+        let overflows = 0n;
+        for (const feed of this.video.values())
+            overflows += feed.overflowCount;
+        for (const feed of this.audio.values())
+            overflows += feed.overflowCount;
+        return overflows;
     }
     videoFeed(name) {
         let feed = this.video.get(name);
@@ -299,78 +349,86 @@ export class NativePeer {
             this.close();
         }
     }
-    pumpEvents() {
+    /** The native readiness callback, on the JavaScript thread: it only wakes pumps. */
+    wake(ready) {
+        if (ready & Ready.Events)
+            Queue.offerUnsafe(this.wakeEvents, undefined);
+        if (ready & Ready.Video)
+            Queue.offerUnsafe(this.wakeVideo, undefined);
+        if (ready & Ready.Audio)
+            Queue.offerUnsafe(this.wakeAudio, undefined);
+    }
+    /**
+     * Drain one native queue with synchronous takes whenever readiness wakes
+     * it. Yielding after every item lets observers run between emits, so a
+     * backlog released by a stalled event loop reaches bounded observation
+     * queues at their readers' pace rather than all at once. Yielding once per
+     * batch of half a subscriber's capacity overflowed an observation queue on
+     * Bun under CPU contention, so each item costs one event-loop turn.
+     */
+    pump(wake, step) {
         const self = this;
         return Effect.gen(function* () {
             while (!self.closed) {
-                const packet = yield* pollPacket(() => self.bridge.pollEvent());
-                if (self.closed)
-                    return;
-                if (packet === null)
-                    return;
-                if (packet === undefined)
-                    continue;
-                const event = yield* Effect.try({
-                    try: () => parseEvent(packet),
-                    catch: (cause) => nativeError(cause, "decode native event"),
-                });
-                if (event.type === "error") {
-                    self.fail(event.error);
-                    return;
+                yield* Queue.take(wake);
+                while (!self.closed && (yield* step)) {
+                    yield* Effect.yieldNow;
                 }
-                self.emit?.(event);
             }
         }).pipe(Effect.catch((error) => Effect.sync(() => self.fail(error))));
     }
-    pumpVideo() {
-        const self = this;
-        return Effect.gen(function* () {
-            while (!self.closed) {
-                const packet = yield* pollPacket(() => self.bridge.pollVideo());
-                if (self.closed)
-                    return;
-                if (packet === null)
-                    return;
-                if (packet === undefined)
-                    continue;
-                const frame = yield* Effect.try({
-                    try: () => {
-                        const frame = parseVideo(packet);
-                        if (self.incoming.get(frame.track) !== "video")
-                            throw new ReactorError("Protocol", "native video was delivered without its declared receive mapping");
-                        return frame;
-                    },
-                    catch: (cause) => nativeError(cause, "decode native video"),
-                });
-                self
-                    .videoFeed(frame.track)
-                    .emit(frame, frame.data.byteLength + frame.metadata.byteLength + frame.track.length * 2);
-            }
-        }).pipe(Effect.catch((error) => Effect.sync(() => self.fail(error))));
+    /**
+     * Deliver one event; false once the queue is empty or closed. A failed
+     * connection is classified here before the pump takes another event, so its
+     * classification decides the error; later events describe the same teardown.
+     */
+    get stepEvent() {
+        return drain(() => {
+            const packet = this.bridge.takeEvent();
+            if (packet === undefined || packet === null)
+                return false;
+            const event = parseEvent(packet);
+            if (event.type === "state" && event.state === "failed")
+                return "failed";
+            if (event.type === "error")
+                this.fail(event.error);
+            else
+                this.emit?.(event);
+            return true;
+        }).pipe(Effect.filterOrElse((taken) => taken !== "failed", () => this.classify.pipe(Effect.as(true))));
     }
-    pumpAudio() {
-        const self = this;
-        return Effect.gen(function* () {
-            while (!self.closed) {
-                const packet = yield* pollPacket(() => self.bridge.pollAudio());
-                if (self.closed)
-                    return;
-                if (packet === null)
-                    return;
-                if (packet === undefined)
-                    continue;
-                const frame = yield* Effect.try({
-                    try: () => {
-                        const frame = parseAudio(packet);
-                        if (self.incoming.get(frame.track) !== "audio")
-                            throw new ReactorError("Protocol", "native audio was delivered without its declared receive mapping");
-                        return frame;
-                    },
-                    catch: (cause) => nativeError(cause, "decode native audio"),
-                });
-                self.audioFeed(frame.track).emit(frame, frame.samples.byteLength + frame.track.length * 2);
-            }
-        }).pipe(Effect.catch((error) => Effect.sync(() => self.fail(error))));
+    get stepVideo() {
+        return drain(() => {
+            const taken = this.bridge.takeVideo();
+            if (taken === undefined || taken === null)
+                return false;
+            const frame = videoFrame(this.tracks, taken);
+            this.videoFeed(frame.track).emit(frame, frame.data.byteLength + frame.metadata.byteLength + frame.track.length * 2);
+            return true;
+        });
+    }
+    get stepAudio() {
+        return drain(() => {
+            const taken = this.bridge.takeAudio();
+            if (taken === undefined || taken === null)
+                return false;
+            const frame = audioFrame(this.tracks, taken);
+            this.audioFeed(frame.track).emit(frame, frame.samples.byteLength + frame.track.length * 2);
+            return true;
+        });
+    }
+    /**
+     * Report a failed connection as IceFailed or TransportFailed rather than a
+     * bare state. The statistics read runs in the events pump, so the connection
+     * scope owns it and its deadline runs on the fiber's Clock.
+     */
+    get classify() {
+        return bridgeEffect("classify native failure", () => this.bridge.call(NativeCall.Stats)).pipe(Effect.map((stats) => Array.isArray(stats)
+            ? connectionFailure(stats)
+            : ReactorError.fromCode("Disconnected", "peer state failed")), Effect.timeoutOrElse({
+            duration: CLASSIFY_TIMEOUT_MS,
+            orElse: () => Effect.fail(ReactorError.fromCode("Timeout", "native failure classification timed out")),
+        }), Effect.catch((cause) => Effect.succeed(ReactorError.fromCode("Disconnected", "peer state failed", { detail: cause }))), Effect.flatMap((error) => drain(() => this.fail(error))));
     }
     prepare(servers, tracks, emit) {
         const self = this;
@@ -379,6 +437,7 @@ export class NativePeer {
                 try: () => validateNativeTracks(tracks),
                 catch: (cause) => nativeError(cause, "validate native tracks"),
             });
+            self.tracks = Object.freeze([...tracks]);
             for (const track of tracks)
                 if (track.direction === "recvonly")
                     self.incoming.set(track.name, track.kind);
@@ -391,9 +450,9 @@ export class NativePeer {
                 try: () => parsePrepared(value),
                 catch: (cause) => nativeError(cause, "decode native prepare"),
             })));
-            yield* Effect.forkScoped(self.pumpEvents());
-            yield* Effect.forkScoped(self.pumpVideo());
-            yield* Effect.forkScoped(self.pumpAudio());
+            yield* Effect.forkScoped(self.pump(self.wakeEvents, self.stepEvent));
+            yield* Effect.forkScoped(self.pump(self.wakeVideo, self.stepVideo));
+            yield* Effect.forkScoped(self.pump(self.wakeAudio, self.stepAudio));
             return prepared;
         });
     }
@@ -408,16 +467,14 @@ export class NativePeer {
     }
     maxBitrate(name, bitsPerSecond) {
         if (!Number.isSafeInteger(bitsPerSecond) || bitsPerSecond < 1 || bitsPerSecond > 0x7fffffff)
-            return Effect.fail(new ReactorError("InvalidInput", "native max bitrate must be an integer in 1..2147483647", {
-                outcome: "not-submitted",
-            }));
+            return Effect.fail(ReactorError.fromCode("InvalidInput", "native max bitrate must be an integer in 1..2147483647", { outcome: "not-submitted" }));
         return bridgeEffect("set native sender bitrate", () => this.bridge.call(NativeCall.MaxBitrate, encodeNativeJson({ name, bitsPerSecond }))).pipe(Effect.asVoid);
     }
-    stats() {
+    get stats() {
         return bridgeEffect("native WebRTC statistics", () => this.bridge.call(NativeCall.Stats)).pipe(Effect.flatMap((value) => Effect.try({
             try: () => {
                 if (!Array.isArray(value))
-                    throw new ReactorError("Protocol", "native stats response is not an array");
+                    throw ReactorError.fromCode("Protocol", "native stats response is not an array");
                 return Object.freeze(statsValue(value));
             },
             catch: (cause) => nativeError(cause, "decode native stats"),
@@ -425,18 +482,18 @@ export class NativePeer {
     }
     mediaSnapshot() {
         return bridgeEffect("native media snapshot", () => this.bridge.call(NativeCall.MediaSnapshot)).pipe(Effect.flatMap((value) => Effect.try({
-            try: () => parseSnapshot(value),
+            try: () => Object.freeze({ ...parseSnapshot(value), readerOverflows: this.readerOverflows() }),
             catch: (cause) => nativeError(cause, "decode native media snapshot"),
         })));
     }
     lease() {
-        throw new ReactorError("UnsupportedCapability", "native WebRTC exposes owned decoded samples, not browser MediaStreamTrack leases", { outcome: "not-submitted" });
+        throw ReactorError.fromCode("UnsupportedCapability", "native WebRTC exposes owned decoded samples, not browser MediaStreamTrack leases", { outcome: "not-submitted" });
     }
     release() {
         /* lease never succeeds on this host. */
     }
     replace() {
-        return Effect.fail(new ReactorError("UnsupportedCapability", "native WebRTC does not accept browser MediaStreamTrack publication", { outcome: "not-submitted" }));
+        return Effect.fail(ReactorError.fromCode("UnsupportedCapability", "native WebRTC does not accept browser MediaStreamTrack publication", { outcome: "not-submitted" }));
     }
     close() {
         if (this.closed)
@@ -444,6 +501,9 @@ export class NativePeer {
         this.closed = true;
         this.emit = undefined;
         this.bridge.close();
+        // Let waiting pumps observe the close and exit.
+        for (const wake of [this.wakeEvents, this.wakeVideo, this.wakeAudio])
+            Queue.offerUnsafe(wake, undefined);
         for (const feed of this.video.values()) {
             if (this.failure === undefined)
                 feed.end();
@@ -457,23 +517,39 @@ export class NativePeer {
                 feed.fail(this.failure);
         }
     }
-    shutdown() {
+    /**
+     * Close, then wait for the native owner join. Only the wait is bounded: the
+     * deadline races the interruptible wait inside the uninterruptible region, so
+     * expiry stops waiting while the join keeps the handle and callback, and the
+     * bridge is retained until the join completes.
+     */
+    get shutdown() {
         return bridgeEffect("shutdown native WebRTC", () => {
             this.close();
             return this.bridge.shutdown();
-        }).pipe(Effect.mapError((error) => error.code === "Shutdown"
+        }).pipe(
+        // A failed shutdown is a Shutdown failure; the native failure it came
+        // from stays in `detail` for inspection.
+        Effect.mapError((error) => error.reason._tag === "Shutdown"
             ? error
-            : new ReactorError("Shutdown", error.message, error.context)), Effect.uninterruptible);
+            : ReactorError.fromCode("Shutdown", error.message, { ...error.context, detail: error })), Effect.timeoutOrElse({
+            duration: this.shutdownTimeout,
+            orElse: () => Effect.suspend(() => {
+                this.bridge.retain();
+                return Effect.fail(ReactorError.fromCode("Shutdown", "native owner join exceeded its deadline; handle retained", { operation: "shutdown native WebRTC" }));
+            }),
+        }), Effect.uninterruptible);
     }
 }
 /** Internal test surface. This module is not a package export. */
 export const nativePeerTesting = Object.freeze({
     parsePrepared,
     parseEvent,
-    parseVideo,
-    parseAudio,
+    videoFrame,
+    audioFrame,
     parseSnapshot,
     statsValue,
     validateNativeTracks,
+    connectionFailure,
 });
 //# sourceMappingURL=peer.js.map