@moltzap/client 2026.503.3 → 2026.504.0

package/dist/ws-client.js

@@ -1,12 +1,13 @@
 import * as Socket from "@effect/platform/Socket";
 import * as NodeSocket from "@effect/platform-node/NodeSocket";
-import { Cause, Deferred, Duration, Effect, Exit, Fiber, HashMap, ManagedRuntime, Option, Ref, Schedule, Scope, } from "effect";
-import { PROTOCOL_VERSION, responseFrame, } from "@moltzap/protocol";
-import { DuplicateServerRpcHandlerError, NotConnectedError, RpcServerError, RpcTimeoutError, } from "./runtime/errors.js";
+import { Cause, Data, Deferred, Duration, Either, Effect, Exit, Fiber, HashMap, ManagedRuntime, Option, Ref, Schedule, Scope, } from "effect";
+import { PROTOCOL_VERSION, Connect, decodeRpcResult, jsonRpcStringId, NotConnectedError, requestFrame, responseFrame, RpcServerError, RpcTimeoutError, } from "@moltzap/protocol";
+import { DuplicateServerRpcHandlerError } from "./runtime/errors.js";
 import { decodeFrames } from "./runtime/frame.js";
 import { makeSubscriberRegistry, } from "./runtime/subscribers.js";
 import { extractCloseInfo } from "./runtime/close-info.js";
-import { makePartitionedDispatcher, } from "./internal/s2c-partitioned-dispatcher.js";
+import { makePartitionedDispatcher, } from "./internal/app-callback-partitioned-dispatcher.js";
+import { PartitionLimitError, PartitionQueueFullError, } from "./internal/app-callback-dispatcher-errors.js";
 /**
  * Default per-RPC timeout. Exported so tests driving `TestClock` can match
  * exactly — keeps tests from silently drifting if this changes.
@@ -15,29 +16,41 @@ export const RPC_TIMEOUT_MS = 30_000;
 /** Reconnect backoff: 1s base, doubling per attempt up to the cap. */
 const BASE_RECONNECT_DELAY_MS = 1000;
 const MAX_RECONNECT_DELAY_MS = 30_000;
+const RECONNECT_BACKOFF_FACTOR = 2;
+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;
 /**
- * Cap on the per-client event buffer. Any frame that has no live
- * `waitForEvent` awaiter lands here until someone drains it. Excess
+ * Cap on the per-client notification buffer. Any frame that has no live
+ * `waitForNotification` awaiter lands here until someone drains it. Excess
  * frames are evicted FIFO so a slow consumer can't leak memory.
  */
 const MAX_EVENT_BUFFER = 1000;
 const MSG_NOT_CONNECTED = "WebSocket not connected";
 const MSG_RPC_ERROR_FALLBACK = "RPC error";
 const UTF8_DECODER = new TextDecoder("utf-8");
