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

package/src/unstable/reactivity/index.ts

@@ -5,207 +5,41 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * The `AsyncResult` module models the state of an asynchronous value inside the
- * reactivity APIs. It represents whether a computation has not produced a
- * result yet, has succeeded, or has failed, while keeping `waiting` as a
- * separate flag for first loads, refreshes, retries, and other in-flight work.
- *
- * This is useful for atoms and UI integrations that need to render async
- * queries, background refreshes, optimistic transitions, stream pulls, or RPC
- * and HTTP calls without losing track of the current value. `Success` contains
- * the latest value and timestamp, and `Failure` contains a `Cause` plus an
- * optional `previousSuccess` so callers can keep showing stale data after a
- * refresh fails.
- *
- * Treat `waiting` as an overlay rather than a fourth state: an `Initial` result
- * can be waiting with no value, and a `Success` or `Failure` can also be waiting
- * while a newer computation is running. Accessors such as `value` and
- * `getOrElse` may return the previous success stored in a failure, so inspect
- * `cause` or `error` when the difference between a current success and stale
- * data matters. Matchers such as `matchWithWaiting` prioritize the waiting flag,
- * while `match` and `matchWithError` expose the underlying state.
- *
  * @since 4.0.0
  */
 export * as AsyncResult from "./AsyncResult.ts"
 
 /**
- * The `Atom` module defines reactive values and the helpers for constructing,
- * composing, running, and persisting them with an `AtomRegistry`. Atoms are
- * small read functions whose regular `get` reads form a dependency graph, so
- * derived values are cached by the registry and invalidated when their
- * dependencies, writable state, refresh hooks, or subscriptions change.
- *
- * Use atoms for application and UI state, derived data, `Effect` or `Stream`
- * queries exposed as `AsyncResult`, writable function atoms for commands,
- * subscription refs, pull-based streams, optimistic updates, URL search
- * parameters, `KeyValueStore` entries, and serializable or server-specific
- * hydration.
- *
- * The cache belongs to the registry, not the atom object: the same atom can have
- * different values in different registries, and serializable atoms are keyed by
- * their serialization key. Stable atom identity matters for dependency tracking
- * and cache reuse, so use `family` for parameterized atoms. Unobserved atoms are
- * disposed unless kept alive or retained by an idle TTL, which can cause derived
- * state, effects, streams, and finalizers to be rebuilt later. Runtime-backed
- * atoms run effects and streams with the registry scheduler, scope, and
- * `AtomRuntime` layer context; `runtime.withReactivity` only refreshes after
- * explicit `Reactivity` invalidations, while one-shot reads such as `once` do
- * not create dependency edges.
- *
  * @since 4.0.0
  */
 export * as Atom from "./Atom.ts"
 
 /**
- * The `AtomHttpApi` module adapts typed `HttpApi` clients to the unstable atom
- * reactivity runtime. Use it to define a `Context.Service` whose generated HTTP
- * API client is available directly and whose endpoints can also be invoked as
- * atoms: `query` creates an atom of `AsyncResult` for reads, while `mutation`
- * creates an `AtomResultFn` for writes.
- *
- * It is intended for applications that want server state to participate in atom
- * caching, invalidation, and hydration. Queries can be associated with
- * `reactivityKeys` so they refresh when those keys are invalidated, mutations can
- * invalidate the same keys after the request succeeds, and `timeToLive` controls
- * whether idle query atoms expire, stay alive for a duration, or are kept alive.
- *
- * Serialization is schema-based and intentionally limited to decoded values.
- * Mutation atoms are serializable only in `"decoded-only"` mode, while query
- * atoms are serializable only in `"decoded-only"` mode when a stable
- * `serializationKey` is supplied. Choose serialization keys that uniquely
- * identify the endpoint request, keep reactivity keys stable across client and
- * server registries during hydration, and avoid serializing response modes that
- * expose raw `HttpClientResponse` values.
- *
- * The service wraps `HttpApiClient.make`, so the same `HttpApi` definition,
- * schemas, base URL, middleware services, and HTTP client layer must be available
- * wherever the atom runtime is constructed. Use `transformClient` and
- * `transformResponse` for cross-cutting client behavior, and remember that
- * schema or low-level HTTP client failures are raised as defects while endpoint
- * and middleware failures remain typed errors.
- *
  * @since 4.0.0
  */
 export * as AtomHttpApi from "./AtomHttpApi.ts"
 
 /**
- * Mutable reactive references for local, in-memory state that should be read,
- * updated, and observed without going through an `AtomRegistry`.
- *
- * `AtomRef` is useful for small state models, form-like state, and collections
- * of item references where callers need direct mutation methods together with
- * subscriptions. A ref exposes its current `value`, notifies subscribers after
- * `set` or `update`, can derive read-only views with `map`, and can focus on
- * nested object or array properties with `prop`.
- *
- * Notifications are equality-aware: setting a value that is `Equal.equals` to
- * the current value is ignored, and mapped or property subscriptions only emit
- * when their derived value changes. Mutate state through `set`, `update`, or a
- * property ref so subscribers are notified; direct mutation of the stored value
- * does not notify listeners. Collection subscribers are notified when items are
- * inserted, removed, or when an item ref changes, while `toArray` returns the
- * current raw item values.
- *
  * @since 4.0.0
  */
 export * as AtomRef from "./AtomRef.ts"
 
 /**
- * The `AtomRegistry` module provides the runtime cache used by reactivity
- * atoms. A registry owns the node graph for a group of atoms, stores their
- * current values, records parent/child dependencies while atoms are read, and
- * coordinates writes, refreshes, stream conversions, and node disposal.
- *
- * Create a registry directly with {@link make} or provide it with {@link layer}
- * or {@link layerOptions} when a UI root, request, test, or other Effect scope
- * needs its own atom state. The same atom can have different cached values in
- * different registries, while serializable atoms are keyed by their
- * serialization key so preloaded values can hydrate a node before its first
- * read.
- *
- * Subscriptions and {@link mount} keep nodes alive and must be released when
- * the consumer is done; scoped helpers install finalizers for this. Unobserved
- * non-`keepAlive` atoms may be removed immediately or after their `idleTTL` (or
- * the registry `defaultIdleTTL`), which means later reads can rebuild derived
- * state. Disposing a registry clears its cache and makes future atom access an
- * error.
- *
  * @since 4.0.0
  */
 export * as AtomRegistry from "./AtomRegistry.ts"
 
 /**
- * The `AtomRpc` module connects typed RPC clients to the atom reactivity
- * runtime. It builds a `Context.Service` that exposes the flattened
- * `RpcClient`, an `AtomRuntime`, mutation helpers, and query helpers for every
- * RPC in an `RpcGroup`.
- *
- * Use it when remote read models should be represented as atoms, mutations
- * should refresh affected reads through `Reactivity` keys, or non-streaming
- * query results need serialization metadata for hydration. The RPC `protocol`
- * layer supplies the transport, and may be static or derived from the current
- * atom context, so request headers, transport dependencies, and client
- * middleware remain part of the normal Effect environment.
- *
- * Non-streaming queries produce atoms of `AsyncResult` values. Supplying a
- * `serializationKey` marks those query atoms as serializable using codecs
- * derived from the RPC success schema and the combined RPC, middleware, and
- * client error schemas; choose stable, unique keys when dehydrating. Streaming
- * RPCs produce writable pull atoms instead, so callers advance the stream by
- * writing to the atom and should not expect serialization metadata. Query family
- * caching includes the payload, normalized headers, reactivity keys, TTL, and
- * serialization key, so use stable values for those inputs when atom identity
- * matters.
- *
  * @since 4.0.0
  */
 export * as AtomRpc from "./AtomRpc.ts"
 
 /**
- * Utilities for moving serializable reactivity state between atom registries.
- *
- * `dehydrate` snapshots atoms marked with `Atom.serializable` from an
- * `AtomRegistry`, preserving their serialization keys, encoded values, and
- * dehydration time so another registry can preload the same state with `hydrate`.
- * This is useful for server rendering, browser bootstrapping, route transitions,
- * and other handoffs where a registry should start from values that were already
- * computed elsewhere.
- *
- * Only serializable atoms are included, and the receiving registry needs atoms
- * with matching stable keys and compatible schemas. Values crossing a
- * client/server boundary should be the encoded JSON-safe values produced by the
- * atom codecs. The optional `resultPromise` used for `AsyncResult.Initial`
- * handoffs is a live JavaScript promise, so it cannot be sent through JSON and
- * should be omitted or replaced by an application-level streaming protocol when
- * dehydrated state leaves the current runtime.
- *
  * @since 4.0.0
  */
 export * as Hydration from "./Hydration.ts"
 
 /**
- * The `Reactivity` module provides an in-memory service for connecting writes to
- * dependent reads through explicit invalidation keys. It is useful for keeping
- * query results, UI subscriptions, read models, or other derived views fresh
- * after mutations without coupling the writer to every consumer that should
- * rerun.
- *
- * Reads are modeled with {@link query} and {@link stream}: the effect runs once
- * immediately and then runs again whenever one of its keys is invalidated.
- * Writes can use {@link mutation} to invalidate keys only after the wrapped
- * effect succeeds, or call {@link invalidate} directly. Keys may be supplied as
- * a flat collection or as a record of namespaces with ids, which lets callers
- * invalidate both broad groups and individual records.
- *
- * The service tracks handlers by hashed keys and does not cache values by
- * itself; consumers receive fresh queue or stream emissions and decide how to
- * store them. Registrations are tied to the surrounding scope, failures from a
- * query fail the queue or stream, and invalidations that arrive while a query is
- * already running schedule a single follow-up run. Use stable key values, be
- * aware that the default layer is process-local, and use the {@link Reactivity}
- * service when many invalidations should be coalesced until the batch exits.
- *
  * @since 4.0.0
  */
 export * as Reactivity from "./Reactivity.ts"

