@moltzap/client 2026.414.0 → 2026.425.0

package/dist/test-utils/fake-service.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Fake `MoltZapService` test double, reusable across the client's own tests
+ * and downstream consumers (nanoclaw, openclaw).
+ *
+ * Strategy: extend the real `MoltZapService`, keeping all stateful logic
+ * intact, and override only `sendRpc` so every RPC is answered from a
+ * canned-response map. The typed `setResponse` helper indexes by
+ * `RpcMethodName` so a typo in the wire name is a compile error — unknown
+ * methods fail *at compile time*, not at runtime.
+ *
+ * Motivation: the `sendToAgent` contract drift bug (A7) happened because a
+ * hand-maintained mock drifted from the real wire shape. Typed method names
+ * surface renames and additions to the RPC surface as compile errors across
+ * every test that uses the fake.
+ *
+ * Two APIs:
+ *   (1) `setResponse(method, result)` — strict. `method` must be a
+ *       `RpcMethodName`; `result` must match `RpcMap[M]["result"]`.
+ *   (2) `responses` — the underlying `Map<string, unknown>`. Permissive,
+ *       preserved so existing callers that set unstyped shapes
+ *       (e.g. `{}` for a method whose real result has required fields)
+ *       keep working. Prefer `setResponse` in new code.
+ */
+import type { Message, RpcMap, RpcMethodName } from "@moltzap/protocol";
+import { Effect } from "effect";
+import { MoltZapService, type ServiceRpcError } from "../service.js";
+/** A tracked `sendRpc` invocation. */
+export interface RecordedCall {
+    method: string;
+    params: unknown;
+}
+/**
+ * Strict canned-response registry shape. Methods must be known protocol
+ * names; results must match their declared schema. Use via `setResponse` —
+ * spelled out as a type so downstream consumers can compose their own
+ * factories.
+ */
+export type CannedResponses = Partial<{
+    [M in RpcMethodName]: RpcMap[M]["result"] | ((params: RpcMap[M]["params"]) => RpcMap[M]["result"]);
+}>;
+export declare class FakeMoltZapService extends MoltZapService {
+    calls: RecordedCall[];
+    /**
+     * Permissive response map. Prefer {@link setResponse} for typed
+     * registration. Keep this as `Map<string, unknown>` so tests that pass
+     * partial or loosely-shaped canned values — and tests that assert on
+     * unknown-method rejection — keep working.
+     */
+    responses: Map<string, unknown>;
+    constructor(opts?: {
+        serverUrl?: string;
+        agentKey?: string;
+    });
+    /**
+     * Register a canned response, typed against the real RPC map. Unknown
+     * method names are a compile error (`RpcMethodName` is a union literal),
+     * and values must match `RpcMap[M]["result"]` — a schema change in the
+     * protocol flows through to every test that sets a response for that
+     * method.
+     */
+    setResponse<M extends RpcMethodName>(method: M, result: RpcMap[M]["result"] | ((params: RpcMap[M]["params"]) => RpcMap[M]["result"])): void;
+    /**
+     * Remove a previously-registered response. Typed against `RpcMethodName`
+     * so `deleteResponse("agents/lookpByName")` (typo) is a compile error.
+     */
+    deleteResponse(method: RpcMethodName): void;
+    sendRpc(method: string, params?: unknown): Effect.Effect<unknown, ServiceRpcError>;
+    /**
+     * Insert a message into the service's internal buffer without going
+     * through the WebSocket path — used to stage state for context-building
+     * tests.
+     */
+    addMessage(convId: string, msg: Message): void;
+    /** Pin an agent name in the internal cache without an RPC round-trip. */
+    setAgentNameDirect(id: string, name: string): void;
+    /**
+     * Typed view of the parent class's private Refs, exposed only to this
+     * fake so its test-only harness methods (addMessage, setAgentNameDirect)
+     * can stage state without going through the WebSocket pipeline. This is
+     * the single spot where the subclass widens its own `this` to see parent
+     * privates — every other caller goes through the narrow harness API.
+     */
+    private get internals();
+}
+//# sourceMappingURL=fake-service.d.ts.map

