effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/process/ChildProcess.ts

@@ -1,43 +1,11 @@
 /**
- * An Effect-native module for working with child processes.
+ * Describes child processes before they are started.
  *
- * This module uses an AST-based approach where commands are built first
- * using `make` and `pipeTo`, then executed using `spawn`.
- *
- * **Example** (Spawning and piping commands)
- *
- * ```ts
- * import { Effect, Stream } from "effect"
- * import { NodeServices } from "@effect/platform-node"
- * import { ChildProcess } from "effect/unstable/process"
- *
- * // Build a command
- * const command = ChildProcess.make`echo "hello world"`
- *
- * // Spawn and collect output
- * const program = Effect.gen(function*() {
- *   // You can `yield*` a command, which calls `ChildProcess.spawn`
- *   const handle = yield* command
- *   const chunks = yield* Stream.runCollect(handle.stdout)
- *   const exitCode = yield* handle.exitCode
- *   return { chunks, exitCode }
- * }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))
- *
- * // With options
- * const withOptions = ChildProcess.make({ cwd: "/tmp" })`ls -la`
- *
- * // Piping commands
- * const pipeline = ChildProcess.make`cat package.json`.pipe(
- *   ChildProcess.pipeTo(ChildProcess.make`grep name`)
- * )
- *
- * // Spawn the pipeline
- * const pipelineProgram = Effect.gen(function*() {
- *   const handle = yield* pipeline
- *   const chunks = yield* Stream.runCollect(handle.stdout)
- *   return chunks
- * }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))
- * ```
+ * A `Command` stores the executable, arguments, environment, standard streams,
+ * working directory, and other process options. Commands can also be piped
+ * together. A command is an `Effect`; running it asks the
+ * `ChildProcessSpawner` service to start the process and returns a
+ * `ChildProcessHandle`.
  *
  * @since 4.0.0
  */

package/src/unstable/process/ChildProcessSpawner.ts