package/src/unstable/rpc/Rpc.ts

@@ -1,19 +1,30 @@
 /**
- * The `Rpc` module defines the typed declaration for a single remote
- * procedure. An RPC definition is the shared contract used by `RpcGroup`,
- * clients, and servers: it stores the procedure tag, payload schema, success
- * schema, error schema, defect schema, middleware, annotations, and the type
- * information needed to derive client calls and server handler signatures.
- *
- * Use this module to declare request/response procedures with {@link make},
- * build custom constructors that transform success and error schemas with
- * {@link custom}, add middleware or annotations to individual procedures, and
- * derive helper types such as {@link Payload}, {@link Success},
- * {@link Error}, and {@link ToHandlerFn}. Server implementations can also use
- * {@link fork} and {@link uninterruptible} wrappers to control how handler
- * results are executed.
- *
- * **Schema gotchas**
+ * Schema-backed declarations for individual RPC procedures.
+ *
+ * An {@link Rpc} is the shared contract for one remote procedure. It records
+ * the procedure tag, payload schema, success schema, error schema, defect
+ * schema, middleware, annotations, and the type information used to derive
+ * client calls and server handler signatures. The declaration is transport
+ * independent; RPC groups, clients, and servers all read the same metadata.
+ *
+ * **Mental model**
+ *
+ * An RPC definition is data. The tag names the procedure, the schemas describe
+ * the values crossing the wire, and middleware or annotations attach
+ * procedure-local behavior and metadata. Nothing is sent or handled until the
+ * definition is placed in a group and interpreted by a client or server.
+ *
+ * **Common tasks**
+ *
+ * Use {@link make} for ordinary request/response procedures, {@link custom} for
+ * constructors that transform success or error schemas, and the instance
+ * methods on {@link Rpc} to refine payloads, attach middleware, prefix tags, or
+ * add annotations. Helper types such as {@link Payload}, {@link Success},
+ * {@link Error}, and {@link ToHandlerFn} expose the derived TypeScript shapes
+ * used by client and handler code. Server handlers can wrap object results with
+ * {@link fork} or {@link uninterruptible} to control how those results are run.
+ *
+ * **Gotchas**
  *
  * - Payloads default to `Schema.Void`; passing struct fields creates a
  *   `Schema.Struct`, while `primaryKey` creates a payload class with a derived
@@ -21,9 +32,9 @@
  * - Success values default to `Schema.Void`, ordinary errors default to
  *   `Schema.Never`, and middleware errors are included in the effective RPC
  *   error channel
- * - Streaming RPCs store the element and stream error schemas in
- *   `RpcSchema.Stream`; the immediate exit success is `void` and the normal
- *   RPC error schema is set to `Schema.Never`
+ * - Streaming RPCs store element and stream-error schemas in
+ *   `RpcSchema.Stream`; the immediate exit success is `void` and the ordinary
+ *   RPC error schema is `Schema.Never`
  * - Defects use a separate defect schema, defaulting to `Schema.Defect`; custom
  *   defect schemas must not require decoding or encoding services
  * - Schema services are directional: clients encode payloads and decode
@@ -61,7 +72,7 @@ const TypeId = "~effect/rpc/Rpc"
 export const isRpc = (u: unknown): u is Rpc<any, any, any> => Predicate.hasProperty(u, TypeId)
 
 /**
- * A schema for RPC defects.
+ * Schema for RPC defects.
  *
  * **Details**
  *
@@ -191,7 +202,12 @@ export interface Rpc<
 }
 
 /**
- * Server-side metadata for the client associated with an RPC request.
+ * Represents server-side metadata for the client associated with an RPC request.
+ *
+ * **When to use**
+ *
+ * Use to inspect or annotate the connected client while handling an RPC request
+ * on the server.
  *
  * **Details**
  *
@@ -1173,7 +1189,7 @@ const WrapperTypeId = "~effect/rpc/Rpc/Wrapper"
  * `fork` requests concurrent execution, and `uninterruptible` requests
  * uninterruptible execution.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export interface Wrapper<A> {
@@ -1187,7 +1203,7 @@ export interface Wrapper<A> {
  * A value that may be returned directly or wrapped with RPC server execution
  * options.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export type WrapperOr<A> = A | Wrapper<A>
@@ -1195,7 +1211,7 @@ export type WrapperOr<A> = A | Wrapper<A>
 /**
  * Returns `true` when the value is an RPC `Wrapper`.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const isWrapper = (u: object): u is Wrapper<any> => WrapperTypeId in u
@@ -1208,7 +1224,7 @@ export const isWrapper = (u: object): u is Wrapper<any> => WrapperTypeId in u
  * When the value is already wrapped, unspecified options are inherited from the
  * existing wrapper.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const wrap = (options: {
@@ -1234,7 +1250,7 @@ export const wrap = (options: {
  * Returns the wrapped response value when the input is an RPC `Wrapper`, or the
  * input itself when it is already unwrapped.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const unwrap = <A extends object>(value: WrapperOr<A>): A => isWrapper(value) ? value.value : value
@@ -1243,7 +1259,7 @@ export const unwrap = <A extends object>(value: WrapperOr<A>): A => isWrapper(va
  * Maps the value inside an RPC wrapper, preserving wrapper options such as
  * `fork` and `uninterruptible`; unwrapped values are mapped directly.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const wrapMap = <A extends object, B extends object>(self: WrapperOr<A>, f: (value: A) => B): WrapperOr<B> => {
@@ -1254,19 +1270,18 @@ export const wrapMap = <A extends object, B extends object>(self: WrapperOr<A>,
 }
 
 /**
- * You can use `fork` to wrap a response Effect or Stream, to ensure that the
- * response is executed concurrently regardless of the RpcServer concurrency
- * setting.
+ * Wraps a response Effect or Stream so the RPC server executes it concurrently
+ * regardless of the server concurrency setting.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const fork: <A extends object>(value: A) => Wrapper<A> = wrap({ fork: true })
 
 /**
- * You can use `uninterruptible` to wrap a response Effect or Stream, to ensure that it is run in an uninterruptible region.
+ * Wraps a response Effect or Stream so the RPC server runs it in an uninterruptible region.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const uninterruptible: <A extends object>(value: A) => Wrapper<A> = wrap({ uninterruptible: true })

package/src/unstable/rpc/RpcClient.ts

@@ -1,29 +1,38 @@
 /**
- * Client-side support for calling RPCs defined in an `RpcGroup`.
+ * Client-side runtime for typed RPC calls.
  *
- * This module derives typed client APIs from RPC definitions, turns method
- * calls into request messages, and routes server responses back to the waiting
- * `Effect` or `Stream`. Use it to construct schema-aware clients over the
- * provided HTTP, socket, and worker transports, or use `makeNoSerialization`
- * when an already-decoded message channel should participate in the same
- * request, interruption, acknowledgement, and streaming lifecycle.
+ * This module turns RPC definitions from an `RpcGroup` into callable client
+ * methods. Each method encodes its payload, sends a request through the active
+ * transport, and routes the matching server response back to the waiting
+ * `Effect` or `Stream`.
  *
- * The `make` constructor requires a `Protocol`, which owns the encoded
- * transport. HTTP sends one request per call and does not support client
- * acknowledgements, while socket and worker protocols keep receive loops alive,
- * support streaming acknowledgements, and can fail in-flight requests with
- * protocol errors. Streaming RPCs return `Stream`s by default, or scoped
- * queues when `asQueue` is enabled, so `streamBufferSize` controls the client
- * side of streaming back pressure.
+ * **Mental model**
  *
- * Payloads, exits, and stream chunks are encoded and decoded through the RPC
- * schemas with the active `RpcSerialization`; any schema services required by
- * those codecs remain part of the generated client method environments.
- * Client middleware declared on an RPC is looked up from
- * `Rpc.MiddlewareClient`, can rewrite or short-circuit outgoing requests, and
- * contributes its client error type to the call signature. Outgoing request
- * headers combine `CurrentHeaders` with per-call headers before the request is
- * passed through middleware and then to the transport.
+ * `make` builds a schema-aware client on top of a client `Protocol`. The
+ * protocol owns the encoded transport boundary: HTTP sends one request per
+ * call, while socket and worker protocols keep receive loops alive for
+ * streaming, acknowledgements, interruption, and protocol-level failures.
+ * `makeNoSerialization` keeps the same request lifecycle when another layer has
+ * already decoded messages.
+ *
+ * **Common tasks**
+ *
+ * - Build a typed client with {@link make} and a provided protocol layer
+ * - Use {@link makeNoSerialization} for in-process or already-decoded channels
+ * - Provide HTTP, socket, or worker transports with {@link layerProtocolHttp},
+ *   {@link layerProtocolSocket}, or {@link layerProtocolWorker}
+ * - Add request headers with {@link withHeaders} or per-call options
+ *
+ * **Gotchas**
+ *
+ * HTTP does not support client acknowledgements, so streaming back pressure is
+ * only available on protocols that keep a live channel. Streaming RPCs return
+ * `Stream`s by default; enabling `asQueue` returns a scoped queue whose buffer
+ * size is controlled by `streamBufferSize`. Payloads, exits, stream chunks, and
+ * middleware errors are encoded and decoded through RPC schemas, so any schema
+ * services required by those codecs remain in the generated method
+ * environment. Client middleware can rewrite or short-circuit requests and adds
+ * its client error type to the call signature.
  *
  * @since 4.0.0
  */
