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

package/dist/_internal/bridge.js

@@ -4,12 +4,18 @@ import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import * as Schema from "effect/Schema";
-import { ReactorError, ErrorCode } from "reactor-effect-client";
-const ABI_VERSION = 2;
+import * as Redacted from "effect/Redacted";
+import { Native, ReactorError } from "reactor-effect-client";
+const ABI_VERSION = 4;
 const CALL_BUFFER_BYTES = 4 * 1024 * 1024;
-const ERROR_BUFFER_BYTES = 4096;
-const MAX_PACKET_BYTES = 96 * 1024 * 1024;
+const FAILURE_BYTES = 1024;
+const VIDEO_HEADER_BYTES = 48;
+const AUDIO_HEADER_BYTES = 24;
+const EVENT_BUFFER_BYTES = 64 * 1024;
+// The native queues' byte bounds: no single item can exceed them.
+const MAX_EVENT_BYTES = 16 * 1024 * 1024;
+const MAX_VIDEO_BYTES = 64 * 1024 * 1024;
+const MAX_AUDIO_SAMPLES = 2 * 1024 * 1024;
 const MAX_IN_FLIGHT_CALLS = 128;
 const MAX_IN_FLIGHT_REQUEST_BYTES = 16 * 1024 * 1024;
 const MAX_REQUEST_BYTES = 1024 * 1024;
@@ -18,6 +24,38 @@ const STATUS_OK = 0;
 const STATUS_AGAIN = 1;
 const STATUS_BUFFER_TOO_SMALL = 2;
 const STATUS_CLOSED = 3;
