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

package/dist/Stream.d.ts

@@ -1,40 +1,83 @@
 /**
- * The `Stream` module provides a typed, composable way to describe effectful
- * sequences of values. A `Stream<A, E, R>` can emit zero or more `A` values,
- * fail with an `E`, and require services from `R` while preserving
- * backpressure and resource safety.
+ * The `Stream` module describes effectful sequences that may emit many values
+ * over time. A `Stream<A, E, R>` can produce zero or more `A` values, fail with
+ * an `E`, and require services from `R`; the Effect runtime handles
+ * backpressure, interruption, scopes, and finalizers while the stream is being
+ * consumed.
+ *
+ * Streams are useful for files, sockets, queues, subscriptions, paginated APIs,
+ * background jobs, and any workflow where values should be processed
+ * incrementally instead of loaded into memory all at once.
  *
  * **Mental model**
  *
- * - A stream is a lazy description; it runs only when consumed with a `run*` function
- * - Streams are pull-based and emit chunks internally for efficient throughput
- * - `A` is the element type, `E` is the failure type, and `R` is the required context
- * - Stream composition mirrors `Effect`: use `map`, `flatMap`, error handling, and `pipe`
- * - Resource scopes, interruption, and finalizers are tracked by the Effect runtime
- * - Interop functions connect streams to queues, pub/subs, web streams, async iterables, and channels
+ * - A stream is a lazy description; it does not run until consumed with
+ *   {@link run}, {@link runCollect}, {@link runForEach}, or another `run*`
+ *   function.
+ * - Pulling drives evaluation. Operators request values from upstream, and the
+ *   runtime propagates demand instead of pushing unbounded data downstream.
+ * - Values are batched internally as chunks for throughput, while user-facing
+ *   combinators still work with individual elements unless they mention chunks.
+ * - `A` is the element type, `E` is the failure type, and `R` is the required
+ *   service context.
+ * - Composition mirrors `Effect`: use `pipe`, {@link map}, {@link flatMap},
+ *   error handling, resource operators, and service provisioning.
  *
  * **Common tasks**
  *
- * - Create streams: {@link make}, {@link fromIterable}, {@link fromEffect}, {@link fromQueue}
- * - Transform values: {@link map}, {@link mapEffect}, {@link flatMap}, {@link filter}
- * - Combine streams: {@link concat}, {@link merge}, {@link zip}, {@link race}
- * - Control demand and timing: {@link take}, {@link drop}, {@link debounce}, {@link throttle}
- * - Manage errors: {@link catchCause}, {@link catchIf}, {@link mapError}, {@link retry}
- * - Manage resources and services: {@link scoped}, {@link ensuring}, {@link provide}
- * - Consume streams: {@link runCollect}, {@link runForEach}, {@link runFold}, {@link runDrain}
+ * - Create streams from values, effects, and collections with {@link make},
+ *   {@link fromEffect}, {@link fromIterable}, and {@link fromQueue}.
+ * - Transform or select values with {@link map}, {@link mapEffect},
+ *   {@link flatMap}, {@link filter}, and {@link filterMap}.
+ * - Combine streams with {@link concat}, {@link merge}, {@link zip},
+ *   {@link race}, and {@link interleave}.
+ * - Control size and timing with {@link take}, {@link drop}, {@link debounce},
+ *   {@link throttle}, {@link grouped}, and {@link groupedWithin}.
+ * - Handle failures with {@link catchCause}, {@link catchIf},
+ *   {@link mapError}, {@link retry}, and {@link withExecutionPlan}.
+ * - Connect to other protocols with {@link fromReadableStream},
+ *   {@link toReadableStream}, {@link fromAsyncIterable}, {@link toQueue}, and
+ *   {@link runIntoQueue}.
+ * - Consume streams with {@link runCollect}, {@link runForEach},
+ *   {@link runFold}, {@link runDrain}, or a {@link Sink.Sink}.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Transforming and collecting values)
+ *
+ * ```ts
+ * import { Effect, Stream } from "effect"
+ *
+ * const program = Stream.make(1, 2, 3).pipe(
+ *   Stream.map((n) => n * 2),
+ *   Stream.runCollect
+ * )
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [2, 4, 6]
+ * ```
  *
  * **Gotchas**
  *
- * - A stream is not a collection; constructors and operators build a description until it is run
- * - Re-running a stream re-executes its effects unless it is explicitly shared or backed by external state
- * - Operators such as {@link merge}, {@link race}, and {@link broadcast} introduce concurrency and interruption semantics
- * - Prefer bounded constructors and sinks for large or infinite streams instead of collecting everything into memory
+ * - A stream is not a collection. Constructors and operators build a
+ *   description; effects run each time the stream is consumed.
+ * - {@link runCollect} stores every emitted value in memory. Prefer
+ *   {@link runForEach}, {@link runFold}, or a streaming sink for large or
+ *   infinite streams.
+ * - Operators such as {@link merge}, {@link race}, {@link broadcast}, and
+ *   {@link share} introduce concurrency, so interruption and finalizer timing
+ *   can matter.
+ * - Reusing the same stream value does not share execution by itself. Use
+ *   {@link share}, {@link broadcast}, queues, or external state when multiple
+ *   consumers must observe one running producer.
  *
  * **See also**
  *
- * - {@link Effect.Effect} for single-result effectful programs
- * - {@link Sink.Sink} for consuming and folding streams
- * - {@link Channel.Channel} for the lower-level primitive underlying streams
+ * - {@link Effect.Effect} for single-result effectful programs.
+ * - {@link Sink.Sink} for reusable stream consumers.
+ * - {@link Channel.Channel} for the lower-level primitive behind streams.
+ * - {@link Queue.Queue} and {@link PubSub.PubSub} for coordinating producers
+ *   and consumers.
  *
  * @since 2.0.0
  */