-/** Drop `waiter` from its event-name bucket, pruning an empty bucket. */
-function removeWaiter(m, eventName, waiter) {
-    const bucket = HashMap.get(m, eventName);
+const makeNotConnectedError = () => new NotConnectedError({ message: MSG_NOT_CONNECTED });
+class ReconnectAttemptFailedError extends Data.TaggedError("ReconnectAttemptFailedError") {
+}
+function notificationMatches(definition, notification) {
+    return notification.definition === definition;
+}
+/** Drop `waiter` from its notification-definition bucket, pruning an empty bucket. */
+function removeWaiter(m, definition, waiter) {
+    const bucket = HashMap.get(m, definition);
     if (bucket._tag === "None")
         return m;
     const filtered = bucket.value.filter((w) => w !== waiter);
     return filtered.length === 0
-        ? HashMap.remove(m, eventName)
-        : HashMap.set(m, eventName, filtered);
+        ? HashMap.remove(m, definition)
+        : HashMap.set(m, definition, filtered);
 }
 /**
  * WebSocket lifecycle: open → auth/connect → active. On disconnect,
@@ -56,17 +69,15 @@ export class MoltZapWsClient {
     pendingRef;
     stateRef;
     malformedRef;
-    eventsBufferRef;
+    notificationsBufferRef;
     /**
-     * Waiters keyed by event name. Each bucket is a FIFO stack: delivery
-     * pops the most recently registered waiter (the tail). Keying by event
-     * name keeps dispatch O(1) per inbound frame regardless of total
-     * outstanding waiters.
+     * Waiters keyed by notification descriptor identity. Each bucket is a FIFO
+     * stack: delivery pops the most recently registered waiter (the tail).
      */
-    eventWaitersRef;
+    notificationWaitersRef;
     runtime;
     /**
-     * Per-subscription event registry. Spec #222 §5.3 (C4 + the
+     * Per-subscription notification registry. Spec #222 §5.3 (C4 + the
      * `RealClientEventSubscriber.subscribe` filter stub). Constructed
      * synchronously alongside the other Refs; `MoltZapWsClient.subscribe`
      * delegates to it directly.
@@ -76,9 +87,9 @@ export class MoltZapWsClient {
      * Per-method handler registry for server-initiated RPCs. Survives
      * reconnects so apps register once and re-attach automatically when the
      * socket comes back. Each entry is invoked by the per-connection
-     * dispatcher fiber when an s2c request frame arrives.
+     * dispatcher fiber when an appCallback request frame arrives.
      */
-    s2cHandlersRef;
+    appCallbackHandlersRef;
     requestCounter = 0;
     closed = false;
     reconnectFiber = null;
@@ -89,15 +100,15 @@ export class MoltZapWsClient {
         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.eventsBufferRef = this.runtime.runSync(Ref.make([]));
-        this.eventWaitersRef = this.runtime.runSync(Ref.make(HashMap.empty()));
+        this.notificationsBufferRef = this.runtime.runSync(Ref.make([]));
+        this.notificationWaitersRef = this.runtime.runSync(Ref.make(HashMap.empty()));
         // 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.s2cHandlersRef = this.runtime.runSync(Ref.make(HashMap.empty()));
+        this.appCallbackHandlersRef = this.runtime.runSync(Ref.make(HashMap.empty()));
     }
     /**
      * Register a handler for a server-initiated RPC method. Survives
@@ -109,18 +120,21 @@ export class MoltZapWsClient {
      *
      * The dispatcher fiber forked at `connect()` time picks up handlers via
      * `Ref.get` per-frame, so a registration made BEFORE `connect()` is
-     * visible to the very first inbound s2c request, and a registration
+     * visible to the very first inbound appCallback request, and a registration
      * made AFTER `connect()` takes effect on the next inbound frame.
      */
-    handleServerRpc(method, handler) {
+    handleServerRpc(definition, handler) {
         return Effect.gen(this, function* () {
-            const swapped = yield* Ref.modify(this.s2cHandlersRef, (m) => {
-                if (HashMap.has(m, method))
+            const swapped = yield* Ref.modify(this.appCallbackHandlersRef, (m) => {
+                if (HashMap.has(m, definition))
                     return [false, m];
-                return [true, HashMap.set(m, method, handler)];
+                return [
+                    true,
+                    HashMap.set(m, definition, handler),
+                ];
             });
             if (!swapped) {
-                return yield* Effect.fail(new DuplicateServerRpcHandlerError({ method }));
+                return yield* Effect.fail(new DuplicateServerRpcHandlerError({ method: definition.name }));
             }
         });
     }
@@ -132,7 +146,7 @@ export class MoltZapWsClient {
     connect() {
         return Effect.suspend(() => {
             if (this.closed) {
-                return Effect.fail(new NotConnectedError({ message: MSG_NOT_CONNECTED }));
+                return Effect.fail(makeNotConnectedError());
             }
             return this.connectEffect().pipe(
             // `makeWebSocket` requires `Socket.WebSocketConstructor`; our
@@ -141,18 +155,48 @@ export class MoltZapWsClient {
             Effect.provide(NodeSocket.layerWebSocketConstructor));
         });
     }
-    sendRpc(method, params, opts) {
-        const methodName = typeof method === "string" ? method : method.name;
-        return this.sendRpcEffect(methodName, params, opts);
+    /**
+     * 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
+     *
+     * 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,
+            }))));
     }
-    sendRpcTracked(method, params) {
-        const methodName = typeof method === "string" ? method : method.name;
-        return this.sendRpcTrackedEffect(methodName, params);
+    /**
+     * Send an RPC and surface the outbound request id alongside the
+     * response envelope `type` and `result`. Spec #222 §5.1–5.2:
+     * un-vacuates B4 (request-id tracking) and V5 (response-type
+     * exposure). Mirrors `sendRpc`'s descriptor-backed call shape.
+     *
+     * Invariant 3 (spec #222 §4): the returned `id` is the same identity
+     * minted inside the existing `rpc-${++counter}` site — no parallel
+     * counter, no mirror. The single-id pre-condition is what makes B4 a
+     * real check rather than a tautology.
+     */
+    sendRpcTracked(definition, params) {
+        return this.sendRpcTrackedEffect(definition, params).pipe(Effect.flatMap((tracked) => definition.validateResult(tracked.result)
+            ? Effect.succeed({ id: tracked.id, result: tracked.result })
+            : Effect.fail(new RpcServerError({
+                code: JSON_RPC_INTERNAL_ERROR_CODE,
+                message: `Invalid result for method: ${definition.name}`,
+                data: tracked.result,
+            }))));
     }
     /**
-     * Register a per-subscription event handler. Spec #222 §5.3 + OQ-2
+     * Register a per-subscription notification handler. Spec #222 §5.3 + OQ-2
      * (A): filter grammar is the three-field `SubscriptionFilter`
-     * (`emissionTag` / `conversationId` / `eventNamePrefix`). Returns a
+     * (`emissionTag` / `conversationId` / `notificationNamePrefix`). Returns a
      * handle whose `unsubscribe` Effect drops delivery starting with the
      * next inbound frame (OQ-3 A snapshot semantics).
      *
@@ -164,7 +208,7 @@ export class MoltZapWsClient {
     subscribe(filter, handler) {
         return Effect.suspend(() => {
             if (this.closed) {
-                return Effect.fail(new NotConnectedError({ message: MSG_NOT_CONNECTED }));
+                return Effect.fail(makeNotConnectedError());
             }
             return this.subscribers.register(filter, handler);
         });
@@ -179,6 +223,7 @@ export class MoltZapWsClient {
         return Effect.gen(this, function* () {
             if (this.closed)
                 return;
+            const hasCompletedHandshake = this._helloOk !== null;
             this.closed = true;
             this._helloOk = null;
             if (this.reconnectFiber !== null) {
@@ -186,19 +231,22 @@ export class MoltZapWsClient {
                 this.reconnectFiber = null;
                 yield* Effect.forkDaemon(Fiber.interrupt(f));
             }
-            yield* Effect.all([
-                this.failAllPending(MSG_NOT_CONNECTED),
-                this.failAllEventWaiters(MSG_NOT_CONNECTED),
-                // Drop every live subscription so handlers stop firing once
-                // the client is permanently torn down. Idempotent.
-                this.subscribers.closeAll,
-            ], { concurrency: "unbounded" });
+            yield* this.failAllPending(MSG_NOT_CONNECTED);
+            yield* this.failAllNotificationWaiters(MSG_NOT_CONNECTED);
+            // Drop every live subscription so handlers stop firing once
+            // the client is permanently torn down. Idempotent.
+            yield* this.subscribers.closeAll;
             const state = yield* Ref.getAndSet(this.stateRef, Option.none());
             if (Option.isSome(state)) {
-                yield* state.value
-                    .write(new Socket.CloseEvent(1000, "normal"))
-                    .pipe(Effect.orDie);
-                yield* Scope.close(state.value.scope, Exit.void);
+                if (hasCompletedHandshake) {
+                    yield* state.value
+                        .write(new Socket.CloseEvent(NORMAL_CLOSE_CODE, "normal"))
+                        .pipe(Effect.orDie);
+                    yield* Scope.close(state.value.scope, Exit.void);
+                }
+                else {
+                    this.runtime.runFork(Scope.close(state.value.scope, Exit.void));
+                }
                 // The partitioned dispatcher's Scope is NOT bound to the
                 // socket Scope (see ConnState doc): tear it down via runFork
                 // so this Effect remains sync-runnable for callers using
@@ -211,40 +259,47 @@ export class MoltZapWsClient {
             void this.runtime.dispose();
         })));
     }
-    /** Wait for the next inbound event whose `event` field equals `eventName`.
+    /** Wait for the next inbound notification matching `definition`.
      * Consumes a buffered match if present; otherwise awaits the next match
      * with a per-call timeout. */
-    waitForEvent(eventName, timeoutMs = 5000) {
+    waitForNotification(definition, timeoutMs = EVENT_WAIT_TIMEOUT_MS) {
         return Effect.gen(this, function* () {
-            const buffered = yield* Ref.modify(this.eventsBufferRef, (events) => {
-                const idx = events.findIndex((e) => e.event === eventName);
-                if (idx === -1)
-                    return [null, events];
-                const chosen = events[idx];
-                const next = [...events.slice(0, idx), ...events.slice(idx + 1)];
-                return [chosen, next];
+            const buffered = yield* Ref.modify(this.notificationsBufferRef, (frames) => {
+                for (const [idx, frame] of frames.entries()) {
+                    if (!notificationMatches(definition, frame))
+                        continue;
+                    const next = [...frames.slice(0, idx), ...frames.slice(idx + 1)];
+                    return [frame, next];
+                }
+                return [null, frames];
             });
             if (buffered !== null)
                 return buffered;
             const deferred = yield* Deferred.make();
-            const waiter = { eventName, deferred };
-            yield* Ref.update(this.eventWaitersRef, (m) => {
-                const existing = HashMap.get(m, eventName);
+            const waiter = {
+                definition,
+                complete: (notification) => notificationMatches(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, eventName, next);
+                return HashMap.set(m, definition, next);
             });
             return yield* Deferred.await(deferred).pipe(Effect.timeoutFail({
                 duration: `${timeoutMs} millis`,
-                onTimeout: () => new Error(`Timeout waiting for event: ${eventName}`),
+                onTimeout: () => new Error(`Timeout waiting for notification: ${definition.name}`),
             }), Effect.onExit((exit) => exit._tag === "Failure"
-                ? Ref.update(this.eventWaitersRef, (m) => removeWaiter(m, eventName, waiter))
+                ? Ref.update(this.notificationWaitersRef, (m) => removeWaiter(m, definition, waiter))
                 : Effect.void));
         });
     }
-    /** Return all buffered events and clear the buffer. Synchronous. */
-    drainEvents() {
-        const snapshot = this.runtime.runSync(Ref.get(this.eventsBufferRef));
-        this.runtime.runSync(Ref.set(this.eventsBufferRef, []));
+    /** Return all buffered notifications and clear the buffer. Synchronous. */
+    drainNotifications() {
+        const snapshot = this.runtime.runSync(Ref.get(this.notificationsBufferRef));
+        this.runtime.runSync(Ref.set(this.notificationsBufferRef, []));
         return [...snapshot];
     }
     /** Close the socket without marking as permanently closed, triggering reconnection. */
@@ -282,13 +337,19 @@ export class MoltZapWsClient {
             const scope = yield* Scope.make();
             // Map Socket open failures (SocketGenericError / SocketCloseError) to
             // NotConnectedError so callers see a single typed error.
-            const socket = yield* Scope.extend(Socket.makeWebSocket(url, { openTimeout: Duration.seconds(10) }), scope).pipe(Effect.catchAllCause((cause) => Effect.zipRight(Effect.sync(() => this.options.logger?.warn("WebSocket open failed", cause)), Scope.close(scope, Exit.void).pipe(Effect.zipRight(Effect.fail(new NotConnectedError({ message: MSG_NOT_CONNECTED })))))));
+            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 write = yield* Scope.extend(socket.writer, scope);
             // Settled first by whichever fires: the auth/connect response, or
             // reader-fiber exit on any close/error before handshake.
             const handshakeSettled = yield* Deferred.make();
-            // Spec #356 — partitioned s2c dispatcher. Replaces the pre-#356
-            // single `Stream.runForEach`-driven `s2cInboundQueue` with a
+            // Spec #356 — partitioned appCallback dispatcher. Replaces the pre-#356
+            // single `Stream.runForEach`-driven `appCallbackInboundQueue` with a
             // partition router keyed on `(sessionId, conversationId,
             // hookKind)`. Each tuple owns one bounded queue + one drain
             // fiber; cross-tuple offers run on independent fibers, so a
@@ -309,8 +370,8 @@ export class MoltZapWsClient {
             const dispatcher = yield* makePartitionedDispatcher({
                 handle: (req) => this.dispatchInboundServerRequest(req, write),
                 scope: dispatcherScope,
-                ...(this.options.s2cDispatcher !== undefined
-                    ? { config: this.options.s2cDispatcher }
+                ...(this.options.appCallbackDispatcher !== undefined
+                    ? { config: this.options.appCallbackDispatcher }
                     : {}),
                 ...(this.options.logger !== undefined
                     ? { logger: this.options.logger }
@@ -329,11 +390,11 @@ export class MoltZapWsClient {
                 this._helloOk = null;
                 yield* this.failAllPending(MSG_NOT_CONNECTED);
                 // Unblock any `connect()` still awaiting the handshake.
-                yield* Deferred.fail(handshakeSettled, new NotConnectedError({ message: MSG_NOT_CONNECTED })).pipe(Effect.ignore);
-                // Clear connection state BEFORE the s2c teardown so
+                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 s2c handler still draining (codex P2).
+                // slow appCallback handler still draining (codex P2).
                 yield* Ref.set(this.stateRef, Option.none());
                 // Tear down the partitioned dispatcher on socket-level
                 // close (e.g. server-initiated). `close()` /
@@ -374,7 +435,7 @@ export class MoltZapWsClient {
                 dispatcher,
                 dispatcherScope,
             }));
-            const authEffect = this.sendRpcEffect("auth/connect", {
+            const authEffect = this.sendRpc(Connect, {
                 agentKey: this.options.agentKey,
                 minProtocol: PROTOCOL_VERSION,
                 maxProtocol: PROTOCOL_VERSION,
@@ -392,26 +453,20 @@ export class MoltZapWsClient {
     /**
      * Tracked variant of `sendRpcEffect`. Reuses the same Deferred /
      * pendingRef plumbing — the only difference is the resolved value:
-     * `{id, type: "response", result}` instead of bare `result`. This
+     * `{id, result}` instead of bare `result`. This
      * keeps Invariant 3 (single id source) trivially: we mint `id` once
      * inside this body, register the Deferred under that id, and return
      * the same id to the caller alongside the result.
      */
-    sendRpcTrackedEffect(method, params, opts) {
+    sendRpcTrackedEffect(definition, params, opts) {
         return Effect.gen(this, function* () {
+            const method = definition.name;
             const state = yield* Ref.get(this.stateRef);
             if (Option.isNone(state)) {
-                return yield* Effect.fail(new NotConnectedError({ message: MSG_NOT_CONNECTED }));
+                return yield* Effect.fail(makeNotConnectedError());
             }
-            const id = `rpc-${++this.requestCounter}`;
-            const frame = {
-                jsonrpc: "2.0",
-                type: "request",
-                direction: "c2s",
-                id,
-                method,
-                params,
-            };
+            const id = jsonRpcStringId(`rpc-${++this.requestCounter}`);
+            const frame = requestFrame(id, definition, params);
             // Register the Deferred BEFORE writing. `write` yields to the
             // scheduler; the reader could interleave, see a close, and
             // `failAllPending` before we register — leaving us to await a
@@ -427,10 +482,16 @@ export class MoltZapWsClient {
             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);
-            if (writeRace !== null && writeRace._tag === "Left") {
-                this.options.logger?.warn("ws.send failed", writeRace.left);
+            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(new NotConnectedError({ message: MSG_NOT_CONNECTED }));
+                return yield* Effect.fail(makeNotConnectedError());
             }
             const timeoutMs = opts?.timeoutMs ?? RPC_TIMEOUT_MS;
             const result = yield* Deferred.await(deferred).pipe(Effect.timeoutFail({
@@ -439,14 +500,12 @@ export class MoltZapWsClient {
             }), Effect.onExit((exit) => Exit.isFailure(exit)
                 ? Ref.update(this.pendingRef, (m) => HashMap.remove(m, id))
                 : Effect.void));
-            // `type: "response"` is surfaced as an observable literal (V5):
-            // the value the caller sees comes from the same response
-            // envelope the reader fiber decoded, not a synthesized adapter
-            // constant. The Frame schema at
-            // `packages/protocol/src/schema/frames.ts:18` pins `type` to
-            // that literal at decode time, so this assignment is the
-            // value-level projection of that schema constraint.
-            return { id, type: "response", result };
+            const decodedResult = yield* decodeRpcResult(definition, result).pipe(Effect.mapError(() => new RpcServerError({
+                code: JSON_RPC_INTERNAL_ERROR_CODE,
+                message: `Invalid result for method: ${definition.name}`,
+                data: result,
+            })));
+            return { id, result: decodedResult };
         });
     }
     /**
@@ -457,8 +516,8 @@ export class MoltZapWsClient {
      * Invariant 5 (typed error channel), and the `socket.writer` latch
      * race described below.
      */
-    sendRpcEffect(method, params, opts) {
-        return this.sendRpcTrackedEffect(method, params, opts).pipe(Effect.map((tracked) => tracked.result));
+    sendRpcEffect(definition, params, opts) {
+        return this.sendRpcTrackedEffect(definition, params, opts).pipe(Effect.map((tracked) => tracked.result));
     }
     /**
      * Translate a typed `OfferRejected` failure from the partitioned
@@ -470,39 +529,31 @@ export class MoltZapWsClient {
      * new tag fails the compile here.
      */
     writeOfferRejection(err, requestId, write) {
-        const reply = (() => {
-            switch (err._tag) {
-                case "MalformedPartitionKeyError":
-                    return responseFrame("s2c", requestId, {
-                        error: {
-                            code: -32602,
-                            message: `Invalid params: ${err.reason}`,
-                        },
-                    });
-                case "PartitionLimitError":
-                    return responseFrame("s2c", requestId, {
-                        error: {
-                            code: -32000,
-                            message: `Server busy: partition limit reached (${err.activePartitions}/${err.maxPartitions})`,
-                        },
-                    });
-                case "PartitionQueueFullError":
-                    return responseFrame("s2c", requestId, {
-                        error: {
-                            code: -32000,
-                            message: `Server busy: partition queue full (capacity=${err.capacity})`,
-                        },
-                    });
-                default: {
-                    const _exhaustive = err;
-                    throw new Error(`writeOfferRejection: unhandled OfferRejected tag: ${String(_exhaustive)}`);
-                }
-            }
-        })();
-        return write(JSON.stringify(reply)).pipe(Effect.catchAll((werr) => Effect.sync(() => this.options.logger?.warn("s2c offer-rejection write failed", werr))));
+        const reply = this.offerRejectedResponse(err, requestId);
+        return write(JSON.stringify(reply)).pipe(Effect.catchAll((werr) => Effect.sync(() => this.options.logger?.warn("appCallback offer-rejection write failed", werr))));
+    }
+    offerRejectedResponse(err, requestId) {
+        if (err instanceof PartitionLimitError) {
+            return responseFrame(requestId, {
+                error: {
+                    code: -32000,
+                    message: `Server busy: partition limit reached (${err.activePartitions}/${err.maxPartitions})`,
+                },
+            });
+        }
+        if (err instanceof PartitionQueueFullError) {
+            return responseFrame(requestId, {
+                error: {
+                    code: -32000,
+                    message: `Server busy: partition queue full (capacity=${err.capacity})`,
+                },
+            });
+        }
+        const _exhaustive = err;
+        return _exhaustive;
     }
     /**
-     * Dispatch one inbound s2c request to the registered handler, encode
+     * Dispatch one inbound appCallback request to the registered handler, encode
      * the response, and write it back to the server. Errors are projected
      * onto an error response so the server's `Deferred.await` always
      * settles deterministically — never hangs on a missing or crashing
@@ -518,26 +569,25 @@ export class MoltZapWsClient {
      */
     dispatchInboundServerRequest(request, write) {
         return Effect.gen(this, function* () {
-            const handlers = yield* Ref.get(this.s2cHandlersRef);
-            const lookup = HashMap.get(handlers, request.method);
+            const handlers = yield* Ref.get(this.appCallbackHandlersRef);
+            const lookup = HashMap.get(handlers, request.definition);
             const buildReply = lookup._tag === "None"
-                ? Effect.succeed(responseFrame("s2c", request.id, {
+                ? Effect.succeed(responseFrame(request.id, {
                     error: {
                         code: -32601,
-                        message: `No handler registered for method: ${request.method}`,
+                        message: "No handler registered for app callback descriptor",
                     },
                 }))
                 : lookup
                     .value(request.params, {
                     requestId: request.id,
-                    method: request.method,
-                    traceparent: request.traceparent,
+                    definition: request.definition,
                 })
                     .pipe(Effect.match({
-                    onSuccess: (result) => responseFrame("s2c", request.id, {
+                    onSuccess: (result) => responseFrame(request.id, {
                         result,
                     }),
-                    onFailure: (err) => responseFrame("s2c", request.id, {
+                    onFailure: (err) => responseFrame(request.id, {
                         error: {
                             code: err.code,
                             message: err.message,
@@ -545,23 +595,23 @@ export class MoltZapWsClient {
                         },
                     }),
                 }), Effect.catchAllCause((cause) => Effect.sync(() => {
-                    this.options.logger?.warn(`s2c handler ${request.method} defected`, Cause.pretty(cause));
-                    return responseFrame("s2c", request.id, {
+                    this.options.logger?.warn("appCallback handler defected", Cause.pretty(cause));
+                    return responseFrame(request.id, {
                         error: { code: -32603, message: "Internal error" },
                     });
                 })));
             const reply = yield* buildReply;
-            yield* write(JSON.stringify(reply)).pipe(Effect.catchAll((err) => Effect.sync(() => this.options.logger?.warn("s2c response write failed", err))));
+            yield* write(JSON.stringify(reply)).pipe(Effect.catchAll((err) => Effect.sync(() => this.options.logger?.warn("appCallback response write failed", err))));
         });
     }
-    /** Route an inbound frame. Malformed frames are logged + dropped; event
-     * frames dispatch to `onEvent` after the shape check. */
+    /** 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, 200));
+                    this.options.logger?.warn(`Malformed frame (#${n}):`, err.raw.slice(0, MALFORMED_FRAME_PREVIEW_CHARS));
                 }
                 return null;
             })));
@@ -580,7 +630,9 @@ export class MoltZapWsClient {
                         continue;
                     if (error) {
                         yield* Deferred.fail(pending, new RpcServerError({
-                            code: typeof error.code === "number" ? error.code : -32603,
+                            code: typeof error.code === "number"
+                                ? error.code
+                                : JSON_RPC_INTERNAL_ERROR_CODE,
                             message: error.message ?? MSG_RPC_ERROR_FALLBACK,
                             data: error.data,
                         }));
@@ -591,7 +643,7 @@ export class MoltZapWsClient {
                     continue;
                 }
                 if (decoded._tag === "ServerRequest") {
-                    // s2c request — hand off to the partitioned dispatcher
+                    // appCallback request — hand off to the partitioned dispatcher
                     // (spec #356). The dispatcher routes by
                     // `(sessionId, conversationId, hookKind)`; the matching
                     // per-tuple worker fiber drains and runs
@@ -603,8 +655,7 @@ export class MoltZapWsClient {
                     // `dispatcher.offer` is non-blocking: every failure mode is
                     // tagged in `OfferRejected` and translated below to a wire
                     // error response so the server's `Deferred.await` always
-                    // settles (no hangs on a malformed-key or partition-full
-                    // request).
+                    // settles (no hangs on partition-full requests).
                     const state = yield* Ref.get(this.stateRef);
                     if (Option.isNone(state)) {
                         // Reader fiber observed a frame without a corresponding
@@ -614,24 +665,24 @@ export class MoltZapWsClient {
                         // gone too.
                         continue;
                     }
-                    const offered = yield* Effect.either(state.value.dispatcher.offer({
-                        id: decoded.id,
-                        method: decoded.method,
-                        params: decoded.params,
-                    }));
-                    if (offered._tag === "Left") {
-                        yield* this.writeOfferRejection(offered.left, decoded.id, state.value.write);
+                    const offered = yield* Effect.either(state.value.dispatcher.offer(decoded));
+                    const offerFailure = Either.match(offered, {
+                        onLeft: (err) => err,
+                        onRight: () => null,
+                    });
+                    if (offerFailure !== null) {
+                        yield* this.writeOfferRejection(offerFailure, decoded.id, state.value.write);
                     }
                     continue;
                 }
-                if (decoded._tag === "Event") {
+                if (decoded._tag === "Notification") {
                     // Spec #222 §5.3 (C4 + subscribe-stub): per-subscription
-                    // fan-out replaces the deleted top-level `onEvent` callback.
+                    // fan-out replaces the deleted top-level `onNotification` callback.
                     // Snapshot-at-dispatch semantics live inside the registry
                     // (OQ-3 A); see runtime/subscribers.ts.
-                    yield* this.subscribers.dispatch(decoded.frame);
-                    const delivered = yield* Ref.modify(this.eventWaitersRef, (m) => {
-                        const bucket = HashMap.get(m, decoded.frame.event);
+                    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];
                         }
@@ -639,16 +690,16 @@ export class MoltZapWsClient {
                         const chosen = arr[arr.length - 1];
                         const rest = arr.slice(0, -1);
                         const nextMap = rest.length === 0
-                            ? HashMap.remove(m, decoded.frame.event)
-                            : HashMap.set(m, decoded.frame.event, rest);
+                            ? HashMap.remove(m, decoded.definition)
+                            : HashMap.set(m, decoded.definition, rest);
                         return [chosen, nextMap];
                     });
                     if (delivered !== null) {
-                        yield* Deferred.succeed(delivered.deferred, decoded.frame).pipe(Effect.ignore);
+                        yield* delivered.complete(decoded);
                         continue;
                     }
-                    yield* Ref.update(this.eventsBufferRef, (xs) => {
-                        const appended = [...xs, decoded.frame];
+                    yield* Ref.update(this.notificationsBufferRef, (xs) => {
+                        const appended = [...xs, decoded];
                         return appended.length > MAX_EVENT_BUFFER
                             ? appended.slice(-MAX_EVENT_BUFFER)
                             : appended;
@@ -657,13 +708,13 @@ export class MoltZapWsClient {
             }
         });
     }
-    /** Fail every outstanding event waiter with `message` and clear the map. */
-    failAllEventWaiters(message) {
+    /** Fail every outstanding notification waiter with `message` and clear the map. */
+    failAllNotificationWaiters(message) {
         return Effect.gen(this, function* () {
-            const waiters = yield* Ref.getAndSet(this.eventWaitersRef, HashMap.empty());
+            const waiters = yield* Ref.getAndSet(this.notificationWaitersRef, HashMap.empty());
             for (const [, bucket] of HashMap.entries(waiters)) {
                 for (const w of bucket) {
-                    yield* Deferred.fail(w.deferred, new Error(message)).pipe(Effect.ignore);
+                    yield* w.fail(new Error(message));
                 }
             }
         });
@@ -690,8 +741,10 @@ export class MoltZapWsClient {
             }
         })), 
         // Collapse typed errors so `Schedule.exponential` can retry.
-        Effect.mapError(() => new Error("reconnect attempt failed")));
-        const backoff = Schedule.exponential(Duration.millis(BASE_RECONNECT_DELAY_MS), 2).pipe(Schedule.either(Schedule.spaced(Duration.millis(MAX_RECONNECT_DELAY_MS))), Schedule.jittered);
+        Effect.mapError(() => new ReconnectAttemptFailedError({
+            reason: "reconnect attempt failed",
+        })));
+        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(() => {
             this.reconnectFiber = null;
         })), Effect.provide(NodeSocket.layerWebSocketConstructor));