@@ -1,20 +1,12 @@
 /**
- * Service contract and helpers for running child processes through Effect.
+ * Service boundary for starting and controlling child processes.
  *
- * This module defines the {@link ChildProcessSpawner} service used by child
- * process commands to start operating-system processes. A spawner turns a
- * command description into a {@link ChildProcessHandle}, which exposes scoped
- * lifecycle operations: write to stdin, stream stdout and stderr, wait for the
- * exit code, kill the process, inspect whether it is still running, and
- * temporarily unreference it from the parent process.
- *
- * Use this module when implementing a platform-specific process backend or
- * when code needs direct access to the process service. Most applications build
- * commands with the `ChildProcess` module; this service is the lower-level
- * execution boundary and also provides convenience methods for collecting exit
- * codes, strings, and output lines. The {@link make} constructor derives those
- * helpers from one primitive `spawn` implementation, so adapters only need to
- * supply process creation.
+ * `ChildProcessSpawner` is the service used by `ChildProcess` commands to start
+ * operating-system processes. A spawner turns a command description into a
+ * handle that can write to stdin, read stdout and stderr, wait for exit, kill
+ * the process, and manage whether the process keeps its parent alive. Platform
+ * backends implement this service, while most application code uses the higher
+ * level `ChildProcess` module.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AsyncResult.ts

@@ -1,44 +1,12 @@
 /**
- * State containers for asynchronous values used by the reactivity APIs.
+ * Represents observable state for asynchronous values.
  *
- * `AsyncResult` records the latest observable state of work that may still be
- * loading, refreshing, retrying, or recovering from failure. The value is one of
- * `Initial`, `Success`, or `Failure`, and every variant also carries a `waiting`
- * flag so callers can keep rendering the current state while newer work is in
- * flight.
- *
- * **Mental model**
- *
- * The variant answers "what do we know right now?", while `waiting` answers "is
- * newer work currently running?". A success contains the current value and its
- * timestamp. A failure contains a `Cause` and may also keep the previous
- * success, which lets UI and atom code show stale data while exposing the latest
- * failure for error displays and retry logic.
- *
- * **Common tasks**
- *
- * - Start with {@link initial}, {@link success}, {@link failure}, or
- *   {@link fail}
- * - Convert Effect exits with {@link fromExit} and
- *   {@link fromExitWithPrevious}
- * - Mark existing state as loading with {@link waiting} or
- *   {@link waitingFrom}
- * - Read values and failures with {@link value}, {@link cause}, {@link error},
- *   {@link getOrElse}, and {@link toExit}
- * - Transform and combine results with {@link map}, {@link flatMap}, and
- *   {@link all}
- * - Render all states with {@link match}, {@link matchWithWaiting}, or
- *   {@link builder}
- *
- * **Gotchas**
- *
- * - `waiting` is an overlay, not a fourth variant; any variant can be waiting.
- * - {@link value} and {@link getOrElse} can read the previous success stored in
- *   a failure, so inspect {@link cause} or {@link error} when stale data and a
- *   current success must be distinguished.
- * - {@link matchWithWaiting} handles waiting before variant-specific branches,
- *   while {@link match} and {@link matchWithError} expose the underlying
- *   variant first.
+ * `AsyncResult<A, E>` records whether asynchronous work has no value yet,
+ * succeeded with an `A`, or failed with an `E`. Every state also carries a
+ * `waiting` flag, so callers can keep showing the current value while newer
+ * work is loading, refreshing, retrying, or recovering. This module includes
+ * constructors, checks, accessors, mapping and matching helpers, ways to combine
+ * several results, and schemas for encoding or decoding results.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Atom.ts

@@ -1,40 +1,12 @@
 /**
- * Reactive state primitives for values evaluated by an {@link AtomRegistry}.
- *
- * An {@link Atom} describes how to read a value. The registry is the runtime
- * owner: it evaluates reads, caches results, records dependency edges, runs
- * effects and streams with the configured runtime services, and disposes nodes
- * when they are no longer observed.
- *
- * **Mental model**
- *
- * Regular `get(atom)` calls inside a read function create dependencies. When a
- * dependency changes or refreshes, dependent atoms are invalidated and re-read
- * on demand. One-shot reads such as `get.once(atom)` read the current value
- * without creating an edge. The same atom can hold different cached values in
- * different registries, so stable atom identity matters; use {@link family} for
- * atoms parameterized by input values.
- *
- * **Common tasks**
- *
- * Use {@link readable} or {@link writable} for synchronous state, {@link make}
- * for effects and streams exposed as `AsyncResult`, {@link fn} for
- * command-style effects, {@link pull} for pull-based streams, and
- * {@link subscriptionRef} to expose a `SubscriptionRef`. Use {@link kvs},
- * {@link searchParam}, and {@link serializable} when atom values need
- * persistence, URL state, or server-to-client hydration. Read and mutate atoms
- * from Effect code with {@link get}, {@link set}, {@link update},
- * {@link refresh}, and {@link mount}; convert observed values to streams with
- * {@link toStream} or {@link toStreamResult}.
- *
- * **Gotchas**
- *
- * Cache lifetime belongs to the registry, not the atom object. Unobserved
- * non-`keepAlive` atoms can be disposed immediately or after their idle TTL,
- * which also releases finalizers and may rebuild effects, streams, and derived
- * state on the next read. Runtime-backed atoms refresh only through their
- * registered refresh hooks or explicit `Reactivity` invalidations; reading an
- * `Effect` by itself does not keep external data subscribed.
+ * Reactive state primitives for values managed by an `AtomRegistry`.
+ *
+ * An `Atom` describes how to produce or update one piece of reactive state. The
+ * registry runs atom reads, remembers current values, tracks dependencies
+ * between atoms, starts effects and streams, and cleans up atoms that are no
+ * longer used. This module includes the atom constructors and update helpers
+ * used for cached values, effect-backed values, streams, browser state, stored
+ * values, and server-rendered values.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -1,30 +1,11 @@
 /**
- * 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.
+ * Connects typed `HttpApi` clients to atoms.
  *
- * 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.
+ * The service created here exposes the generated HTTP API client plus
+ * atom-based query and mutation helpers. Query atoms call endpoints and track
+ * their asynchronous result, while mutations run endpoint calls that can
+ * invalidate reactivity keys after a successful request. Query atoms can also be
+ * cached, serialized for hydration, and kept alive with a time-to-live.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRef.ts

@@ -2,35 +2,10 @@
  * Mutable reactive references for local, in-memory state.
  *
  * `AtomRef` provides small observable state cells that can be read, updated,
- * focused, and subscribed to without going through an `AtomRegistry`. It is
- * suited to form state, local view models, and collections of item references
- * where callers need direct mutation methods together with change notifications.
- *
- * **Mental model**
- *
- * An `AtomRef` is a value cell with a stable key and a subscriber list.
- * {@link make} creates a mutable cell, `map` derives read-only views, and `prop`
- * focuses on nested object or array properties while preserving mutation
- * helpers. {@link collection} stores ordered item refs and emits collection
- * updates when items are inserted, removed, or changed through their refs.
- *
- * **Common tasks**
- *
- * - Use {@link make} for standalone local state.
- * - Use `ref.set` or `ref.update` to replace the current value.
- * - Use `ref.map` for derived read-only values.
- * - Use `ref.prop` to update nested object fields or array entries.
- * - Use {@link collection} for ordered lists whose items should remain
- *   individually mutable.
- *
- * **Gotchas**
- *
- * Notifications are equality-aware: values that are `Equal.equals` to the
- * current value do not notify subscribers, and mapped or property subscriptions
- * only emit when their derived value changes. Directly mutating an object or
- * array stored in a ref does not notify listeners; use `set`, `update`, or a
- * property ref instead. `toArray` returns the current raw item values, not the
- * item refs.
+ * mapped, and subscribed to without going through an `AtomRegistry`. Mutable
+ * refs can also create refs for nested properties. The module also provides a
+ * collection helper that stores item refs and notifies subscribers when items are
+ * inserted, removed, or changed.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRegistry.ts

@@ -1,78 +1,11 @@
 /**
- * The `AtomRegistry` module provides the runtime cache for unstable reactivity
- * atoms. A registry owns the node graph for a group of atoms, stores current
- * values, records parent and child dependencies while atoms are read, and
- * coordinates writes, refreshes, subscriptions, stream conversions, and node
- * disposal.
+ * Stores and runs atoms for one reactive runtime.
  *
- * Use a separate registry for each UI root, request, test, route boundary, or
- * other lifetime that needs isolated atom state. The same atom object can have
- * different cached values in different registries, while serializable atoms use
- * their stable serialization key so preloaded values can hydrate a node before
- * the first read.
- *
- * **Mental model**
- *
- * - Reading an atom creates or reuses a registry node, evaluates the atom when
- *   its value is missing or stale, and records any nested atom reads as
- *   dependencies.
- * - Writing a writable atom updates its node through the atom's write function,
- *   invalidates dependent nodes, and notifies listeners after batching settles.
- * - Subscriptions and scoped {@link mount} calls keep nodes alive. When the last
- *   listener and dependent child disappear, non-`keepAlive` atoms can be
- *   removed immediately or after their idle TTL.
- * - Effects and streams started by atoms run with the registry scheduler and
- *   are finalized when the node is rebuilt, removed, reset, or disposed.
- * - Disposing a registry clears its nodes and makes later atom access an error.
- *
- * **Common tasks**
- *
- * - Create a registry directly with {@link make}, or provide one to Effect
- *   programs with {@link layer} or {@link layerOptions}.
- * - Read and write atom state with the registry instance methods `get`, `set`,
- *   `modify`, `update`, and `refresh`.
- * - Keep an atom alive for an Effect scope with {@link mount}; subscribe with
- *   `subscribe` when integrating with callback-based UI code.
- * - Convert observed atom values with {@link toStream} and
- *   {@link toStreamResult}, or wait for an `AsyncResult` atom with
- *   {@link getResult}.
- * - Preload encoded serializable state with `setSerializable` before the
- *   matching atom is read.
- *
- * **Quickstart**
- *
- * **Example** (Isolated atom state)
- *
- * ```ts
- * import { Atom, AtomRegistry } from "effect/unstable/reactivity"
- *
- * const count = Atom.make(0)
- * const doubled = Atom.make((get) => get(count) * 2)
- *
- * const registry = AtomRegistry.make()
- *
- * registry.set(count, 21)
- * registry.get(doubled)
- * // 42
- * ```
- *
- * **Gotchas**
- *
- * - Atom identity matters. Creating a new atom object creates a different node
- *   unless the atom is serializable and uses the same serialization key.
- * - Unobserved atoms without `keepAlive` can be removed, so later reads may
- *   rebuild derived values, restart effects or streams, and rerun finalizers.
- * - `subscribe` and the instance `mount` method return release callbacks; call
- *   them when the external consumer is done. The exported {@link mount} helper
- *   ties that release to an Effect scope.
- * - `reset` and `dispose` remove every node in the registry. Use a new registry
- *   when a whole lifetime should start from empty state.
- *
- * **See also**
- *
- * - {@link Atom.Atom} for defining reactive values read by a registry.
- * - {@link Result.AsyncResult} for asynchronous atom results.
- * - {@link Stream.Stream} for streams produced from observed atom values.
+ * An `AtomRegistry` evaluates atoms, caches their current values, tracks
+ * dependencies, applies writes and refreshes, manages subscriptions, and
+ * disposes unused nodes. Each registry is independent, so the same atom can hold
+ * different values in different registries. Serializable atom values can also be
+ * preloaded before the first read.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/AtomRpc.ts

@@ -1,25 +1,11 @@
 /**
- * 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`.
+ * Connects typed RPC clients to atoms.
  *
- * 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.
+ * The service created here exposes a flattened RPC client plus atom-based query
+ * and mutation helpers. Query atoms call RPCs and track asynchronous or
+ * streaming results, while mutations run RPC calls that can invalidate
+ * reactivity keys after success. Query atoms can also use request headers,
+ * time-to-live settings, and serialization keys for hydration.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Hydration.ts

@@ -1,35 +1,12 @@
 /**
- * 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.
+ * Saves and restores serializable atom state.
+ *
+ * `dehydrate` reads atoms marked with `Atom.serializable` from an
+ * `AtomRegistry` and returns encoded entries keyed by their serialization keys.
+ * `hydrate` preloads those entries into another registry before the atoms are
+ * read. Initial `AsyncResult` values can be ignored, encoded as values, or
+ * represented by promises that update the target registry once the result is no
+ * longer initial.
  *
  * @since 4.0.0
  */

