effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/reactivity/Hydration.ts

@@ -1,20 +1,35 @@
 /**
- * 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.
+ * Moves serializable reactivity state between `AtomRegistry` instances.
+ *
+ * The `Hydration` module snapshots atoms marked with `Atom.serializable` and
+ * loads those encoded values into another registry before the atoms are read. It
+ * is useful for server rendering, browser bootstrapping, route transitions, and
+ * other handoffs where a new registry should start from values computed by a
+ * previous one.
+ *
+ * **Mental model**
+ *
+ * `dehydrate` walks the source registry and produces `DehydratedAtomValue`
+ * records keyed by each atom's serialization key. `hydrate` stores those encoded
+ * values in the target registry so the matching atom can decode them with its own
+ * serializable codec. Atom identity is not transferred; only the stable key,
+ * encoded value, dehydration timestamp, and optional async handoff are.
+ *
+ * **Common tasks**
+ *
+ * Use `dehydrate` before rendering or crossing a route boundary, then call
+ * `hydrate` on the registry that will serve the next read. Use `toValues` when
+ * code accepts generic `DehydratedAtom` entries but needs the concrete record
+ * shape, and use `encodeInitialAs` to choose how `AsyncResult.Initial` values
+ * should appear in the snapshot.
+ *
+ * **Gotchas**
+ *
+ * Only serializable atoms are included, and the target registry must contain
+ * atoms with matching stable keys and compatible codecs. The optional
+ * `resultPromise` used for `AsyncResult.Initial` is a live JavaScript promise; it
+ * can be handed to another registry in the same runtime, but it cannot be sent
+ * through JSON or across process boundaries.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Reactivity.ts

@@ -1,24 +1,42 @@
 /**
- * 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.
+ * The `Reactivity` module provides process-local invalidation for connecting
+ * writes to dependent reads. It does not cache values itself; it tracks keys,
+ * registers query handlers, and reruns effects when matching keys are
+ * invalidated so queues, streams, UI subscriptions, and read models can stay
+ * fresh after successful writes.
  *
- * 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.
+ * **Mental model**
  *
- * 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.
+ * A query registers one or more keys, runs once immediately, and publishes each
+ * result to a queue or stream. Invalidating any registered key schedules the
+ * query to rerun. Mutations wrap an effect and invalidate keys only after it
+ * succeeds. Keys can be a flat array, or a record whose property names act as
+ * broad namespaces and whose ids address individual records.
+ *
+ * **Common tasks**
+ *
+ * - Provide the default in-memory service with {@link layer}.
+ * - Use {@link query} when callers need a queue of rerun results.
+ * - Use {@link stream} when downstream code should consume reruns as a stream.
+ * - Wrap writes with {@link mutation}, or call {@link invalidate} directly when
+ *   invalidation is already part of the workflow.
+ * - Use the {@link Reactivity} service directly when many invalidations should
+ *   be coalesced until a batch exits.
+ *
+ * **Gotchas**
+ *
+ * - The default layer is process-local; it does not coordinate invalidations
+ *   across processes or cluster runners.
+ * - Non-primitive keys are matched by their `Hash.hash` value, so prefer stable
+ *   key values over mutable objects.
+ * - If a query fails, its queue or stream fails with the same cause.
+ * - Invalidations that arrive while a query is already running coalesce into one
+ *   follow-up run.
+ *
+ * **See also**
+ *
+ * - {@link query}, {@link stream}, {@link mutation}, and {@link invalidate}
+ * - {@link layer} and {@link Reactivity}
  *
  * @since 4.0.0
  */

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

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
  */

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
  */

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
  */

package/src/unstable/rpc/RpcMessage.ts

@@ -1,20 +1,38 @@
 /**
- * Defines the protocol message envelopes shared by unstable RPC clients,
- * servers, 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.
- *
- * 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.
+ * Message envelopes shared by unstable RPC clients, servers, serializers, and
+ * transports.
+ *
+ * `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.
+ *
+ * **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
  */