+/** The C ABI's closed set of failure classes, keyed by status. */
+const FAILURE_CODES = new Map([
+    [STATUS_CLOSED, "Closed"],
+    [-1, "InvalidInput"],
+    [-2, "Native"],
+    [-3, "Overflow"],
+    [-4, "Protocol"],
+    [-5, "SdpRejected"],
+    [-6, "ChannelClosed"],
+]);
+/** A status outside the ABI's classes is an unclassified native failure. */
+export const failureCode = (status) => FAILURE_CODES.get(status) ?? "Native";
+/**
+ * A failure the native ABI returned with `status`, classified by its failure
+ * class. libwebrtc's own text can contain peer SDP or caller-supplied
+ * signaling material, so it is kept Redacted for explicit inspection: in the
+ * `Native` reason for an unclassified failure, and in `context.detail`, beside
+ * the status, for a classified one.
+ */
+export const nativeFailure = (status, backendText, message, context, detail = {}) => {
+    const code = failureCode(status);
+    const backendMessage = Redacted.make(backendText);
+    return code === "Native"
+        ? new ReactorError({
+            reason: new Native({ message: message(code), status, backendMessage }),
+            context: Object.keys(detail).length === 0 ? context : { ...context, detail },
+        })
+        : ReactorError.fromCode(code, message(code), {
+            ...context,
+            detail: { status, backendMessage, ...detail },
+        });
+};
 export const NativeCall = Object.freeze({
     Prepare: 1,
     Answer: 2,
@@ -26,7 +64,11 @@ export const NativeCall = Object.freeze({
     Stats: 5,
     MediaSnapshot: 6,
 });
+/** Readiness bits the native notifier passes to the host callback. */
+export const Ready = Object.freeze({ Events: 1, Video: 2, Audio: 4 });
 const APIs = new Map();
+// Koffi type names are process-global; one anonymous prototype serves every library.
+let notifyType;
 const libraryName = () => {
     switch (process.platform) {
         case "darwin":
@@ -46,7 +88,7 @@ const defaultPaths = () => {
 };
 const asAsync = (value, symbol) => {
     if (typeof value !== "function" || !("async" in value)) {
-        throw new ReactorError("Native", `native library symbol ${symbol} does not support asynchronous calls`);
+        throw ReactorError.fromCode("Native", `native library symbol ${symbol} does not support asynchronous calls`);
     }
     return value;
 };
@@ -56,7 +98,7 @@ const importKoffi = async () => {
         return module.default;
     }
     catch (cause) {
-        throw new ReactorError("UnsupportedHost", "the native export requires the optional koffi dependency", { detail: cause, outcome: "not-submitted" });
+        throw ReactorError.fromCode("UnsupportedHost", "the native export requires the optional koffi dependency", { detail: cause, outcome: "not-submitted" });
     }
 };
 const loadAt = async (path) => {
@@ -73,7 +115,7 @@ const loadAt = async (path) => {
         library = koffi.load(path);
     }
     catch (cause) {
-        throw new ReactorError("Native", `could not load native WebRTC bridge at ${path}`, {
+        throw ReactorError.fromCode("Native", `could not load native WebRTC bridge at ${path}`, {
             detail: cause,
             outcome: "not-submitted",
         });
@@ -83,25 +125,29 @@ const loadAt = async (path) => {
             return library.func(prototype);
         }
         catch (cause) {
-            throw new ReactorError("Native", `native WebRTC bridge is incompatible: missing ${prototype.split("(")[0] ?? prototype}`, { detail: cause, outcome: "not-submitted" });
+            throw ReactorError.fromCode("Native", `native WebRTC bridge is incompatible: missing ${prototype.split("(")[0] ?? prototype}`, { detail: cause, outcome: "not-submitted" });
         }
     };
     const abi = symbol("uint32_t reactor_effect_abi_version(void)");
     const actual = abi();
     if (actual !== ABI_VERSION)
-        throw new ReactorError("Native", `native WebRTC ABI mismatch: expected ${ABI_VERSION}, received ${actual}`, { outcome: "not-submitted" });
+        throw ReactorError.fromCode("Native", `native WebRTC ABI mismatch: expected ${ABI_VERSION}, received ${actual}`, { outcome: "not-submitted" });
+    notifyType ??= koffi.pointer(koffi.proto("void", ["uint32_t"]));
+    const notify = notifyType;
     const api = {
         library,
         binarySha256,
         buildIdentity: symbol("const char *reactor_effect_build_identity(void)")(),
-        create: symbol("void *reactor_effect_peer_create(void)"),
-        call: asAsync(symbol("int reactor_effect_peer_call(void *peer, uint32_t operation, const uint8_t *request, size_t request_len, _Out_ uint8_t *response, size_t response_cap, _Out_ size_t *response_len)"), "reactor_effect_peer_call"),
-        send: asAsync(symbol("int reactor_effect_peer_send(void *peer, uint32_t channel, const uint8_t *data, size_t data_len, _Out_ uint8_t *error, size_t error_cap, _Out_ size_t *error_len)"), "reactor_effect_peer_send"),
-        pollEvent: asAsync(symbol("int reactor_effect_peer_poll_event(void *peer, uint32_t timeout_ms, _Out_ uint8_t *out, size_t out_cap, _Out_ size_t *out_len)"), "reactor_effect_peer_poll_event"),
-        pollVideo: asAsync(symbol("int reactor_effect_peer_poll_video(void *peer, uint32_t timeout_ms, _Out_ uint8_t *out, size_t out_cap, _Out_ size_t *out_len)"), "reactor_effect_peer_poll_video"),
-        pollAudio: asAsync(symbol("int reactor_effect_peer_poll_audio(void *peer, uint32_t timeout_ms, _Out_ uint8_t *out, size_t out_cap, _Out_ size_t *out_len)"), "reactor_effect_peer_poll_audio"),
+        register: (callback) => koffi.register(callback, notify),
+        unregister: (callback) => koffi.unregister(callback),
+        create: symbol("void *reactor_effect_peer_create(void *notify)"),
+        call: asAsync(symbol("int reactor_effect_peer_call(void *peer, uint32_t operation, const uint8_t *request, size_t request_len, _Out_ uint8_t *response, size_t response_cap, _Out_ size_t *response_len, _Out_ uint8_t *failure)"), "reactor_effect_peer_call"),
+        send: asAsync(symbol("int reactor_effect_peer_send(void *peer, uint32_t channel, const uint8_t *data, size_t data_len, _Out_ uint8_t *failure)"), "reactor_effect_peer_send"),
+        takeEvent: symbol("int reactor_effect_peer_take_event(void *peer, _Out_ uint8_t *out, size_t out_cap, _Out_ size_t *out_len)"),
+        takeVideo: symbol("int reactor_effect_peer_take_video(void *peer, _Out_ uint8_t *header, _Out_ uint8_t *bgra, size_t bgra_cap, _Out_ uint8_t *metadata, size_t metadata_cap)"),
+        takeAudio: symbol("int reactor_effect_peer_take_audio(void *peer, _Out_ uint8_t *header, _Out_ int16_t *pcm, size_t pcm_cap)"),
         close: symbol("void reactor_effect_peer_close(void *peer)"),
-        shutdown: asAsync(symbol("int reactor_effect_peer_shutdown(void *peer, _Out_ uint8_t *error, size_t error_cap, _Out_ size_t *error_len)"), "reactor_effect_peer_shutdown"),
+        shutdown: asAsync(symbol("int reactor_effect_peer_shutdown(void *peer, _Out_ uint8_t *failure)"), "reactor_effect_peer_shutdown"),
         destroy: symbol("void reactor_effect_peer_destroy(void *peer)"),
     };
     APIs.set(path, api);
@@ -122,7 +168,7 @@ export const resolveNativeBridge = async (path) => {
             failures.push(cause instanceof Error ? cause.message : String(cause));
         }
     }
-    throw new ReactorError("Native", "native WebRTC bridge is not staged or its identity is invalid; run bun run native:build or provide an explicit library path", { detail: failures, outcome: "not-submitted" });
+    throw ReactorError.fromCode("Native", "native WebRTC bridge is not staged or its identity is invalid; run bun run native:build or provide an explicit library path", { detail: failures, outcome: "not-submitted" });
 };
 export const checkNativeBridge = async (path) => {
     await resolveNativeBridge(path);
@@ -130,13 +176,13 @@ export const checkNativeBridge = async (path) => {
 const checked = (path) => {
     const api = APIs.get(path);
     if (api === undefined)
-        throw new ReactorError("InvalidState", "native WebRTC bridge was not preflighted; run PeerFactory.check before make", { outcome: "not-submitted" });
+        throw ReactorError.fromCode("InvalidState", "native WebRTC bridge was not loaded; build Native.layer before making a peer", { outcome: "not-submitted" });
     return api;
 };
 const toNumber = (value, name) => {
     const number = typeof value === "bigint" ? Number(value) : value;
     if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 0)
-        throw new ReactorError("Protocol", `native ${name} is outside the safe integer range`);
+        throw ReactorError.fromCode("Protocol", `native ${name} is outside the safe integer range`);
     return number;
 };
 const jsonRecord = (bytes, operation) => {
@@ -145,12 +191,12 @@ const jsonRecord = (bytes, operation) => {
         value = JSON.parse(new TextDecoder().decode(bytes));
     }
     catch (cause) {
-        throw new ReactorError("Protocol", `native ${operation} returned invalid JSON`, {
+        throw ReactorError.fromCode("Protocol", `native ${operation} returned invalid JSON`, {
             detail: cause,
         });
     }
     if (value === null || typeof value !== "object" || Array.isArray(value))
-        throw new ReactorError("Protocol", `native ${operation} returned a non-object response`);
+        throw ReactorError.fromCode("Protocol", `native ${operation} returned a non-object response`);
     return value;
 };
 /** Validate the staged artifact used by both source and installed-package tests. */
@@ -165,79 +211,134 @@ export const verifyStagedNativeBridge = async (path) => {
             manifest.platform !== `${process.platform}-${process.arch}` ||
             manifest.library !== libraryName() ||
             manifest.sha256 !== createHash("sha256").update(binary).digest("hex")) {
-            throw new ReactorError("Native", "native artifact does not match its staged identity");
+            throw ReactorError.fromCode("Native", "native artifact does not match its staged identity");
         }
         const api = await loadAt(path);
         if (api.binarySha256 !== manifest.sha256) {
-            throw new ReactorError("Native", "staged native artifact changed after this process loaded it");
+            throw ReactorError.fromCode("Native", "staged native artifact changed after this process loaded it");
         }
         const prefix = "reactor-effect-native:build-identity:", suffix = ":end";
         if (!api.buildIdentity.startsWith(prefix) || !api.buildIdentity.endsWith(suffix)) {
-            throw new ReactorError("Native", "loaded native artifact omitted its source/build identity");
+            throw ReactorError.fromCode("Native", "loaded native artifact omitted its source/build identity");
         }
         const build = jsonRecord(Buffer.from(api.buildIdentity.slice(prefix.length, -suffix.length)), "build identity");
         if (build.abiVersion !== ABI_VERSION ||
             build.profile !== "release" ||
             JSON.stringify(build) !== JSON.stringify(manifest.build)) {
-            throw new ReactorError("Native", "loaded native build identity differs from its staged artifact");
+            throw ReactorError.fromCode("Native", "loaded native build identity differs from its staged artifact");
         }
         return Object.freeze(manifest);
     }
     catch (cause) {
-        throw new ReactorError("Native", "native staged artifact verification failed", {
+        throw ReactorError.fromCode("Native", "native staged artifact verification failed", {
             detail: cause,
             outcome: "not-submitted",
         });
     }
 };
-const isErrorCode = Schema.is(ErrorCode);
-const operationError = (status, bytes, operation) => {
-    const response = bytes.length === 0 ? {} : jsonRecord(bytes, operation);
-    const rawCode = typeof response.code === "string" ? response.code : undefined;
-    const code = isErrorCode(rawCode) ? rawCode : status === STATUS_CLOSED ? "Closed" : "Native";
-    // A native status/code does not establish whether a side effect executed.
-    // Keep backend messages for explicit inspection rather than diagnostics: a
-    // libwebrtc error can contain peer SDP or caller-supplied signaling material.
-    return new ReactorError(code, `native ${operation} failed (${code})`, {
-        operation,
-        outcome: "unknown",
-        detail: response,
-    });
+const failureOf = (status, failure, operation, detail = {}) => {
+    const length = Math.min(new DataView(failure.buffer, failure.byteOffset, failure.byteLength).getUint32(0, true), failure.byteLength - 4);
+    // A native status does not establish whether a side effect executed.
+    return nativeFailure(status, new TextDecoder().decode(failure.subarray(4, 4 + length)), (code) => `native ${operation} failed (${code})`, { operation, outcome: "unknown" }, detail);
 };
 const asyncStatus = (fn, args) => new Promise((resolve, reject) => {
-    fn.async(...args, (error, result) => (error == null ? resolve(result) : reject(error)));
+    fn.async(...args, (error, result) => error == null
+        ? resolve(result)
+        : reject(error instanceof Error
+            ? error
+            : new Error("native async call failed", { cause: error })));
 });
 const parsePacket = (bytes) => {
     if (bytes.length < 4)
-        throw new ReactorError("Protocol", "native packet omitted its header length");
+        throw ReactorError.fromCode("Protocol", "native packet omitted its header length");
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const headerLength = view.getUint32(0, true);
     if (headerLength > bytes.length - 4)
-        throw new ReactorError("Protocol", "native packet header length exceeds packet size");
+        throw ReactorError.fromCode("Protocol", "native packet header length exceeds packet size");
     const header = jsonRecord(bytes.subarray(4, 4 + headerLength), "packet");
-    const payload = Uint8Array.from(bytes.subarray(4 + headerLength));
-    return { header: Object.freeze(header), payload };
+    return { header: Object.freeze(header), payload: bytes.slice(4 + headerLength) };
 };
+const overSized = (what, size) => ReactorError.fromCode("Protocol", `native ${what} of ${size} exceeds the native queue bound`);
+/**
+ * Bridges whose owner join outlived the host's shutdown deadline. The pending
+ * join still owns the handle and needs the registered callback until the
+ * notifier is joined; holding the bridge here keeps both reachable whatever
+ * its peer's owner drops. A bridge leaves once its join completes and has
+ * destroyed the handle; one whose join fails stays.
+ */
+const retained = new Set();
+/**
+ * One native peer. Media and transport events never cross into JavaScript on
+ * their own: a native notifier thread invokes `onReady` on the JavaScript
+ * thread, and the host drains each named queue with synchronous takes, one
+ * copy per item into memory the consumer then owns.
+ */
 export class NativeBridge {
+    /**
+     * Refuse a new peer on a library that holds a retained join. Every peer of a
+     * loaded library shares its one libwebrtc factory, so an owner that did not
+     * join may have wedged the threads a new owner would need; failing here keeps
+     * a caller from stacking wedged owners and allocating remote sessions for them.
+     */
+    static requireUsable(path) {
+        const api = checked(path);
+        for (const bridge of retained)
+            if (bridge.api === api)
+                throw ReactorError.fromCode("Native", "native WebRTC runtime is degraded: an earlier peer's owner join exceeded its shutdown deadline and is still retained", { outcome: "not-submitted" });
+    }
     api;
+    notify;
     handle;
     closed = false;
     active = new Set();
-    readers = new Set();
     requestBytes = 0;
     shutdownTask;
-    constructor(path) {
+    videoHeader = new Uint8Array(VIDEO_HEADER_BYTES);
+    audioHeader = new Uint8Array(AUDIO_HEADER_BYTES);
+    eventLength = [0];
+    event = new Uint8Array(EVENT_BUFFER_BYTES);
+    metadata = new Uint8Array(256);
+    // The buffer the next take copies into. Frames keep their size, so each is
+    // allocated once at the previous frame's size and handed to its consumer.
+    nextVideo = new Uint8Array(0);
+    nextAudio = new Int16Array(0);
+    constructor(path, onReady) {
+        NativeBridge.requireUsable(path);
         this.api = checked(path);
-        const handle = this.api.create();
+        // Koffi throws its own errors from these calls: a native failure, not a bug.
+        const allocationFailed = (cause) => ReactorError.fromCode("Native", "native WebRTC peer allocation failed", {
+            outcome: "not-submitted",
+            detail: cause,
+        });
+        try {
+            this.notify = this.api.register((ready) => {
+                if (!this.closed)
+                    onReady(ready);
+            });
+        }
+        catch (cause) {
+            throw allocationFailed(cause);
+        }
+        let handle = null;
+        try {
+            handle = this.api.create(this.notify);
+        }
+        catch (cause) {
+            throw allocationFailed(cause);
+        }
+        finally {
+            if (handle === null)
+                this.api.unregister(this.notify);
+        }
         if (handle === null)
-            throw new ReactorError("Native", "native WebRTC peer allocation failed", {
+            throw ReactorError.fromCode("Native", "native WebRTC peer allocation failed", {
                 outcome: "not-submitted",
             });
         this.handle = handle;
     }
     require() {
         if (this.closed || this.handle === undefined)
-            throw new ReactorError("Closed", "native WebRTC peer is closed", {
+            throw ReactorError.fromCode("Closed", "native WebRTC peer is closed", {
                 outcome: "not-submitted",
             });
         return this.handle;
@@ -246,7 +347,7 @@ export class NativeBridge {
         const handle = this.require();
         if (this.active.size >= MAX_IN_FLIGHT_CALLS ||
             this.requestBytes + bytes > MAX_IN_FLIGHT_REQUEST_BYTES) {
-            throw new ReactorError("Overflow", "native foreign-call admission bound exceeded", {
+            throw ReactorError.fromCode("Overflow", "native foreign-call admission bound exceeded", {
                 outcome: "not-submitted",
             });
         }
@@ -256,7 +357,7 @@ export class NativeBridge {
         });
         // Register before dispatching to Koffi. Effect interruption may abandon the
         // waiter, but the lease belongs to actual native completion, including time
-        // spent queued on Koffi's executor and both halves of a packet poll.
+        // spent queued on Koffi's executor.
         this.active.add(lease);
         this.requestBytes += bytes;
         try {
@@ -270,11 +371,11 @@ export class NativeBridge {
     }
     async call(operation, request = new Uint8Array()) {
         if (request.byteLength > MAX_REQUEST_BYTES)
-            throw new ReactorError("Overflow", "native request exceeds 1 MiB", {
+            throw ReactorError.fromCode("Overflow", "native request exceeds 1 MiB", {
                 outcome: "not-submitted",
             });
         return this.withHandle(CALL_BUFFER_BYTES + request.byteLength, async (handle) => {
-            const response = Buffer.allocUnsafe(CALL_BUFFER_BYTES), responseLength = [0];
+            const response = Buffer.allocUnsafe(CALL_BUFFER_BYTES), responseLength = [0], failure = Buffer.alloc(FAILURE_BYTES);
             const input = Buffer.from(request);
             let status;
             try {
@@ -286,35 +387,38 @@ export class NativeBridge {
                     response,
                     response.byteLength,
                     responseLength,
+                    failure,
                 ]);
             }
             catch (cause) {
-                throw new ReactorError("Native", "native WebRTC call completion failed", {
+                throw ReactorError.fromCode("Native", "native WebRTC call completion failed", {
                     detail: cause,
                     outcome: "unknown",
                 });
             }
+            if (status !== STATUS_OK)
+                throw failureOf(status, failure, `call:${operation}`);
             const length = toNumber(responseLength[0], "call response length");
             if (length > response.byteLength)
-                throw new ReactorError("Protocol", "native call response exceeded its declared buffer");
-            const bytes = Uint8Array.from(response.subarray(0, length));
-            if (status !== STATUS_OK)
-                throw operationError(status, bytes, `call:${operation}`);
+                throw ReactorError.fromCode("Protocol", "native call response exceeded its declared buffer");
             try {
-                return JSON.parse(new TextDecoder().decode(bytes));
+                const reply = JSON.parse(new TextDecoder().decode(response.subarray(0, length)));
+                return reply;
             }
             catch (cause) {
-                throw new ReactorError("Protocol", "native call returned invalid JSON", { detail: cause });
+                throw ReactorError.fromCode("Protocol", "native call returned invalid JSON", {
+                    detail: cause,
+                });
             }
         });
     }
     async send(channel, bytes) {
         if (bytes.byteLength > MAX_MESSAGE_BYTES)
-            throw new ReactorError("Overflow", "native data channel message exceeds 262144 bytes", {
+            throw ReactorError.fromCode("Overflow", "native data channel message exceeds 262144 bytes", {
                 outcome: "not-submitted",
             });
-        return this.withHandle(ERROR_BUFFER_BYTES + bytes.byteLength, async (handle) => {
-            const error = Buffer.allocUnsafe(ERROR_BUFFER_BYTES), errorLength = [0];
+        return this.withHandle(FAILURE_BYTES + bytes.byteLength, async (handle) => {
+            const failure = Buffer.alloc(FAILURE_BYTES);
             const input = Buffer.from(bytes);
             let status;
             try {
@@ -323,89 +427,116 @@ export class NativeBridge {
                     channel === "control" ? 0 : 1,
                     input,
                     input.byteLength,
-                    error,
-                    error.byteLength,
-                    errorLength,
+                    failure,
                 ]);
             }
             catch (cause) {
-                throw new ReactorError("Native", `native ${channel} send completion failed`, {
+                throw ReactorError.fromCode("Native", `native ${channel} send completion failed`, {
                     detail: cause,
                     outcome: "unknown",
                 });
             }
-            const length = toNumber(errorLength[0], "send error length");
-            if (length > error.byteLength)
-                throw new ReactorError("Protocol", "native send error exceeded its declared buffer");
             if (status !== STATUS_OK)
-                throw operationError(status, Uint8Array.from(error.subarray(0, length)), `send:${channel}`);
+                throw failureOf(status, failure, `send:${channel}`, { channel });
         });
     }
-    async poll(fn, timeoutMs) {
-        if (this.closed)
-            return { _tag: "Closed" };
-        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 0xffffffff) {
-            throw new ReactorError("InvalidInput", "native poll timeout must be an unsigned 32-bit integer", { outcome: "not-submitted" });
-        }
-        if (this.readers.has(fn))
-            throw new ReactorError("AlreadyReading", "native packet queue already has a reader", {
-                outcome: "not-submitted",
-            });
-        this.readers.add(fn);
-        try {
-            return await this.withHandle(0, async (handle) => {
-                const needed = [0];
-                let status;
-                try {
-                    status = await asyncStatus(fn, [handle, timeoutMs, null, 0, needed]);
-                }
-                catch (cause) {
-                    throw new ReactorError("Native", "native event poll could not execute", {
-                        detail: cause,
-                    });
-                }
-                if (this.closed)
-                    return { _tag: "Closed" };
-                if (status === STATUS_AGAIN)
-                    return { _tag: "Again" };
-                if (status === STATUS_CLOSED)
-                    return { _tag: "Closed" };
-                if (status !== STATUS_BUFFER_TOO_SMALL)
-                    throw new ReactorError("Native", `native event poll failed with status ${status}`);
-                const length = toNumber(needed[0], "packet length");
-                if (length < 4 || length > MAX_PACKET_BYTES)
-                    throw new ReactorError("Overflow", `native packet size ${length} exceeds the local bound`);
-                const output = Buffer.allocUnsafe(length), actual = [0];
-                try {
-                    status = await asyncStatus(fn, [handle, 0, output, output.byteLength, actual]);
-                }
-                catch (cause) {
-                    throw new ReactorError("Native", "native packet copy could not execute", {
-                        detail: cause,
-                    });
-                }
-                if (this.closed || status === STATUS_CLOSED)
-                    return { _tag: "Closed" };
-                if (status !== STATUS_OK)
-                    throw new ReactorError("Native", `native packet copy failed with status ${status}`);
-                const actualLength = toNumber(actual[0], "copied packet length");
-                if (actualLength !== length)
-                    throw new ReactorError("Protocol", "native packet changed between size and copy polls");
-                return { _tag: "Packet", packet: parsePacket(Uint8Array.from(output)) };
-            });
-        }
-        finally {
-            this.readers.delete(fn);
+    /** Synchronous and nonblocking; call from the readiness callback until empty. */
+    takeEvent() {
+        const handle = this.handle;
+        if (this.closed || handle === undefined)
+            return null;
+        for (;;) {
+            const status = this.api.takeEvent(handle, this.event, this.event.byteLength, this.eventLength);
+            if (status === STATUS_AGAIN)
+                return undefined;
+            if (status === STATUS_CLOSED)
+                return null;
+            const length = toNumber(this.eventLength[0], "event length");
+            if (status === STATUS_OK) {
+                if (length > this.event.byteLength)
+                    throw ReactorError.fromCode("Protocol", "native event exceeded its declared buffer");
+                return parsePacket(this.event.subarray(0, length));
+            }
+            if (status !== STATUS_BUFFER_TOO_SMALL)
+                throw ReactorError.fromCode("Native", `native event take failed with status ${status}`);
+            if (length <= this.event.byteLength || length > MAX_EVENT_BYTES)
+                throw overSized("event", length);
+            this.event = new Uint8Array(length);
         }
     }
-    pollEvent(timeoutMs = 100) {
-        return this.poll(this.api.pollEvent, timeoutMs);
-    }
-    pollVideo(timeoutMs = 100) {
-        return this.poll(this.api.pollVideo, timeoutMs);
+    /** Synchronous and nonblocking; the returned bytes belong to the caller. */
+    takeVideo() {
+        const handle = this.handle;
+        if (this.closed || handle === undefined)
+            return null;
+        const header = new DataView(this.videoHeader.buffer);
+        for (;;) {
+            const status = this.api.takeVideo(handle, this.videoHeader, this.nextVideo, this.nextVideo.byteLength, this.metadata, this.metadata.byteLength);
+            if (status === STATUS_AGAIN)
+                return undefined;
+            if (status === STATUS_CLOSED)
+                return null;
+            const dataLength = header.getUint32(8, true), metadataLength = header.getUint32(12, true);
+            if (status === STATUS_OK) {
+                const data = this.nextVideo;
+                this.nextVideo = new Uint8Array(dataLength);
+                return {
+                    track: header.getUint32(32, true),
+                    width: header.getUint32(0, true),
+                    height: header.getUint32(4, true),
+                    frameId: header.getBigUint64(16, true),
+                    timestampMicros: header.getBigUint64(24, true),
+                    sequence: header.getBigUint64(40, true),
+                    // A smaller frame than its predecessor leaves slack; never expose it.
+                    data: dataLength === data.byteLength ? data : data.slice(0, dataLength),
+                    metadata: this.metadata.slice(0, metadataLength),
+                };
+            }
+            if (status !== STATUS_BUFFER_TOO_SMALL)
+                throw ReactorError.fromCode("Native", `native video take failed with status ${status}`);
+            if (dataLength + metadataLength > MAX_VIDEO_BYTES)
+                throw overSized("video frame", dataLength + metadataLength);
+            const growData = dataLength > this.nextVideo.byteLength, growMetadata = metadataLength > this.metadata.byteLength;
+            if (!growData && !growMetadata)
+                throw ReactorError.fromCode("Protocol", "native video take refused a fitting frame");
+            if (growData)
+                this.nextVideo = new Uint8Array(dataLength);
+            if (growMetadata)
+                this.metadata = new Uint8Array(metadataLength);
+        }
     }
-    pollAudio(timeoutMs = 100) {
-        return this.poll(this.api.pollAudio, timeoutMs);
+    /** Synchronous and nonblocking; the returned samples belong to the caller. */
+    takeAudio() {
+        const handle = this.handle;
+        if (this.closed || handle === undefined)
+            return null;
+        const header = new DataView(this.audioHeader.buffer);
+        for (;;) {
+            const status = this.api.takeAudio(handle, this.audioHeader, this.nextAudio, this.nextAudio.length);
+            if (status === STATUS_AGAIN)
+                return undefined;
+            if (status === STATUS_CLOSED)
+                return null;
+            const samples = header.getUint32(8, true);
+            if (status === STATUS_OK) {
+                const pcm = this.nextAudio;
+                this.nextAudio = new Int16Array(samples);
+                return {
+                    sampleRate: header.getUint32(0, true),
+                    channels: header.getUint32(4, true),
+                    track: header.getUint32(12, true),
+                    sequence: header.getBigUint64(16, true),
+                    samples: samples === pcm.length ? pcm : pcm.slice(0, samples),
+                };
+            }
+            if (status !== STATUS_BUFFER_TOO_SMALL)
+                throw ReactorError.fromCode("Native", `native audio take failed with status ${status}`);
+            if (samples > MAX_AUDIO_SAMPLES)
+                throw overSized("audio block", samples);
+            if (samples <= this.nextAudio.length)
+                throw ReactorError.fromCode("Protocol", "native audio take refused a fitting block");
+            this.nextAudio = new Int16Array(samples);
+        }
     }
     close() {
         if (this.closed)
@@ -425,26 +556,40 @@ export class NativeBridge {
         this.shutdownTask = this.finishShutdown(handle);
         return this.shutdownTask;
     }
+    /**
+     * The host stopped waiting for this bridge's join. The join still owns the
+     * handle: destruction and unregistration run only once it completes.
+     */
+    retain() {
+        const task = this.shutdownTask;
+        if (task === undefined || retained.has(this))
+            return;
+        retained.add(this);
+        void task.then(() => retained.delete(this), () => undefined);
+    }
     async finishShutdown(handle) {
-        // close() fences new host admission and wakes native polls. Drain all host
-        // foreign calls before joining and destroying the native owner. A native
-        // owner join cannot see work that is still queued in Koffi.
+        // close() fences new host admission. Drain all host foreign calls before
+        // joining and destroying the native owner. A native owner join cannot see
+        // work that is still queued in Koffi.
         await Promise.all(this.active);
-        const error = Buffer.allocUnsafe(ERROR_BUFFER_BYTES), errorLength = [0];
+        const failure = Buffer.alloc(FAILURE_BYTES);
         let status;
         try {
-            status = await asyncStatus(this.api.shutdown, [handle, error, error.byteLength, errorLength]);
+            // Asynchronous on purpose: the join waits for a notifier that may be
+            // blocked until this thread runs its readiness callback.
+            status = await asyncStatus(this.api.shutdown, [handle, failure]);
         }
         catch (cause) {
-            throw new ReactorError("Shutdown", "native WebRTC owner join could not execute; handle retained", { detail: cause });
+            throw ReactorError.fromCode("Shutdown", "native WebRTC owner join could not execute; handle retained", { detail: cause });
+        }
+        if (status !== STATUS_OK) {
+            const error = failureOf(status, failure, "shutdown");
+            throw ReactorError.fromCode("Shutdown", error.message, error.context);
         }
-        const length = toNumber(errorLength[0], "shutdown error length");
-        if (length > error.byteLength)
-            throw new ReactorError("Shutdown", "native shutdown error exceeded its declared buffer");
-        if (status !== STATUS_OK)
-            throw new ReactorError("Shutdown", operationError(status, Uint8Array.from(error.subarray(0, length)), "shutdown").message);
         this.api.destroy(handle);
         this.handle = undefined;
+        // The notifier thread is joined: nothing can invoke the callback again.
+        this.api.unregister(this.notify);
     }
 }
 export const encodeNativeJson = (value) => Uint8Array.from(new TextEncoder().encode(JSON.stringify(value)));