package/dist/test-utils/fake-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-service.d.ts","sourceRoot":"","sources":["../../src/test-utils/fake-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAwB,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrE,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC;KACnC,CAAC,IAAI,aAAa,GACf,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACnB,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC3D,CAAC,CAAC;AAEH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,KAAK,EAAE,YAAY,EAAE,CAAM;IAC3B;;;;;OAKG;IACH,SAAS,uBAA8B;gBAGrC,IAAI,GAAE;QACJ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACd;IAQR;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,SAAS,aAAa,EACjC,MAAM,EAAE,CAAC,EACT,MAAM,EACF,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACnB,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GACzD,IAAI;IAIP;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIlC,OAAO,CACd,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC;IAqB1C;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAY9C,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMlD;;;;;;OAMG;IACH,OAAO,KAAK,SAAS,GAGpB;CACF"}

package/dist/test-utils/fake-service.js

@@ -0,0 +1,103 @@
+/**
+ * Fake `MoltZapService` test double, reusable across the client's own tests
+ * and downstream consumers (nanoclaw, openclaw).
+ *
+ * Strategy: extend the real `MoltZapService`, keeping all stateful logic
+ * intact, and override only `sendRpc` so every RPC is answered from a
+ * canned-response map. The typed `setResponse` helper indexes by
+ * `RpcMethodName` so a typo in the wire name is a compile error — unknown
+ * methods fail *at compile time*, not at runtime.
+ *
+ * Motivation: the `sendToAgent` contract drift bug (A7) happened because a
+ * hand-maintained mock drifted from the real wire shape. Typed method names
+ * surface renames and additions to the RPC surface as compile errors across
+ * every test that uses the fake.
+ *
+ * Two APIs:
+ *   (1) `setResponse(method, result)` — strict. `method` must be a
+ *       `RpcMethodName`; `result` must match `RpcMap[M]["result"]`.
+ *   (2) `responses` — the underlying `Map<string, unknown>`. Permissive,
+ *       preserved so existing callers that set unstyped shapes
+ *       (e.g. `{}` for a method whose real result has required fields)
+ *       keep working. Prefer `setResponse` in new code.
+ */
+import { Effect, HashMap, Option, Ref } from "effect";
+import { MoltZapService } from "../service.js";
+import { RpcServerError } from "../runtime/errors.js";
+export class FakeMoltZapService extends MoltZapService {
+    calls = [];
+    /**
+     * Permissive response map. Prefer {@link setResponse} for typed
+     * registration. Keep this as `Map<string, unknown>` so tests that pass
+     * partial or loosely-shaped canned values — and tests that assert on
+     * unknown-method rejection — keep working.
+     */
+    responses = new Map();
+    constructor(opts = {}) {
+        super({
+            serverUrl: opts.serverUrl ?? "ws://test.invalid",
+            agentKey: opts.agentKey ?? "test-key",
+        });
+    }
+    /**
+     * Register a canned response, typed against the real RPC map. Unknown
+     * method names are a compile error (`RpcMethodName` is a union literal),
+     * and values must match `RpcMap[M]["result"]` — a schema change in the
+     * protocol flows through to every test that sets a response for that
+     * method.
+     */
+    setResponse(method, result) {
+        this.responses.set(method, result);
+    }
+    /**
+     * Remove a previously-registered response. Typed against `RpcMethodName`
+     * so `deleteResponse("agents/lookpByName")` (typo) is a compile error.
+     */
+    deleteResponse(method) {
+        this.responses.delete(method);
+    }
+    sendRpc(method, params) {
+        return Effect.suspend(() => {
+            this.calls.push({ method, params });
+            if (this.responses.has(method)) {
+                const entry = this.responses.get(method);
+                if (typeof entry === "function") {
+                    return Effect.sync(() => entry(params));
+                }
+                return Effect.succeed(entry);
+            }
+            return Effect.fail(new RpcServerError({
+                code: -32601,
+                message: `FakeMoltZapService: no canned response for ${method}`,
+            }));
+        });
+    }
+    // --- Test harness: reach into private state ---
+    /**
+     * Insert a message into the service's internal buffer without going
+     * through the WebSocket path — used to stage state for context-building
+     * tests.
+     */
+    addMessage(convId, msg) {
+        Effect.runSync(Ref.update(this.internals.messagesRef, (m) => {
+            const existing = Option.getOrElse(HashMap.get(m, convId), () => []);
+            return HashMap.set(m, convId, [...existing, msg]);
+        }));
+    }
+    /** Pin an agent name in the internal cache without an RPC round-trip. */
+    setAgentNameDirect(id, name) {
+        Effect.runSync(Ref.update(this.internals.agentNamesRef, (m) => HashMap.set(m, id, name)));
+    }
+    /**
+     * Typed view of the parent class's private Refs, exposed only to this
+     * fake so its test-only harness methods (addMessage, setAgentNameDirect)
+     * can stage state without going through the WebSocket pipeline. This is
+     * the single spot where the subclass widens its own `this` to see parent
+     * privates — every other caller goes through the narrow harness API.
+     */
+    get internals() {
+        // #ignore-sloppy-code-next-line[as-unknown-as]: single test-only view over parent class's private state; callers use this.internals.<ref>
+        return this;
+    }
+}
+//# sourceMappingURL=fake-service.js.map