@@ -68,7 +111,7 @@ import type * as Unify from "./Unify.ts";
 /**
  * String literal type used as the unique brand for `Stream` values.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/Stream";
@@ -76,7 +119,14 @@ export type TypeId = "~effect/Stream";
  * Runtime identifier stored on `Stream` values and used by `isStream` to
  * recognize them.
  *
- * @category Type Identifiers
+ * **Details**
+ *
+ * This marker is part of the runtime representation of `Stream` values. Prefer
+ * `isStream` when narrowing unknown values.
+ *
+ * @see {@link isStream} for the public guard that checks this identifier
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export declare const TypeId: TypeId;
@@ -316,8 +366,7 @@ export type HaltStrategy = Channel.HaltStrategy;
  */
 export declare const fromChannel: <Arr extends Arr.NonEmptyReadonlyArray<any>, E, R>(channel: Channel.Channel<Arr, E, void, unknown, unknown, unknown, R>) => Stream<Arr extends Arr.NonEmptyReadonlyArray<infer A> ? A : never, E, R>;
 /**
- * Either emits the success value of this effect or terminates the stream
- * with the failure value of this effect.
+ * Creates a stream from an effect.
  *
  * **Example** (Creating a stream from an effect)
  *
@@ -375,6 +424,11 @@ export declare const service: <I, S>(service: Context.Key<I, S>) => Stream<S, ne
  * Optionally accesses a service from the context and emits the result as a
  * single element.
  *
+ * **When to use**
+ *
+ * Use to emit an optional dependency as a stream element without requiring that
+ * dependency to be present.
+ *
  * **Example** (Accessing an optional service as a stream)
  *
  * ```ts
@@ -539,7 +593,7 @@ export declare const tick: (interval: Duration.Input) => Stream<void>;
  */
 export declare const fromPull: <A, E, R, EX, RX>(pull: Effect.Effect<Pull.Pull<Arr.NonEmptyReadonlyArray<A>, E, void, R>, EX, RX>) => Stream<A, Pull.ExcludeDone<E> | EX, R | RX>;
 /**
- * Derive a stream by transforming its pull effect.
+ * Derives a stream by transforming its pull effect.
  *
  * **Example** (Transforming a pull effect)
  *
@@ -629,7 +683,7 @@ export declare const toChannel: <A, E, R>(stream: Stream<A, E, R>) => Channel.Ch
  *
  * **When to use**
  *
- * You can use the `Queue` with the apis from the `Queue` module to emit
+ * Use when you can use the `Queue` with the apis from the `Queue` module to emit
  * values to the stream or to signal the stream ending.
  *
  * By default it uses an "unbounded" buffer size.
@@ -1305,7 +1359,7 @@ export declare const fromSchedule: <O, E, R>(schedule: Schedule.Schedule<O, unkn
  *
  * **When to use**
  *
- * Use `PubSub.subscribe` to create the subscription and `Stream.take` or
+ * Use to create the subscription and `Stream.take` or
  * cancellation to control how many values are consumed.
  *
  * **Example** (Creating a stream from a PubSub subscription)
@@ -1418,9 +1472,17 @@ export declare const fromEventListener: <A = unknown>(target: EventListener<A>,
  */
 export declare const unfold: <S, A, E, R>(s: S, f: (s: S) => Effect.Effect<readonly [A, S] | undefined, E, R>) => Stream<A, E, R>;
 /**
- * Like `Stream.unfold`, but allows the emission of values to end one step further
- * than the unfolding of the state. This is useful for embedding paginated APIs,
- * hence the name.
+ * Creates a stream by repeatedly evaluating an effectful page function.
+ *
+ * **When to use**
+ *
+ * Use to consume paginated APIs where each step returns a batch of values
+ * together with an optional next state.
+ *
+ * **Details**
+ *
+ * This is similar to {@link unfold}, but each step can emit zero or more values
+ * and independently decide whether another state should be requested.
  *
  * **Example** (Paginating stream state)
  *
@@ -1970,7 +2032,7 @@ export declare const flattenEffect: <Arg extends Stream<Effect.Effect<any, any,
     readonly unordered?: boolean | undefined;
 } | undefined) => [Arg] extends [Stream<Effect.Effect<infer _A, infer _EX, infer _RX>, infer _E, infer _R>] ? Stream<_A, _EX | _E, _RX | _R> : <A, EX, RX, E, R>(self: Stream<Effect.Effect<A, EX, RX>, E, R>) => Stream<A, EX | E, RX | R>;
 /**
- * Effectfully maps over non-empty array chunks emitted by the stream.
+ * Maps over non-empty array chunks emitted by the stream effectfully.
  *
  * **Example** (Effectfully mapping stream chunks)
  *
@@ -1997,7 +2059,7 @@ export declare const flattenEffect: <Arg extends Stream<Effect.Effect<any, any,
  */
 export declare const mapArrayEffect: {
     /**
-     * Effectfully maps over non-empty array chunks emitted by the stream.
+     * Maps over non-empty array chunks emitted by the stream effectfully.
      *
      * **Example** (Effectfully mapping stream chunks)
      *
@@ -2024,7 +2086,7 @@ export declare const mapArrayEffect: {
      */
     <A, B, E2, R2>(f: (a: Arr.NonEmptyReadonlyArray<A>, i: number) => Effect.Effect<Arr.NonEmptyReadonlyArray<B>, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>;
     /**
-     * Effectfully maps over non-empty array chunks emitted by the stream.
+     * Maps over non-empty array chunks emitted by the stream effectfully.
      *
      * **Example** (Effectfully mapping stream chunks)
      *
@@ -2300,8 +2362,7 @@ export declare const tapBoth: {
     }): Stream<A, E | E2 | E3, R | R2 | R3>;
 };
 /**
- * Sends all elements emitted by this stream to the specified sink in addition
- * to emitting them.
+ * Runs a sink for all stream elements while still emitting them downstream.
  *
  * **Example** (Tapping values with a sink)
  *
@@ -2332,8 +2393,7 @@ export declare const tapBoth: {
  */
 export declare const tapSink: {
     /**
-     * Sends all elements emitted by this stream to the specified sink in addition
-     * to emitting them.
+     * Runs a sink for all stream elements while still emitting them downstream.
      *
      * **Example** (Tapping values with a sink)
      *
@@ -2364,8 +2424,7 @@ export declare const tapSink: {
      */
     <A, E2, R2>(sink: Sink.Sink<unknown, A, unknown, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>;
     /**
-     * Sends all elements emitted by this stream to the specified sink in addition
-     * to emitting them.
+     * Runs a sink for all stream elements while still emitting them downstream.
      *
      * **Example** (Tapping values with a sink)
      *
@@ -2830,7 +2889,7 @@ export declare const repeat: {
     <A, E, R, B, E2, R2>(self: Stream<A, E, R>, schedule: Schedule.Schedule<B, void, E2, R2> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, void, SE, SR>) => Schedule.Schedule<SO, void, SE, SR>) => Schedule.Schedule<B, void, E2, R2>)): Stream<A, E | E2, R | R2>;
 };
 /**
- * Spaces the stream's elements according to the provided `schedule`.
+ * Schedules the stream's elements according to the provided schedule.
  *
  * **Example** (Scheduling stream elements)
  *
@@ -2850,12 +2909,12 @@ export declare const repeat: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const schedule: {
     /**
-     * Spaces the stream's elements according to the provided `schedule`.
+     * Schedules the stream's elements according to the provided schedule.
      *
      * **Example** (Scheduling stream elements)
      *
@@ -2875,12 +2934,12 @@ export declare const schedule: {
      * // Output: [ 1, 2, 3 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <X, E2, R2, A>(schedule: Schedule.Schedule<X, NoInfer<A>, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>;
     /**
-     * Spaces the stream's elements according to the provided `schedule`.
+     * Schedules the stream's elements according to the provided schedule.
      *
      * **Example** (Scheduling stream elements)
      *
@@ -2900,7 +2959,7 @@ export declare const schedule: {
      * // Output: [ 1, 2, 3 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R, X, E2, R2>(self: Stream<A, E, R>, schedule: Schedule.Schedule<X, NoInfer<A>, E2, R2>): Stream<A, E | E2, R | R2>;
@@ -2926,7 +2985,7 @@ export declare const schedule: {
  * // Output: [ 1 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const timeout: {
@@ -2951,7 +3010,7 @@ export declare const timeout: {
      * // Output: [ 1 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     (duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
@@ -2976,7 +3035,7 @@ export declare const timeout: {
      * // Output: [ 1 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, duration: Duration.Input): Stream<A, E, R>;
@@ -2985,13 +3044,24 @@ export declare const timeout: {
  * Switches to a fallback stream if this stream does not emit a value within
  * the specified duration.
  *
+ * **When to use**
+ *
+ * Use when a stream should continue with another stream if an upstream pull
+ * waits longer than the allowed duration.
+ *
  * **Details**
  *
  * The timeout is checked for each pull. A zero duration uses `orElse`
  * immediately, while an infinite duration leaves the original stream
  * unchanged.
  *
- * @category Rate Limiting
+ * **Gotchas**
+ *
+ * The fallback stream is not timed after the switch.
+ *
+ * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+ *
+ * @category rate limiting
  * @since 4.0.0
  */
 export declare const timeoutOrElse: {
@@ -2999,13 +3069,24 @@ export declare const timeoutOrElse: {
      * Switches to a fallback stream if this stream does not emit a value within
      * the specified duration.
      *
+     * **When to use**
+     *
+     * Use when a stream should continue with another stream if an upstream pull
+     * waits longer than the allowed duration.
+     *
      * **Details**
      *
      * The timeout is checked for each pull. A zero duration uses `orElse`
      * immediately, while an infinite duration leaves the original stream
      * unchanged.
      *
-     * @category Rate Limiting
+     * **Gotchas**
+     *
+     * The fallback stream is not timed after the switch.
+     *
+     * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+     *
+     * @category rate limiting
      * @since 4.0.0
      */
     <B, E2, R2>(options: {
@@ -3016,13 +3097,24 @@ export declare const timeoutOrElse: {
      * Switches to a fallback stream if this stream does not emit a value within
      * the specified duration.
      *
+     * **When to use**
+     *
+     * Use when a stream should continue with another stream if an upstream pull
+     * waits longer than the allowed duration.
+     *
      * **Details**
      *
      * The timeout is checked for each pull. A zero duration uses `orElse`
      * immediately, while an infinite duration leaves the original stream
      * unchanged.
      *
-     * @category Rate Limiting
+     * **Gotchas**
+     *
+     * The fallback stream is not timed after the switch.
+     *
+     * @see {@link timeout} for ending the stream instead of switching to a fallback stream
+     *
+     * @category rate limiting
      * @since 4.0.0
      */
     <A, E, R, B, E2, R2>(self: Stream<A, E, R>, options: {
@@ -3133,7 +3225,7 @@ export declare const repeatElements: {
  */
 export declare const forever: <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
 /**
- * Submerges the iterables emitted by this stream into the stream's structure.
+ * Flattens the iterables emitted by this stream into the stream's structure.
  *
  * **Example** (Flattening iterable values)
  *
@@ -3811,8 +3903,16 @@ export declare const mergeRight: {
 /**
  * Merges a collection of streams, running up to the specified number concurrently.
  *
- * @category Merging
- * @since 2.0.0
+ * **When to use**
+ *
+ * Use to merge an iterable of already-created streams while bounding how many
+ * inner streams may run at the same time.
+ *
+ * **Details**
+ *
+ * The `concurrency` option is required and may be a number or `"unbounded"`.
+ * `bufferSize` controls buffering between inner streams, and outputs are
+ * emitted as they arrive under concurrent merging.
  *
  * **Example** (Merging streams with bounded concurrency)
  *
@@ -3834,13 +3934,27 @@ export declare const mergeRight: {
  * Effect.runPromise(program)
  * // Output: [ "B", "A" ]
  * ```
+ *
+ * @see {@link merge} for merging exactly two streams and choosing a halt strategy
+ * @see {@link flatten} for flattening a stream that already emits streams
+ *
+ * @category Merging
+ * @since 2.0.0
  */
 export declare const mergeAll: {
     /**
      * Merges a collection of streams, running up to the specified number concurrently.
      *
-     * @category Merging
-     * @since 2.0.0
+     * **When to use**
+     *
+     * Use to merge an iterable of already-created streams while bounding how many
+     * inner streams may run at the same time.
+     *
+     * **Details**
+     *
+     * The `concurrency` option is required and may be a number or `"unbounded"`.
+     * `bufferSize` controls buffering between inner streams, and outputs are
+     * emitted as they arrive under concurrent merging.
      *
      * **Example** (Merging streams with bounded concurrency)
      *
@@ -3862,6 +3976,12 @@ export declare const mergeAll: {
      * Effect.runPromise(program)
      * // Output: [ "B", "A" ]
      * ```
+     *
+     * @see {@link merge} for merging exactly two streams and choosing a halt strategy
+     * @see {@link flatten} for flattening a stream that already emits streams
+     *
+     * @category Merging
+     * @since 2.0.0
      */
     (options: {
         readonly concurrency: number | "unbounded";
@@ -3870,8 +3990,16 @@ export declare const mergeAll: {
     /**
      * Merges a collection of streams, running up to the specified number concurrently.
      *
-     * @category Merging
-     * @since 2.0.0
+     * **When to use**
+     *
+     * Use to merge an iterable of already-created streams while bounding how many
+     * inner streams may run at the same time.
+     *
+     * **Details**
+     *
+     * The `concurrency` option is required and may be a number or `"unbounded"`.
+     * `bufferSize` controls buffering between inner streams, and outputs are
+     * emitted as they arrive under concurrent merging.
      *
      * **Example** (Merging streams with bounded concurrency)
      *
@@ -3893,6 +4021,12 @@ export declare const mergeAll: {
      * Effect.runPromise(program)
      * // Output: [ "B", "A" ]
      * ```
+     *
+     * @see {@link merge} for merging exactly two streams and choosing a halt strategy
+     * @see {@link flatten} for flattening a stream that already emits streams
+     *
+     * @category Merging
+     * @since 2.0.0
      */
     <A, E, R>(streams: Iterable<Stream<A, E, R>>, options: {
         readonly concurrency: number | "unbounded";
@@ -5194,6 +5328,19 @@ export declare const filter: {
 /**
  * Filters and maps stream elements in one pass using a `Filter`.
  *
+ * **When to use**
+ *
+ * Use to keep only stream elements accepted by a `Filter` and emit each filter
+ * success value.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+ *
+ * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+ * @see {@link filterMapEffect} for an effectful `Filter`
+ * @see {@link partition} for consuming both filter success and failure values
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -5201,6 +5348,19 @@ export declare const filterMap: {
     /**
      * Filters and maps stream elements in one pass using a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to keep only stream elements accepted by a `Filter` and emit each filter
+     * success value.
+     *
+     * **Details**
+     *
+     * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+     *
+     * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+     * @see {@link filterMapEffect} for an effectful `Filter`
+     * @see {@link partition} for consuming both filter success and failure values
+     *
      * @category filtering
      * @since 2.0.0
      */
@@ -5208,13 +5368,26 @@ export declare const filterMap: {
     /**
      * Filters and maps stream elements in one pass using a `Filter`.
      *
+     * **When to use**
+     *
+     * Use to keep only stream elements accepted by a `Filter` and emit each filter
+     * success value.
+     *
+     * **Details**
+     *
+     * `Result.succeed` values are emitted and `Result.fail` values are skipped.
+     *
+     * @see {@link filter} for keeping original elements with a boolean predicate or refinement
+     * @see {@link filterMapEffect} for an effectful `Filter`
+     * @see {@link partition} for consuming both filter success and failure values
+     *
      * @category filtering
      * @since 2.0.0
      */
     <A, E, R, B, X>(self: Stream<A, E, R>, filter: Filter.Filter<A, B, X>): Stream<B, E, R>;
 };
 /**
- * Effectfully filters elements in a single pass.
+ * Filters elements in a single pass effectfully.
  *
  * **Example** (Effectfully filtering stream values)
  *
@@ -5237,7 +5410,7 @@ export declare const filterMap: {
  */
 export declare const filterEffect: {
     /**
-     * Effectfully filters elements in a single pass.
+     * Filters elements in a single pass effectfully.
      *
      * **Example** (Effectfully filtering stream values)
      *
@@ -5260,7 +5433,7 @@ export declare const filterEffect: {
      */
     <A, EX, RX>(predicate: (a: NoInfer<A>, i: number) => Effect.Effect<boolean, EX, RX>): <E, R>(self: Stream<A, E, R>) => Stream<A, E | EX, R | RX>;
     /**
-     * Effectfully filters elements in a single pass.
+     * Filters elements in a single pass effectfully.
      *
      * **Example** (Effectfully filtering stream values)
      *
@@ -5284,21 +5457,63 @@ export declare const filterEffect: {
     <A, E, R, EX, RX>(self: Stream<A, E, R>, predicate: (a: NoInfer<A>, i: number) => Effect.Effect<boolean, EX, RX>): Stream<A, E | EX, R | RX>;
 };
 /**
- * Effectfully filters and maps elements in a single pass.
+ * Filters and maps elements in one pass effectfully using a `FilterEffect`.
+ *
+ * **When to use**
+ *
+ * Use to apply effectful logic that can reject stream elements or emit
+ * transformed values before they continue downstream.
+ *
+ * **Details**
+ *
+ * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+ * effect failures fail the stream.
+ *
+ * @see {@link filterMap} for the synchronous `Filter` variant
+ * @see {@link filterEffect} for effectfully keeping original elements
+ * @see {@link mapEffect} for effectfully transforming every element
  *
  * @category filtering
  * @since 2.0.0
  */
 export declare const filterMapEffect: {
     /**
-     * Effectfully filters and maps elements in a single pass.
+     * Filters and maps elements in one pass effectfully using a `FilterEffect`.
+     *
+     * **When to use**
+     *
+     * Use to apply effectful logic that can reject stream elements or emit
+     * transformed values before they continue downstream.
+     *
+     * **Details**
+     *
+     * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+     * effect failures fail the stream.
+     *
+     * @see {@link filterMap} for the synchronous `Filter` variant
+     * @see {@link filterEffect} for effectfully keeping original elements
+     * @see {@link mapEffect} for effectfully transforming every element
      *
      * @category filtering
      * @since 2.0.0
      */
     <A, B, X, EX, RX>(filter: Filter.FilterEffect<NoInfer<A>, B, X, EX, RX>): <E, R>(self: Stream<A, E, R>) => Stream<B, E | EX, R | RX>;
     /**
-     * Effectfully filters and maps elements in a single pass.
+     * Filters and maps elements in one pass effectfully using a `FilterEffect`.
+     *
+     * **When to use**
+     *
+     * Use to apply effectful logic that can reject stream elements or emit
+     * transformed values before they continue downstream.
+     *
+     * **Details**
+     *
+     * `Result.succeed` values are emitted, `Result.fail` values are skipped, and
+     * effect failures fail the stream.
+     *
+     * @see {@link filterMap} for the synchronous `Filter` variant
+     * @see {@link filterEffect} for effectfully keeping original elements
+     * @see {@link mapEffect} for effectfully transforming every element
      *
      * @category filtering
      * @since 2.0.0
@@ -5428,12 +5643,21 @@ export declare const partitionQueue: {
  * Splits a stream with an effectful `Filter`, returning scoped streams for
  * filter successes and failures.
  *
+ * **When to use**
+ *
+ * Use when each stream element must be classified by an effectful `Filter` and
+ * both passing and failing mapped values need to be consumed as streams.
+ *
  * **Details**
  *
  * The returned streams are backed by queues in the current scope and should be
  * consumed while that scope remains open. The first stream emits success values
  * from the filter, and the second emits failure values.
  *
+ * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+ * @see {@link partitionQueue} for the lower-level queue result
+ * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -5442,12 +5666,21 @@ export declare const partitionEffect: {
      * Splits a stream with an effectful `Filter`, returning scoped streams for
      * filter successes and failures.
      *
+     * **When to use**
+     *
+     * Use when each stream element must be classified by an effectful `Filter` and
+     * both passing and failing mapped values need to be consumed as streams.
+     *
      * **Details**
      *
      * The returned streams are backed by queues in the current scope and should be
      * consumed while that scope remains open. The first stream emits success values
      * from the filter, and the second emits failure values.
      *
+     * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+     * @see {@link partitionQueue} for the lower-level queue result
+     * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -5462,12 +5695,21 @@ export declare const partitionEffect: {
      * Splits a stream with an effectful `Filter`, returning scoped streams for
      * filter successes and failures.
      *
+     * **When to use**
+     *
+     * Use when each stream element must be classified by an effectful `Filter` and
+     * both passing and failing mapped values need to be consumed as streams.
+     *
      * **Details**
      *
      * The returned streams are backed by queues in the current scope and should be
      * consumed while that scope remains open. The first stream emits success values
      * from the filter, and the second emits failure values.
      *
+     * @see {@link partition} for the pure `Filter` variant, which returns the failing stream before the passing stream
+     * @see {@link partitionQueue} for the lower-level queue result
+     * @see {@link filterMapEffect} for effectful filtering that discards failed filter results
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -5787,7 +6029,7 @@ export declare const peel: {
  * // Output: [ 1, 2, 3 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const buffer: {
@@ -5819,7 +6061,7 @@ export declare const buffer: {
      * // Output: [ 1, 2, 3 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     (options: {
@@ -5856,7 +6098,7 @@ export declare const buffer: {
      * // Output: [ 1, 2, 3 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, options: {
@@ -5893,7 +6135,7 @@ export declare const buffer: {
  * // Output: [ 1, 2, 3, 4 ]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 4.0.0
  */
 export declare const bufferArray: {
@@ -5924,7 +6166,7 @@ export declare const bufferArray: {
      * // Output: [ 1, 2, 3, 4 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 4.0.0
      */
     (options: {
@@ -5960,7 +6202,7 @@ export declare const bufferArray: {
      * // Output: [ 1, 2, 3, 4 ]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 4.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, options: {
@@ -6187,7 +6429,7 @@ export {
  */
 catch_ as catch };
 /**
- * Effectfully peeks at errors without changing the stream unless the tap fails.
+ * Peeks at errors effectfully without changing the stream unless the tap fails.
  *
  * **Example** (Effectfully peeking at errors)
  *
@@ -6216,7 +6458,7 @@ catch_ as catch };
  */
 export declare const tapError: {
     /**
-     * Effectfully peeks at errors without changing the stream unless the tap fails.
+     * Peeks at errors effectfully without changing the stream unless the tap fails.
      *
      * **Example** (Effectfully peeking at errors)
      *
@@ -6245,7 +6487,7 @@ export declare const tapError: {
      */
     <E, A2, E2, R2>(f: (error: E) => Effect.Effect<A2, E2, R2>): <A, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>;
     /**
-     * Effectfully peeks at errors without changing the stream unless the tap fails.
+     * Peeks at errors effectfully without changing the stream unless the tap fails.
      *
      * **Example** (Effectfully peeking at errors)
      *
@@ -6343,7 +6585,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <E, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(refinement: Refinement<NoInfer<E>, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A2 | A | A3, E2 | E3, R2 | R | R3>;
+    <E, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(refinement: Refinement<NoInfer<E>, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
     /**
      * Recovers from errors that match a predicate by switching to a recovery stream.
      *
@@ -6378,7 +6620,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <E, A2, E2, R2, A3 = never, E3 = E, R3 = never>(predicate: Predicate<NoInfer<E>>, f: (e: NoInfer<E>) => Stream<A2, E2, R2>, orElse?: ((e: NoInfer<E>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A2 | A | A3, E2 | E3, R2 | R | R3>;
+    <E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(predicate: Predicate<NoInfer<E>>, f: (e: NoInfer<E>) => Stream<A2, E2, R2>, orElse?: ((e: NoInfer<E>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>;
     /**
      * Recovers from errors that match a predicate by switching to a recovery stream.
      *
@@ -6413,7 +6655,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <A, E, R, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(self: Stream<A, E, R>, refinement: Refinement<E, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>;
+    <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, refinement: Refinement<E, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
     /**
      * Recovers from errors that match a predicate by switching to a recovery stream.
      *
@@ -6448,12 +6690,27 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <A, E, R, A2, E2, R2, A3 = never, E3 = E, R3 = never>(self: Stream<A, E, R>, predicate: Predicate<E>, f: (e: E) => Stream<A2, E2, R2>, orElse?: ((e: E) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>;
+    <A, E, R, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, predicate: Predicate<E>, f: (e: E) => Stream<A2, E2, R2>, orElse?: ((e: E) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>;
 };
 /**
  * Recovers from errors that match a `Filter` by switching to a recovery
  * stream.
  *
+ * **When to use**
+ *
+ * Use to recover from stream errors with a reusable `Filter` when matching can
+ * also narrow or transform the error before choosing the recovery stream.
+ *
+ * **Details**
+ *
+ * Successful filter results are passed to `f`. Failed filter results go to
+ * `orElse` when provided; otherwise the filter failure is re-failed.
+ *
+ * @see {@link catchIf} for predicate or refinement based recovery
+ * @see {@link catchTag} for `_tag` based recovery from one tagged error
+ * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+ * @see {@link catchCauseFilter} for filtering full causes
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -6462,18 +6719,48 @@ export declare const catchFilter: {
      * Recovers from errors that match a `Filter` by switching to a recovery
      * stream.
      *
+     * **When to use**
+     *
+     * Use to recover from stream errors with a reusable `Filter` when matching can
+     * also narrow or transform the error before choosing the recovery stream.
+     *
+     * **Details**
+     *
+     * Successful filter results are passed to `f`. Failed filter results go to
+     * `orElse` when provided; otherwise the filter failure is re-failed.
+     *
+     * @see {@link catchIf} for predicate or refinement based recovery
+     * @see {@link catchTag} for `_tag` based recovery from one tagged error
+     * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+     * @see {@link catchCauseFilter} for filtering full causes
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <E, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(filter: Filter.Filter<NoInfer<E>, EB, X>, f: (failure: EB) => Stream<A2, E2, R2>, orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | A3, E2 | E3, R | R2 | R3>;
+    <E, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(filter: Filter.Filter<NoInfer<E>, EB, X>, f: (failure: EB) => Stream<A2, E2, R2>, orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>;
     /**
      * Recovers from errors that match a `Filter` by switching to a recovery
      * stream.
      *
+     * **When to use**
+     *
+     * Use to recover from stream errors with a reusable `Filter` when matching can
+     * also narrow or transform the error before choosing the recovery stream.
+     *
+     * **Details**
+     *
+     * Successful filter results are passed to `f`. Failed filter results go to
+     * `orElse` when provided; otherwise the filter failure is re-failed.
+     *
+     * @see {@link catchIf} for predicate or refinement based recovery
+     * @see {@link catchTag} for `_tag` based recovery from one tagged error
+     * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
+     * @see {@link catchCauseFilter} for filtering full causes
+     *
      * @category error handling
      * @since 4.0.0
      */
-    <A, E, R, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(self: Stream<A, E, R>, filter: Filter.Filter<NoInfer<E>, EB, X>, f: (failure: EB) => Stream<A2, E2, R2>, orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | A3, E2 | E3, R | R2 | R3>;
+    <A, E, R, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, filter: Filter.Filter<NoInfer<E>, EB, X>, f: (failure: EB) => Stream<A2, E2, R2>, orElse?: ((failure: X) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>;
 };
 /**
  * Recovers from failures whose `_tag` matches the provided value by switching to
@@ -6481,7 +6768,7 @@ export declare const catchFilter: {
  *
  * **When to use**
  *
- * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+ * Use when your error type is a tagged union with a readonly `_tag`
  * field and you want to handle a specific error case.
  *
  * **Example** (Catching tagged failures)
@@ -6516,7 +6803,7 @@ export declare const catchTag: {
      *
      * **When to use**
      *
-     * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+     * Use when your error type is a tagged union with a readonly `_tag`
      * field and you want to handle a specific error case.
      *
      * **Example** (Catching tagged failures)
@@ -6544,14 +6831,14 @@ export declare const catchTag: {
      * @category error handling
      * @since 2.0.0
      */
-    <const K extends Tags<E> | Arr.NonEmptyReadonlyArray<Tags<E>>, E, A1, E1, R1, A2 = never, E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, R2 = never>(k: K, f: (e: ExtractTag<NoInfer<E>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A1, E1, R1>, orElse?: ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A2, E2, R2>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A1 | A | A2, E1 | E2, R1 | R | R2>;
+    <const K extends Tags<E> | Arr.NonEmptyReadonlyArray<Tags<E>>, E, A1, E1, R1, A2 = unassigned, E2 = never, R2 = never>(k: K, f: (e: ExtractTag<NoInfer<E>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A1, E1, R1>, orElse?: ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A2, E2, R2>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A1 | Exclude<A2, unassigned>, E1 | E2 | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never), R | R1 | R2>;
     /**
      * Recovers from failures whose `_tag` matches the provided value by switching to
      * the stream returned by `f`.
      *
      * **When to use**
      *
-     * Use `catchTag` when your error type is a tagged union with a readonly `_tag`
+     * Use when your error type is a tagged union with a readonly `_tag`
      * field and you want to handle a specific error case.
      *
      * **Example** (Catching tagged failures)
@@ -6579,7 +6866,7 @@ export declare const catchTag: {
      * @category error handling
      * @since 2.0.0
      */
-    <A, E, R, const K extends Tags<E> | Arr.NonEmptyReadonlyArray<Tags<E>>, R1, E1, A1, A2 = never, E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, R2 = never>(self: Stream<A, E, R>, k: K, f: (e: ExtractTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A1, E1, R1>, orElse?: ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A2, E2, R2>) | undefined): Stream<A1 | A | A2, E1 | E2, R1 | R | R2>;
+    <A, E, R, const K extends Tags<E> | Arr.NonEmptyReadonlyArray<Tags<E>>, R1, E1, A1, A2 = unassigned, E2 = never, R2 = never>(self: Stream<A, E, R>, k: K, f: (e: ExtractTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A1, E1, R1>, orElse?: ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Stream<A2, E2, R2>) | undefined): Stream<A | A1 | Exclude<A2, unassigned>, E1 | E2 | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never), R | R1 | R2>;
 };
 /**
  * Switches to a recovery stream based on matching `_tag` handlers.
@@ -6662,13 +6949,13 @@ export declare const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, {
             _tag: K;
         }>) => Stream<any, any, any>;
-    } : {}), A2 = never, E2 = Exclude<E, {
-        _tag: keyof Cases;
-    }>, R2 = never>(cases: Cases, orElse?: ((e: Exclude<E, {
+    } : {}), A2 = unassigned, E2 = never, R2 = never>(cases: Cases, orElse?: ((e: Exclude<E, {
         _tag: keyof Cases;
-    }>) => Stream<A2, E2, R2>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | {
+    }>) => Stream<A2, E2, R2>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | Exclude<A2, unassigned> | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<infer A, any, any>) ? A : never;
-    }[keyof Cases], E2 | {
+    }[keyof Cases], E2 | (A2 extends unassigned ? Exclude<E, {
+        _tag: keyof Cases;
+    }> : never) | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, infer E, any>) ? E : never;
     }[keyof Cases], R | R2 | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, any, infer R>) ? R : never;
@@ -6716,13 +7003,13 @@ export declare const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, {
             _tag: K;
         }>) => Stream<any, any, any>;
-    } : {}), A2 = never, E2 = Exclude<E, {
-        _tag: keyof Cases;
-    }>, R2 = never>(self: Stream<A, E, R>, cases: Cases, orElse?: ((e: Exclude<E, {
+    } : {}), A2 = unassigned, E2 = never, R2 = never>(self: Stream<A, E, R>, cases: Cases, orElse?: ((e: Exclude<E, {
         _tag: keyof Cases;
-    }>) => Stream<A2, E2, R2>) | undefined): Stream<A | A2 | {
+    }>) => Stream<A2, E2, R2>) | undefined): Stream<A | Exclude<A2, unassigned> | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<infer A, any, any>) ? A : never;
-    }[keyof Cases], E2 | {
+    }[keyof Cases], E2 | (A2 extends unassigned ? Exclude<E, {
+        _tag: keyof Cases;
+    }> : never) | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, infer E, any>) ? E : never;
     }[keyof Cases], R | R2 | {
         [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Stream<any, any, infer R>) ? R : never;
@@ -6733,7 +7020,7 @@ export declare const catchTags: {
  *
  * **When to use**
  *
- * Use this to handle nested error causes without removing the parent error
+ * Use to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
  * **Example** (Catching a tagged error reason)
@@ -6780,7 +7067,7 @@ export declare const catchReason: {
      *
      * **When to use**
      *
-     * Use this to handle nested error causes without removing the parent error
+     * Use to handle nested error causes without removing the parent error
      * from the error channel. The handler receives the unwrapped reason.
      *
      * **Example** (Catching a tagged error reason)
@@ -6821,13 +7108,13 @@ export declare const catchReason: {
      * @category error handling
      * @since 4.0.0
      */
-    <K extends Tags<E>, E, RK extends ReasonTags<ExtractTag<NoInfer<E>, K>>, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(errorTag: K, reasonTag: RK, f: (reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>, error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>) => Stream<A2, E2, R2>, orElse?: ((reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, RK>, error: OmitReason<ExtractTag<NoInfer<E>, K>, RK>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | Exclude<A3, unassigned>, (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3, R | R2 | R3>;
+    <K extends Tags<E>, E, RK extends ReasonTags<ExtractTag<NoInfer<E>, K>>, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(errorTag: K, reasonTag: RK, f: (reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>, error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>) => Stream<A2, E2, R2>, orElse?: ((reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, RK>, error: OmitReason<ExtractTag<NoInfer<E>, K>, RK>) => Stream<A3, E3, R3>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | A2 | Exclude<A3, unassigned>, ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never), R | R2 | R3>;
     /**
      * Catches a specific reason within a tagged error.
      *
      * **When to use**
      *
-     * Use this to handle nested error causes without removing the parent error
+     * Use to handle nested error causes without removing the parent error
      * from the error channel. The handler receives the unwrapped reason.
      *
      * **Example** (Catching a tagged error reason)
@@ -6868,7 +7155,7 @@ export declare const catchReason: {
      * @category error handling
      * @since 4.0.0
      */
-    <A, E, R, K extends Tags<E>, RK extends ReasonTags<ExtractTag<E, K>>, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, errorTag: K, reasonTag: RK, f: (reason: ExtractReason<ExtractTag<E, K>, RK>, error: NarrowReason<ExtractTag<E, K>, RK>) => Stream<A2, E2, R2>, orElse?: ((reason: ExcludeReason<ExtractTag<E, K>, RK>, error: OmitReason<ExtractTag<E, K>, RK>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3, R | R2 | R3>;
+    <A, E, R, K extends Tags<E>, RK extends ReasonTags<ExtractTag<E, K>>, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, errorTag: K, reasonTag: RK, f: (reason: ExtractReason<ExtractTag<E, K>, RK>, error: NarrowReason<ExtractTag<E, K>, RK>) => Stream<A2, E2, R2>, orElse?: ((reason: ExcludeReason<ExtractTag<E, K>, RK>, error: OmitReason<ExtractTag<E, K>, RK>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never), R | R2 | R3>;
 };
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
@@ -6959,7 +7246,7 @@ export declare const catchReasons: {
         [RK in ReasonTags<ExtractTag<NoInfer<E>, K>>]+?: (reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>, error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>) => Stream<any, any, any>;
     }, A2 = unassigned, E2 = never, R2 = never>(errorTag: K, cases: Cases, orElse?: ((reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>, error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>) => Stream<A2, E2, R2>) | undefined): <A, R>(self: Stream<A, E, R>) => Stream<A | Exclude<A2, unassigned> | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<infer A, any, any> ? A : never;
-    }[keyof Cases], (A2 extends unassigned ? E : ExcludeTag<E, K>) | E2 | {
+    }[keyof Cases], ExcludeTag<E, K> | E2 | (A2 extends unassigned ? ExtractTag<E, K> : never) | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, infer E, any> ? E : never;
     }[keyof Cases], R | R2 | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, any, infer R> ? R : never;
@@ -7010,7 +7297,7 @@ export declare const catchReasons: {
         [RK in ReasonTags<ExtractTag<E, K>>]+?: (reason: ExtractReason<ExtractTag<E, K>, RK>, error: NarrowReason<ExtractTag<E, K>, RK>) => Stream<any, any, any>;
     }, A2 = unassigned, E2 = never, R2 = never>(self: Stream<A, E, R>, errorTag: K, cases: Cases, orElse?: ((reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>, error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>) => Stream<A2, E2, R2>) | undefined): Stream<A | Exclude<A2, unassigned> | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<infer A, any, any> ? A : never;
-    }[keyof Cases], (A2 extends unassigned ? E : ExcludeTag<E, K>) | E2 | {
+    }[keyof Cases], ExcludeTag<E, K> | E2 | (A2 extends unassigned ? ExtractTag<E, K> : never) | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, infer E, any> ? E : never;
     }[keyof Cases], R | R2 | {
         [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Stream<any, any, infer R> ? R : never;
@@ -7184,6 +7471,22 @@ export declare const catchCauseIf: {
  * Recovers from stream failures by filtering the `Cause` and switching to a
  * recovery stream.
  *
+ * **When to use**
+ *
+ * Use when you need to recover a stream only from causes selected by a
+ * `Filter`, and the recovery needs both the selected value and the original
+ * `Cause`.
+ *
+ * **Details**
+ *
+ * The filter is applied to the full `Cause`. A successful filter result is
+ * passed to `f` together with the original cause; a failed filter result
+ * re-fails with the residual cause.
+ *
+ * @see {@link catchCauseIf} for predicate-based cause selection
+ * @see {@link catchFilter} for filtering typed error values instead of full causes
+ * @see {@link catchCause} for recovering from every cause without filtering
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -7192,6 +7495,22 @@ export declare const catchCauseFilter: {
      * Recovers from stream failures by filtering the `Cause` and switching to a
      * recovery stream.
      *
+     * **When to use**
+     *
+     * Use when you need to recover a stream only from causes selected by a
+     * `Filter`, and the recovery needs both the selected value and the original
+     * `Cause`.
+     *
+     * **Details**
+     *
+     * The filter is applied to the full `Cause`. A successful filter result is
+     * passed to `f` together with the original cause; a failed filter result
+     * re-fails with the residual cause.
+     *
+     * @see {@link catchCauseIf} for predicate-based cause selection
+     * @see {@link catchFilter} for filtering typed error values instead of full causes
+     * @see {@link catchCause} for recovering from every cause without filtering
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -7200,6 +7519,22 @@ export declare const catchCauseFilter: {
      * Recovers from stream failures by filtering the `Cause` and switching to a
      * recovery stream.
      *
+     * **When to use**
+     *
+     * Use when you need to recover a stream only from causes selected by a
+     * `Filter`, and the recovery needs both the selected value and the original
+     * `Cause`.
+     *
+     * **Details**
+     *
+     * The filter is applied to the full `Cause`. A successful filter result is
+     * passed to `f` together with the original cause; a failed filter result
+     * re-fails with the residual cause.
+     *
+     * @see {@link catchCauseIf} for predicate-based cause selection
+     * @see {@link catchFilter} for filtering typed error values instead of full causes
+     * @see {@link catchCause} for recovering from every cause without filtering
+     *
      * @category error handling
      * @since 4.0.0
      */
@@ -7384,7 +7719,9 @@ export declare const orDie: <A, E, R>(self: Stream<A, E, R>) => Stream<A, never,
  *
  * **When to use**
  *
- * Use the `log` option to emit the full {@link Cause} when the stream fails.
+ * Use when you want a failing stream to end gracefully rather than propagate
+ * the error. The `log` option controls whether the failure is logged before
+ * the stream terminates.
  *
  * **Example** (Ignoring stream failures)
  *
@@ -7420,6 +7757,8 @@ export declare const orDie: <A, E, R>(self: Stream<A, E, R>) => Stream<A, never,
  * // []
  * ```
  *
+ * @see {@link ignoreCause} for a variant that also ignores defects, not just typed failures
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -7433,7 +7772,9 @@ export declare const ignore: <Arg extends Stream<any, any, any> | {
  *
  * **When to use**
  *
- * Use the `log` option to emit the full {@link Cause} when the stream fails.
+ * Use when a stream may fail with defects and you want to silently suppress the
+ * entire failure cause — including both typed errors and defects — rather than
+ * propagate it downstream.
  *
  * **Example** (Ignoring stream failure causes)
  *
@@ -7452,6 +7793,8 @@ export declare const ignore: <Arg extends Stream<any, any, any> | {
  * // [ 1, 2 ]
  * ```
  *
+ * @see {@link ignore} to ignore only typed failures without suppressing defects
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -7461,7 +7804,7 @@ export declare const ignoreCause: <Arg extends Stream<any, any, any> | {
     readonly log?: boolean | Severity | undefined;
 } | undefined) => [Arg] extends [Stream<infer A, infer _E, infer R>] ? Stream<A, never, R> : <A, E, R>(self: Stream<A, E, R>) => Stream<A, never, R>;
 /**
- * When the stream fails, retry it according to the given schedule.
+ * Retries the stream according to the given schedule when it fails.
  *
  * **Details**
  *
@@ -7496,7 +7839,7 @@ export declare const ignoreCause: <Arg extends Stream<any, any, any> | {
  */
 export declare const retry: {
     /**
-     * When the stream fails, retry it according to the given schedule.
+     * Retries the stream according to the given schedule when it fails.
      *
      * **Details**
      *
@@ -7531,7 +7874,7 @@ export declare const retry: {
      */
     <E, X, E2, R2>(policy: Schedule.Schedule<X, NoInfer<E>, E2, R2> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<E>, SE, SR>) => Schedule.Schedule<SO, E, SE, SR>) => Schedule.Schedule<X, NoInfer<E>, E2, R2>)): <A, R>(self: Stream<A, E, R>) => Stream<A, E | E2, R2 | R>;
     /**
-     * When the stream fails, retry it according to the given schedule.
+     * Retries the stream according to the given schedule when it fails.
      *
      * **Details**
      *
@@ -7567,7 +7910,7 @@ export declare const retry: {
     <A, E, R, X, E2, R2>(self: Stream<A, E, R>, policy: Schedule.Schedule<X, NoInfer<E>, E2, R2> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<E>, SE, SR>) => Schedule.Schedule<SO, E, SE, SR>) => Schedule.Schedule<X, NoInfer<E>, E2, R2>)): Stream<A, E | E2, R2 | R>;
 };
 /**
- * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+ * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
  * **Details**
@@ -7611,7 +7954,7 @@ export declare const retry: {
  */
 export declare const withExecutionPlan: {
     /**
-     * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+     * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
      * until it succeeds or the plan is exhausted.
      *
      * **Details**
@@ -7662,7 +8005,7 @@ export declare const withExecutionPlan: {
         readonly preventFallbackOnPartialStream?: boolean | undefined;
     }): <A, E extends Input, R>(self: Stream<A, E, R>) => Stream<A, E | PolicyE, R2 | Exclude<R, Provides>>;
     /**
-     * Apply an `ExecutionPlan` to a stream, retrying with step-provided resources
+     * Applies an `ExecutionPlan` to a stream, retrying with step-provided resources
      * until it succeeds or the plan is exhausted.
      *
      * **Details**
@@ -7970,7 +8313,7 @@ export declare const takeUntil: {
     }): Stream<A, E, R>;
 };
 /**
- * Effectful predicate version of `takeUntil`.
+ * Takes stream elements until an effectful predicate returns `true`.
  *
  * **Example** (Taking until an effectful predicate matches)
  *
@@ -7994,7 +8337,7 @@ export declare const takeUntil: {
  */
 export declare const takeUntilEffect: {
     /**
-     * Effectful predicate version of `takeUntil`.
+     * Takes stream elements until an effectful predicate returns `true`.
      *
      * **Example** (Taking until an effectful predicate matches)
      *
@@ -8020,7 +8363,7 @@ export declare const takeUntilEffect: {
         readonly excludeLast?: boolean | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>;
     /**
-     * Effectful predicate version of `takeUntil`.
+     * Takes stream elements until an effectful predicate returns `true`.
      *
      * **Example** (Taking until an effectful predicate matches)
      *
@@ -8176,10 +8519,19 @@ export declare const takeWhile: {
  * Takes the longest initial prefix accepted by a `Filter` and emits the
  * filter's success values.
  *
+ * **When to use**
+ *
+ * Use to keep the leading stream elements that a `Filter` accepts, emit the
+ * filter's success values, and stop at the first filter failure.
+ *
  * **Details**
  *
  * The stream stops at the first `Result.fail` returned by the filter.
  *
+ * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+ * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+ * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -8188,10 +8540,19 @@ export declare const takeWhileFilter: {
      * Takes the longest initial prefix accepted by a `Filter` and emits the
      * filter's success values.
      *
+     * **When to use**
+     *
+     * Use to keep the leading stream elements that a `Filter` accepts, emit the
+     * filter's success values, and stop at the first filter failure.
+     *
      * **Details**
      *
      * The stream stops at the first `Result.fail` returned by the filter.
      *
+     * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+     * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+     * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -8200,10 +8561,19 @@ export declare const takeWhileFilter: {
      * Takes the longest initial prefix accepted by a `Filter` and emits the
      * filter's success values.
      *
+     * **When to use**
+     *
+     * Use to keep the leading stream elements that a `Filter` accepts, emit the
+     * filter's success values, and stop at the first filter failure.
+     *
      * **Details**
      *
      * The stream stops at the first `Result.fail` returned by the filter.
      *
+     * @see {@link takeWhile} for keeping original elements with a boolean predicate or refinement
+     * @see {@link filterMap} for filtering across the whole stream instead of only the leading prefix
+     * @see {@link dropWhileFilter} for dropping the accepted prefix and keeping the remaining original elements
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -8586,6 +8956,21 @@ export declare const dropWhile: {
 /**
  * Drops elements while the filter succeeds.
  *
+ * **When to use**
+ *
+ * Use when you need to remove a leading stream prefix based on a synchronous
+ * `Filter` result while preserving the remaining original stream elements.
+ *
+ * **Details**
+ *
+ * `Result.succeed` drops the current element. The first `Result.fail` stops
+ * dropping, emits that original element, and the rest of the source stream is
+ * emitted without further filtering.
+ *
+ * @see {@link dropWhile} for boolean predicate prefix dropping
+ * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+ * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+ *
  * @category filtering
  * @since 4.0.0
  */
@@ -8593,6 +8978,21 @@ export declare const dropWhileFilter: {
     /**
      * Drops elements while the filter succeeds.
      *
+     * **When to use**
+     *
+     * Use when you need to remove a leading stream prefix based on a synchronous
+     * `Filter` result while preserving the remaining original stream elements.
+     *
+     * **Details**
+     *
+     * `Result.succeed` drops the current element. The first `Result.fail` stops
+     * dropping, emits that original element, and the rest of the source stream is
+     * emitted without further filtering.
+     *
+     * @see {@link dropWhile} for boolean predicate prefix dropping
+     * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+     * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -8600,6 +9000,21 @@ export declare const dropWhileFilter: {
     /**
      * Drops elements while the filter succeeds.
      *
+     * **When to use**
+     *
+     * Use when you need to remove a leading stream prefix based on a synchronous
+     * `Filter` result while preserving the remaining original stream elements.
+     *
+     * **Details**
+     *
+     * `Result.succeed` drops the current element. The first `Result.fail` stops
+     * dropping, emits that original element, and the rest of the source stream is
+     * emitted without further filtering.
+     *
+     * @see {@link dropWhile} for boolean predicate prefix dropping
+     * @see {@link takeWhileFilter} for keeping the accepted prefix as filter success values
+     * @see {@link dropWhileEffect} for effectful predicate prefix dropping
+     *
      * @category filtering
      * @since 4.0.0
      */
@@ -8784,12 +9199,12 @@ export declare const dropRight: {
  * // Output: [ [ 1, 2 ], [ 3, 4 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const chunks: <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
 /**
- * Re-chunks the stream into arrays of the specified size, preserving element order.
+ * Groups the stream into arrays of the specified size, preserving element order.
  *
  * **Details**
  *
@@ -8813,12 +9228,12 @@ export declare const chunks: <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonE
  * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const rechunk: {
     /**
-     * Re-chunks the stream into arrays of the specified size, preserving element order.
+     * Groups the stream into arrays of the specified size, preserving element order.
      *
      * **Details**
      *
@@ -8842,12 +9257,12 @@ export declare const rechunk: {
      * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     (size: number): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
     /**
-     * Re-chunks the stream into arrays of the specified size, preserving element order.
+     * Groups the stream into arrays of the specified size, preserving element order.
      *
      * **Details**
      *
@@ -8871,7 +9286,7 @@ export declare const rechunk: {
      * // Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, size: number): Stream<A, E, R>;
@@ -8895,7 +9310,7 @@ export declare const rechunk: {
  * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const sliding: {
@@ -8918,7 +9333,7 @@ export declare const sliding: {
      * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     (chunkSize: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -8941,7 +9356,7 @@ export declare const sliding: {
      * // Output: [ [1, 2], [2, 3], [3, 4], [4, 5] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, chunkSize: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -8966,7 +9381,7 @@ export declare const sliding: {
  * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const slidingSize: {
@@ -8990,7 +9405,7 @@ export declare const slidingSize: {
      * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     (chunkSize: number, stepSize: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -9014,7 +9429,7 @@ export declare const slidingSize: {
      * // Output: [ [ 1, 2, 3 ], [ 3, 4, 5 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, chunkSize: number, stepSize: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -9043,7 +9458,7 @@ export declare const slidingSize: {
  * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const split: {
@@ -9071,7 +9486,7 @@ export declare const split: {
      * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): <E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<Exclude<A, B>>, E, R>;
@@ -9099,7 +9514,7 @@ export declare const split: {
      * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A>(predicate: Predicate<NoInfer<A>>): <E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -9127,7 +9542,7 @@ export declare const split: {
      * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R, B extends A>(self: Stream<A, E, R>, refinement: Refinement<A, B>): Stream<Arr.NonEmptyReadonlyArray<Exclude<A, B>>, E, R>;
@@ -9155,7 +9570,7 @@ export declare const split: {
      * // Output: [ [1, 2, 3], [5, 6, 7], [9] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, predicate: Predicate<A>): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -9273,11 +9688,18 @@ export declare const combine: {
     <A, E, R, A2, E2, R2, S, A3, E3, R3>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<A, E, void>, pullRight: Pull.Pull<A2, E2, void>) => Effect.Effect<readonly [A3, S], E3, R3>): Stream<A3, E3, R | R2 | R3>;
 };
 /**
- * Combines the arrays (chunks) from this stream and the specified stream by
- * repeatedly applying the function `f` to extract an array using both sides and
- * conceptually "offer" it to the destination stream. `f` can maintain some
- * internal state to control the combining process, with the initial state
- * being specified by `s`.
+ * Combines two streams chunk-by-chunk with a stateful pull function.
+ *
+ * **When to use**
+ *
+ * Use to coordinate pulling chunks from two streams when each emitted chunk
+ * depends on both sides and local state.
+ *
+ * **Details**
+ *
+ * The combining function receives the current state and pull functions for the
+ * left and right streams. It returns the next non-empty chunk together with the
+ * next state.
  *
  * **Example** (Combining stream chunks with state)
  *
@@ -9310,11 +9732,18 @@ export declare const combine: {
  */
 export declare const combineArray: {
     /**
-     * Combines the arrays (chunks) from this stream and the specified stream by
-     * repeatedly applying the function `f` to extract an array using both sides and
-     * conceptually "offer" it to the destination stream. `f` can maintain some
-     * internal state to control the combining process, with the initial state
-     * being specified by `s`.
+     * Combines two streams chunk-by-chunk with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling chunks from two streams when each emitted chunk
+     * depends on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right streams. It returns the next non-empty chunk together with the
+     * next state.
      *
      * **Example** (Combining stream chunks with state)
      *
@@ -9347,11 +9776,18 @@ export declare const combineArray: {
      */
     <A2, E2, R2, S, E, A, A3, E3, R3>(that: Stream<A2, E2, R2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<Arr.NonEmptyReadonlyArray<A>, E, void>, pullRight: Pull.Pull<Arr.NonEmptyReadonlyArray<A2>, E2, void>) => Effect.Effect<readonly [Arr.NonEmptyReadonlyArray<A3>, S], E3, R3>): <R>(self: Stream<A, E, R>) => Stream<A3, Pull.ExcludeDone<E3>, R2 | R3 | R>;
     /**
-     * Combines the arrays (chunks) from this stream and the specified stream by
-     * repeatedly applying the function `f` to extract an array using both sides and
-     * conceptually "offer" it to the destination stream. `f` can maintain some
-     * internal state to control the combining process, with the initial state
-     * being specified by `s`.
+     * Combines two streams chunk-by-chunk with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling chunks from two streams when each emitted chunk
+     * depends on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right streams. It returns the next non-empty chunk together with the
+     * next state.
      *
      * **Example** (Combining stream chunks with state)
      *
@@ -9385,7 +9821,7 @@ export declare const combineArray: {
     <R, A2, E2, R2, S, E, A, A3, E3, R3>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<Arr.NonEmptyReadonlyArray<A>, E, void>, pullRight: Pull.Pull<Arr.NonEmptyReadonlyArray<A2>, E2, void>) => Effect.Effect<readonly [Arr.NonEmptyReadonlyArray<A3>, S], E3, R3>): Stream<A3, Pull.ExcludeDone<E3>, R | R2 | R3>;
 };
 /**
- * Statefully maps elements, emitting zero or more outputs per input.
+ * Maps elements statefully, emitting zero or more outputs per input.
  *
  * **Example** (Statefully mapping stream values)
  *
@@ -9413,7 +9849,7 @@ export declare const combineArray: {
  */
 export declare const mapAccum: {
     /**
-     * Statefully maps elements, emitting zero or more outputs per input.
+     * Maps elements statefully, emitting zero or more outputs per input.
      *
      * **Example** (Statefully mapping stream values)
      *
@@ -9443,7 +9879,7 @@ export declare const mapAccum: {
         readonly onHalt?: ((state: S) => ReadonlyArray<B>) | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<B, E, R>;
     /**
-     * Statefully maps elements, emitting zero or more outputs per input.
+     * Maps elements statefully, emitting zero or more outputs per input.
      *
      * **Example** (Statefully mapping stream values)
      *
@@ -9474,7 +9910,7 @@ export declare const mapAccum: {
     }): Stream<B, E, R>;
 };
 /**
- * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+ * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
  *
  * **Details**
  *
@@ -9506,7 +9942,7 @@ export declare const mapAccum: {
  */
 export declare const mapAccumArray: {
     /**
-     * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+     * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
      *
      * **Details**
      *
@@ -9540,7 +9976,7 @@ export declare const mapAccumArray: {
         readonly onHalt?: ((state: S) => ReadonlyArray<B>) | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<B, E, R>;
     /**
-     * Statefully maps over non-empty chunk arrays, emitting zero or more values per chunk.
+     * Maps over non-empty chunk arrays statefully, emitting zero or more values per chunk.
      *
      * **Details**
      *
@@ -9575,7 +10011,7 @@ export declare const mapAccumArray: {
     }): Stream<B, E, R>;
 };
 /**
- * Statefully and effectfully maps each element, emitting zero or more output
+ * Maps each element statefully and effectfully, emitting zero or more output
  * values per input.
  *
  * **Details**
@@ -9609,7 +10045,7 @@ export declare const mapAccumArray: {
  */
 export declare const mapAccumEffect: {
     /**
-     * Statefully and effectfully maps each element, emitting zero or more output
+     * Maps each element statefully and effectfully, emitting zero or more output
      * values per input.
      *
      * **Details**
@@ -9645,7 +10081,7 @@ export declare const mapAccumEffect: {
         readonly onHalt?: ((state: S) => ReadonlyArray<B>) | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>;
     /**
-     * Statefully and effectfully maps each element, emitting zero or more output
+     * Maps each element statefully and effectfully, emitting zero or more output
      * values per input.
      *
      * **Details**
@@ -9682,7 +10118,7 @@ export declare const mapAccumEffect: {
     }): Stream<B, E | E2, R | R2>;
 };
 /**
- * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+ * Maps each non-empty input chunk statefully and effectfully, emitting zero or
  * more output values per chunk.
  *
  * **Details**
@@ -9718,7 +10154,7 @@ export declare const mapAccumEffect: {
  */
 export declare const mapAccumArrayEffect: {
     /**
-     * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+     * Maps each non-empty input chunk statefully and effectfully, emitting zero or
      * more output values per chunk.
      *
      * **Details**
@@ -9756,7 +10192,7 @@ export declare const mapAccumArrayEffect: {
         readonly onHalt?: ((state: S) => ReadonlyArray<B>) | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<B, E | E2, R | R2>;
     /**
-     * Statefully and effectfully maps each non-empty input chunk, emitting zero or
+     * Maps each non-empty input chunk statefully and effectfully, emitting zero or
      * more output values per chunk.
      *
      * **Details**
@@ -9868,7 +10304,7 @@ export declare const scan: {
     <A, E, R, S>(self: Stream<A, E, R>, initial: S, f: (s: S, a: A) => S): Stream<S, E, R>;
 };
 /**
- * Effectfully accumulates state and emits the initial state plus each accumulated state.
+ * Accumulates state effectfully and emits the initial state plus each accumulated state.
  *
  * **Example** (Effectfully scanning stream state)
  *
@@ -9890,7 +10326,7 @@ export declare const scan: {
  */
 export declare const scanEffect: {
     /**
-     * Effectfully accumulates state and emits the initial state plus each accumulated state.
+     * Accumulates state effectfully and emits the initial state plus each accumulated state.
      *
      * **Example** (Effectfully scanning stream state)
      *
@@ -9912,7 +10348,7 @@ export declare const scanEffect: {
      */
     <S, A, E2, R2>(initial: S, f: (s: S, a: A) => Effect.Effect<S, E2, R2>): <E, R>(self: Stream<A, E, R>) => Stream<S, E | E2, R | R2>;
     /**
-     * Effectfully accumulates state and emits the initial state plus each accumulated state.
+     * Accumulates state effectfully and emits the initial state plus each accumulated state.
      *
      * **Example** (Effectfully scanning stream state)
      *
@@ -9955,7 +10391,7 @@ export declare const scanEffect: {
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const debounce: {
@@ -9980,7 +10416,7 @@ export declare const debounce: {
      * })
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     (duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
@@ -10005,19 +10441,23 @@ export declare const debounce: {
      * })
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, duration: Duration.Input): Stream<A, E, R>;
 };
 /**
- * Delays the arrays of this stream according to the given bandwidth
- * parameters using the token bucket algorithm. Allows for burst processing by
- * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
- * The weight of each array is determined by the effectful `cost` function.
+ * Rate-limits stream chunks with an effectful cost function.
+ *
+ * **When to use**
+ *
+ * Use to throttle chunks when computing each chunk's cost requires an effect.
  *
  * **Details**
  *
+ * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+ * and each chunk consumes the cost returned by the effectful `cost` function.
+ *
  * If using the "enforce" strategy, arrays that do not meet the bandwidth
  * constraints are dropped. If using the "shape" strategy, arrays are delayed
  * until they can be emitted without exceeding the bandwidth constraints.
@@ -10046,18 +10486,22 @@ export declare const debounce: {
  * // Output: [0, 1, 2, 3, 4, 5]
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const throttleEffect: {
     /**
-     * Delays the arrays of this stream according to the given bandwidth
-     * parameters using the token bucket algorithm. Allows for burst processing by
-     * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
-     * The weight of each array is determined by the effectful `cost` function.
+     * Rate-limits stream chunks with an effectful cost function.
+     *
+     * **When to use**
+     *
+     * Use to throttle chunks when computing each chunk's cost requires an effect.
      *
      * **Details**
      *
+     * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+     * and each chunk consumes the cost returned by the effectful `cost` function.
+     *
      * If using the "enforce" strategy, arrays that do not meet the bandwidth
      * constraints are dropped. If using the "shape" strategy, arrays are delayed
      * until they can be emitted without exceeding the bandwidth constraints.
@@ -10086,7 +10530,7 @@ export declare const throttleEffect: {
      * // Output: [0, 1, 2, 3, 4, 5]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E2, R2>(options: {
@@ -10097,13 +10541,17 @@ export declare const throttleEffect: {
         readonly strategy?: "enforce" | "shape" | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>;
     /**
-     * Delays the arrays of this stream according to the given bandwidth
-     * parameters using the token bucket algorithm. Allows for burst processing by
-     * allowing the bucket to accumulate tokens up to a `units + burst` threshold.
-     * The weight of each array is determined by the effectful `cost` function.
+     * Rate-limits stream chunks with an effectful cost function.
+     *
+     * **When to use**
+     *
+     * Use to throttle chunks when computing each chunk's cost requires an effect.
      *
      * **Details**
      *
+     * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+     * and each chunk consumes the cost returned by the effectful `cost` function.
+     *
      * If using the "enforce" strategy, arrays that do not meet the bandwidth
      * constraints are dropped. If using the "shape" strategy, arrays are delayed
      * until they can be emitted without exceeding the bandwidth constraints.
@@ -10132,7 +10580,7 @@ export declare const throttleEffect: {
      * // Output: [0, 1, 2, 3, 4, 5]
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R, E2, R2>(self: Stream<A, E, R>, options: {
@@ -10144,12 +10592,17 @@ export declare const throttleEffect: {
     }): Stream<A, E | E2, R | R2>;
 };
 /**
- * Delays the arrays of this stream using a token bucket and a per-array cost.
- * Allows bursts by letting the bucket accumulate up to a `units + burst`
- * threshold. The weight of each array is determined by the `cost` function.
+ * Rate-limits stream chunks with a synchronous cost function.
+ *
+ * **When to use**
+ *
+ * Use to throttle chunks when each chunk's cost can be computed synchronously.
  *
  * **Details**
  *
+ * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+ * and each chunk consumes the cost returned by `cost`.
+ *
  * If using the "enforce" strategy, arrays that do not meet the bandwidth
  * constraints are dropped. If using the "shape" strategy, arrays are delayed
  * until they can be emitted without exceeding the bandwidth constraints.
@@ -10178,17 +10631,22 @@ export declare const throttleEffect: {
  * })
  * ```
  *
- * @category Rate Limiting
+ * @category rate limiting
  * @since 2.0.0
  */
 export declare const throttle: {
     /**
-     * Delays the arrays of this stream using a token bucket and a per-array cost.
-     * Allows bursts by letting the bucket accumulate up to a `units + burst`
-     * threshold. The weight of each array is determined by the `cost` function.
+     * Rate-limits stream chunks with a synchronous cost function.
+     *
+     * **When to use**
+     *
+     * Use to throttle chunks when each chunk's cost can be computed synchronously.
      *
      * **Details**
      *
+     * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+     * and each chunk consumes the cost returned by `cost`.
+     *
      * If using the "enforce" strategy, arrays that do not meet the bandwidth
      * constraints are dropped. If using the "shape" strategy, arrays are delayed
      * until they can be emitted without exceeding the bandwidth constraints.
@@ -10217,7 +10675,7 @@ export declare const throttle: {
      * })
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A>(options: {
@@ -10228,12 +10686,17 @@ export declare const throttle: {
         readonly strategy?: "enforce" | "shape" | undefined;
     }): <E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
     /**
-     * Delays the arrays of this stream using a token bucket and a per-array cost.
-     * Allows bursts by letting the bucket accumulate up to a `units + burst`
-     * threshold. The weight of each array is determined by the `cost` function.
+     * Rate-limits stream chunks with a synchronous cost function.
+     *
+     * **When to use**
+     *
+     * Use to throttle chunks when each chunk's cost can be computed synchronously.
      *
      * **Details**
      *
+     * Uses a token bucket. The bucket can accumulate up to `units + burst` tokens,
+     * and each chunk consumes the cost returned by `cost`.
+     *
      * If using the "enforce" strategy, arrays that do not meet the bandwidth
      * constraints are dropped. If using the "shape" strategy, arrays are delayed
      * until they can be emitted without exceeding the bandwidth constraints.
@@ -10262,7 +10725,7 @@ export declare const throttle: {
      * })
      * ```
      *
-     * @category Rate Limiting
+     * @category rate limiting
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, options: {
@@ -10297,7 +10760,7 @@ export declare const throttle: {
  * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const grouped: {
@@ -10325,7 +10788,7 @@ export declare const grouped: {
      * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     (n: number): <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -10353,7 +10816,7 @@ export declare const grouped: {
      * // Output: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, n: number): Stream<Arr.NonEmptyReadonlyArray<A>, E, R>;
@@ -10379,7 +10842,7 @@ export declare const grouped: {
  * // Output: [ [ 1, 2 ], [ 3 ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const groupedWithin: {
@@ -10404,7 +10867,7 @@ export declare const groupedWithin: {
      * // Output: [ [ 1, 2 ], [ 3 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     (chunkSize: number, duration: Duration.Input): <A, E, R>(self: Stream<A, E, R>) => Stream<Array<A>, E, R>;
@@ -10429,7 +10892,7 @@ export declare const groupedWithin: {
      * // Output: [ [ 1, 2 ], [ 3 ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R>(self: Stream<A, E, R>, chunkSize: number, duration: Duration.Input): Stream<Array<A>, E, R>;
@@ -10463,7 +10926,7 @@ export declare const groupedWithin: {
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const groupBy: {
@@ -10496,7 +10959,7 @@ export declare const groupBy: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, K, V, E2, R2>(f: (a: NoInfer<A>) => Effect.Effect<readonly [K, V], E2, R2>, options?: {
@@ -10532,7 +10995,7 @@ export declare const groupBy: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R, K, V, E2, R2>(self: Stream<A, E, R>, f: (a: NoInfer<A>) => Effect.Effect<readonly [K, V], E2, R2>, options?: {
@@ -10567,7 +11030,7 @@ export declare const groupBy: {
  * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
  * ```
  *
- * @category Grouping
+ * @category grouping
  * @since 2.0.0
  */
 export declare const groupByKey: {
@@ -10598,7 +11061,7 @@ export declare const groupByKey: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, K>(f: (a: NoInfer<A>) => K, options?: {
@@ -10632,7 +11095,7 @@ export declare const groupByKey: {
      * // Output: [ [ "odd", [ 1, 3, 5 ] ], [ "even", [ 2, 4 ] ] ]
      * ```
      *
-     * @category Grouping
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R, K>(self: Stream<A, E, R>, f: (a: NoInfer<A>) => K, options?: {
@@ -10643,39 +11106,66 @@ export declare const groupByKey: {
 /**
  * Groups consecutive elements that have equal keys into non-empty arrays.
  *
+ * **When to use**
+ *
+ * Use when a stream is already ordered by the grouping key and you want to emit
+ * each consecutive run as a non-empty array while keeping later non-adjacent
+ * runs separate.
+ *
  * **Details**
  *
  * The key is computed with `f`; adjacent elements whose keys are equal by
  * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
  * with the same key are emitted separately.
  *
- * @category Grouping
+ * @see {@link groupByKey} for grouping all elements with the same key across the stream
+ * @see {@link groupBy} for custom grouped stream construction
+ *
+ * @category grouping
  * @since 2.0.0
  */
 export declare const groupAdjacentBy: {
     /**
      * Groups consecutive elements that have equal keys into non-empty arrays.
      *
+     * **When to use**
+     *
+     * Use when a stream is already ordered by the grouping key and you want to emit
+     * each consecutive run as a non-empty array while keeping later non-adjacent
+     * runs separate.
+     *
      * **Details**
      *
      * The key is computed with `f`; adjacent elements whose keys are equal by
      * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
      * with the same key are emitted separately.
      *
-     * @category Grouping
+     * @see {@link groupByKey} for grouping all elements with the same key across the stream
+     * @see {@link groupBy} for custom grouped stream construction
+     *
+     * @category grouping
      * @since 2.0.0
      */
     <A, K>(f: (a: NoInfer<A>) => K): <E, R>(self: Stream<A, E, R>) => Stream<readonly [K, Arr.NonEmptyArray<A>], E, R>;
     /**
      * Groups consecutive elements that have equal keys into non-empty arrays.
      *
+     * **When to use**
+     *
+     * Use when a stream is already ordered by the grouping key and you want to emit
+     * each consecutive run as a non-empty array while keeping later non-adjacent
+     * runs separate.
+     *
      * **Details**
      *
      * The key is computed with `f`; adjacent elements whose keys are equal by
      * `Equal.equals` are emitted as one `[key, group]`. Later non-adjacent runs
      * with the same key are emitted separately.
      *
-     * @category Grouping
+     * @see {@link groupByKey} for grouping all elements with the same key across the stream
+     * @see {@link groupBy} for custom grouped stream construction
+     *
+     * @category grouping
      * @since 2.0.0
      */
     <A, E, R, K>(self: Stream<A, E, R>, f: (a: NoInfer<A>) => K): Stream<readonly [K, Arr.NonEmptyArray<A>], E, R>;
@@ -10886,7 +11376,7 @@ export declare const aggregateWithin: {
     <A, E, R, B, A2, E2, R2, C, E3, R3>(self: Stream<A, E, R>, sink: Sink.Sink<B, A | A2, A2, E2, R2>, schedule: Schedule.Schedule<C, Option.Option<B>, E3, R3>): Stream<B, E | E2 | E3, R | R2 | R3>;
 };
 /**
- * Fan out the stream, producing a fixed-size tuple of streams that each emit
+ * Creates a fixed-size tuple of streams that each emit
  * the same elements as the source stream.
  *
  * **Details**
@@ -10926,7 +11416,7 @@ export declare const aggregateWithin: {
  */
 export declare const broadcastN: {
     /**
-     * Fan out the stream, producing a fixed-size tuple of streams that each emit
+     * Creates a fixed-size tuple of streams that each emit
      * the same elements as the source stream.
      *
      * **Details**
@@ -10975,7 +11465,7 @@ export declare const broadcastN: {
         readonly replay?: number | undefined;
     }): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<TupleOf<N, Stream<A, E>>, never, Scope.Scope | R>;
     /**
-     * Fan out the stream, producing a fixed-size tuple of streams that each emit
+     * Creates a fixed-size tuple of streams that each emit
      * the same elements as the source stream.
      *
      * **Details**
@@ -11961,7 +12451,7 @@ export declare const intersperse: {
     <A, E, R, A2>(self: Stream<A, E, R>, element: A2): Stream<A | A2, E, R>;
 };
 /**
- * Intersperse stream elements with a middle value, adding a start and end value.
+ * Adds a start value, middle value, and end value around stream elements.
  *
  * **Details**
  *
@@ -11990,7 +12480,7 @@ export declare const intersperse: {
  */
 export declare const intersperseAffixes: {
     /**
-     * Intersperse stream elements with a middle value, adding a start and end value.
+     * Adds a start value, middle value, and end value around stream elements.
      *
      * **Details**
      *
@@ -12023,7 +12513,7 @@ export declare const intersperseAffixes: {
         readonly end: A4;
     }): <A, E, R>(self: Stream<A, E, R>) => Stream<A2 | A3 | A4 | A, E, R>;
     /**
-     * Intersperse stream elements with a middle value, adding a start and end value.
+     * Adds a start value, middle value, and end value around stream elements.
      *
      * **Details**
      *
@@ -12360,7 +12850,21 @@ export declare const interruptWhen: {
     <A, E, R, X, E2, R2>(self: Stream<A, E, R>, effect: Effect.Effect<X, E2, R2>): Stream<A, E | E2, R | R2>;
 };
 /**
- * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+ * Stops a stream after the current element when an effect completes.
+ *
+ * **When to use**
+ *
+ * Use to stop before the next pull after an external signal completes.
+ *
+ * **Details**
+ *
+ * The effect is forked, its success value is discarded, and its failure fails
+ * the stream.
+ *
+ * **Gotchas**
+ *
+ * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+ * the stream should be interrupted immediately.
  *
  * **Example** (Halting a stream after an effect completes)
  *
@@ -12387,7 +12891,21 @@ export declare const interruptWhen: {
  */
 export declare const haltWhen: {
     /**
-     * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+     * Stops a stream after the current element when an effect completes.
+     *
+     * **When to use**
+     *
+     * Use to stop before the next pull after an external signal completes.
+     *
+     * **Details**
+     *
+     * The effect is forked, its success value is discarded, and its failure fails
+     * the stream.
+     *
+     * **Gotchas**
+     *
+     * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+     * the stream should be interrupted immediately.
      *
      * **Example** (Halting a stream after an effect completes)
      *
@@ -12414,7 +12932,21 @@ export declare const haltWhen: {
      */
     <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>;
     /**
-     * Halts evaluation after the current element once the provided effect completes; the effect is forked, its success is discarded, failures fail the stream, and it does not interrupt an in-progress pull (use `interruptWhen` for that).
+     * Stops a stream after the current element when an effect completes.
+     *
+     * **When to use**
+     *
+     * Use to stop before the next pull after an external signal completes.
+     *
+     * **Details**
+     *
+     * The effect is forked, its success value is discarded, and its failure fails
+     * the stream.
+     *
+     * **Gotchas**
+     *
+     * This does not interrupt an in-progress pull. Use {@link interruptWhen} when
+     * the stream should be interrupted immediately.
      *
      * **Example** (Halting a stream after an effect completes)
      *
@@ -14248,6 +14780,24 @@ export declare const runHead: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<
 /**
  * Runs the stream and returns the last element as an `Option`.
  *
+ * **When to use**
+ *
+ * Use to consume a finite stream when only the final emitted element matters.
+ *
+ * **Details**
+ *
+ * `Option.some` contains the last emitted element. `Option.none` means the
+ * stream completed without emitting.
+ *
+ * **Gotchas**
+ *
+ * The returned effect waits for the stream to complete before it can produce a
+ * value.
+ *
+ * @see {@link runHead} for consuming only the first emitted element
+ * @see {@link runCollect} for collecting every emitted element
+ * @see {@link runDrain} for consuming the stream while discarding emitted elements
+ *
  * @category destructors
  * @since 2.0.0
  */
@@ -15012,7 +15562,7 @@ export declare const runIntoPubSub: {
     } | undefined): Effect.Effect<void, never, R>;
 };
 /**
- * Converts a stream to a PubSub for concurrent consumption.
+ * Converts a stream to a PubSub of emitted values for concurrent consumption.
  *
  * **Details**
  *
@@ -15040,7 +15590,7 @@ export declare const runIntoPubSub: {
  */
 export declare const toPubSub: {
     /**
-     * Converts a stream to a PubSub for concurrent consumption.
+     * Converts a stream to a PubSub of emitted values for concurrent consumption.
      *
      * **Details**
      *
@@ -15077,7 +15627,7 @@ export declare const toPubSub: {
         readonly shutdownOnEnd?: boolean | undefined;
     }): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<PubSub.PubSub<A>, never, R | Scope.Scope>;
     /**
-     * Converts a stream to a PubSub for concurrent consumption.
+     * Converts a stream to a PubSub of emitted values for concurrent consumption.
      *
      * **Details**
      *
@@ -15115,7 +15665,7 @@ export declare const toPubSub: {
     }): Effect.Effect<PubSub.PubSub<A>, never, R | Scope.Scope>;
 };
 /**
- * Converts a stream to a PubSub for concurrent consumption.
+ * Converts a stream to a PubSub of `Take` values for concurrent consumption.
  *
  * **Details**
  *
@@ -15144,7 +15694,7 @@ export declare const toPubSub: {
  */
 export declare const toPubSubTake: {
     /**
-     * Converts a stream to a PubSub for concurrent consumption.
+     * Converts a stream to a PubSub of `Take` values for concurrent consumption.
      *
      * **Details**
      *
@@ -15180,7 +15730,7 @@ export declare const toPubSubTake: {
         readonly replay?: number | undefined;
     }): <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<PubSub.PubSub<Take.Take<A, E>>, never, R | Scope.Scope>;
     /**
-     * Converts a stream to a PubSub for concurrent consumption.
+     * Converts a stream to a PubSub of `Take` values for concurrent consumption.
      *
      * **Details**
      *