effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/rpc/RpcMessage.ts

@@ -1,20 +1,38 @@
 /**
- * Defines the protocol message envelopes shared by unstable RPC clients,
- * servers, and transports.
+ * Message envelopes shared by unstable RPC clients, servers, serializers, and
+ * transports.
  *
- * This module is used when implementing or testing RPC transports, codecs, and
- * protocol handlers. It separates decoded messages, which carry typed RPC tags,
- * payloads, headers, exits, and branded request identifiers, from encoded
- * messages, which are suitable for transport boundaries where request ids and
- * payloads have already been serialized.
+ * `RpcMessage` is the protocol vocabulary below `RpcClient` and `RpcServer`.
+ * It defines decoded messages for in-process channels and encoded messages for
+ * transport boundaries, so custom protocols can move the same request,
+ * streaming, acknowledgement, interrupt, keepalive, and defect signals as the
+ * built-in HTTP, socket, worker, and test transports.
  *
- * Request identifiers are the correlation point for requests, response chunks,
- * terminal exits, acknowledgements, and interrupts, so transports must preserve
- * them across the encoded string form and the decoded branded form. Streaming
- * responses can send one or more `Chunk` batches before a terminal `Exit`; use
- * `Ack` messages only for transports that require backpressure, treat `Eof` as
- * the end of client input, and reserve `Ping`/`Pong` for connection liveness
- * rather than RPC completion.
+ * **Mental model**
+ *
+ * A request is identified by a `RequestId` from the first `Request` through any
+ * `Chunk` batches, the terminal `Exit`, optional `Ack`s, and optional
+ * `Interrupt`s. Decoded messages carry branded ids, typed RPC tags, headers,
+ * and typed payload, chunk, or exit values. Encoded messages use string ids and
+ * `unknown` payloads that have already crossed the schema serialization
+ * boundary.
+ *
+ * **Message families**
+ *
+ * Client-to-server messages start work (`Request`), acknowledge streamed chunks
+ * (`Ack`), cancel in-flight work (`Interrupt`), close client input (`Eof`), or
+ * check liveness (`Ping`). Server-to-client messages stream successful values
+ * (`Chunk`), complete work (`Exit`), report connection-level defects
+ * (`Defect`), end a client connection (`ClientEnd`), answer keepalives
+ * (`Pong`), or report client protocol errors.
+ *
+ * **Gotchas**
+ *
+ * `Ack` is part of streaming back pressure, not call completion. `Eof` closes
+ * client input but does not replace terminal `Exit` responses. `Ping` and
+ * `Pong` are connection liveness messages. Transports must preserve request ids
+ * exactly across encoded strings and decoded branded values, or responses,
+ * interrupts, and acknowledgements can be routed to the wrong in-flight call.
  *
  * @since 4.0.0
  */
@@ -164,7 +182,7 @@ export interface Ping {
 }
 
 /**
- * The reusable `Eof` message value.
+ * Represents the reusable `Eof` message value.
  *
  * @category request
  * @since 4.0.0
@@ -172,7 +190,7 @@ export interface Ping {
 export const constEof: Eof = { _tag: "Eof" }
 
 /**
- * The reusable `Ping` message value.
+ * Represents the reusable `Ping` message value.
  *
  * @category request
  * @since 4.0.0
@@ -207,7 +225,7 @@ export type FromServerEncoded =
 /**
  * The brand identifier used by the `ResponseId` type.
  *
- * @category response
+ * @category type IDs
  * @since 4.0.0
  */
 export const ResponseIdTypeId = "~effect//rpc/RpcServer/ResponseId"
@@ -215,7 +233,7 @@ export const ResponseIdTypeId = "~effect//rpc/RpcServer/ResponseId"
 /**
  * The literal type of the `ResponseId` brand identifier.
  *
- * @category response
+ * @category type IDs
  * @since 4.0.0
  */
 export type ResponseIdTypeId = typeof ResponseIdTypeId