@@ -815,9 +824,14 @@ const rpcSchemas = (rpc: Rpc.AnyWithProps) => {
 }
 
 /**
- * A fiber-local reference containing headers that are merged into outgoing RPC
+ * Fiber reference containing headers that are merged into outgoing RPC
  * client requests.
  *
+ * **When to use**
+ *
+ * Use to set request headers that should be automatically merged into outgoing
+ * RPC client messages.
+ *
  * @category headers
  * @since 4.0.0
  */
@@ -856,10 +870,15 @@ export const withHeaders: {
 )
 
 /**
- * Service interface for an RPC client transport, responsible for running the
+ * Defines the service interface for an RPC client transport, responsible for running the
  * receive loop and sending encoded client messages.
  *
- * @category protocol
+ * **When to use**
+ *
+ * Use to provide the transport boundary for RPC clients over HTTP, WebSocket,
+ * workers, sockets, or custom protocols.
+ *
+ * @category protocols
  * @since 4.0.0
  */
 export class Protocol extends Context.Service<Protocol, {
@@ -887,7 +906,7 @@ export class Protocol extends Context.Service<Protocol, {
  * Creates a client `Protocol` that sends each RPC request through the supplied
  * `HttpClient` and decodes responses with the current `RpcSerialization`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
@@ -978,7 +997,7 @@ export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
  * Provides a client `Protocol` backed by `HttpClient`, targeting the configured
  * URL and optionally transforming the client before use.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
@@ -1000,7 +1019,7 @@ export const layerProtocolHttp = (options: {
  * `RpcSerialization`, connection hooks, ping timeouts, and the configured retry
  * policy.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolSocket = (options?: {
@@ -1167,7 +1186,7 @@ const makePinger = Effect.fnUntraced(function*<A, E, R>(writePing: Effect.Effect
  * Provides a client `Protocol` backed by the current `Socket` and
  * `RpcSerialization` services.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolSocket = (options?: {
@@ -1182,7 +1201,7 @@ export const layerProtocolSocket = (options?: {
  * Creates a client `Protocol` backed by a pool of workers, routing RPC requests
  * to workers and supporting transferable values when the platform does.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWorker = (
@@ -1348,7 +1367,7 @@ export const makeProtocolWorker = (
  * Provides a client `Protocol` backed by a worker pool using the current worker
  * platform and spawner services.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolWorker: (
@@ -1370,10 +1389,15 @@ export const layerProtocolWorker: (
 > = flow(makeProtocolWorker, Layer.effect(Protocol))
 
 /**
- * Optional client protocol hooks that run when a transport connects and
- * disconnects.
+ * Represents optional client protocol hooks that run when a transport connects
+ * and disconnects.
+ *
+ * **When to use**
+ *
+ * Use to run setup or cleanup effects when an RPC client transport opens or
+ * closes.
  *
- * @category ConnectionHooks
+ * @category connection hooks
  * @since 4.0.0
  */
 export class ConnectionHooks extends Context.Service<ConnectionHooks, {

package/src/unstable/rpc/RpcClientError.ts

@@ -1,19 +1,33 @@
 /**
- * Shared error types for the RPC client protocol layer.
+ * Client-side protocol failures reported by unstable RPC transports.
  *
- * This module defines the client-side failures added to schema-aware RPC
- * clients. `RpcClientError` wraps transport failures from the built-in HTTP,
- * socket, and worker protocols, while `RpcClientDefect` records protocol
- * problems such as empty HTTP responses, malformed response batches, failed
- * transport decoding, or unexpected connection failures.
+ * `RpcClientError` is the error type generated clients use when a call fails
+ * before a remote handler can return its declared typed error. Its `reason`
+ * covers built-in transport failures from HTTP, sockets, and workers, plus
+ * `RpcClientDefect` values for malformed or incompatible protocol data.
  *
- * These errors are separate from a remote handler's typed error. Remote
- * failures that match an RPC's error schema are decoded from the RPC exit and
- * remain part of the procedure's domain error channel. Server defects and
- * schema mismatches are not normal remote errors: they surface as defects or
- * protocol failures, so handlers commonly inspect `RpcClientError.reason` to
- * decide whether a failure is retryable transport trouble or an incompatible
- * client/server schema or serialization boundary.
+ * **Mental model**
+ *
+ * Handler errors belong to the RPC's declared error schema and are decoded from
+ * the response exit. Client errors describe the client or transport boundary:
+ * unavailable transport, aborted connections, unreadable response bodies,
+ * failed response decoding, or protocol shapes that do not match the RPC group
+ * the client was built for. Treat them as infrastructure or compatibility
+ * failures rather than business-domain failures.
+ *
+ * **Common tasks**
+ *
+ * Inspect `error.reason._tag` to decide whether to retry, reconnect, report a
+ * transport issue, or surface a schema or codec mismatch. Custom protocols can
+ * use `RpcClientDefect` to put invalid client-side protocol state in the same
+ * public error channel used by the built-in transports.
+ *
+ * **Gotchas**
+ *
+ * Server defects are sent through protocol messages and normally fail the call
+ * as defects rather than as declared RPC errors. Serialization and schema
+ * decode failures can appear as client defects because the client cannot safely
+ * produce the typed success or error value promised by the RPC definition.
  *
  * @since 4.0.0
  */
@@ -38,8 +52,8 @@ export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/
 }) {}
 
 /**
- * The public RPC client error type, wrapping worker, socket, HTTP client, and
- * client protocol defect failures.
+ * Error wrapper for RPC client failures, including worker, socket, HTTP client,
+ * and client protocol defect failures.
  *
  * @category errors
  * @since 4.0.0

package/src/unstable/rpc/RpcGroup.ts

@@ -1,24 +1,35 @@
 /**
- * Groups typed `Rpc` definitions into a protocol that can be shared by
- * clients, servers, tests, cluster entities, workflows, and other RPC
+ * Protocol composition for typed RPC definitions.
+ *
+ * An {@link RpcGroup} collects RPC definitions under their tags and preserves
+ * the payload, success, error, defect, middleware, and annotation metadata used
+ * by clients, servers, tests, cluster entities, workflows, and other RPC
  * integrations.
  *
- * An `RpcGroup` keeps RPC definitions keyed by their tags while preserving the
- * payload, success, error, defect, middleware, and annotation metadata carried
- * by each `Rpc`. Build groups with `make`, extend them with `add`, combine them
- * with `merge`, remove calls with `omit`, and turn the final protocol into
- * handler contexts or layers with `toHandlers`, `toLayer`, or `toLayerHandler`.
+ * **Mental model**
+ *
+ * A group is a typed map from RPC tag to RPC definition. The `add`, `merge`,
+ * `omit`, `prefix`, `middleware`, and `annotateRpcs` methods return new groups
+ * whose type tracks the changed protocol. The final group can then be turned
+ * into handler contexts or layers with `toHandlers`, `toLayer`, or
+ * `toLayerHandler`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link make} to define a service surface once, split large protocols into
+ * feature groups that are merged later, prefix generated or proxied names, and
+ * attach metadata for higher-level runtimes. Use {@link HandlersFrom} and
+ * {@link HandlerFrom} when implementing handlers separately from the group
+ * expression that declares them.
+ *
+ * **Gotchas**
  *
- * Common uses include defining a service surface once and deriving both client
- * and server implementations from it, splitting a large protocol into feature
- * groups that are merged later, prefixing generated or proxied RPC names, and
- * attaching metadata for higher-level runtimes. Composition order matters:
- * `middleware` and `annotateRpcs` update only the RPCs currently in the group,
- * duplicate tags from `add` or `merge` replace the existing definition, and
- * handlers are keyed by the tags after any prefixing. Schema requirements still
- * come from each RPC's payload, success, error, defect, and middleware schemas;
- * grouping preserves those requirements but does not provide the services
- * needed to encode, decode, or handle them.
+ * Composition order matters. `middleware` and `annotateRpcs` affect only the
+ * RPCs already in the group, duplicate tags from `add` or `merge` replace the
+ * existing definition, and handlers are keyed by tags after any prefixing.
+ * Schema requirements still come from each RPC's payload, success, error,
+ * defect, and middleware schemas; grouping preserves those requirements but
+ * does not provide the services needed to encode, decode, or handle them.
  *
  * @since 4.0.0
  */