@moltzap/client 2026.503.3 → 2026.504.0

package/dist/ws-client.test.js

@@ -14,14 +14,50 @@
  * `TestClock` (see the `describe("reconnect backoff")` block for details).
  */
 import { execSync } from "node:child_process";
+import { createServer } from "node:net";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { it as itEffect } from "@effect/vitest";
 import { Cause, Duration, Effect, Exit, Fiber, Option, Scope, TestClock, } from "effect";
 import * as NodeSocketServer from "@effect/platform-node/NodeSocketServer";
 import * as Socket from "@effect/platform/Socket";
-import { PROTOCOL_VERSION } from "@moltzap/protocol";
 import { MoltZapWsClient, RPC_TIMEOUT_MS, } from "./ws-client.js";
-import { RpcServerError, RpcTimeoutError } from "./runtime/errors.js";
+import { RpcServerError, RpcTimeoutError } from "@moltzap/protocol";
+import { AppsOnClose, AppsOnJoin, Connect, ConversationsList, JSON_RPC_VERSION, MessagesSend, MessageReceivedNotificationDefinition, PROTOCOL_VERSION, agentId, conversationId, jsonRpcStringId, messageId, notificationFrame, requestFrame, responseFrame, validators, } from "@moltzap/protocol";
+import { onCloseParams, onJoinParams, SESSION_A, SESSION_B, } from "./internal/__tests__/app-callback-test-requests.js";
+// ── Test server helpers ────────────────────────────────────────────────
+const LOCALHOST_HOST = "127.0.0.1";
+const TEST_AGENT_ID = agentId("11111111-1111-4111-8111-111111111111");
+const RECONNECT_AGENT_ID = agentId("22222222-2222-4222-8222-222222222222");
+const TEST_MESSAGE_ID = messageId("44444444-4444-4444-8444-444444444444");
+const TEST_CONVERSATION_ID = conversationId("33333333-3333-4333-8333-333333333333");
+const TEST_POLICY = {
+    maxMessageBytes: 1_000_000,
+    maxPartsPerMessage: 10,
+    maxTextLength: 32_768,
+    maxGroupParticipants: 100,
+    heartbeatIntervalMs: 30_000,
+    rateLimits: {
+        messagesPerMinute: 60,
+        requestsPerMinute: 120,
+    },
+};
+const helloOk = (agentId = TEST_AGENT_ID) => ({
+    protocolVersion: PROTOCOL_VERSION,
+    agentId,
+    conversations: [],
+    unreadCounts: {},
+    policy: TEST_POLICY,
+});
+const TEST_MESSAGE = {
+    id: TEST_MESSAGE_ID,
+    conversationId: TEST_CONVERSATION_ID,
+    senderId: TEST_AGENT_ID,
+    parts: [{ type: "text", text: "hello" }],
+    createdAt: "2026-05-03T00:00:00.000Z",
+};
+const messageReceivedFrame = () => notificationFrame(MessageReceivedNotificationDefinition, {
+    message: TEST_MESSAGE,
+});
 /**
  * Spin up an in-process `@effect/platform` WS server on `127.0.0.1:0`.
  * Caller owns the provided scope; when it closes, the server shuts down.
@@ -29,7 +65,7 @@ import { RpcServerError, RpcTimeoutError } from "./runtime/errors.js";
 const startTestServer = (handler) => Effect.gen(function* () {
     const server = yield* NodeSocketServer.makeWebSocket({
         port: 0,
-        host: "127.0.0.1",
+        host: LOCALHOST_HOST,
     });
     const addr = server.address;
     if (addr._tag !== "TcpAddress") {
@@ -58,12 +94,31 @@ const startTestServer = (handler) => Effect.gen(function* () {
     }))
         .pipe(Effect.ignore));
     return {
-        url: `http://${addr.hostname}:${addr.port}`,
+        url: `http://${LOCALHOST_HOST}:${addr.port}`,
         get connections() {
             return connections;
         },
     };
 });
+const findClosedLocalPort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, LOCALHOST_HOST, () => {
+        const address = server.address();
+        if (address === null || typeof address === "string") {
+            server.close();
+            reject(new Error("expected TCP server address"));
+            return;
+        }
+        server.close((err) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(address.port);
+        });
+    });
+});
 // ── Logger helper ──────────────────────────────────────────────────────
 function makeLogger() {
     return {
@@ -73,7 +128,7 @@ function makeLogger() {
     };
 }
 const connectP = (client) => Effect.runPromise(client.connect().pipe(Effect.catchTag("RpcTimeoutError", (err) => Effect.fail(new Error(`RPC timeout: ${err.method}`))), Effect.catchAll((err) => Effect.fail(new Error(err.message)))));
-const sendRpcP = (client, method, params) => Effect.runPromise(client.sendRpc(method, params).pipe(Effect.catchTag("RpcTimeoutError", (err) => Effect.fail(new Error(`RPC timeout: ${err.method}`))), Effect.catchAll((err) => Effect.fail(new Error(err.message)))));
+const sendRpcP = (client, definition, params) => Effect.runPromise(client.sendRpc(definition, params).pipe(Effect.catchTag("RpcTimeoutError", (err) => Effect.fail(new Error(`RPC timeout: ${err.method}`))), Effect.catchAll((err) => Effect.fail(new Error(err.message)))));
 const closeClient = (client) => client.close();
 /**
  * Start a server whose handler auto-responds to `auth/connect` and forwards
@@ -81,15 +136,15 @@ const closeClient = (client) => client.close();
  * about post-handshake behaviour.
  */
 const startHandshakingServer = (handler) => startTestServer((conn, raw) => Effect.gen(function* () {
-    const frame = JSON.parse(raw);
-    if (frame.method === "auth/connect") {
-        yield* conn.send(JSON.stringify({
-            jsonrpc: "2.0",
-            type: "response",
-            direction: "c2s",
-            id: frame.id,
-            result: { agentId: "agent-xyz", protocol: PROTOCOL_VERSION },
-        }));
+    const parsed = JSON.parse(raw);
+    if (!validators.requestFrame(parsed)) {
+        return yield* Effect.die("expected JSON-RPC request frame");
+    }
+    const frame = parsed;
+    if (frame.method === Connect.name) {
+        yield* conn.send(JSON.stringify(responseFrame(frame.id, {
+            result: helloOk(),
+        })));
         return;
     }
     yield* handler(conn, raw, frame);
@@ -124,10 +179,10 @@ async function waitFor(pred, { maxMs = 2000 } = {}) {
     }
 }
 /**
- * Build a `MoltZapWsClient`. Spec #222 OQ-4 deletion: `onEvent` is no
+ * Build a `MoltZapWsClient`. Spec #222 OQ-4 deletion: `onNotification` is no
  * longer a constructor option; tests that previously stashed an
- * `onEvent` callback now register a `subscribe({}, …)` subscription
- * post-construction. The helper accepts the same `onEvent` callback as
+ * `onNotification` callback now register a `subscribe({}, …)` subscription
+ * post-construction. The helper accepts the same `onNotification` callback as
  * a convenience and wires it through the new subscription registry,
  * keeping migration noise local to the helper.
  */
@@ -139,8 +194,8 @@ function makeClient(url, overrides) {
         onReconnect: overrides?.onReconnect ?? (() => { }),
         logger: overrides?.logger ?? makeLogger(),
     });
-    if (overrides?.onEvent !== undefined) {
-        const cb = overrides.onEvent;
+    if (overrides?.onNotification !== undefined) {
+        const cb = overrides.onNotification;
         Effect.runSync(client.subscribe({}, (frame) => Effect.sync(() => cb(frame))));
     }
     return client;
@@ -178,7 +233,8 @@ describe("§5.1 connect() does not hang on pre-open failure", () => {
         // Observed: ECONNREFUSED fires in single-digit ms locally; give
         // generous CI headroom via the 15s assertion but keep test timeout at
         // 20s to avoid flakes on slow runners.
-        const client = makeClient("http://127.0.0.1:1");
+        const refusedPort = await findClosedLocalPort();
+        const client = makeClient(`http://${LOCALHOST_HOST}:${refusedPort}`);
         const t0 = Date.now();
         try {
             await connectP(client);
@@ -196,7 +252,7 @@ describe("§5.1 connect() does not hang on pre-open failure", () => {
             const server = yield* startHandshakingServer(() => Effect.void);
             const client = makeClient(server.url);
             const hello = (yield* Effect.promise(() => connectP(client)));
-            expect(hello.agentId).toBe("agent-xyz");
+            expect(hello.agentId).toBe(TEST_AGENT_ID);
             expect(client.helloOk).toEqual(hello);
             yield* closeClient(client);
         }));
@@ -213,8 +269,8 @@ describe("§5.2 pending RPCs fail on disconnect", () => {
             const server = yield* startHandshakingServer(() => Effect.void);
             const client = makeClient(server.url);
             yield* Effect.promise(() => connectP(client));
-            const rpcP = sendRpcP(client, "messages/send", {
-                conversationId: "c1",
+            const rpcP = sendRpcP(client, MessagesSend, {
+                conversationId: TEST_CONVERSATION_ID,
                 parts: [{ type: "text", text: "hi" }],
             });
             // Wait for the RPC frame to land on the server.
@@ -251,8 +307,8 @@ describe("§5.3 sendRpc does NOT retry on timeout (TestClock)", () => {
         yield* Effect.promise(() => connectP(client));
         const serverConn = server.connections[0];
         const beforeCount = serverConn.received.length;
-        const rpcFiber = yield* Effect.fork(client.sendRpc("messages/send", {
-            conversationId: "c1",
+        const rpcFiber = yield* Effect.fork(client.sendRpc(MessagesSend, {
+            conversationId: TEST_CONVERSATION_ID,
             parts: [{ type: "text", text: "payload" }],
         }));
         // Wait for the frame to land on the server using real-time polling.
@@ -288,7 +344,7 @@ describe("§5.3 sendRpc does NOT retry on timeout (TestClock)", () => {
                 const err = failed.value;
                 expect(err).toBeInstanceOf(RpcTimeoutError);
                 if (err instanceof RpcTimeoutError) {
-                    expect(err.method).toBe("messages/send");
+                    expect(err.method).toBe(MessagesSend.name);
                     expect(err.timeoutMs).toBe(RPC_TIMEOUT_MS);
                 }
             }
@@ -318,16 +374,16 @@ describe("reconnect backoff", () => {
             let authResponsesSent = 0;
             let reconnectHello = null;
             const server = yield* startTestServer((conn, raw) => Effect.gen(function* () {
-                const frame = JSON.parse(raw);
-                if (frame.method === "auth/connect") {
+                const parsed = JSON.parse(raw);
+                if (!validators.requestFrame(parsed)) {
+                    return yield* Effect.die("expected JSON-RPC request frame");
+                }
+                const frame = parsed;
+                if (frame.method === Connect.name) {
                     authResponsesSent++;
-                    yield* conn.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "response",
-                        direction: "c2s",
-                        id: frame.id,
-                        result: { agentId: "agent-1" },
-                    }));
+                    yield* conn.send(JSON.stringify(responseFrame(frame.id, {
+                        result: helloOk(RECONNECT_AGENT_ID),
+                    })));
                 }
             }));
             const client = makeClient(server.url, {
@@ -346,7 +402,7 @@ describe("reconnect backoff", () => {
             expect(server.connections.length).toBeGreaterThanOrEqual(2);
             expect(authResponsesSent).toBeGreaterThanOrEqual(2);
             yield* Effect.promise(() => waitFor(() => reconnectHello !== null, { maxMs: 500 }));
-            expect(reconnectHello.agentId).toBe("agent-1");
+            expect(reconnectHello.agentId).toBe(RECONNECT_AGENT_ID);
             yield* closeClient(client);
         }));
     });
@@ -361,103 +417,87 @@ describe("§5.4 malformed frames are logged but do not affect pending RPCs", ()
             // Server auto-handshakes. On `conversations/list`, injects a few
             // malformed inbound frames, then the real response.
             const server = yield* startHandshakingServer((conn, _raw, frame) => Effect.gen(function* () {
-                if (frame.method !== "conversations/list")
+                if (frame.method !== ConversationsList.name)
                     return;
-                // Inject: non-JSON, then missing-id response, then unknown type.
+                // Inject: non-JSON, then a missing-id response-like frame, then
+                // an unknown object shape.
                 yield* conn.send("not json at all");
-                yield* conn.send(JSON.stringify({ type: "response" }));
-                yield* conn.send(JSON.stringify({ type: "unknown", id: frame.id }));
+                yield* conn.send(JSON.stringify({ jsonrpc: JSON_RPC_VERSION, result: {} }));
+                yield* conn.send(JSON.stringify({ jsonrpc: JSON_RPC_VERSION, id: frame.id }));
                 // Real well-formed response.
-                yield* conn.send(JSON.stringify({
-                    jsonrpc: "2.0",
-                    type: "response",
-                    direction: "c2s",
-                    id: frame.id,
+                yield* conn.send(JSON.stringify(responseFrame(frame.id, {
                     result: { conversations: [] },
-                }));
+                })));
             }));
             const client = makeClient(server.url, { logger });
             yield* Effect.promise(() => connectP(client));
-            const result = (yield* Effect.promise(() => sendRpcP(client, "conversations/list", {})));
+            const result = (yield* Effect.promise(() => sendRpcP(client, ConversationsList, {})));
             expect(result.conversations).toEqual([]);
             // Logger saw at least one malformed-frame warning.
             expect(logger.warn).toHaveBeenCalled();
             yield* closeClient(client);
         }));
     });
-    it("accepts a padded chunk that contains both an event and the response", async () => {
+    it("accepts a padded chunk that contains both a notification and the response", async () => {
         await withTestServer(Effect.gen(function* () {
             const logger = makeLogger();
             const events = [];
             const server = yield* startHandshakingServer((conn, _raw, frame) => Effect.gen(function* () {
-                if (frame.method !== "conversations/list")
+                if (frame.method !== ConversationsList.name)
                     return;
-                yield* conn.send(JSON.stringify({
-                    jsonrpc: "2.0",
-                    type: "event",
-                    event: "messages/received",
-                    data: { message: { id: "m-1", conversationId: "c-1" } },
-                }) +
+                yield* conn.send(JSON.stringify(messageReceivedFrame()) +
                     "\u0000" +
-                    JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "response",
-                        direction: "c2s",
-                        id: frame.id,
+                    JSON.stringify(responseFrame(frame.id, {
                         result: { conversations: [] },
-                    }));
+                    })));
             }));
             const client = makeClient(server.url, {
                 logger,
-                onEvent: (event) => events.push(event),
+                onNotification: (event) => events.push(event),
             });
             yield* Effect.promise(() => connectP(client));
-            const result = (yield* Effect.promise(() => sendRpcP(client, "conversations/list", {})));
+            const result = (yield* Effect.promise(() => sendRpcP(client, ConversationsList, {})));
             expect(result.conversations).toEqual([]);
             expect(events).toHaveLength(1);
-            expect(events[0]).toMatchObject({ event: "messages/received" });
+            expect(events[0]).toMatchObject({
+                method: MessageReceivedNotificationDefinition.name,
+            });
             expect(logger.warn).not.toHaveBeenCalled();
             yield* closeClient(client);
         }));
     });
-    it("routes a well-formed event frame to onEvent", async () => {
+    it("routes a well-formed notification frame to onNotification", async () => {
         await withTestServer(Effect.gen(function* () {
             const events = [];
-            const server = yield* startHandshakingServer((conn) => conn.send(JSON.stringify({
-                jsonrpc: "2.0",
-                type: "event",
-                event: "message.received",
-                data: { message: { id: "m-1", conversationId: "c-1" } },
-            })));
+            const server = yield* startHandshakingServer((conn) => conn.send(JSON.stringify(messageReceivedFrame())));
             const client = makeClient(server.url, {
-                onEvent: (e) => events.push(e),
+                onNotification: (e) => events.push(e),
             });
             yield* Effect.promise(() => connectP(client));
-            // Fire-and-forget: the server responds with an out-of-band event
+            // Fire-and-forget: the server responds with an out-of-band notification
             // rather than an RPC response, so the noop Deferred never resolves.
             // Awaiting it would wedge the test for the full RPC_TIMEOUT_MS.
-            void sendRpcP(client, "noop", {}).catch(() => { });
+            void sendRpcP(client, ConversationsList, {}).catch(() => { });
             yield* Effect.promise(() => waitFor(() => events.length > 0, { maxMs: 2000 }));
             expect(events[0]).toMatchObject({
-                type: "event",
-                event: "message.received",
+                method: MessageReceivedNotificationDefinition.name,
             });
             yield* closeClient(client);
         }));
     });
-    it("does NOT route an event frame missing the event name field", async () => {
+    it("does NOT route a notification frame missing the method field", async () => {
         await withTestServer(Effect.gen(function* () {
             const events = [];
             const logger = makeLogger();
-            // Send a malformed event on the first post-handshake frame.
-            const server = yield* startHandshakingServer((conn) => conn.send(JSON.stringify({ type: "event", data: {} })));
+            // Send a malformed notification on the first post-handshake frame.
+            const server = yield* startHandshakingServer((conn) => conn.send(JSON.stringify({ jsonrpc: JSON_RPC_VERSION, params: {} })));
             const client = makeClient(server.url, {
-                onEvent: (e) => events.push(e),
+                onNotification: (e) => events.push(e),
                 logger,
             });
             yield* Effect.promise(() => connectP(client));
             // Fire-and-forget: see the well-formed-event test above for rationale.
-            void sendRpcP(client, "noop", {}).catch(() => { });
+            void sendRpcP(client, ConversationsList, {}).catch(() => { });
             yield* Effect.promise(() => new Promise((r) => setTimeout(r, 50)));
             expect(events).toHaveLength(0);
             expect(logger.warn).toHaveBeenCalled();
@@ -484,7 +524,7 @@ describe("malformed-frame log cadence (MALFORMED_LOG_EVERY)", () => {
             logger.warn.mockClear();
             // Fire-and-forget: server responds with 101 malformed frames, no
             // actual RPC response, so awaiting the noop would wedge the test.
-            void sendRpcP(client, "noop", {}).catch(() => { });
+            void sendRpcP(client, ConversationsList, {}).catch(() => { });
             // Wait for the malformed frames to flush through the reader fiber.
             yield* Effect.promise(() => new Promise((r) => setTimeout(r, 300)));
             expect(logger.warn).toHaveBeenCalledTimes(3);
@@ -506,7 +546,7 @@ describe("close() interleaved with a pending RPC", () => {
             const server = yield* startHandshakingServer(() => Effect.void);
             const client = makeClient(server.url);
             yield* Effect.promise(() => connectP(client));
-            const rpcP = sendRpcP(client, "conversations/list", {});
+            const rpcP = sendRpcP(client, ConversationsList, {});
             yield* Effect.promise(() => waitFor(() => server.connections[0].received.length >= 2));
             const beforeMs = Date.now();
             yield* closeClient(client);
@@ -526,7 +566,7 @@ describe("socket error after connect", () => {
             const server = yield* startHandshakingServer((conn) => conn.close(1011));
             const client = makeClient(server.url, { logger });
             yield* Effect.promise(() => connectP(client));
-            const rpcP = sendRpcP(client, "conversations/list", {});
+            const rpcP = sendRpcP(client, ConversationsList, {});
             yield* Effect.promise(() => expect(rpcP).rejects.toThrow(/WebSocket not connected/));
             // Logger captured the WebSocket error (warn level).
             expect(logger.warn).toHaveBeenCalled();
@@ -541,40 +581,19 @@ describe("sendRpc(RpcDefinition, params) — typed manifest overload", () => {
     it("uses definition.name as the wire-level method string", async () => {
         await withTestServer(Effect.gen(function* () {
             const { AgentsLookupByName } = yield* Effect.promise(() => import("@moltzap/protocol"));
-            // Echo the method name + params back as the result so the test can
-            // verify both the wire-level method and the forwarded params.
-            const server = yield* startHandshakingServer((conn, _raw, frame) => conn.send(JSON.stringify({
-                jsonrpc: "2.0",
-                type: "response",
-                direction: "c2s",
-                id: frame.id,
-                result: {
-                    echoedMethod: frame.method,
-                    echoedParams: frame.params,
-                    agents: [],
-                },
-            })));
-            const client = makeClient(server.url);
-            yield* Effect.promise(() => connectP(client));
-            const result = (yield* Effect.promise(() => Effect.runPromise(client.sendRpc(AgentsLookupByName, { names: ["alice"] }))));
-            expect(result.echoedMethod).toBe("agents/lookupByName");
-            expect(result.echoedParams).toEqual({ names: ["alice"] });
-            yield* closeClient(client);
-        }));
-    });
-    it("preserves the legacy string overload for back-compat", async () => {
-        await withTestServer(Effect.gen(function* () {
-            const server = yield* startHandshakingServer((conn, _raw, frame) => conn.send(JSON.stringify({
-                jsonrpc: "2.0",
-                type: "response",
-                direction: "c2s",
-                id: frame.id,
-                result: { echoedMethod: frame.method, agents: [] },
-            })));
+            const captured = { current: null };
+            const server = yield* startHandshakingServer((conn, _raw, frame) => Effect.gen(function* () {
+                captured.current = frame;
+                yield* conn.send(JSON.stringify(responseFrame(frame.id, {
+                    result: { agents: [] },
+                })));
+            }));
             const client = makeClient(server.url);
             yield* Effect.promise(() => connectP(client));
-            const result = (yield* Effect.promise(() => sendRpcP(client, "agents/lookupByName", { names: ["bob"] })));
-            expect(result.echoedMethod).toBe("agents/lookupByName");
+            const result = yield* Effect.promise(() => Effect.runPromise(client.sendRpc(AgentsLookupByName, { names: ["alice"] })));
+            expect(result.agents).toEqual([]);
+            expect(captured.current?.method).toBe(AgentsLookupByName.name);
+            expect(captured.current?.params).toEqual({ names: ["alice"] });
             yield* closeClient(client);
         }));
     });
@@ -673,55 +692,49 @@ describe("spec #222 §5.4 — onDisconnect close metadata (V7)", () => {
 });
 // ─────────────────────────────────────────────────────────────────────
 // Phase 1.0 (B.1) gating tests — client-side server-initiated RPC
-// (handleServerRpc + dispatcher fiber + s2c response write-back)
+// (handleServerRpc + dispatcher fiber + appCallback response write-back)
 // ─────────────────────────────────────────────────────────────────────
 describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
-    it("dispatches an inbound s2c request to the registered handler and writes the response back", async () => {
+    it("dispatches an inbound appCallback request to the registered handler and writes the response back", async () => {
         await withTestServer(Effect.gen(function* () {
             // Server: auto-handshake; immediately AFTER replying to
-            // auth/connect, send an s2c request to the client; capture every
+            // auth/connect, send an appCallback request to the client; capture every
             // subsequent inbound frame the client writes back. We're testing
             // the client's dispatcher fiber + handler registry + response
             // encoding.
             const server = yield* startTestServer((conn, raw) => Effect.gen(function* () {
-                const frame = JSON.parse(raw);
-                if (frame.method === "auth/connect") {
-                    yield* conn.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "response",
-                        direction: "c2s",
-                        id: frame.id,
-                        result: { agentId: "agent-xyz", protocol: PROTOCOL_VERSION },
-                    }));
-                    // Fire the s2c request straight after auth response. The
+                const parsed = JSON.parse(raw);
+                if (!validators.requestFrame(parsed)) {
+                    return yield* Effect.die("expected JSON-RPC request frame");
+                }
+                const frame = parsed;
+                if (frame.method === Connect.name) {
+                    yield* conn.send(JSON.stringify(responseFrame(frame.id, {
+                        result: helloOk(),
+                    })));
+                    // Fire the appCallback request straight after auth response. The
                     // client's dispatcher fiber was forked into the connect
                     // scope BEFORE auth/connect was sent, so the inbound queue
                     // is live the moment we land here.
-                    yield* conn.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "request",
-                        direction: "s2c",
-                        id: "srv-test-1",
-                        method: "apps/onJoin",
-                        params: { sessionId: "sess-A" },
-                    }));
+                    yield* conn.send(JSON.stringify(requestFrame(jsonRpcStringId("srv-test-1"), AppsOnJoin, onJoinParams(SESSION_A))));
                 }
             }));
             const client = makeClient(server.url);
             // Register a handler BEFORE connect so the dispatcher fiber sees
-            // it on the very first inbound s2c request.
-            yield* client.handleServerRpc("apps/onJoin", (params) => Effect.succeed({
+            // it on the very first inbound appCallback request.
+            yield* client.handleServerRpc(AppsOnJoin, (params) => Effect.succeed({
                 ack: true,
                 saw: params.sessionId,
             }));
             yield* Effect.promise(() => connectP(client));
             // Wait for the response frame the dispatcher writes back. The
-            // server records every inbound frame in `received` — the s2c
+            // server records every inbound frame in `received` — the appCallback
             // response should appear after the client's auth/connect.
             const responseRaw = yield* Effect.promise(() => waitFor(() => server.connections[0].received.some((r) => {
                 try {
                     const parsed = JSON.parse(r);
-                    return (parsed.type === "response" && parsed.id === "srv-test-1");
+                    return (validators.responseFrame(parsed) &&
+                        parsed.id === "srv-test-1");
                 }
                 catch {
                     return false;
@@ -729,51 +742,44 @@ describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
             }), { maxMs: 2000 })).pipe(Effect.flatMap(() => Effect.sync(() => server.connections[0].received.find((r) => {
                 try {
                     const parsed = JSON.parse(r);
-                    return parsed.id === "srv-test-1";
+                    return (validators.responseFrame(parsed) &&
+                        parsed.id === "srv-test-1");
                 }
                 catch {
                     return false;
                 }
             }))));
             const parsedResponse = JSON.parse(responseRaw);
-            expect(parsedResponse.type).toBe("response");
-            expect(parsedResponse.direction).toBe("s2c");
+            expect(validators.responseFrame(parsedResponse)).toBe(true);
+            if (!validators.responseFrame(parsedResponse))
+                return;
             expect(parsedResponse.id).toBe("srv-test-1");
-            expect(parsedResponse.result.ack).toBe(true);
-            expect(parsedResponse.result.saw).toBe("sess-A");
+            expect("result" in parsedResponse).toBe(true);
+            if (!("result" in parsedResponse))
+                return;
+            const result = parsedResponse.result;
+            expect(result.ack).toBe(true);
+            expect(result.saw).toBe(SESSION_A);
             yield* closeClient(client);
         }));
     });
     it("encodes a typed RpcServerError from the handler as a `response` frame with `error`", async () => {
         await withTestServer(Effect.gen(function* () {
             const server = yield* startTestServer((conn, raw) => Effect.gen(function* () {
-                const frame = JSON.parse(raw);
-                if (frame.method === "auth/connect") {
-                    yield* conn.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "response",
-                        direction: "c2s",
-                        id: frame.id,
-                        result: { agentId: "agent-xyz", protocol: PROTOCOL_VERSION },
-                    }));
-                    yield* conn.send(JSON.stringify({
-                        jsonrpc: "2.0",
-                        type: "request",
-                        direction: "s2c",
-                        id: "srv-err-1",
-                        method: "apps/onClose",
-                        // Spec #356: the partitioned dispatcher
-                        // narrow-validates routing fields; sessionId is
-                        // required for every s2c hook. Synthetic test
-                        // payloads must include it or the dispatcher
-                        // rejects the offer with a `-32602` wire error
-                        // before reaching the handler.
-                        params: { sessionId: "sess-err-1" },
-                    }));
+                const parsed = JSON.parse(raw);
+                if (!validators.requestFrame(parsed)) {
+                    return yield* Effect.die("expected JSON-RPC request frame");
+                }
+                const frame = parsed;
+                if (frame.method === Connect.name) {
+                    yield* conn.send(JSON.stringify(responseFrame(frame.id, {
+                        result: helloOk(),
+                    })));
+                    yield* conn.send(JSON.stringify(requestFrame(jsonRpcStringId("srv-err-1"), AppsOnClose, onCloseParams(SESSION_B))));
                 }
             }));
             const client = makeClient(server.url);
-            yield* client.handleServerRpc("apps/onClose", () => Effect.fail(new RpcServerError({
+            yield* client.handleServerRpc(AppsOnClose, () => Effect.fail(new RpcServerError({
                 code: -32099,
                 message: "domain-rejected",
                 data: { reason: "test" },
@@ -782,7 +788,9 @@ describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
             yield* Effect.promise(() => waitFor(() => server.connections[0].received.some((r) => {
                 try {
                     const parsed = JSON.parse(r);
-                    return (parsed.id === "srv-err-1" && parsed.error !== undefined);
+                    return (validators.responseFrame(parsed) &&
+                        parsed.id === "srv-err-1" &&
+                        "error" in parsed);
                 }
                 catch {
                     return false;
@@ -790,14 +798,20 @@ describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
             }), { maxMs: 2000 }));
             const found = server.connections[0].received.find((r) => {
                 try {
-                    return JSON.parse(r).id === "srv-err-1";
+                    const parsed = JSON.parse(r);
+                    return (validators.responseFrame(parsed) && parsed.id === "srv-err-1");
                 }
                 catch {
                     return false;
                 }
             });
             const parsed = JSON.parse(found);
-            expect(parsed.direction).toBe("s2c");
+            expect(validators.responseFrame(parsed)).toBe(true);
+            if (!validators.responseFrame(parsed))
+                return;
+            expect("error" in parsed).toBe(true);
+            if (!("error" in parsed))
+                return;
             expect(parsed.error.code).toBe(-32099);
             expect(parsed.error.message).toBe("domain-rejected");
             expect(parsed.error.data.reason).toBe("test");
@@ -809,9 +823,9 @@ describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
             serverUrl: "http://127.0.0.1:1",
             agentKey: "test",
         });
-        const first = await Effect.runPromiseExit(client.handleServerRpc("apps/onJoin", () => Effect.succeed({})));
+        const first = await Effect.runPromiseExit(client.handleServerRpc(AppsOnJoin, () => Effect.succeed({})));
         expect(Exit.isSuccess(first)).toBe(true);
-        const second = await Effect.runPromiseExit(client.handleServerRpc("apps/onJoin", () => Effect.succeed({})));
+        const second = await Effect.runPromiseExit(client.handleServerRpc(AppsOnJoin, () => Effect.succeed({})));
         expect(Exit.isFailure(second)).toBe(true);
         if (Exit.isFailure(second)) {
             const err = Cause.failureOption(second.cause);
@@ -826,7 +840,7 @@ describe("Phase 1.0 (B.1) — handleServerRpc round-trip", () => {
 // ─────────────────────────────────────────────────────────────────────
 // Regression gate (review-295): runSync(client.close()) and
 // runSync(client.disconnect()) must not throw AsyncFiberException after
-// the s2c queue + dispatcher were added. The s2c machinery lives off the
+// the appCallback queue + dispatcher were added. The appCallback machinery lives off the
 // per-connect Scope (allocated inline + forked via runtime.runFork) so
 // `Scope.close` stays sync; teardown of the queue and dispatcher fiber
 // is dispatched via `runFork` from close()/disconnectSync().