package/dist/test-utils/fake-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-service.js","sourceRoot":"","sources":["../../src/test-utils/fake-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,cAAc,EAAwB,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoBtD,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,KAAK,GAAmB,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEvC,YACE,OAGI,EAAE;QAEN,KAAK,CAAC;YACJ,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,mBAAmB;YAChD,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,UAAU;SACtC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CACT,MAAS,EACT,MAE0D;QAE1D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,MAAqB;QAClC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAEQ,OAAO,CACd,MAAc,EACd,MAAgB;QAEhB,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACpC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACzC,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;oBAChC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAE,KAAiC,CAAC,MAAM,CAAC,CAAC,CAAC;gBACvE,CAAC;gBACD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,cAAc,CAAC;gBACjB,IAAI,EAAE,CAAC,KAAK;gBACZ,OAAO,EAAE,8CAA8C,MAAM,EAAE;aAChE,CAAC,CACH,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,iDAAiD;IAEjD;;;;OAIG;IACH,UAAU,CAAC,MAAc,EAAE,GAAY;QACrC,MAAM,CAAC,OAAO,CACZ,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;YAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,EACtB,GAAG,EAAE,CAAC,EAA4B,CACnC,CAAC;YACF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,kBAAkB,CAAC,EAAU,EAAE,IAAY;QACzC,MAAM,CAAC,OAAO,CACZ,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAC1E,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,IAAY,SAAS;QACnB,0IAA0I;QAC1I,OAAO,IAAkC,CAAC;IAC5C,CAAC;CACF"}

package/dist/test-utils/index.d.ts

@@ -1,4 +1,6 @@
 export { createFakeChannelService, type ChannelServiceEmit, type ChannelServiceState, type CreateFakeChannelServiceOptions, type FakeChannelService, } from "./channel-service-fixture.js";
+export { FakeMoltZapService, type CannedResponses, type RecordedCall, } from "./fake-service.js";
+export { createMoltZapRealClientFactory, type RealClientFactoryOptions, } from "./conformance-adapter.js";
 import type { Message } from "@moltzap/protocol";
 export declare function buildMessage(overrides?: Partial<Message>): Message;
 export declare function flushDispatchChain(): Promise<void>;

