@moltzap/client 2026.511.1 → 2026.519.0

package/dist/ws-client.js

@@ -1,7 +1,7 @@
 import * as Socket from "@effect/platform/Socket";
 import * as NodeSocket from "@effect/platform-node/NodeSocket";
-import { Cause, Data, Deferred, Duration, Either, Effect, Exit, Fiber, HashMap, ManagedRuntime, Option, Queue, Ref, Schedule, Scope, } from "effect";
-import { PROTOCOL_VERSION, Connect, encodeErrorResponse, NotConnectedError, RpcServerError, RpcTimeoutError, } from "@moltzap/protocol";
+import { Data, Deferred, Duration, Either, Effect, Exit, Fiber, HashMap, ManagedRuntime, Option, Queue, Ref, Schedule, Scope, } from "effect";
+import { PROTOCOL_VERSION, Connect, encodeErrorResponse, makeJsonRpcClient, makeJsonRpcServer, NotConnectedError, RpcTimeoutError, } from "@moltzap/protocol";
 import { DuplicateServerRpcHandlerError } from "./runtime/errors.js";
 import { decodeFrames } from "./runtime/frame.js";
 import { makeSubscriberRegistry, } from "./runtime/subscribers.js";
@@ -19,12 +19,12 @@ const NORMAL_CLOSE_CODE = 1000;
 const EVENT_WAIT_TIMEOUT_MS = 5000;
 const WEB_SOCKET_OPEN_TIMEOUT_SECONDS = 10;
 const MALFORMED_FRAME_PREVIEW_CHARS = 200;
-const JSON_RPC_INTERNAL_ERROR_CODE = -32603;
 /**
  * Log 1-of-N malformed frames. A misbehaving server could flood us otherwise;
  * the counter in the log makes it clear how many we've dropped between logs.
  */
 const MALFORMED_LOG_EVERY = 50;
+export const shouldLogMalformedFrame = (count) => count === 1 || count % MALFORMED_LOG_EVERY === 0;
 /**
  * Cap on the per-client notification buffer. Any frame that has no live
  * `waitForNotification` awaiter lands here until someone drains it. Excess
@@ -44,15 +44,16 @@ const MAX_EVENT_BUFFER = 1000;
  */
 const TASK_CALLBACK_QUEUE_CAPACITY = 8192;
 const MSG_NOT_CONNECTED = "WebSocket not connected";
-const MSG_RPC_ERROR_FALLBACK = "RPC error";
 const UTF8_DECODER = new TextDecoder("utf-8");
 const makeNotConnectedError = () => new NotConnectedError({ message: MSG_NOT_CONNECTED });
 class ReconnectAttemptFailedError extends Data.TaggedError("ReconnectAttemptFailedError") {
 }
-/** Notifications are pre-validated by the wire decoder
+/**
+ * Notifications are pre-validated by the wire decoder
  * (`decodeNotification` in `@moltzap/protocol`) — fail-close on unknown
  * methods or bad params. Buffer + waiters hold the validated shape
- * directly; no separate Raw|Unknown lift remains. */
+ * directly; no separate Raw|Unknown lift remains.
+ */
 function acceptTypedNotification(definition, notification) {
     return notification.definition === definition;
 }