@@ -402,7 +420,7 @@ export interface Pong {
 }
 
 /**
- * The reusable `Pong` message value.
+ * Represents the reusable `Pong` message value.
  *
  * @category response
  * @since 4.0.0

package/src/unstable/rpc/RpcMiddleware.ts

@@ -1,29 +1,39 @@
 /**
- * The `RpcMiddleware` module defines middleware services that can wrap RPC
- * handler execution on the server and request execution in generated clients.
+ * Middleware services for the unstable RPC runtime.
  *
- * Use middleware to attach cross-cutting behavior to individual RPCs or whole
- * `RpcGroup`s, such as authentication, authorization, request logging, tracing,
- * metrics, rate limiting, header propagation, or adding request-scoped services
- * to the handler context. A middleware service records the services it requires
- * and provides, the schema for errors it can fail with, and whether clients must
- * install a matching middleware via `layerClient`.
+ * A middleware service wraps server handler execution and can also install a
+ * client-side wrapper for generated clients. Its metadata records the services
+ * provided to downstream handlers, the services required by the middleware
+ * implementation, the schema for server-visible failures, the client-only error
+ * type, and whether generated clients must require the matching client layer.
  *
- * Server middleware receives the target `rpc`, decoded `payload`, request
- * `headers`, `requestId`, and `Rpc.ServerClient`, then wraps the handler effect.
- * Its `provides` type removes services from the downstream handler requirement,
- * while `requires` adds the services needed by the middleware implementation.
- * Middleware errors must be declared with a `Schema` so they can be encoded as
- * RPC failures, and any schema encoding or decoding services remain part of the
- * generated RPC environments.
+ * **Mental model**
  *
- * Client middleware is installed with `layerClient`, captures the surrounding
- * layer context, and can inspect, rewrite, retry, or short-circuit outgoing
- * requests before calling `next`. Set `requiredForClient` when an RPC's typed
- * client must require that `ForClient` layer; otherwise a client implementation
- * is used only when one is present. `clientError` contributes only to the
+ * A server {@link RpcMiddleware} receives the target RPC, decoded payload,
+ * request headers, request id, and `Rpc.ServerClient`, then wraps the handler
+ * effect. `provides` removes services from the downstream handler requirement,
+ * while `requires` adds the services needed by the middleware. A client
+ * {@link RpcMiddlewareClient} is installed with {@link layerClient}; it can
+ * inspect, rewrite, retry, or short-circuit outgoing requests before calling
+ * `next`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link Service} to define authentication, authorization, logging,
+ * tracing, metrics, rate limiting, header propagation, or request-scoped
+ * service injection. Attach the service to individual RPCs or whole groups,
+ * then provide the server implementation like any other `Context.Service`.
+ * Provide a client implementation with {@link layerClient} when outgoing
+ * requests need matching behavior.
+ *
+ * **Gotchas**
+ *
+ * Middleware failures that cross the RPC boundary must be declared with a
+ * `Schema`, and any encoding or decoding services required by that schema stay
+ * in the generated RPC environments. `clientError` contributes only to the
  * client-side call error channel, while the middleware `error` schema is shared
- * with server failures.
+ * with server failures. Set `requiredForClient` only when typed clients must
+ * reject calls unless the matching client middleware layer is installed.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcSchema.ts

@@ -1,26 +1,36 @@
 /**
- * The `RpcSchema` module contains the RPC-specific schema markers and cause
- * annotations shared by the RPC declaration, client, and server layers. It is
- * used when an RPC response is a `Stream`, and when server-side interruption
- * logic needs to identify a client-initiated abort.
+ * RPC schema markers and interruption annotations.
  *
- * Use {@link Stream} to mark an RPC success schema as a streamed response,
- * {@link isStreamSchema} to detect that marker, and the stored success and
- * error schemas to encode or decode stream chunks. Request payload schemas live
- * on the `Rpc` definition itself; this module only describes the streamed
- * response shape. For streaming RPCs, the success schema passed to
- * `RpcSchema.Stream` is the stream element schema, while the error schema is
- * the stream error schema. When the marker is installed by the `Rpc`
- * constructor's `stream` option, the immediate RPC exit succeeds with `void`,
- * the ordinary RPC error schema is set to `Schema.Never`, and the stream error
- * schema is used for stream failures.
- *
- * Streaming schemas are not general-purpose codecs for arbitrary stream values:
- * they are RPC metadata that lets the protocol distinguish one-shot successes
- * from streamed elements and keep stream errors on the chunk stream. Use
- * {@link ClientAbort} when annotating interruptions caused by a remote client
+ * This module contains the small pieces of schema metadata that the RPC
+ * declaration, client, server, cluster, and reactivity layers share. It marks
+ * streamed responses and annotates interruptions that came from a remote client
  * closing or cancelling a request.
  *
+ * **Mental model**
+ *
+ * A streaming RPC still has a normal RPC exit, but its success schema is marked
+ * with {@link Stream}. The marker stores the stream element schema and the
+ * stream error schema so transports can encode and decode each chunk while
+ * keeping stream failures on the chunk stream.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link Stream} when constructing RPC metadata directly
+ * - Use {@link isStreamSchema} to branch between one-shot and streaming
+ *   responses in protocol implementations
+ * - Read the stored `success` and `error` schemas when encoding or decoding
+ *   stream chunks
+ * - Use {@link ClientAbort} to tag interruptions caused by client disconnects
+ *
+ * **Gotchas**
+ *
+ * - `Rpc.make(..., { stream: true })` installs this marker for you
+ * - For streaming RPCs, the immediate RPC exit succeeds with `void`; stream
+ *   elements and stream errors are encoded separately
+ * - Request payload schemas live on the `Rpc` definition, not in this module
+ * - `Stream` is RPC metadata, not a general-purpose codec for arbitrary
+ *   `Stream` values
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"
@@ -95,7 +105,7 @@ export function Stream<A extends Schema.Top, E extends Schema.Top>(success: A, e
 }
 
 /**
- * Cause annotation used to mark interruptions that originate from an RPC client
+ * Annotation that marks interruptions that originate from an RPC client
  * abort.
  *
  * @category Cause annotations

package/src/unstable/rpc/RpcSerialization.ts

@@ -1,27 +1,37 @@
 /**
  * Serialization support for the unstable RPC protocol.
  *
- * This module provides the `RpcSerialization` service used by RPC clients and
- * servers to encode and decode transport-level `RpcMessage` envelopes. Use the
- * built-in JSON, newline-delimited JSON, JSON-RPC 2.0, and MessagePack
- * implementations when wiring HTTP, sockets, workers, or custom transports, or
- * provide a custom service when a transport needs a different content type,
- * frame format, or binary codec.
+ * `RpcSerialization` is the boundary between encoded RPC protocol messages and
+ * the bytes or strings carried by a transport. RPC clients and servers use the
+ * service to turn `RpcMessage` envelopes into JSON, newline-delimited JSON,
+ * JSON-RPC 2.0, or MessagePack payloads, and to parse those payloads back into
+ * protocol messages.
  *
- * Serialization runs after RPC schemas have encoded payloads, successes,
- * failures, and stream chunks into transport-safe values, and before schemas
- * decode those values on the other side. Choose a format that can represent the
- * schema-encoded data: JSON is easy to inspect but needs schema encodings for
- * arbitrary binary values, while MessagePack is more compact and carries binary
- * data more naturally.
+ * **Mental model**
  *
- * Transport framing is significant. `json` and `jsonRpc` expect a complete
- * payload for each decode call and are intended for transports such as HTTP
- * that already delimit message bodies. `ndjson`, `ndJsonRpc`, and `msgPack`
- * maintain parser state for chunked streams, so they can decode multiple
- * messages or incomplete fragments from sockets and other streaming transports.
- * Match the serialization layer to the transport boundary, otherwise messages
- * may be buffered, split, or parsed at the wrong frame.
+ * RPC schemas are responsible for encoding payloads, successes, failures, and
+ * stream chunks into transport-safe values. This module then chooses how those
+ * values are represented on the wire and whether message boundaries are part of
+ * that representation. The parser returned by `makeUnsafe` may be stateful, so
+ * transports should create a parser for the lifetime of the stream, connection,
+ * or request body they are decoding.
+ *
+ * **Common tasks**
+ *
+ * Use `layerJson` or `layerJsonRpc` when the transport already frames each
+ * payload, such as ordinary HTTP request and response bodies. Use
+ * `layerNdjson`, `layerNdJsonRpc`, or `layerMsgPack` for sockets, workers, and
+ * other streaming transports that can receive partial chunks or several
+ * messages in one chunk. Provide a custom `RpcSerialization` service when a
+ * transport requires a different content type, frame format, or binary codec.
+ *
+ * **Gotchas**
+ *
+ * Both ends of the connection must use compatible serialization and framing.
+ * `json` and `jsonRpc` expect a complete payload for each decode call, while
+ * `ndjson`, `ndJsonRpc`, and `msgPack` keep parser state for incomplete input.
+ * JSON is easy to inspect but needs schema encodings for arbitrary binary
+ * values; MessagePack is more compact and carries binary data more naturally.
  *
  * @since 4.0.0
  */