package/dist/test-utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,+BAA+B,EACpC,KAAK,kBAAkB,GACxB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,wBAAgB,YAAY,CAAC,SAAS,GAAE,OAAO,CAAC,OAAO,CAAM,GAAG,OAAO,CAUtE;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,+BAA+B,EACpC,KAAK,kBAAkB,GACxB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,8BAA8B,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,wBAAgB,YAAY,CAAC,SAAS,GAAE,OAAO,CAAC,OAAO,CAAM,GAAG,OAAO,CAStE;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIxD"}

package/dist/test-utils/index.js

@@ -1,10 +1,11 @@
 export { createFakeChannelService, } from "./channel-service-fixture.js";
+export { FakeMoltZapService, } from "./fake-service.js";
+export { createMoltZapRealClientFactory, } from "./conformance-adapter.js";
 export function buildMessage(overrides = {}) {
     return {
         id: "msg-1",
         conversationId: "conv-1",
-        sender: { type: "agent", id: "agent-alice" },
-        seq: 1,
+        senderId: "agent-alice",
         parts: [{ type: "text", text: "hello" }],
         createdAt: "2026-04-10T12:00:00.000Z",
         ...overrides,

package/dist/test-utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAKzB,MAAM,8BAA8B,CAAC;AAItC,MAAM,UAAU,YAAY,CAAC,YAA8B,EAAE;IAC3D,OAAO;QACL,EAAE,EAAE,OAAO;QACX,cAAc,EAAE,QAAQ;QACxB,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE;QAC5C,GAAG,EAAE,CAAC;QACN,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACxC,SAAS,EAAE,0BAA0B;QACrC,GAAG,SAAS;KACF,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/test-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAKzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,kBAAkB,GAGnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,8BAA8B,GAE/B,MAAM,0BAA0B,CAAC;AAIlC,MAAM,UAAU,YAAY,CAAC,YAA8B,EAAE;IAC3D,OAAO;QACL,EAAE,EAAE,OAAO;QACX,cAAc,EAAE,QAAQ;QACxB,QAAQ,EAAE,aAAa;QACvB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACxC,SAAS,EAAE,0BAA0B;QACrC,GAAG,SAAS;KACF,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/ws-client.d.ts

@@ -1,4 +1,14 @@
-import { type EventFrame } from "@moltzap/protocol";
+import { Effect } from "effect";
+import { type EventFrame, type RpcDefinition, type TSchema, type Static } from "@moltzap/protocol";
+import { NotConnectedError, RpcServerError, RpcTimeoutError } from "./runtime/errors.js";
+import { type EventSubscription, type SubscriberHandler, type SubscriptionFilter } from "./runtime/subscribers.js";
+import { type CloseInfo } from "./runtime/close-info.js";
+export type { CloseInfo };
+/**
+ * Default per-RPC timeout. Exported so tests driving `TestClock` can match
+ * exactly — keeps tests from silently drifting if this changes.
+ */
+export declare const RPC_TIMEOUT_MS = 30000;
 export interface WsClientLogger {
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
@@ -7,35 +17,164 @@ export interface WsClientLogger {
 export interface MoltZapWsClientOptions {
     serverUrl: string;
     agentKey: string;
-    onEvent: (event: EventFrame) => void;
-    onDisconnect: () => void;
-    onReconnect: (helloOk: unknown) => void;
+    /**
+     * Called once per disconnect (not reconnect). Spec #222 §5.4 + OQ-5 (A):
+     * `close` is the typed close metadata — real WebSocket `{code, reason}`
+     * when the transport surfaces them, OQ-5 defaults otherwise. Required
+     * arg (OQ-6 rewrite): zero-arg `() => void` callers must migrate to
+     * accept (and may ignore) the arg.
+     *
+     * Migration note (spec #222 OQ-4 rewrite): the previous `onEvent`
+     * callback was deleted in this rewrite. Callers that want to observe
+     * every inbound event register `client.subscribe({}, handler)` after
+     * construction; events flow through the per-subscription registry,
+     * not through a top-level option.
+     */
+    onDisconnect?: (close: CloseInfo) => void;
+    onReconnect?: (helloOk: unknown) => void;
     logger?: WsClientLogger;
 }
 /**
- * WebSocket connection lifecycle:
+ * Return shape of `MoltZapWsClient.sendRpcTracked`. Spec #222 OQ-1
+ * resolution (B): surface the outbound request `id` (un-vacuates B4 at
+ * `packages/protocol/src/testing/conformance/client/rpc-semantics.ts:205-216`)
+ * and the response envelope `type` (un-vacuates V5 at
+ * `rpc-semantics.ts:103-110`), without leaking `jsonrpc` onto the
+ * caller surface.
+ *
+ * `type` is the literal `"response"` — the only response-frame kind
+ * `packages/protocol/src/schema/frames.ts:18` defines — but it is
+ * surfaced as an observable value (not a synthesized adapter constant)
+ * so the V5 predicate can flip under a mutation that forges a
+ * non-response shape.
+ */
+export interface TrackedRpcResponse<R> {
+    readonly id: string;
+    readonly type: "response";
+    readonly result: R;
+}
+/**
+ * WebSocket lifecycle: open → auth/connect → active. On disconnect,
+ * exponential backoff (1s base, 30s cap, jittered) retries the handshake via
+ * `Effect.sleep` + `Schedule` so TestClock can drive it. Public API is
+ * Effect-based — consumers run the returned Effects themselves (typically at
+ * a framework or CLI edge).
  *
- *   connect -> auth/connect -> HelloOk -> active
- *       | (disconnect)
- *   backoff (1s, 2s, 4s, 8s, max 30s with jitter) -> reconnect -> auth/connect -> ...
+ * Transport: `@effect/platform/Socket.makeWebSocket` backed by
+ * `@effect/platform-node/NodeSocket.layerWebSocketConstructor`. The Node
+ * `WebSocketConstructor` layer is provided internally via `ManagedRuntime`
+ * so callers' `connect()` / `sendRpc()` Effects have no extra requirement.
  */
 export declare class MoltZapWsClient {
-    private options;
-    private ws;
-    private reconnectAttempt;
-    private maxReconnectDelay;
-    private pendingRequests;
+    private readonly options;
+    private readonly pendingRef;
+    private readonly stateRef;
+    private readonly malformedRef;
+    private readonly eventsBufferRef;
+    /**
+     * 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.
+     */
+    private readonly eventWaitersRef;
+    private readonly runtime;
+    /**
+     * Per-subscription event registry. Spec #222 §5.3 (C4 + the
+     * `RealClientEventSubscriber.subscribe` filter stub). Constructed
+     * synchronously alongside the other Refs; `MoltZapWsClient.subscribe`
+     * delegates to it directly.
+     */
+    private readonly subscribers;
     private requestCounter;
     private closed;
+    private reconnectFiber;
     private _helloOk;
     constructor(options: MoltZapWsClientOptions);
     get helloOk(): unknown;
-    connect(): Promise<unknown>;
-    sendRpc(method: string, params?: unknown): Promise<unknown>;
-    /** Close the socket permanently (no reconnection). */
-    close(): void;
+    /** Open the socket, perform auth/connect, resolve with HelloOk. Fails
+     * immediately on pre-open close or error. */
+    connect(): Effect.Effect<unknown, NotConnectedError | RpcTimeoutError | RpcServerError>;
+    /**
+     * 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
+     *
+     * Overloads: pass an `RpcDefinition` for compile-time param/result typing,
+     * or a raw method string for untyped legacy call sites.
+     */
+    sendRpc<D extends RpcDefinition<string, TSchema, TSchema>>(method: D, params: Static<D["paramsSchema"]>): Effect.Effect<Static<D["resultSchema"]>, NotConnectedError | RpcTimeoutError | RpcServerError>;
+    sendRpc(method: string, params?: unknown): Effect.Effect<unknown, NotConnectedError | RpcTimeoutError | RpcServerError>;
+    /**
+     * 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 typed/raw overloads.
+     *
+     * 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<D extends RpcDefinition<string, TSchema, TSchema>>(method: D, params: Static<D["paramsSchema"]>): Effect.Effect<TrackedRpcResponse<Static<D["resultSchema"]>>, NotConnectedError | RpcTimeoutError | RpcServerError>;
+    sendRpcTracked(method: string, params?: unknown): Effect.Effect<TrackedRpcResponse<unknown>, NotConnectedError | RpcTimeoutError | RpcServerError>;
+    /**
+     * Register a per-subscription event handler. Spec #222 §5.3 + OQ-2
+     * (A): filter grammar is the three-field `SubscriptionFilter`
+     * (`emissionTag` / `conversationId` / `eventNamePrefix`). Returns a
+     * handle whose `unsubscribe` Effect drops delivery starting with the
+     * next inbound frame (OQ-3 A snapshot semantics).
+     *
+     * Subscription is legal pre-`connect()`; the registry buffers
+     * registrations and starts dispatching once the reader fiber begins
+     * producing frames. Fails with `NotConnectedError` only if the client
+     * has been permanently torn down via `close()`.
+     */
+    subscribe(filter: SubscriptionFilter, handler: SubscriberHandler): Effect.Effect<EventSubscription, NotConnectedError>;
+    /**
+     * Close the socket permanently (no reconnection). Writes a clean WebSocket
+     * close frame (code 1000) before tearing down the scope so the server
+     * observes a graceful handshake rather than an abrupt disconnect, preventing
+     * lingering CLOSE_WAIT sockets on the server side.
+     */
+    close(): Effect.Effect<void, never>;
+    /** Wait for the next inbound event whose `event` field equals `eventName`.
+     * Consumes a buffered match if present; otherwise awaits the next match
+     * with a per-call timeout. */
+    waitForEvent(eventName: string, timeoutMs?: number): Effect.Effect<EventFrame, Error>;
+    /** Return all buffered events and clear the buffer. Synchronous. */
+    drainEvents(): EventFrame[];
     /** Close the socket without marking as permanently closed, triggering reconnection. */
-    disconnect(): void;
+    disconnect(): Effect.Effect<void, never>;
+    private disconnectSync;
+    private connectEffect;
+    /**
+     * 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
+     * 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.
+     */
+    private sendRpcTrackedEffect;
+    /**
+     * Bare-result RPC — projects the tracked RPC envelope onto its
+     * `result` field, discarding the `{id, type}` observability surface.
+     * The write / race / timeout plumbing lives in `sendRpcTrackedEffect`
+     * so there is one shared site for Invariant 3 (single id source),
+     * Invariant 5 (typed error channel), and the `socket.writer` latch
+     * race described below.
+     */
+    private sendRpcEffect;
+    /** Route an inbound frame. Malformed frames are logged + dropped; event
+     * frames dispatch to `onEvent` after the shape check. */
+    private handleIncoming;
+    /** Fail every outstanding event waiter with `message` and clear the map. */
+    private failAllEventWaiters;
+    private failAllPending;
+    /** Schedule a reconnect attempt. Jittered exponential backoff (1s base,
+     * 30s cap) routed through `Effect.sleep` so `TestClock` can drive it. */
     private scheduleReconnect;
 }
 //# sourceMappingURL=ws-client.d.ts.map

package/dist/ws-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws-client.d.ts","sourceRoot":"","sources":["../src/ws-client.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAed,OAAO,CAAC,OAAO;IAd3B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,eAAe,CAMnB;IACJ,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAiB;gBAEb,OAAO,EAAE,sBAAsB;IAEnD,IAAI,OAAO,IAAI,OAAO,CAErB;IAEK,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAqD3B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA4CjE,sDAAsD;IACtD,KAAK,IAAI,IAAI;IAKb,uFAAuF;IACvF,UAAU,IAAI,IAAI;IAIlB,OAAO,CAAC,iBAAiB;CAiB1B"}
+{"version":3,"file":"ws-client.d.ts","sourceRoot":"","sources":["../src/ws-client.ts"],"names":[],"mappings":"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"}