package/src/unstable/reactivity/Reactivity.ts

@@ -1,42 +1,11 @@
 /**
- * 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.
+ * Process-local invalidation for connecting writes to dependent reads.
  *
- * **Mental model**
- *
- * 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}
+ * This module does not cache values itself. It lets callers register handlers
+ * for keys, invalidate those keys, wrap successful mutations so they invalidate
+ * keys, and expose effects as queues or streams that rerun when matching keys
+ * change. The service can also batch invalidations so handlers run after the
+ * batch completes.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/Rpc.ts

@@ -1,44 +1,12 @@
 /**
- * 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
- *   `PrimaryKey`
- * - 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 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
- *   responses, while servers decode payloads and encode responses
+ * Defines schema-backed contracts for individual RPC procedures.
+ *
+ * An `Rpc` describes one remote procedure by recording its tag, payload schema,
+ * success schema, error schema, defect schema, middleware, and annotations.
+ * Clients and servers read the same declaration, so the procedure contract is
+ * independent of the transport used to call it. This module includes
+ * constructors, type helpers for deriving client and handler shapes, exit
+ * schemas, and handler wrappers for special execution modes.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcClient.ts

@@ -1,38 +1,12 @@
 /**
- * Client-side runtime for typed RPC calls.
+ * Runs typed RPC calls from the client side.
  *
  * 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`.
- *
- * **Mental model**
- *
- * `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.
+ * methods. Each call encodes its payload, sends a message through the active
+ * `Protocol`, decodes exits or stream chunks from the server, and routes the
+ * response back to the waiting `Effect`, `Stream`, or queue. It also defines
+ * the protocol service and includes protocol layers for HTTP, sockets, and
+ * workers.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcClientError.ts

@@ -6,29 +6,6 @@
  * covers built-in transport failures from HTTP, sockets, and workers, plus
  * `RpcClientDefect` values for malformed or incompatible protocol data.
  *
- * **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
  */
 import * as Schema from "../../Schema.ts"