@@ -33,10 +43,15 @@ import { hasProperty } from "../../Predicate.ts"
 import type * as RpcMessage from "./RpcMessage.ts"
 
 /**
- * Service describing how RPC protocol messages are encoded and decoded,
+ * Service that describes how RPC protocol messages are encoded and decoded,
  * including the content type and whether the serialization format provides
  * message framing.
  *
+ * **When to use**
+ *
+ * Use to provide the serialization boundary shared by RPC clients and servers
+ * for a chosen wire format.
+ *
  * @category serialization
  * @since 4.0.0
  */
@@ -82,7 +97,7 @@ export const json: RpcSerialization["Service"] = RpcSerialization.of({
 })
 
 /**
- * Newline-delimited JSON RPC serialization that frames each protocol message
+ * Serializes RPC protocol messages as newline-delimited JSON, framing each message
  * with a trailing newline.
  *
  * @category serialization
@@ -495,12 +510,13 @@ export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerializ
 export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: true })
 
 /**
- * A rpc serialization layer that uses JSON for serialization.
+ * RPC serialization layer that uses JSON for serialization.
  *
  * **When to use**
  *
- * Use this if your protocol supports framing for messages, otherwise use
- * {@link layerNdjson}.
+ * Use when the transport protocol already provides message framing.
+ *
+ * @see {@link layerNdjson} for transports that need newline-delimited framing
  *
  * @category serialization
  * @since 4.0.0
@@ -508,12 +524,13 @@ export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: tr
 export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(json)
 
 /**
- * A rpc serialization layer that uses NDJSON for serialization.
+ * RPC serialization layer that uses NDJSON for serialization.
  *
  * **When to use**
  *
- * Use this if your protocol does not support framing for messages, otherwise
- * use {@link layerJson}.
+ * Use when the transport protocol does not provide message framing.
+ *
+ * @see {@link layerJson} for transports that already provide message framing
  *
  * @category serialization
  * @since 4.0.0
@@ -521,7 +538,7 @@ export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSeriali
 export const layerNdjson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(ndjson)
 
 /**
- * A rpc serialization layer that uses JSON-RPC for serialization.
+ * RPC serialization layer that uses JSON-RPC for serialization.
  *
  * @category serialization
  * @since 4.0.0
@@ -531,8 +548,8 @@ export const layerJsonRpc = (options?: {
 }): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(jsonRpc(options))
 
 /**
- * A rpc serialization layer that uses JSON-RPC for serialization seperated by
- * new lines.
+ * RPC serialization layer that uses newline-delimited JSON-RPC for
+ * serialization.
  *
  * @category serialization
  * @since 4.0.0
@@ -542,7 +559,7 @@ export const layerNdJsonRpc = (options?: {
 }): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(ndJsonRpc(options))
 
 /**
- * A rpc serialization layer that uses MessagePack for serialization.
+ * RPC serialization layer that uses MessagePack for serialization.
  *
  * **Details**
  *

package/src/unstable/rpc/RpcServer.ts

@@ -1,33 +1,41 @@
 /**
- * Server-side support for running RPCs defined in an `RpcGroup`.
+ * Server-side runtime for RPC groups.
  *
- * This module connects typed RPC handlers to an encoded or already-decoded
- * transport, decodes client requests, invokes the matching handler, and sends
- * exits, stream chunks, defects, interrupts, and client-end notifications back
- * through the active server protocol. Use it to expose an RPC group through
- * `layerHttp`, standalone HTTP effects, websocket or socket servers, stdio,
- * worker runners, or a custom `Protocol`; use `makeNoSerialization` when the
- * surrounding system already owns message serialization.
+ * This module connects typed handlers for an RPC group to a transport. It
+ * receives client messages, decodes request payloads, runs the matching
+ * handler, and writes exits, stream chunks, defects, interrupts, and client-end
+ * notifications back through the active server protocol. It supports encoded
+ * protocols such as HTTP, websocket, socket, stdio, and worker transports, plus
+ * already-decoded channels through {@link makeNoSerialization}.
  *
- * The `Protocol` service is the transport boundary. It declares how encoded
- * client messages are received and how encoded responses are written, plus
- * whether the transport supports stream acknowledgements, transferable
- * objects, and span propagation. HTTP request/response serving is useful for
- * simple calls and response streaming, but it does not provide client
- * acknowledgements or span propagation; websocket, socket, stdio, and worker
- * protocols keep a live channel and can participate in the streaming
- * acknowledgement lifecycle.
+ * **Mental model**
  *
- * **Handler gotchas**
+ * {@link Protocol} is the transport boundary. It owns how encoded client
+ * messages arrive, how encoded server responses are written, and whether the
+ * channel supports acknowledgements, transferable objects, or span
+ * propagation. {@link make} and {@link layer} combine that protocol with an RPC
+ * group and the handler context required by `Rpc.ToHandler` and
+ * `Rpc.Middleware`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerHttp} for route-mounted HTTP or websocket serving,
+ * {@link toHttpEffect} and {@link toHttpEffectWebsocket} for standalone HTTP
+ * effects, the `layerProtocol*` constructors for socket, stdio, or worker
+ * transports, and {@link makeNoSerialization} when another component already
+ * owns message serialization.
+ *
+ * **Gotchas**
  *
  * - Server handlers are looked up from `Rpc.ToHandler`, while RPC middleware
- *   is looked up from `Rpc.Middleware` and wraps the handler with metadata
- *   containing the `Rpc.ServerClient`, request id, headers, and decoded payload
- * - Payloads are decoded on the server and exits, stream chunks, and request
+ *   is looked up from `Rpc.Middleware` and wraps handlers with metadata that
+ *   includes `Rpc.ServerClient`, request id, headers, and decoded payload
+ * - Payloads are decoded on the server; exits, stream chunks, and request
  *   defects are encoded on the server using the RPC schemas and the handler's
- *   schema services; encode failures are reported as request defects and the
- *   in-flight request is interrupted
- * - Streaming RPCs send chunks before the final exit, and transports with
+ *   schema services
+ * - Encode failures are reported as request defects and interrupt the
+ *   in-flight request
+ * - Streaming RPCs send chunks before the final exit, and protocols with
  *   acknowledgement support wait for client acknowledgements between chunks to
  *   provide back pressure
  * - Fatal handler defects are sent as protocol defects by default; set
@@ -810,7 +818,7 @@ export const layer = <Rpcs extends Rpc.Any>(
  * Defaults to using websockets for communication, but can be configured to use
  * HTTP.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerHttp = <Rpcs extends Rpc.Any>(options: {
@@ -840,11 +848,16 @@ export const layerHttp = <Rpcs extends Rpc.Any>(options: {
   )
 
 /**
- * Service interface for an RPC server transport, responsible for receiving
+ * Defines the service interface for an RPC server transport, responsible for receiving
  * encoded client messages, sending encoded responses, tracking clients, and
  * declaring transport capabilities.
  *
- * @category protocol
+ * **When to use**
+ *
+ * Use to provide the transport boundary for RPC servers over HTTP, WebSocket,
+ * workers, sockets, or custom protocols.
+ *
+ * @category protocols
  * @since 4.0.0
  */
 export class Protocol extends Context.Service<