@@ -80,7 +81,6 @@ function removeWaiter(m, definition, waiter) {
  */
 export class MoltZapWsClient {
     options;
-    pendingRef;
     stateRef;
     malformedRef;
     notificationsBufferRef;
@@ -104,14 +104,12 @@ export class MoltZapWsClient {
      * dispatcher fiber when an appCallback request frame arrives.
      */
     appCallbackHandlersRef;
-    requestCounter = 0;
     closed = false;
     reconnectFiber = null;
     _helloOk = null;
     constructor(options) {
         this.options = options;
         this.runtime = ManagedRuntime.make(NodeSocket.layerWebSocketConstructor);
-        this.pendingRef = this.runtime.runSync(Ref.make(HashMap.empty()));
         this.stateRef = this.runtime.runSync(Ref.make(Option.none()));
         this.malformedRef = this.runtime.runSync(Ref.make(0));
         this.notificationsBufferRef = this.runtime.runSync(Ref.make([]));
@@ -119,15 +117,13 @@ export class MoltZapWsClient {
         // Registry construction is `Effect<…, never>`; running it sync here
         // matches every other Ref initializer in this constructor and
         // keeps `subscribers` non-nullable inside the class.
-        this.subscribers = this.runtime.runSync(makeSubscriberRegistry({
-            warn: (...args) => this.options.logger?.warn(...args),
-        }));
+        this.subscribers = this.runtime.runSync(makeSubscriberRegistry());
         this.appCallbackHandlersRef = this.runtime.runSync(Ref.make(HashMap.empty()));
     }
     /**
      * Register a handler for a server-initiated RPC method. Survives
      * reconnects — the registry lives on the client, not the per-connection
-     * `ConnState`. Returns `Effect<void>` that fails with
+     * `ConnState`. Returns `Effect&lt;void>` that fails with
      * `DuplicateServerRpcHandlerError` if a handler for `method` is already
      * registered (shadowing the existing one would silently swap behaviour
      * mid-flight).
@@ -155,8 +151,10 @@ export class MoltZapWsClient {
     get helloOk() {
         return this._helloOk;
     }
-    /** Open the socket, perform network/connect, resolve with HelloOk. Fails
-     * immediately on pre-open close or error. */
+    /**
+     * Open the socket, perform network/connect, resolve with HelloOk. Fails
+     * immediately on pre-open close or error.
+     */
     connect() {
         return Effect.suspend(() => {
             if (this.closed) {
@@ -173,19 +171,15 @@ export class MoltZapWsClient {
      * Send an RPC. Fails with a typed error:
      *   - `NotConnectedError` if the socket isn't OPEN or closes mid-RPC
      *   - `RpcTimeoutError` after `RPC_TIMEOUT_MS` — no automatic retry
-     *   - `RpcServerError` on a typed server-error frame
+     *   - a registered tagged error for known protocol error codes
+     *   - `RpcServerError` for unknown protocol error codes
      *
      * Descriptor-backed RPC call. Callers pass the protocol descriptor, and the
      * client extracts the wire method only inside the encoder path.
      */
     sendRpc(definition, params, opts) {
-        return this.sendRpcEffect(definition, params, opts).pipe(Effect.flatMap((result) => definition.validateResult(result)
-            ? Effect.succeed(result)
-            : Effect.fail(new RpcServerError({
-                code: JSON_RPC_INTERNAL_ERROR_CODE,
-                message: `Invalid result for method: ${definition.name}`,
-                data: result,
-            }))));
+        const timeoutMs = opts?.timeoutMs ?? RPC_TIMEOUT_MS;
+        return this.sendRpcEffect(definition, params, timeoutMs);
     }
     /**
      * Register a per-subscription notification handler. Spec #222 §5.3 + OQ-2
@@ -250,49 +244,70 @@ export class MoltZapWsClient {
                 this.runtime.runFork(Scope.close(state.value.dispatcherScope, Exit.void));
             }
         }).pipe(Effect.asVoid, Effect.ensuring(Effect.sync(() => {
-            void this.runtime.dispose();
+            this.runtime.dispose();
         })));
     }
-    /** Wait for the next inbound notification matching `definition`.
+    /**
+     * Wait for the next inbound notification matching `definition`.
      * Consumes a buffered match if present; otherwise awaits the next match
-     * with a per-call timeout. */
+     * with a per-call timeout.
+     */
     waitForNotification(definition, timeoutMs = EVENT_WAIT_TIMEOUT_MS) {
         return Effect.gen(this, function* () {
-            const buffered = yield* Ref.modify(this.notificationsBufferRef, (frames) => {
-                for (const [idx, frame] of frames.entries()) {
-                    if (!acceptTypedNotification(definition, frame))
-                        continue;
-                    const next = [...frames.slice(0, idx), ...frames.slice(idx + 1)];
-                    return [frame, next];
-                }
-                return [null, frames];
-            });
+            const buffered = yield* this.takeBufferedNotification(definition);
             if (buffered !== null)
                 return buffered;
+            return yield* this.awaitNotification(definition, timeoutMs);
+        });
+    }
+    takeBufferedNotification(definition) {
+        return Ref.modify(this.notificationsBufferRef, (frames) => {
+            for (const [idx, frame] of frames.entries()) {
+                if (!acceptTypedNotification(definition, frame))
+                    continue;
+                const next = [...frames.slice(0, idx), ...frames.slice(idx + 1)];
+                return [frame, next];
+            }
+            return [null, frames];
+        });
+    }
+    awaitNotification(definition, timeoutMs) {
+        return Effect.gen(this, function* () {
             const deferred = yield* Deferred.make();
-            const waiter = {
-                definition,
-                complete: (notification) => acceptTypedNotification(definition, notification)
-                    ? Deferred.succeed(deferred, notification).pipe(Effect.asVoid)
-                    : Effect.void,
-                fail: (error) => Deferred.fail(deferred, error).pipe(Effect.asVoid),
-            };
-            yield* Ref.update(this.notificationWaitersRef, (m) => {
-                const existing = HashMap.get(m, definition);
-                const next = existing._tag === "Some" ? [...existing.value, waiter] : [waiter];
-                return HashMap.set(m, definition, next);
-            });
+            const waiter = this.makeNotificationWaiter(definition, deferred);
+            yield* this.addNotificationWaiter(definition, waiter);
             return yield* Deferred.await(deferred).pipe(Effect.timeoutFail({
                 duration: `${timeoutMs} millis`,
                 onTimeout: () => new Error(`Timeout waiting for notification: ${definition.name}`),
-            }), Effect.onExit((exit) => exit._tag === "Failure"
-                ? Ref.update(this.notificationWaitersRef, (m) => removeWaiter(m, definition, waiter))
+            }), Effect.onExit((exit) => Exit.isFailure(exit)
+                ? this.removeNotificationWaiter(definition, waiter)
                 : Effect.void));
         });
     }
-    /** Return all buffered notifications and clear the buffer. Synchronous.
+    makeNotificationWaiter(definition, deferred) {
+        return {
+            definition,
+            complete: (notification) => acceptTypedNotification(definition, notification)
+                ? Deferred.succeed(deferred, notification).pipe(Effect.asVoid)
+                : Effect.void,
+            fail: (error) => Deferred.fail(deferred, error).pipe(Effect.asVoid),
+        };
+    }
+    addNotificationWaiter(definition, waiter) {
+        return Ref.update(this.notificationWaitersRef, (m) => {
+            const existing = HashMap.get(m, definition);
+            const next = existing._tag === "Some" ? [...existing.value, waiter] : [waiter];
+            return HashMap.set(m, definition, next);
+        });
+    }
+    removeNotificationWaiter(definition, waiter) {
+        return Ref.update(this.notificationWaitersRef, (m) => removeWaiter(m, definition, waiter));
+    }
+    /**
+     * Return all buffered notifications and clear the buffer. Synchronous.
      * Frames are pre-validation (`params: unknown`) — buffer holds the
-     * raw shape produced by the wire decoder. */
+     * raw shape produced by the wire decoder.
+     */
     drainNotifications() {
         const snapshot = this.runtime.runSync(Ref.get(this.notificationsBufferRef));
         this.runtime.runSync(Ref.set(this.notificationsBufferRef, []));
@@ -308,11 +323,7 @@ export class MoltZapWsClient {
             return;
         // Detach from state first so sendRpc fails fast while we tear down.
         this.runtime.runSync(Ref.set(this.stateRef, Option.none()));
-        // Fail pendings via runFork — `failAllPending` yields through
-        // `Deferred.fail` (not safe for runSync). Fire-and-forget: the reader
-        // fiber's onExit will also drain on interrupt; duplicate drain is
-        // harmless because `failAllPending` resets the pendingRef atomically.
-        this.runtime.runFork(this.failAllPending(MSG_NOT_CONNECTED));
+        this.runtime.runFork(this.failConnectionPending(state.value));
         // Interrupt the reader fiber. runRaw exits, the socket scope closes,
         // ws.close(1000) fires as part of that teardown.
         this.runtime.runFork(Fiber.interrupt(state.value.readerFiber));
@@ -325,166 +336,105 @@ export class MoltZapWsClient {
         // finalizers.
         this.runtime.runFork(Scope.close(state.value.dispatcherScope, Exit.void));
     }
+    notifyDisconnect(close) {
+        return Effect.gen(this, function* () {
+            try {
+                this.options.onDisconnect?.(close);
+            }
+            catch (err) {
+                yield* Effect.logWarning("onDisconnect handler threw", err);
+            }
+        });
+    }
     connectEffect() {
         return Effect.gen(this, function* () {
-            const url = this.options.serverUrl.replace(/^http/, "ws") + "/ws";
-            // Fresh scope per connect attempt. Held by the client (not the caller's
-            // fiber) so the reader + writer outlive the outer `connect()` Effect.
+            const url = this.webSocketUrl();
             const scope = yield* Scope.make();
-            // Map Socket open failures (SocketGenericError / SocketCloseError) to
-            // NotConnectedError so callers see a single typed error.
-            const openTimeout = Duration.seconds(WEB_SOCKET_OPEN_TIMEOUT_SECONDS);
-            const socket = yield* Scope.extend(Socket.makeWebSocket(url, { openTimeout }), scope).pipe(Effect.timeoutFail({
-                duration: openTimeout,
-                onTimeout: makeNotConnectedError,
-            }), Effect.catchAllCause((cause) => Effect.zipRight(Effect.sync(() => this.options.logger?.warn("WebSocket open failed", cause)), Effect.sync(() => {
-                this.runtime.runFork(Scope.close(scope, Exit.void));
-            }).pipe(Effect.zipRight(Effect.fail(makeNotConnectedError()))))));
+            const socket = yield* this.openSocket(url, scope);
             const write = yield* Scope.extend(socket.writer, scope);
-            // Settled first by whichever fires: the network/connect response, or
-            // reader-fiber exit on any close/error before handshake.
+            const jsonRpcClient = yield* Scope.extend(makeJsonRpcClient({
+                write: (raw) => write(raw),
+                idPrefix: "rpc",
+            }), scope);
             const handshakeSettled = yield* Deferred.make();
-            // Cutover (#533) — single bounded global queue + single drain
-            // fiber replaces the pre-cutover partitioned dispatcher. The
-            // queue capacity (`TASK_CALLBACK_QUEUE_CAPACITY` = 8192)
-            // preserves today's 256×32 burst envelope. The drain fiber
-            // takes one request at a time and runs the registered handler
-            // serially; the only remaining task-callback descriptor today
-            // is `dispatch/authorize`, which the recipient may not handle
-            // concurrently with itself.
-            //
-            // Dispatcher Scope is allocated independently of the per-connect
-            // socket Scope (`scope` above). Closing it interrupts the drain
-            // fiber via Scope finalizers; teardown from `close()` /
-            // `disconnectSync()` is `runFork(Scope.close(...))`, mirroring
-            // the reader-fiber ownership pattern (off-Scope so
-            // `runSync(client.close())` doesn't yield through the runtime
-            // — load-bearing regression gate at
-            // `ws-client.test.ts:1233-1259`).
-            const dispatcherScope = yield* Scope.make();
-            const taskCallbackQueue = yield* Queue.bounded(TASK_CALLBACK_QUEUE_CAPACITY);
-            // Drain fiber: serialize handler execution. Forked into the
-            // off-Scope `dispatcherScope` so it is interrupted exactly when
-            // the dispatcher Scope closes, not when the socket Scope closes.
-            const drainEffect = Effect.forever(Queue.take(taskCallbackQueue).pipe(Effect.flatMap((req) => this.dispatchInboundServerRequest(req, write))));
-            yield* Effect.forkIn(drainEffect, dispatcherScope);
-            // Use `onExit` (not `tapErrorCause`) so the clean-close path also
-            // triggers pending-drain. `@effect/platform/Socket` treats code 1000
-            // as a SUCCESS exit, so error-only handlers miss it and pending RPCs
-            // would hang forever.
-            const readerEffect = socket
-                .runRaw((data) => this.handleIncoming(typeof data === "string" ? data : UTF8_DECODER.decode(data)))
-                .pipe(Effect.onExit((exit) => Effect.gen(this, function* () {
-                if (Exit.isFailure(exit)) {
-                    this.options.logger?.warn("WebSocket error", exit.cause);
-                }
-                this._helloOk = null;
-                yield* this.failAllPending(MSG_NOT_CONNECTED);
-                // Unblock any `connect()` still awaiting the handshake.
-                yield* Deferred.fail(handshakeSettled, makeNotConnectedError()).pipe(Effect.ignore);
-                // Clear connection state BEFORE the appCallback teardown so
-                // `sendRpc` and observers see the closed state immediately.
-                // Awaiting `Fiber.interrupt` would block this branch on a
-                // slow appCallback handler still draining (codex P2).
-                yield* Ref.set(this.stateRef, Option.none());
-                // Tear down the task-callback dispatcher Scope on
-                // socket-level close (e.g. server-initiated). `close()`
-                // / `disconnectSync()` already handle their own
-                // teardown for client-initiated paths; this branch
-                // covers the case where the server closes us. Forked
-                // so a slow handler does not delay the rest of the
-                // disconnect path. Idempotent with the explicit
-                // teardown in close().
-                this.runtime.runFork(Scope.close(dispatcherScope, Exit.void));
-                // Spec #222 §5.4 (V7): project the reader-fiber exit onto
-                // a typed `CloseInfo` and pass it to `onDisconnect`. Pure
-                // total classifier — see runtime/close-info.ts.
-                const close = extractCloseInfo(exit);
-                yield* Effect.sync(() => {
-                    try {
-                        this.options.onDisconnect?.(close);
-                    }
-                    catch (err) {
-                        this.options.logger?.warn("onDisconnect handler threw", err);
-                    }
-                });
-                if (!this.closed) {
-                    this.scheduleReconnect();
-                }
-            })));
-            // Fork the reader on the CLIENT's runtime (not the caller's fiber) so
-            // it outlives the outer `connect()`. Otherwise the caller's fiber tree
-            // finalizes on return, interrupts the reader, and `onExit` clears
-            // `_helloOk` behind a caller that believed connect() succeeded.
-            const readerFiber = this.runtime.runFork(readerEffect);
-            // Publish state BEFORE network/connect: the write goes through
-            // `sendRpcEffect`, which reads `stateRef`.
-            yield* Ref.set(this.stateRef, Option.some({
+            const dispatcher = yield* this.startTaskCallbackDispatcher(write);
+            const readerFiber = this.runtime.runFork(this.readerEffect(socket, handshakeSettled, dispatcher.dispatcherScope));
+            yield* this.publishConnectionState({
                 write,
                 readerFiber,
                 scope,
+                jsonRpcClient,
                 handshakeSettled,
-                taskCallbackQueue,
-                dispatcherScope,
-            }));
-            const authEffect = this.sendRpc(Connect, {
-                agentKey: this.options.agentKey,
-                minProtocol: PROTOCOL_VERSION,
-                maxProtocol: PROTOCOL_VERSION,
+                taskCallbackQueue: dispatcher.taskCallbackQueue,
+                dispatcherScope: dispatcher.dispatcherScope,
             });
-            // Race the network/connect response against the handshakeSettled deferred
-            // `raceFirst` (not `race`) — `race` waits for the loser when the
-            // winner fails, so a typed network/connect error would hang behind the
-            // still-pending handshake-watchdog Deferred.
-            const result = yield* Effect.raceFirst(authEffect, Deferred.await(handshakeSettled)).pipe(Effect.tap((value) => Effect.sync(() => {
-                this._helloOk = value;
-            })));
-            return result;
+            return yield* this.awaitConnectAuth(handshakeSettled);
+        });
+    }
+    webSocketUrl() {
+        return this.options.serverUrl.replace(/^http/, "ws") + "/ws";
+    }
+    openSocket(url, scope) {
+        const openTimeout = Duration.seconds(WEB_SOCKET_OPEN_TIMEOUT_SECONDS);
+        return Scope.extend(Socket.makeWebSocket(url, { openTimeout }), scope).pipe(Effect.timeoutFail({
+            duration: openTimeout,
+            onTimeout: makeNotConnectedError,
+        }), Effect.catchAllCause((cause) => Effect.zipRight(Effect.logWarning("WebSocket open failed", cause), Effect.sync(() => {
+            this.runtime.runFork(Scope.close(scope, Exit.void));
+        }).pipe(Effect.zipRight(Effect.fail(makeNotConnectedError()))))));
+    }
+    startTaskCallbackDispatcher(write) {
+        return Effect.gen(this, function* () {
+            const dispatcherScope = yield* Scope.make();
+            const taskCallbackQueue = yield* Queue.bounded(TASK_CALLBACK_QUEUE_CAPACITY);
+            const drainEffect = Effect.forever(Queue.take(taskCallbackQueue).pipe(Effect.flatMap((req) => this.dispatchInboundServerRequest(req, write))));
+            yield* Effect.forkIn(drainEffect, dispatcherScope);
+            return { dispatcherScope, taskCallbackQueue };
+        });
+    }
+    readerEffect(socket, handshakeSettled, dispatcherScope) {
+        return socket
+            .runRaw((data) => this.handleIncoming(typeof data === "string" ? data : UTF8_DECODER.decode(data)))
+            .pipe(Effect.onExit((exit) => this.handleReaderExit(exit, handshakeSettled, dispatcherScope)));
+    }
+    handleReaderExit(exit, handshakeSettled, dispatcherScope) {
+        return Effect.gen(this, function* () {
+            if (Exit.isFailure(exit)) {
+                yield* Effect.logWarning("WebSocket error", exit.cause);
+            }
+            this._helloOk = null;
+            yield* this.failAllPending(MSG_NOT_CONNECTED);
+            yield* Deferred.fail(handshakeSettled, makeNotConnectedError()).pipe(Effect.ignore);
+            yield* Ref.set(this.stateRef, Option.none());
+            this.runtime.runFork(Scope.close(dispatcherScope, Exit.void));
+            yield* this.notifyDisconnect(extractCloseInfo(exit));
+            if (!this.closed)
+                this.scheduleReconnect();
+        });
+    }
+    publishConnectionState(state) {
+        return Ref.set(this.stateRef, Option.some(state));
+    }
+    awaitConnectAuth(handshakeSettled) {
+        const authEffect = this.sendRpc(Connect, {
+            agentKey: this.options.agentKey,
+            minProtocol: PROTOCOL_VERSION,
+            maxProtocol: PROTOCOL_VERSION,
         });
+        return Effect.raceFirst(authEffect, Deferred.await(handshakeSettled)).pipe(Effect.tap((value) => Effect.sync(() => {
+            this._helloOk = value;
+        })));
     }
-    sendRpcEffect(definition, params, opts) {
+    sendRpcEffect(definition, params, timeoutMs) {
         return Effect.gen(this, function* () {
-            const method = definition.name;
             const state = yield* Ref.get(this.stateRef);
             if (Option.isNone(state)) {
                 return yield* Effect.fail(makeNotConnectedError());
             }
-            const frame = definition.encodeRequest(`rpc-${++this.requestCounter}`, params);
-            const id = frame.id;
-            // Register the Deferred BEFORE writing — write yields, reader could
-            // close + failAllPending before we register, leaving us awaiting a
-            // never-resolved Deferred.
-            const deferred = yield* Deferred.make();
-            yield* Ref.update(this.pendingRef, (m) => HashMap.set(m, id, deferred));
-            const writeAttempt = Effect.either(state.value.write(JSON.stringify(frame)));
-            const earlyFailure = Deferred.await(deferred).pipe(Effect.catchAll(() => Effect.succeed(null)), Effect.as(null));
-            const writeRace = yield* Effect.race(writeAttempt, earlyFailure);
-            const writeFailure = writeRace === null
-                ? null
-                : Either.match(writeRace, {
-                    onLeft: (err) => err,
-                    onRight: () => null,
-                });
-            if (writeFailure !== null) {
-                this.options.logger?.warn("ws.send failed", writeFailure);
-                yield* Ref.update(this.pendingRef, (m) => HashMap.remove(m, id));
-                return yield* Effect.fail(makeNotConnectedError());
-            }
-            const timeoutMs = opts?.timeoutMs ?? RPC_TIMEOUT_MS;
-            const result = yield* Deferred.await(deferred).pipe(Effect.timeoutFail({
+            return yield* state.value.jsonRpcClient.call(definition, params).pipe(Effect.timeoutFail({
                 duration: `${timeoutMs} millis`,
-                onTimeout: () => new RpcTimeoutError({ method, timeoutMs }),
-            }), Effect.onExit((exit) => Exit.isFailure(exit)
-                ? Ref.update(this.pendingRef, (m) => HashMap.remove(m, id))
-                : Effect.void));
-            if (!definition.validateResult(result)) {
-                return yield* Effect.fail(new RpcServerError({
-                    code: JSON_RPC_INTERNAL_ERROR_CODE,
-                    message: `Invalid result for method: ${definition.name}`,
-                    data: result,
-                }));
-            }
-            return result;
+                onTimeout: () => new RpcTimeoutError({ method: definition.name, timeoutMs }),
+            }));
         });
     }
     /**
@@ -498,7 +448,7 @@ export class MoltZapWsClient {
             code: -32000,
             message: `Server busy: task-callback executor queue full (capacity=${TASK_CALLBACK_QUEUE_CAPACITY})`,
         });
-        return write(JSON.stringify(reply)).pipe(Effect.catchAll((werr) => Effect.sync(() => this.options.logger?.warn("task-callback queue-full rejection write failed", werr))));
+        return write(JSON.stringify(reply)).pipe(Effect.catchAll((werr) => Effect.logWarning("task-callback queue-full rejection write failed", werr)));
     }
     /**
      * Dispatch one inbound appCallback request to the registered handler, encode
@@ -509,130 +459,125 @@ export class MoltZapWsClient {
      *
      * Cases:
      *   - Handler registered + Effect succeeds → encode `result`.
-     *   - Handler registered + Effect fails (RpcServerError) → encode
-     *     `error` from the tag.
+     *   - Handler registered + Effect fails with a registered tagged error →
+     *     encode `error` from the tag.
      *   - Handler registered + Effect defects (untagged crash) →
      *     encode generic InternalError, log the cause.
      *   - No handler registered → encode MethodNotFound error response.
      */
     dispatchInboundServerRequest(request, write) {
+        return Effect.gen(this, function* () {
+            const reply = yield* this.buildInboundServerReply(request);
+            yield* this.writeInboundServerReply(write, reply);
+        });
+    }
+    buildInboundServerReply(request) {
         return Effect.gen(this, function* () {
             const handlers = yield* Ref.get(this.appCallbackHandlersRef);
-            const lookup = HashMap.get(handlers, request.definition);
-            const buildReply = lookup._tag === "None"
-                ? Effect.succeed(encodeErrorResponse(request.id, {
-                    code: -32601,
-                    message: "No handler registered for app callback descriptor",
-                }))
-                : lookup
-                    .value(request.params, {
-                    requestId: request.id,
-                    definition: request.definition,
-                })
-                    .pipe(Effect.match({
-                    onSuccess: (result) => request.definition.encodeResponse(request.id, result),
-                    onFailure: (err) => encodeErrorResponse(request.id, {
-                        code: err.code,
-                        message: err.message,
-                        ...(err.data !== undefined ? { data: err.data } : {}),
-                    }),
-                }), Effect.catchAllCause((cause) => Effect.sync(() => {
-                    this.options.logger?.warn("appCallback handler defected", Cause.pretty(cause));
-                    return encodeErrorResponse(request.id, {
-                        code: -32603,
-                        message: "Internal error",
-                    });
-                })));
-            const reply = yield* buildReply;
-            yield* write(JSON.stringify(reply)).pipe(Effect.catchAll((err) => Effect.sync(() => this.options.logger?.warn("appCallback response write failed", err))));
+            const rpcServer = makeJsonRpcServer(this.appCallbackRpcHandlers(handlers));
+            return yield* rpcServer.handle(request.frame, {
+                requestId: request.id,
+                definition: request.definition,
+            });
         });
     }
-    /** Route an inbound frame. Malformed frames are logged + dropped; notification
-     * frames dispatch to `onNotification` after the shape check. */
+    appCallbackRpcHandlers(handlers) {
+        return Array.from(HashMap.entries(handlers), ([definition, appHandler]) => ({
+            definition,
+            handle: (params, ctx) => appHandler(params, { ...ctx, definition }),
+        }));
+    }
+    writeInboundServerReply(write, reply) {
+        return write(JSON.stringify(reply)).pipe(Effect.catchAll((err) => Effect.logWarning("appCallback response write failed", err)));
+    }
+    recordMalformedFrame(err) {
+        return Effect.gen(this, function* () {
+            const count = yield* Ref.updateAndGet(this.malformedRef, (n) => n + 1);
+            if (shouldLogMalformedFrame(count)) {
+                yield* Effect.logWarning(`Malformed frame (#${count})`).pipe(Effect.annotateLogs({
+                    rawPreview: err.raw.slice(0, MALFORMED_FRAME_PREVIEW_CHARS),
+                }));
+            }
+            return null;
+        });
+    }
+    handleDecodedResponse(decoded) {
+        return Effect.gen(this, function* () {
+            const state = yield* Ref.get(this.stateRef);
+            if (Option.isNone(state))
+                return;
+            yield* state.value.jsonRpcClient
+                .resolve(decoded.frame)
+                .pipe(Effect.asVoid);
+        });
+    }
+    handleDecodedServerRequest(decoded) {
+        return Effect.gen(this, function* () {
+            const state = yield* Ref.get(this.stateRef);
+            if (Option.isNone(state))
+                return;
+            const offered = yield* Queue.offer(state.value.taskCallbackQueue, decoded);
+            if (!offered) {
+                yield* this.writeQueueFullRejection(decoded.id, state.value.write);
+            }
+        });
+    }
+    takeNotificationWaiter(decoded) {
+        return Ref.modify(this.notificationWaitersRef, (waitersMap) => {
+            const bucket = HashMap.get(waitersMap, decoded.definition);
+            if (bucket._tag === "None" || bucket.value.length === 0) {
+                return [null, waitersMap];
+            }
+            const arr = bucket.value;
+            const chosen = arr[arr.length - 1];
+            const rest = arr.slice(0, -1);
+            const nextMap = rest.length === 0
+                ? HashMap.remove(waitersMap, decoded.definition)
+                : HashMap.set(waitersMap, decoded.definition, rest);
+            return [chosen, nextMap];
+        });
+    }
+    bufferNotification(decoded) {
+        return Ref.update(this.notificationsBufferRef, (buffer) => {
+            const appended = [...buffer, decoded];
+            return appended.length > MAX_EVENT_BUFFER
+                ? appended.slice(-MAX_EVENT_BUFFER)
+                : appended;
+        });
+    }
+    handleDecodedNotification(decoded) {
+        return Effect.gen(this, function* () {
+            yield* this.subscribers.dispatch(decoded);
+            const delivered = yield* this.takeNotificationWaiter(decoded);
+            if (delivered !== null) {
+                yield* delivered.complete(decoded);
+                return;
+            }
+            yield* this.bufferNotification(decoded);
+        });
+    }
+    handleDecodedFrame(decoded) {
+        switch (decoded._tag) {
+            case "ResponseSuccess":
+            case "ResponseError":
+                return this.handleDecodedResponse(decoded);
+            case "ServerRequest":
+                return this.handleDecodedServerRequest(decoded);
+            case "Notification":
+                return this.handleDecodedNotification(decoded);
+        }
+    }
+    /**
+     * Route an inbound frame. Malformed frames are logged + dropped; notification
+     * frames dispatch to `onNotification` after the shape check.
+     */
     handleIncoming(raw) {
         return Effect.gen(this, function* () {
-            const decodedFrames = yield* decodeFrames(raw).pipe(Effect.catchTag("MalformedFrameError", (err) => Effect.gen(this, function* () {
-                const n = yield* Ref.updateAndGet(this.malformedRef, (c) => c + 1);
-                if (n === 1 || n % MALFORMED_LOG_EVERY === 0) {
-                    this.options.logger?.warn(`Malformed frame (#${n}):`, err.raw.slice(0, MALFORMED_FRAME_PREVIEW_CHARS));
-                }
-                return null;
-            })));
+            const decodedFrames = yield* decodeFrames(raw).pipe(Effect.catchTag("MalformedFrameError", (err) => this.recordMalformedFrame(err)));
             if (decodedFrames === null)
                 return;
             for (const decoded of decodedFrames) {
-                if (decoded._tag === "ResponseSuccess" ||
-                    decoded._tag === "ResponseError") {
-                    const id = decoded.id;
-                    const pending = yield* Ref.modify(this.pendingRef, (m) => {
-                        const entry = HashMap.get(m, id);
-                        return entry._tag === "Some"
-                            ? [entry.value, HashMap.remove(m, id)]
-                            : [null, m];
-                    });
-                    if (pending === null)
-                        continue;
-                    if (decoded._tag === "ResponseError") {
-                        const { error } = decoded;
-                        yield* Deferred.fail(pending, new RpcServerError({
-                            code: typeof error.code === "number"
-                                ? error.code
-                                : JSON_RPC_INTERNAL_ERROR_CODE,
-                            message: error.message ?? MSG_RPC_ERROR_FALLBACK,
-                            data: error.data,
-                        }));
-                    }
-                    else {
-                        yield* Deferred.succeed(pending, decoded.result);
-                    }
-                    continue;
-                }
-                if (decoded._tag === "ServerRequest") {
-                    // Task-callback request — non-blocking offer to the global
-                    // bounded queue (cutover #533). The drain fiber serializes
-                    // handler execution. If the queue is saturated, surface a
-                    // typed wire-level error so the server's `Deferred.await`
-                    // settles deterministically rather than hanging.
-                    const state = yield* Ref.get(this.stateRef);
-                    if (Option.isNone(state)) {
-                        // Reader fiber observed a frame without a corresponding
-                        // ConnState — only path here is a frame arriving between
-                        // scope-close finalization and reader-exit observation.
-                        // Drop silently: the queue + drain fiber are already gone.
-                        continue;
-                    }
-                    const offered = yield* Queue.offer(state.value.taskCallbackQueue, decoded);
-                    if (!offered) {
-                        yield* this.writeQueueFullRejection(decoded.id, state.value.write);
-                    }
-                    continue;
-                }
-                if (decoded._tag === "Notification") {
-                    yield* this.subscribers.dispatch(decoded);
-                    const delivered = yield* Ref.modify(this.notificationWaitersRef, (m) => {
-                        const bucket = HashMap.get(m, decoded.definition);
-                        if (bucket._tag === "None" || bucket.value.length === 0) {
-                            return [null, m];
-                        }
-                        const arr = bucket.value;
-                        const chosen = arr[arr.length - 1];
-                        const rest = arr.slice(0, -1);
-                        const nextMap = rest.length === 0
-                            ? HashMap.remove(m, decoded.definition)
-                            : HashMap.set(m, decoded.definition, rest);
-                        return [chosen, nextMap];
-                    });
-                    if (delivered !== null) {
-                        yield* delivered.complete(decoded);
-                        continue;
-                    }
-                    yield* Ref.update(this.notificationsBufferRef, (xs) => {
-                        const appended = [...xs, decoded];
-                        return appended.length > MAX_EVENT_BUFFER
-                            ? appended.slice(-MAX_EVENT_BUFFER)
-                            : appended;
-                    });
-                }
+                yield* this.handleDecodedFrame(decoded);
             }
         });
     }
@@ -647,30 +592,36 @@ export class MoltZapWsClient {
             }
         });
     }
+    failConnectionPending(state) {
+        return state.jsonRpcClient.failAllPending(new NotConnectedError({ message: MSG_NOT_CONNECTED }));
+    }
     failAllPending(message) {
         return Effect.gen(this, function* () {
-            const pending = yield* Ref.getAndSet(this.pendingRef, HashMap.empty());
-            for (const [, d] of HashMap.entries(pending)) {
-                yield* Deferred.fail(d, new NotConnectedError({ message })).pipe(Effect.ignore);
-            }
+            const state = yield* Ref.get(this.stateRef);
+            if (Option.isNone(state))
+                return;
+            yield* state.value.jsonRpcClient.failAllPending(new NotConnectedError({ message }));
         });
     }
-    /** Schedule a reconnect attempt. Jittered exponential backoff (1s base,
-     * 30s cap) routed through `Effect.sleep` so `TestClock` can drive it. */
+    /**
+     * Schedule a reconnect attempt. Jittered exponential backoff (1s base,
+     * 30s cap) routed through `Effect.sleep` so `TestClock` can drive it.
+     */
     scheduleReconnect() {
         if (this.closed || this.reconnectFiber !== null)
             return;
-        const attempt = this.connectEffect().pipe(Effect.tap((helloOk) => Effect.sync(() => {
+        const attempt = this.connectEffect().pipe(Effect.tap((helloOk) => Effect.gen(this, function* () {
             try {
                 this.options.onReconnect?.(helloOk);
             }
             catch (err) {
-                this.options.logger?.warn("onReconnect handler threw", err);
+                yield* Effect.logWarning("onReconnect handler threw", err);
             }
-        })), 
-        // Collapse typed errors so `Schedule.exponential` can retry.
-        Effect.mapError(() => new ReconnectAttemptFailedError({
-            reason: "reconnect attempt failed",
+        })), Effect.either, Effect.flatMap(Either.match({
+            onLeft: () => Effect.fail(new ReconnectAttemptFailedError({
+                reason: "reconnect attempt failed",
+            })),
+            onRight: (value) => Effect.succeed(value),
         })));
         const backoff = Schedule.exponential(Duration.millis(BASE_RECONNECT_DELAY_MS), RECONNECT_BACKOFF_FACTOR).pipe(Schedule.either(Schedule.spaced(Duration.millis(MAX_RECONNECT_DELAY_MS))), Schedule.jittered);
         const loop = attempt.pipe(Effect.retry(backoff), Effect.asVoid, Effect.catchAll(() => Effect.void), Effect.ensuring(Effect.sync(() => {