@@ -879,7 +892,7 @@ export class Protocol extends Context.Service<
  * Creates a server `Protocol` backed by the current `SocketServer`, accepting
  * socket connections and routing decoded RPC messages.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolSocketServer = Effect.gen(function*() {
@@ -892,9 +905,9 @@ export const makeProtocolSocketServer = Effect.gen(function*() {
 })
 
 /**
- * A rpc protocol that uses `SocketServer` for communication.
+ * RPC protocol that uses `SocketServer` for communication.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolSocketServer: Layer.Layer<
@@ -907,7 +920,7 @@ export const layerProtocolSocketServer: Layer.Layer<
  * Creates a websocket server `Protocol` together with an HTTP effect that
  * upgrades the current request to a websocket and attaches it to the protocol.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWithHttpEffectWebsocket: Effect.Effect<
@@ -942,7 +955,7 @@ export const makeProtocolWithHttpEffectWebsocket: Effect.Effect<
  * Creates a websocket server `Protocol` and registers its upgrade handler as a
  * GET route on the current `HttpRouter`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWebsocket: (options: {
@@ -959,9 +972,9 @@ export const makeProtocolWebsocket: (options: {
 })
 
 /**
- * A rpc protocol that uses websockets for communication.
+ * RPC protocol that uses WebSockets for communication.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolWebsocket = (options: {
@@ -979,7 +992,7 @@ export const layerProtocolWebsocket = (options: {
  * effect that decodes the current request and streams or returns encoded RPC
  * responses.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWithHttpEffect: Effect.Effect<
@@ -1146,7 +1159,7 @@ const mergeUint8Arrays = (arrays: ReadonlyArray<Uint8Array>) => {
  * Creates an HTTP server `Protocol` and registers its request handler as a POST
  * route on the current `HttpRouter`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolHttp: (options: {
@@ -1166,7 +1179,7 @@ export const makeProtocolHttp: (options: {
  * Provides a server `Protocol` that uses HTTP POST requests for RPC
  * communication.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
@@ -1261,7 +1274,7 @@ export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
  * Creates a server `Protocol` that reads RPC messages from `Stdio.stdin` and
  * writes encoded responses to `Stdio.stdout`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolStdio = Effect.gen(function*() {
@@ -1322,7 +1335,7 @@ export const makeProtocolStdio = Effect.gen(function*() {
  * Provides a server `Protocol` that reads RPC messages from `Stdio.stdin` and
  * writes encoded responses to `Stdio.stdout`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolStdio: Layer.Layer<
@@ -1335,7 +1348,7 @@ export const layerProtocolStdio: Layer.Layer<
  * Creates a server `Protocol` backed by `WorkerRunnerPlatform`, routing worker
  * messages to the RPC server and server responses back to workers.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWorkerRunner: Effect.Effect<
@@ -1393,7 +1406,7 @@ export const makeProtocolWorkerRunner: Effect.Effect<
 /**
  * Provides a server `Protocol` backed by the current `WorkerRunnerPlatform`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolWorkerRunner: Layer.Layer<

package/src/unstable/rpc/RpcTest.ts

@@ -1,19 +1,35 @@
 /**
- * Utilities for testing RPC groups without opening a network transport.
+ * In-memory test harness for RPC groups.
  *
- * This module connects a generated RPC client directly to an in-memory
- * `RpcServer` for the same group, using the group's handlers from the Effect
- * environment and the no-serialization message path. It is intended for tests
- * that need to exercise client calls, server handlers, middleware, request
- * routing, and streaming behavior without standing up HTTP, sockets, workers,
- * or a serializer.
+ * `RpcTest` connects a generated client directly to `RpcServer` handlers for
+ * the same `RpcGroup`. It uses the no-serialization path, so requests,
+ * responses, stream chunks, acknowledgements, interrupts, headers, and
+ * middleware metadata travel through the normal client/server machinery without
+ * opening HTTP, socket, worker, or serializer infrastructure.
  *
- * Because messages stay decoded in memory, this module is not a substitute for
- * transport or schema-encoding tests. Callers still need to provide the handler
- * layer, any client/server middleware services, and a `Scope`; the returned
- * client is scoped to that in-memory connection. The `flatten` option follows
- * `RpcClient.makeNoSerialization`, and acknowledgements are enabled to match
- * the normal bidirectional client/server protocol used by the test harness.
+ * **Mental model**
+ *
+ * `makeClient` builds an in-memory server, wires the client and server write
+ * callbacks together, and returns the scoped generated client. The handlers,
+ * server middleware, client middleware, and `Scope` still come from the Effect
+ * environment just as they would for a real transport; only the byte-level
+ * protocol is skipped.
+ *
+ * **Common tasks**
+ *
+ * Use this module for tests that should exercise RPC routing, handler lookup,
+ * middleware, headers, typed errors, interruptions, and streaming behavior
+ * quickly. Use a real transport plus `RpcSerialization` coverage when you need
+ * to test HTTP status handling, socket framing, worker transferables, schema
+ * encoding or decoding, or wire compatibility.
+ *
+ * **Gotchas**
+ *
+ * Because no serialization happens, invalid wire payloads and mismatched codecs
+ * will not be discovered here. The client is scoped to the in-memory
+ * connection; acquire it inside a scoped test or provide `Scope` explicitly.
+ * The `flatten` option matches `RpcClient.makeNoSerialization`, and
+ * acknowledgements are enabled to mirror the bidirectional streaming protocol.
  *
  * @since 4.0.0
  */