effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Channel.d.ts

@@ -28,7 +28,8 @@
  * 2. **Sequencing**: Use the result of one channel to create another
  * 3. **Concatenating**: Combine multiple channels into a single channel
  *
- * @example
+ * **Example** (Creating a simple channel)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -41,7 +42,8 @@
  * // Running the channel would output: 84
  * ```
  *
- * @example
+ * **Example** (Transforming array-backed channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -79,19 +81,25 @@ import { ParentSpan, type SpanOptions } from "./Tracer.ts";
 import type * as Types from "./Types.ts";
 import type * as Unify from "./Unify.ts";
 /**
- * @since 4.0.0
+ * String literal type used as the unique brand for `Channel` values.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export type TypeId = "~effect/Channel";
 /**
- * @since 4.0.0
+ * Runtime identifier stored on `Channel` values and used by `isChannel` to
+ * recognize them.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export declare const TypeId: TypeId;
 /**
  * Tests if a value is a `Channel`.
  *
- * @example
+ * **Example** (Checking for channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -127,7 +135,8 @@ export declare const isChannel: (u: unknown) => u is Channel<unknown, unknown, u
  *    channels, which are all concatenated together. The first channel and the
  *    function that makes the other channels can be composed into a channel.
  *
- * @example
+ * **Example** (Typing channels)
+ *
  * ```ts
  * import type { Channel } from "effect"
  *
@@ -149,8 +158,8 @@ export declare const isChannel: (u: unknown) => u is Channel<unknown, unknown, u
  * >
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Channel<out OutElem, out OutErr = never, out OutDone = void, in InElem = unknown, in InErr = unknown, in InDone = unknown, out Env = never> extends Variance<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, Pipeable {
     [Unify.typeSymbol]?: unknown;
@@ -158,8 +167,14 @@ export interface Channel<out OutElem, out OutErr = never, out OutDone = void, in
     [Unify.ignoreSymbol]?: ChannelUnifyIgnore;
 }
 /**
- * @since 2.0.0
+ * Type-level unification support for `Channel` values.
+ *
+ * This preserves all `Channel` type parameters when `Unify` normalizes unions
+ * or generic return types that include channels. Users normally do not need to
+ * reference this interface directly.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface ChannelUnify<A extends {
     [Unify.typeSymbol]?: any;
@@ -167,6 +182,13 @@ export interface ChannelUnify<A extends {
     Channel?: () => A[Unify.typeSymbol] extends Channel<infer OutElem, infer OutErr, infer OutDone, infer InElem, infer InErr, infer InDone, infer Env> | infer _ ? Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env> : never;
 }
 /**
+ * Marker used by `Unify` while resolving `Channel` values.
+ *
+ * It prevents the inherited `Effect` unifier from being selected when the
+ * channel-specific unifier should preserve `Channel` input, output, and
+ * environment type parameters. Users normally do not need to reference this
+ * interface directly.
+ *
  * @category models
  * @since 2.0.0
  */
@@ -177,15 +199,29 @@ type TagsWithReason<E> = {
     [T in Types.Tags<E>]: Types.ReasonTags<Types.ExtractTag<E, T>> extends never ? never : T;
 }[Types.Tags<E>];
 /**
- * @since 2.0.0
+ * Phantom variance marker for the type parameters of `Channel`.
+ *
+ * Output element, output error, output done, and environment types are
+ * covariant. Input element, input error, and input done types are
+ * contravariant. This is type-level machinery and is not used directly at
+ * runtime.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface Variance<out OutElem, out OutErr, out OutDone, in InElem, in InErr, in InDone, out Env> {
     readonly [TypeId]: VarianceStruct<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 }
 /**
- * @since 2.0.0
+ * Structural encoding used by `Variance` to record each `Channel` type
+ * parameter's variance.
+ *
+ * The `_OutElem`, `_OutErr`, `_OutDone`, and `_Env` fields are covariant; the
+ * `_InElem`, `_InErr`, and `_InDone` fields are contravariant. Users normally
+ * do not need to reference this interface directly.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface VarianceStruct<out OutElem, out OutErr, out OutDone, in InElem, in InErr, in InDone, out Env> {
     _Env: Types.Covariant<Env>;
@@ -199,7 +235,8 @@ export interface VarianceStruct<out OutElem, out OutErr, out OutDone, in InElem,
 /**
  * Creates a `Channel` from a transformation function that operates on upstream pulls.
  *
- * @example
+ * **Example** (Creating channels from transforms)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -215,7 +252,8 @@ export declare const fromTransform: <OutElem, OutErr, OutDone, InElem, InErr, In
 /**
  * Transforms a Channel by applying a function to its Pull implementation.
  *
- * @example
+ * **Example** (Transforming pull behavior)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -239,7 +277,8 @@ export declare const transformPull: <OutElem, OutErr, OutDone, InElem, InErr, In
 /**
  * Creates a `Channel` from an `Effect` that produces a `Pull`.
  *
- * @example
+ * **Example** (Creating channels from pulls)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -257,14 +296,15 @@ export declare const fromPull: <OutElem, OutErr, OutDone, EX, EnvX, Env>(effect:
  * pulls, but also provides a forked scope that closes when the resulting
  * Channel completes.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromTransformBracket: <OutElem, OutErr, OutDone, InElem, InErr, InDone, EX, EnvX, Env>(f: (upstream: Pull.Pull<InElem, InErr, InDone>, scope: Scope.Scope, forkedScope: Scope.Scope) => Effect.Effect<Pull.Pull<OutElem, OutErr, OutDone, EnvX>, EX, Env>) => Channel<OutElem, Pull.ExcludeDone<OutErr> | EX, OutDone, InElem, InErr, InDone, Env | EnvX>;
 /**
  * Converts a `Channel` back to its underlying transformation function.
  *
- * @example
+ * **Example** (Extracting channel transforms)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -280,7 +320,8 @@ export declare const toTransform: <OutElem, OutErr, OutDone, InElem, InErr, InDo
 /**
  * The default chunk size used by channels for batching operations.
  *
- * @example
+ * **Example** (Reading the default chunk size)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -294,7 +335,8 @@ export declare const DefaultChunkSize: number;
 /**
  * Creates a `Channel` that interacts with a callback function using a queue.
  *
- * @example
+ * **Example** (Creating channels from callbacks)
+ *
  * ```ts
  * import { Channel, Effect, Queue } from "effect"
  *
@@ -317,7 +359,8 @@ export declare const callback: <A, E = never, R = never>(f: (queue: Queue.Queue<
 /**
  * Creates a `Channel` that interacts with a callback function using a queue, emitting arrays.
  *
- * @example
+ * **Example** (Creating array channels from callbacks)
+ *
  * ```ts
  * import { Channel, Effect, Queue } from "effect"
  *
@@ -338,7 +381,8 @@ export declare const callbackArray: <A, E = never, R = never>(f: (queue: Queue.Q
 /**
  * Creates a `Channel` that lazily evaluates to another channel.
  *
- * @example
+ * **Example** (Suspending channel creation)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -351,9 +395,15 @@ export declare const callbackArray: <A, E = never, R = never>(f: (queue: Queue.Q
  */
 export declare const suspend: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(evaluate: LazyArg<Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 /**
- * Creates a `Channel` with resource management using acquire-use-release pattern.
+ * Acquires a resource, uses it to build a `Channel`, and guarantees that
+ * `release` runs with the channel's `Exit` when the channel completes, fails,
+ * or is interrupted.
+ *
+ * Acquisition is uninterruptible. If acquisition fails, `use` is not run and
+ * `release` is not registered.
+ *
+ * **Example** (Managing resources with acquire-use-release)
  *
- * @example
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -369,9 +419,15 @@ export declare const suspend: <OutElem, OutErr, OutDone, InElem, InErr, InDone,
  */
 export declare const acquireUseRelease: <A, E, R, OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(acquire: Effect.Effect<A, E, R>, use: (a: A) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, release: (a: A, exit: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 /**
- * Creates a `Channel` with resource management using acquire-release pattern.
+ * Acquires a resource, emits the acquired value as a single channel element,
+ * and registers `release` in the channel scope.
+ *
+ * The release action runs when the channel scope closes and receives the scope
+ * exit. If acquisition fails, no element is emitted and `release` is not
+ * registered.
+ *
+ * **Example** (Managing resources with acquire-release)
  *
- * @example
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -386,9 +442,15 @@ export declare const acquireUseRelease: <A, E, R, OutElem, OutErr, OutDone, InEl
  */
 export declare const acquireRelease: {
     /**
-     * Creates a `Channel` with resource management using acquire-release pattern.
+     * Acquires a resource, emits the acquired value as a single channel element,
+     * and registers `release` in the channel scope.
+     *
+     * The release action runs when the channel scope closes and receives the scope
+     * exit. If acquisition fails, no element is emitted and `release` is not
+     * registered.
+     *
+     * **Example** (Managing resources with acquire-release)
      *
-     * @example
      * ```ts
      * import { Channel, Effect } from "effect"
      *
@@ -403,9 +465,15 @@ export declare const acquireRelease: {
      */
     <Z>(release: (z: Z, e: Exit.Exit<unknown, unknown>) => Effect.Effect<unknown>): <E, R>(self: Effect.Effect<Z, E, R>) => Channel<Z, E, void, unknown, unknown, unknown, R>;
     /**
-     * Creates a `Channel` with resource management using acquire-release pattern.
+     * Acquires a resource, emits the acquired value as a single channel element,
+     * and registers `release` in the channel scope.
+     *
+     * The release action runs when the channel scope closes and receives the scope
+     * exit. If acquisition fails, no element is emitted and `release` is not
+     * registered.
+     *
+     * **Example** (Managing resources with acquire-release)
      *
-     * @example
      * ```ts
      * import { Channel, Effect } from "effect"
      *
@@ -423,7 +491,8 @@ export declare const acquireRelease: {
 /**
  * Creates a `Channel` from an iterator.
  *
- * @example
+ * **Example** (Creating channels from iterators)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -439,7 +508,8 @@ export declare const fromIterator: <A, L>(iterator: LazyArg<Iterator<A, L>>) =>
 /**
  * Creates a `Channel` that emits all elements from an array.
  *
- * @example
+ * **Example** (Creating channels from arrays)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -454,7 +524,8 @@ export declare const fromArray: <A>(array: ReadonlyArray<A>) => Channel<A>;
 /**
  * Creates a `Channel` that emits all elements from a chunk.
  *
- * @example
+ * **Example** (Creating channels from chunks)
+ *
  * ```ts
  * import { Channel, Chunk } from "effect"
  *
@@ -470,7 +541,8 @@ export declare const fromChunk: <A>(chunk: Chunk.Chunk<A>) => Channel<A>;
 /**
  * Creates a `Channel` from an iterator that emits arrays of elements.
  *
- * @example
+ * **Example** (Batching iterator output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -491,7 +563,8 @@ export declare const fromChunk: <A>(chunk: Chunk.Chunk<A>) => Channel<A>;
  * // This will emit arrays: [0, 1], [2], then complete with "finished"
  * ```
  *
- * @example
+ * **Example** (Batching generator output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -508,14 +581,15 @@ export declare const fromChunk: <A>(chunk: Chunk.Chunk<A>) => Channel<A>;
  * // Emits: [0, 1, 1], [2, 3], then completes
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromIteratorArray: <A, L>(iterator: LazyArg<Iterator<A, L>>, chunkSize?: number) => Channel<Arr.NonEmptyReadonlyArray<A>, never, L>;
 /**
  * Creates a `Channel` that emits all elements from an iterable.
  *
- * @example
+ * **Example** (Creating channels from iterables)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -531,7 +605,8 @@ export declare const fromIterable: <A, L>(iterable: Iterable<A, L>) => Channel<A
 /**
  * Creates a `Channel` that emits arrays of elements from an iterable.
  *
- * @example
+ * **Example** (Batching iterable output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -547,7 +622,8 @@ export declare const fromIterableArray: <A, L>(iterable: Iterable<A, L>, chunkSi
 /**
  * Creates a `Channel` that emits a single value and then ends.
  *
- * @example
+ * **Example** (Creating channels that succeed)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -562,7 +638,8 @@ export declare const succeed: <A>(value: A) => Channel<A>;
 /**
  * Creates a `Channel` that immediately ends with the specified value.
  *
- * @example
+ * **Example** (Ending with a value)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -584,12 +661,18 @@ export declare const endSync: <A>(evaluate: LazyArg<A>) => Channel<never, never,
 /**
  * Creates a `Channel` that emits a single value computed by a lazy evaluation.
  *
- * @example
+ * **Example** (Computing values lazily)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
- * const channel = Channel.sync(() => Math.random())
- * // Emits a random number computed when the channel runs
+ * let requests = 0
+ *
+ * const channel = Channel.sync(() => {
+ *   requests += 1
+ *   return `request-${requests}`
+ * })
+ * // Emits "request-1" when the channel runs for the first time
  * ```
  *
  * @category constructors
@@ -599,7 +682,8 @@ export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
 /**
  * Represents an Channel that emits no elements
  *
- * @example
+ * **Example** (Using empty channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -615,14 +699,15 @@ export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
  *   shouldEmit ? Channel.succeed("data") : Channel.empty
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const empty: Channel<never>;
 /**
  * Represents an Channel that never completes
  *
- * @example
+ * **Example** (Using non-terminating channels)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -640,14 +725,15 @@ export declare const empty: Channel<never>;
  *   shouldComplete ? Channel.succeed("done") : Channel.never
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const never: Channel<never, never, never>;
 /**
  * Constructs a channel that fails immediately with the specified error.
  *
- * @example
+ * **Example** (Failing with an error)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -670,15 +756,16 @@ export declare const never: Channel<never, never, never>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fail: <E>(error: E) => Channel<never, E, never>;
 /**
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated error.
  *
- * @example
+ * **Example** (Failing with a lazy error)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -689,25 +776,28 @@ export declare const fail: <E>(error: E) => Channel<never, E, never>;
  * })
  *
  * // The error computation is deferred until the channel runs
- * const conditionalError = Channel.failSync(() =>
- *   Math.random() > 0.5 ? "Error A" : "Error B"
- * )
+ * let attempts = 0
+ * const conditionalError = Channel.failSync(() => {
+ *   attempts += 1
+ *   return `Error after attempt ${attempts}`
+ * })
  *
  * // Use with expensive error construction
  * const expensiveError = Channel.failSync(() => {
- *   const timestamp = Date.now()
- *   return new Error(`Failed at: ${timestamp}`)
+ *   const requestId = "request-123"
+ *   return new Error(`Failed while processing ${requestId}`)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failSync: <E>(evaluate: LazyArg<E>) => Channel<never, E, never>;
 /**
  * Constructs a channel that fails immediately with the specified `Cause`.
  *
- * @example
+ * **Example** (Failing with causes)
+ *
  * ```ts
  * import { Cause, Channel } from "effect"
  *
@@ -724,39 +814,42 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Channel<never, E, ne
  * const simpleFail = Channel.failCause(failCause)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failCause: <E>(cause: Cause.Cause<E>) => Channel<never, E, never>;
 /**
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated `Cause`.
  *
- * @example
+ * **Example** (Failing with lazy causes)
+ *
  * ```ts
  * import { Cause, Channel } from "effect"
  *
  * // Create a channel that fails with a lazily computed cause
+ * let attempts = 0
  * const failedChannel = Channel.failCauseSync(() => {
- *   const errorType = Math.random() > 0.5 ? "A" : "B"
- *   return Cause.fail(`Runtime error ${errorType}`)
+ *   attempts += 1
+ *   return Cause.fail(`Runtime error after attempt ${attempts}`)
  * })
  *
  * // Create a channel with die cause computation
  * const dieCauseChannel = Channel.failCauseSync(() => {
- *   const timestamp = Date.now()
- *   return Cause.die(`Error at ${timestamp}`)
+ *   const operation = "load-profile"
+ *   return Cause.die(`Unexpected defect during ${operation}`)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Channel<never, E, never>;
 /**
  * Constructs a channel that fails immediately with the specified defect.
  *
- * @example
+ * **Example** (Dying with defects)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -773,14 +866,15 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ch
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const die: (defect: unknown) => Channel<never, never, never>;
 /**
  * Use an effect to write a single value to the channel.
  *
- * @example
+ * **Example** (Creating channels from effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -810,31 +904,43 @@ export declare const die: (defect: unknown) => Channel<never, never, never>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => Channel<A, Pull.ExcludeDone<E>, void, unknown, unknown, unknown, R>;
 /**
- * @since 4.0.0
+ * Creates a channel that evaluates an effect and uses its successful value as
+ * the channel's done value without emitting any output elements.
+ *
+ * If the effect fails, the channel fails with the effect's error.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromEffectDone: <A, E, R>(effect: Effect.Effect<A, E, R>) => Channel<never, Pull.ExcludeDone<E>, A, unknown, unknown, unknown, R>;
 /**
  * Use an effect and discard its result.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromEffectDrain: <A, E, R>(effect: Effect.Effect<A, E, R>) => Channel<never, E, void, unknown, unknown, unknown, R>;
 /**
- * @since 4.0.0
+ * Creates a channel from an effect that produces a `Take`.
+ *
+ * A successful `Take` emits a non-empty array of output elements. A failed
+ * `Take` fails the channel. A done `Take` completes the channel with its done
+ * value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<Take.Take<A, E, Done>, E2, R>) => Channel<Arr.NonEmptyReadonlyArray<A>, E | E2, Done, unknown, unknown, unknown, R>;
 /**
  * Create a channel from a queue
  *
- * @example
+ * **Example** (Creating channels from queues)
+ *
  * ```ts
  * import { Channel, Data, Effect, Queue } from "effect"
  *
@@ -866,14 +972,15 @@ export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<T
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromQueue: <A, E>(queue: Queue.Dequeue<A, E>) => Channel<A, Exclude<E, Cause.Done>>;
 /**
  * Create a channel from a queue that emits arrays of elements
  *
- * @example
+ * **Example** (Creating batched channels from queues)
+ *
  * ```ts
  * import { Channel, Data, Effect, Queue } from "effect"
  *
@@ -909,19 +1016,23 @@ export declare const fromQueue: <A, E>(queue: Queue.Dequeue<A, E>) => Channel<A,
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromQueueArray: <A, E>(queue: Queue.Dequeue<A, E>) => Channel<Arr.NonEmptyReadonlyArray<A>, Exclude<E, Cause.Done>>;
 /**
- * @since 2.0.0
+ * Creates a channel that forwards upstream input elements, input errors, and
+ * the upstream done value unchanged.
+ *
  * @category Constructors
+ * @since 2.0.0
  */
 export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, Elem, Err, Done>;
 /**
  * Create a channel from a PubSub subscription
  *
- * @example
+ * **Example** (Creating channels from subscriptions)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -958,8 +1069,8 @@ export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, E
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>) => Channel<A>;
 /**
@@ -972,7 +1083,8 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  * @param subscription - The PubSub subscription to read from
  * @param chunkSize - The maximum number of elements to read in each chunk (default: 4096)
  *
- * @example
+ * **Example** (Batching subscription values)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -998,7 +1110,8 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  * })
  * ```
  *
- * @example
+ * **Example** (Processing subscription values in batches)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -1023,13 +1136,10 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Aggregating subscription metrics)
  *
- * class MetricsError extends Data.TaggedError("MetricsError")<{
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * const metricsAggregator = Effect.gen(function*() {
  *   const metricsPubSub = yield* PubSub.bounded<
@@ -1054,7 +1164,8 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  *       average: avg,
  *       min,
  *       max,
- *       timestamp: Date.now()
+ *       firstTimestamp: Math.min(...metrics.map((m) => m.timestamp)),
+ *       lastTimestamp: Math.max(...metrics.map((m) => m.timestamp))
  *     }
  *   })
  *
@@ -1062,8 +1173,8 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscription<A>) => Channel<Arr.NonEmptyReadonlyArray<A>>;
 /**
@@ -1075,7 +1186,8 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  *
  * @param pubsub - The PubSub to read from
  *
- * @example
+ * **Example** (Creating channels from PubSubs)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -1099,13 +1211,10 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Streaming PubSub notifications)
  *
- * class NotificationError extends Data.TaggedError("NotificationError")<{
- *   readonly reason: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * const notificationService = Effect.gen(function*() {
  *   const notificationPubSub = yield* PubSub.bounded<string>(50)
@@ -1114,24 +1223,21 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  *   const notificationChannel = Channel.fromPubSub(notificationPubSub)
  *
  *   // Transform notifications to add timestamps
+ *   const receivedAt = "2024-01-01T00:00:00.000Z"
  *   const timestampedChannel = Channel.map(notificationChannel, (message) => ({
  *     message,
- *     timestamp: new Date().toISOString(),
- *     id: Math.random().toString(36).substr(2, 9)
+ *     receivedAt,
+ *     id: `notification:${message}`
  *   }))
  *
  *   return timestampedChannel
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub events)
  *
- * class EventProcessingError extends Data.TaggedError("EventProcessingError")<{
- *   readonly eventType: string
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface DomainEvent {
  *   readonly type: string
@@ -1151,7 +1257,7 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  *       return {
  *         ...event,
  *         processed: true,
- *         processedAt: Date.now()
+ *         processedAt: event.timestamp + 1
  *       }
  *     }
  *     return event
@@ -1161,8 +1267,8 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
 /**
@@ -1175,7 +1281,8 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  * @param pubsub - The PubSub to read from
  * @param chunkSize - The maximum number of elements to collect in each array (default: 4096)
  *
- * @example
+ * **Example** (Batching PubSub values)
+ *
  * ```ts
  * import { Channel, Data, Effect, PubSub } from "effect"
  *
@@ -1200,20 +1307,17 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub orders in batches)
  *
- * class OrderProcessingError extends Data.TaggedError("OrderProcessingError")<{
- *   readonly orderId: string
- *   readonly reason: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface Order {
  *   readonly id: string
  *   readonly customerId: string
  *   readonly items: ReadonlyArray<string>
  *   readonly total: number
+ *   readonly submittedAt: number
  * }
  *
  * const orderBatchProcessor = Effect.gen(function*() {
@@ -1233,7 +1337,7 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  *       batchSize: orderBatch.length,
  *       totalRevenue,
  *       uniqueCustomers: customerCount,
- *       processedAt: Date.now(),
+ *       firstSubmittedAt: Math.min(...orderBatch.map((order) => order.submittedAt)),
  *       orders: orderBatch
  *     }
  *   })
@@ -1242,14 +1346,10 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  * })
  * ```
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect, PubSub } from "effect"
+ * **Example** (Processing PubSub logs in batches)
  *
- * class LogProcessingError extends Data.TaggedError("LogProcessingError")<{
- *   readonly batchId: string
- *   readonly cause: string
- * }> {}
+ * ```ts
+ * import { Channel, Effect, PubSub } from "effect"
  *
  * interface LogEntry {
  *   readonly timestamp: number
@@ -1276,7 +1376,7 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  *     }
  *
  *     return {
- *       batchId: Math.random().toString(36).substr(2, 9),
+ *       batchId: `${timeRange.start}-${timeRange.end}`,
  *       totalEntries: logBatch.length,
  *       errorCount,
  *       warnCount,
@@ -1290,40 +1390,56 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromPubSubArray: <A>(pubsub: PubSub.PubSub<A>) => Channel<Arr.NonEmptyReadonlyArray<A>>;
 /**
- * @since 4.0.0
+ * Subscribes to a `PubSub` of `Take` values and exposes them as a channel.
+ *
+ * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
+ * fail the channel. Done `Take` values complete the channel.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromPubSubTake: <A, E, Done>(pubsub: PubSub.PubSub<Take.Take<A, E, Done>>) => Channel<Arr.NonEmptyReadonlyArray<A>, E, Done>;
 /**
  * Creates a Channel from a Schedule.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromSchedule: <O, E, R>(schedule: Schedule.Schedule<O, unknown, E, R>) => Channel<O, E, O, unknown, unknown, unknown, R>;
 /**
- * Creates a Channel from a AsyncIterable.
+ * Creates a channel that pulls values from an `AsyncIterable`.
+ *
+ * Each yielded value is emitted as an output element. The iterator's return
+ * value becomes the channel's done value. Thrown or rejected iterator errors
+ * are converted with `onError`. If the channel scope closes early and the
+ * iterator has a `return` method, that method is called.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromAsyncIterable: <A, D, E>(iterable: AsyncIterable<A, D>, onError: (error: unknown) => E) => Channel<A, E, D>;
 /**
- * Creates a Channel from a AsyncIterable that emits arrays of elements.
+ * Creates a channel from an `AsyncIterable`, emitting each yielded value as a
+ * single-element non-empty array.
+ *
+ * The iterator's return value becomes the channel's done value. Thrown or
+ * rejected iterator errors are converted with `onError`. If the channel scope
+ * closes early and the iterator has a `return` method, that method is called.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromAsyncIterableArray: <A, D, E>(iterable: AsyncIterable<A, D>, onError: (error: unknown) => E) => Channel<Arr.NonEmptyReadonlyArray<A>, E, D>;
 /**
  * Maps the output of this channel using the specified function.
  *
- * @example
+ * **Example** (Mapping channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1355,14 +1471,15 @@ export declare const fromAsyncIterableArray: <A, D, E>(iterable: AsyncIterable<A
  * }))
  * ```
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const map: {
     /**
      * Maps the output of this channel using the specified function.
      *
-     * @example
+     * **Example** (Mapping channel output)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1394,14 +1511,15 @@ export declare const map: {
      * }))
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutElem2>(f: (o: OutElem, i: number) => OutElem2): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem2, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Maps the output of this channel using the specified function.
      *
-     * @example
+     * **Example** (Mapping channel output)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1433,63 +1551,66 @@ export declare const map: {
      * }))
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (o: OutElem, i: number) => OutElem2): Channel<OutElem2, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
  * Maps the done value of this channel using the specified function.
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const mapDone: {
     /**
      * Maps the done value of this channel using the specified function.
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutDone, OutDone2>(f: (o: OutDone) => OutDone2): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone2, InElem, InErr, InDone, Env>;
     /**
      * Maps the done value of this channel using the specified function.
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (o: OutDone) => OutDone2): Channel<OutElem, OutErr, OutDone2, InElem, InErr, InDone, Env>;
 };
 /**
  * Maps the done value of this channel using the specified effectful function.
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const mapDoneEffect: {
     /**
      * Maps the done value of this channel using the specified effectful function.
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutDone, OutDone2, E, R>(f: (o: OutDone) => Effect.Effect<OutDone2, E, R>): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone2, InElem, InErr, InDone, Env | R>;
     /**
      * Maps the done value of this channel using the specified effectful function.
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (o: OutDone) => Effect.Effect<OutDone2, E, R>): Channel<OutElem, OutErr | E, OutDone2, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element with an effectful function, preserving the source
+ * channel's done value.
+ *
+ * The mapping function receives the output element and its zero-based index.
+ * By default elements are mapped sequentially. Use `options.concurrency` to
+ * map multiple elements concurrently, and `options.unordered` to allow
+ * concurrently mapped outputs to be emitted as soon as they complete.
+ *
+ * **Example** (Mapping channel output with effects)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -1526,18 +1647,21 @@ export declare const mapDoneEffect: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const mapEffect: {
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element with an effectful function, preserving the source
+     * channel's done value.
+     *
+     * The mapping function receives the output element and its zero-based index.
+     * By default elements are mapped sequentially. Use `options.concurrency` to
+     * map multiple elements concurrently, and `options.unordered` to allow
+     * concurrently mapped outputs to be emitted as soon as they complete.
+     *
+     * **Example** (Mapping channel output with effects)
      *
-     * @example
      * ```ts
      * import { Channel, Data, Effect } from "effect"
      *
@@ -1574,21 +1698,24 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutElem1, OutErr1, Env1>(f: (d: OutElem, i: number) => Effect.Effect<OutElem1, OutErr1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
         readonly unordered?: boolean | undefined;
     }): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem1, OutErr1 | OutErr, OutDone, InElem, InErr, InDone, Env1 | Env>;
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element with an effectful function, preserving the source
+     * channel's done value.
+     *
+     * The mapping function receives the output element and its zero-based index.
+     * By default elements are mapped sequentially. Use `options.concurrency` to
+     * map multiple elements concurrently, and `options.unordered` to allow
+     * concurrently mapped outputs to be emitted as soon as they complete.
+     *
+     * **Example** (Mapping channel output with effects)
      *
-     * @example
      * ```ts
      * import { Channel, Data, Effect } from "effect"
      *
@@ -1625,8 +1752,8 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: OutElem, i: number) => Effect.Effect<OutElem1, OutErr1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -1637,24 +1764,24 @@ export declare const mapEffect: {
  * Returns a new channel which is the same as this one but applies the given
  * function to the input channel’s input elements.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const mapInput: {
     /**
      * Returns a new channel which is the same as this one but applies the given
      * function to the input channel’s input elements.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <InElem, InElem2, InErr, R = never>(f: (i: InElem2) => Effect.Effect<InElem, InErr, R>): <OutElem, OutErr, OutDone, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>) => Channel<OutElem, OutErr, OutDone, InElem2, InErr, InDone, Env>;
     /**
      * Returns a new channel which is the same as this one but applies the given
      * function to the input channel’s input elements.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, InElem2, R = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (i: InElem2) => Effect.Effect<InElem, InErr, R>): Channel<OutElem, OutErr, OutDone, InElem2, InErr, InDone, Env | R>;
 };
@@ -1662,24 +1789,24 @@ export declare const mapInput: {
  * Returns a new channel which is the same as this one but applies the given
  * function to the input errors.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const mapInputError: {
     /**
      * Returns a new channel which is the same as this one but applies the given
      * function to the input errors.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <InErr, InErr2, R = never>(f: (i: InErr2) => Effect.Effect<InErr, InErr, R>): <OutElem, OutErr, OutDone, InElem, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>) => Channel<OutElem, OutErr, OutDone, InElem, InErr2, InDone, Env>;
     /**
      * Returns a new channel which is the same as this one but applies the given
      * function to the input errors.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, InErr2, R = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (i: InErr2) => Effect.Effect<InErr, InErr, R>): Channel<OutElem, OutErr, OutDone, InElem, InErr2, InDone, Env | R>;
 };
@@ -1691,7 +1818,8 @@ export declare const mapInputError: {
  * debugging) on each element emitted by a channel without modifying the
  * elements themselves.
  *
- * @example
+ * **Example** (Tapping channel output)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -1712,8 +1840,8 @@ export declare const mapInputError: {
  * // Outputs: 1, 2, 3 (while logging each)
  * ```
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const tap: {
     /**
@@ -1724,7 +1852,8 @@ export declare const tap: {
      * debugging) on each element emitted by a channel without modifying the
      * elements themselves.
      *
-     * @example
+     * **Example** (Tapping channel output)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -1745,8 +1874,8 @@ export declare const tap: {
      * // Outputs: 1, 2, 3 (while logging each)
      * ```
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <OutElem, X, OutErr1, Env1>(f: (d: Types.NoInfer<OutElem>) => Effect.Effect<X, OutErr1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -1759,7 +1888,8 @@ export declare const tap: {
      * debugging) on each element emitted by a channel without modifying the
      * elements themselves.
      *
-     * @example
+     * **Example** (Tapping channel output)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -1780,21 +1910,24 @@ export declare const tap: {
      * // Outputs: 1, 2, 3 (while logging each)
      * ```
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, X, OutErr1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: Types.NoInfer<OutElem>) => Effect.Effect<X, OutErr1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
     }): Channel<OutElem, OutErr | OutErr1, OutDone, InElem, InErr, InDone, Env | Env1>;
 };
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element to a channel and flattens the child channel
+ * outputs.
+ *
+ * The source channel's done value is preserved. Child channel done values are
+ * used only for child-channel completion. By default child channels are run
+ * sequentially. Use `options.concurrency` and `options.bufferSize` to run child
+ * channels concurrently.
+ *
+ * **Example** (FlatMapping channel output)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1816,18 +1949,21 @@ export declare const tap: {
  * // Outputs: "item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const flatMap: {
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element to a channel and flattens the child channel
+     * outputs.
+     *
+     * The source channel's done value is preserved. Child channel done values are
+     * used only for child-channel completion. By default child channels are run
+     * sequentially. Use `options.concurrency` and `options.bufferSize` to run child
+     * channels concurrently.
+     *
+     * **Example** (FlatMapping channel output)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1849,21 +1985,24 @@ export declare const flatMap: {
      * // Outputs: "item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(f: (d: OutElem) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
         readonly bufferSize?: number | undefined;
     }): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem1, OutErr1 | OutErr, OutDone, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element to a channel and flattens the child channel
+     * outputs.
+     *
+     * The source channel's done value is preserved. Child channel done values are
+     * used only for child-channel completion. By default child channels are run
+     * sequentially. Use `options.concurrency` and `options.bufferSize` to run child
+     * channels concurrently.
+     *
+     * **Example** (FlatMapping channel output)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1885,8 +2024,8 @@ export declare const flatMap: {
      * // Outputs: "item-1-0", "item-2-0", "item-2-1", "item-3-0", "item-3-1", "item-3-2"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: OutElem) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -1897,7 +2036,8 @@ export declare const flatMap: {
  * Concatenates this channel with another channel created from the terminal value
  * of this channel. The new channel is created using the provided function.
  *
- * @example
+ * **Example** (Concatenating with completion values)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1914,15 +2054,16 @@ export declare const flatMap: {
  * // Outputs: 1, 2, 3, then "Completed processing"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const concatWith: {
     /**
      * Concatenates this channel with another channel created from the terminal value
      * of this channel. The new channel is created using the provided function.
      *
-     * @example
+     * **Example** (Concatenating with completion values)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1939,15 +2080,16 @@ export declare const concatWith: {
      * // Outputs: 1, 2, 3, then "Completed processing"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutDone, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
     /**
      * Concatenates this channel with another channel created from the terminal value
      * of this channel. The new channel is created using the provided function.
      *
-     * @example
+     * **Example** (Concatenating with completion values)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -1964,8 +2106,8 @@ export declare const concatWith: {
      * // Outputs: 1, 2, 3, then "Completed processing"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
@@ -1973,7 +2115,8 @@ export declare const concatWith: {
  * Concatenates this channel with another channel, so that the second channel
  * starts emitting values after the first channel has completed.
  *
- * @example
+ * **Example** (Concatenating channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -1991,15 +2134,16 @@ export declare const concatWith: {
  * // Outputs: 1, 2, 3, "a", "b", "c"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const concat: {
     /**
      * Concatenates this channel with another channel, so that the second channel
      * starts emitting values after the first channel has completed.
      *
-     * @example
+     * **Example** (Concatenating channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -2017,15 +2161,16 @@ export declare const concat: {
      * // Outputs: 1, 2, 3, "a", "b", "c"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(that: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
     /**
      * Concatenates this channel with another channel, so that the second channel
      * starts emitting values after the first channel has completed.
      *
-     * @example
+     * **Example** (Concatenating channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -2043,8 +2188,8 @@ export declare const concat: {
      * // Outputs: 1, 2, 3, "a", "b", "c"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
@@ -2055,8 +2200,8 @@ export declare const concat: {
  * some internal state to control the combining process, with the initial
  * state being specified by `s`.
  *
- * @since 4.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const combine: {
     /**
@@ -2066,8 +2211,8 @@ export declare const combine: {
      * some internal state to control the combining process, with the initial
      * state being specified by `s`.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2, S, OutElem, OutErr, OutDone, A, E, R>(that: Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<OutElem, OutErr, OutDone>, pullRight: Pull.Pull<OutElem2, OutErr2, OutDone2>) => Effect.Effect<readonly [A, S], E, R>): <InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<A, Pull.ExcludeDone<E>, Cause.Done.Extract<E>, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env | Env2 | R>;
     /**
@@ -2077,31 +2222,53 @@ export declare const combine: {
      * some internal state to control the combining process, with the initial
      * state being specified by `s`.
      *
-     * @since 4.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2, S, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<OutElem, OutErr, OutDone>, pullRight: Pull.Pull<OutElem2, OutErr2, OutDone2>) => Effect.Effect<readonly [A, S], E, R>): Channel<A, Pull.ExcludeDone<E>, Cause.Done.Extract<E>, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env | Env2 | R>;
 };
 /**
- * @since 2.0.0
+ * Runs a fallback channel if this channel completes without emitting any
+ * output elements.
+ *
+ * If the source emits at least one element, the source is used unchanged. If
+ * the source completes before emitting an element, the fallback function
+ * receives the source done value and returns the replacement channel.
+ *
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const orElseIfEmpty: {
     /**
-     * @since 2.0.0
+     * Runs a fallback channel if this channel completes without emitting any
+     * output elements.
+     *
+     * If the source emits at least one element, the source is used unchanged. If
+     * the source completes before emitting an element, the fallback function
+     * receives the source done value and returns the replacement channel.
+     *
      * @category sequencing
+     * @since 2.0.0
      */
     <OutDone, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
     /**
-     * @since 2.0.0
+     * Runs a fallback channel if this channel completes without emitting any
+     * output elements.
+     *
+     * If the source emits at least one element, the source is used unchanged. If
+     * the source completes before emitting an element, the fallback function
+     * receives the source done value and returns the replacement channel.
+     *
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
 /**
  * Flatten a channel of channels.
  *
- * @example
+ * **Example** (Flattening nested channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2122,14 +2289,15 @@ export declare const orElseIfEmpty: {
  * // Outputs: 1, 2, 3, 4, 5, 6
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const flatten: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(channels: Channel<Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>) => Channel<OutElem, OutErr | OutErr1, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
 /**
  * Flattens a channel that outputs arrays into a channel that outputs individual elements.
  *
- * @example
+ * **Example** (Flattening arrays of channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -2150,20 +2318,27 @@ export declare const flatten: <OutElem, OutErr, OutDone, InElem, InErr, InDone,
  * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const flattenArray: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<ReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 /**
- * @since 4.0.0
+ * Flattens a channel that emits `Take` values into a channel that emits the
+ * `Take` outputs directly.
+ *
+ * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
+ * fail the returned channel. Done `Take` values complete the returned channel.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const flattenTake: <OutElem, OutErr, OutDone, OutErr2, OutDone2, InElem, InErr, InDone, Env>(self: Channel<Take.Take<OutElem, OutErr, OutDone>, OutErr2, OutDone2, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr | OutErr2, OutDone, InElem, InErr, InDone, Env>;
 /**
  * Creates a new channel that consumes all output from the source channel
  * but emits nothing, preserving only the completion value.
  *
- * @example
+ * **Example** (Draining channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -2177,52 +2352,76 @@ export declare const flattenTake: <OutElem, OutErr, OutDone, OutErr2, OutDone2,
  * // Useful for consuming side effects without collecting output
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const drain: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<never, OutErr, OutDone, InElem, InErr, InDone, Env>;
 /**
  * Repeats this channel according to the provided schedule.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const repeat: {
     /**
      * Repeats this channel according to the provided schedule.
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <SO, OutDone, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<OutDone>, SE, SR>) => Schedule.Schedule<SO, OutDone, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR>)): <OutElem, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
     /**
      * Repeats this channel according to the provided schedule.
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutDone, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, NoInfer<OutDone>, SE, SR>) => Schedule.Schedule<SO, OutDone, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutDone>, SE, SR>)): Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
 };
 /**
  * Repeats this channel forever.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const forever: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, never, InElem, InErr, InDone, Env>;
 /**
- * @since 4.0.0
+ * Runs a schedule step for each output element while preserving the emitted
+ * elements.
+ *
+ * The schedule receives each output element as input. Schedule delays are
+ * applied between emitted elements. If the schedule fails, the returned channel
+ * fails. If the schedule finishes, the returned channel completes with the
+ * schedule output.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const schedule: {
     /**
-     * @since 4.0.0
+     * Runs a schedule step for each output element while preserving the emitted
+     * elements.
+     *
+     * The schedule receives each output element as input. Schedule delays are
+     * applied between emitted elements. If the schedule fails, the returned channel
+     * fails. If the schedule finishes, the returned channel completes with the
+     * schedule output.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <SO, OutElem, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutElem>, SE, SR>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone | SO, InElem, InErr, InDone, Env | SR>;
     /**
-     * @since 4.0.0
+     * Runs a schedule step for each output element while preserving the emitted
+     * elements.
+     *
+     * The schedule receives each output element as input. Schedule delays are
+     * applied between emitted elements. If the schedule fails, the returned channel
+     * fails. If the schedule finishes, the returned channel completes with the
+     * schedule output.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutElem, SE, SR>): Channel<OutElem, OutErr | SE, OutDone | SO, InElem, InErr, InDone, Env | SR>;
 };
@@ -2230,7 +2429,8 @@ export declare const schedule: {
  * Filters the output elements of a channel using a predicate function.
  * Elements that don't match the predicate are discarded.
  *
- * @example
+ * **Example** (Filtering channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -2250,15 +2450,16 @@ export declare const schedule: {
  * // Outputs: 1, 2, 3 (all typed as numbers)
  * ```
  *
- * @since 2.0.0
  * @category Filtering
+ * @since 2.0.0
  */
 export declare const filter: {
     /**
      * Filters the output elements of a channel using a predicate function.
      * Elements that don't match the predicate are discarded.
      *
-     * @example
+     * **Example** (Filtering channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2278,15 +2479,16 @@ export declare const filter: {
      * // Outputs: 1, 2, 3 (all typed as numbers)
      * ```
      *
-     * @since 2.0.0
      * @category Filtering
+     * @since 2.0.0
      */
     <OutElem, B extends OutElem>(refinement: Predicate.Refinement<OutElem, B>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<B, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters the output elements of a channel using a predicate function.
      * Elements that don't match the predicate are discarded.
      *
-     * @example
+     * **Example** (Filtering channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2306,15 +2508,16 @@ export declare const filter: {
      * // Outputs: 1, 2, 3 (all typed as numbers)
      * ```
      *
-     * @since 2.0.0
      * @category Filtering
+     * @since 2.0.0
      */
     <OutElem>(predicate: Predicate.Predicate<OutElem>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters the output elements of a channel using a predicate function.
      * Elements that don't match the predicate are discarded.
      *
-     * @example
+     * **Example** (Filtering channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2334,15 +2537,16 @@ export declare const filter: {
      * // Outputs: 1, 2, 3 (all typed as numbers)
      * ```
      *
-     * @since 2.0.0
      * @category Filtering
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B extends OutElem>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutElem, B>): Channel<B, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters the output elements of a channel using a predicate function.
      * Elements that don't match the predicate are discarded.
      *
-     * @example
+     * **Example** (Filtering channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2362,56 +2566,110 @@ export declare const filter: {
      * // Outputs: 1, 2, 3 (all typed as numbers)
      * ```
      *
-     * @since 2.0.0
      * @category Filtering
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<OutElem>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * @since 4.0.0
+ * Filters and maps output elements using a `Filter`.
+ *
+ * Successful filter results are emitted as mapped values. Failed filter
+ * results are discarded. The source channel's errors and done value are
+ * preserved.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterMap: {
     /**
-     * @since 4.0.0
+     * Filters and maps output elements using a `Filter`.
+     *
+     * Successful filter results are emitted as mapped values. Failed filter
+     * results are discarded. The source channel's errors and done value are
+     * preserved.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, B, X>(filter: Filter.Filter<OutElem, B, X>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<B, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * @since 4.0.0
+     * Filters and maps output elements using a `Filter`.
+     *
+     * Successful filter results are emitted as mapped values. Failed filter
+     * results are discarded. The source channel's errors and done value are
+     * preserved.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<OutElem, B, X>): Channel<B, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * @since 4.0.0
+ * Filters output elements with an effectful predicate.
+ *
+ * Elements for which the predicate succeeds with `true` are emitted. Elements
+ * for which the predicate succeeds with `false` are discarded. Predicate
+ * failures fail the returned channel.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterEffect: {
     /**
-     * @since 4.0.0
+     * Filters output elements with an effectful predicate.
+     *
+     * Elements for which the predicate succeeds with `true` are emitted. Elements
+     * for which the predicate succeeds with `false` are discarded. Predicate
+     * failures fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, E, R>(predicate: (a: OutElem) => Effect.Effect<boolean, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Filters output elements with an effectful predicate.
+     *
+     * Elements for which the predicate succeeds with `true` are emitted. Elements
+     * for which the predicate succeeds with `false` are discarded. Predicate
+     * failures fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: (a: OutElem) => Effect.Effect<boolean, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * @since 4.0.0
+ * Filters and maps output elements using an effectful `Filter`.
+ *
+ * Successful filter results are emitted as mapped values. Failed filter
+ * results are discarded. Failures from the effectful filter fail the returned
+ * channel.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterMapEffect: {
     /**
-     * @since 4.0.0
+     * Filters and maps output elements using an effectful `Filter`.
+     *
+     * Successful filter results are emitted as mapped values. Failed filter
+     * results are discarded. Failures from the effectful filter fail the returned
+     * channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, B, X, EX, RX>(filter: Filter.FilterEffect<OutElem, B, X, EX, RX>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<B, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
     /**
-     * @since 4.0.0
+     * Filters and maps output elements using an effectful `Filter`.
+     *
+     * Successful filter results are emitted as mapped values. Failed filter
+     * results are discarded. Failures from the effectful filter fail the returned
+     * channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X, EX, RX>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.FilterEffect<OutElem, B, X, EX, RX>): Channel<B, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
 };
@@ -2419,7 +2677,8 @@ export declare const filterMapEffect: {
  * Filters arrays of elements emitted by a channel, applying the filter
  * to each element within the arrays and only emitting non-empty filtered arrays.
  *
- * @example
+ * **Example** (Filtering array output)
+ *
  * ```ts
  * import { Array, Channel } from "effect"
  *
@@ -2447,15 +2706,16 @@ export declare const filterMapEffect: {
  * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
  * ```
  *
- * @since 4.0.0
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterArray: {
     /**
      * Filters arrays of elements emitted by a channel, applying the filter
      * to each element within the arrays and only emitting non-empty filtered arrays.
      *
-     * @example
+     * **Example** (Filtering array output)
+     *
      * ```ts
      * import { Array, Channel } from "effect"
      *
@@ -2483,15 +2743,16 @@ export declare const filterArray: {
      * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
      * ```
      *
-     * @since 4.0.0
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, B extends OutElem>(refinement: Predicate.Refinement<OutElem, B>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<B>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters arrays of elements emitted by a channel, applying the filter
      * to each element within the arrays and only emitting non-empty filtered arrays.
      *
-     * @example
+     * **Example** (Filtering array output)
+     *
      * ```ts
      * import { Array, Channel } from "effect"
      *
@@ -2519,15 +2780,16 @@ export declare const filterArray: {
      * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
      * ```
      *
-     * @since 4.0.0
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem>(predicate: Predicate.Predicate<Types.NoInfer<OutElem>>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters arrays of elements emitted by a channel, applying the filter
      * to each element within the arrays and only emitting non-empty filtered arrays.
      *
-     * @example
+     * **Example** (Filtering array output)
+     *
      * ```ts
      * import { Array, Channel } from "effect"
      *
@@ -2555,15 +2817,16 @@ export declare const filterArray: {
      * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
      * ```
      *
-     * @since 4.0.0
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B extends OutElem>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutElem, B>): Channel<Arr.NonEmptyReadonlyArray<B>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Filters arrays of elements emitted by a channel, applying the filter
      * to each element within the arrays and only emitting non-empty filtered arrays.
      *
-     * @example
+     * **Example** (Filtering array output)
+     *
      * ```ts
      * import { Array, Channel } from "effect"
      *
@@ -2591,63 +2854,124 @@ export declare const filterArray: {
      * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
      * ```
      *
-     * @since 4.0.0
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<Types.NoInfer<OutElem>>): Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * @since 4.0.0
+ * Filters and maps each element inside emitted non-empty arrays using a
+ * `Filter`.
+ *
+ * Successful filter results are kept as mapped values. Failed filter results
+ * are removed from the array. Arrays that become empty are discarded.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterMapArray: {
     /**
-     * @since 4.0.0
+     * Filters and maps each element inside emitted non-empty arrays using a
+     * `Filter`.
+     *
+     * Successful filter results are kept as mapped values. Failed filter results
+     * are removed from the array. Arrays that become empty are discarded.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, B, X>(filter: Filter.Filter<Types.NoInfer<OutElem>, B, X>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<B>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * @since 4.0.0
+     * Filters and maps each element inside emitted non-empty arrays using a
+     * `Filter`.
+     *
+     * Successful filter results are kept as mapped values. Failed filter results
+     * are removed from the array. Arrays that become empty are discarded.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<OutElem, B, X>): Channel<Arr.NonEmptyReadonlyArray<B>, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * @since 4.0.0
+ * Filters each element inside emitted non-empty arrays with an effectful
+ * predicate.
+ *
+ * The predicate receives the element and its index within the array. Elements
+ * for which the predicate succeeds with `true` are kept. Arrays that become
+ * empty are discarded. Predicate failures fail the returned channel.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterArrayEffect: {
     /**
-     * @since 4.0.0
+     * Filters each element inside emitted non-empty arrays with an effectful
+     * predicate.
+     *
+     * The predicate receives the element and its index within the array. Elements
+     * for which the predicate succeeds with `true` are kept. Arrays that become
+     * empty are discarded. Predicate failures fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, E, R>(predicate: (a: Types.NoInfer<OutElem>, index: number) => Effect.Effect<boolean, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Filters each element inside emitted non-empty arrays with an effectful
+     * predicate.
+     *
+     * The predicate receives the element and its index within the array. Elements
+     * for which the predicate succeeds with `true` are kept. Arrays that become
+     * empty are discarded. Predicate failures fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, E, R>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: (a: Types.NoInfer<OutElem>, index: number) => Effect.Effect<boolean, E, R>): Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * @since 4.0.0
+ * Filters and maps each element inside emitted non-empty arrays using an
+ * effectful `Filter`.
+ *
+ * Successful filter results are kept as mapped values. Failed filter results
+ * are removed from the array. Arrays that become empty are discarded. Failures
+ * from the effectful filter fail the returned channel.
+ *
  * @category Filtering
+ * @since 4.0.0
  */
 export declare const filterMapArrayEffect: {
     /**
-     * @since 4.0.0
+     * Filters and maps each element inside emitted non-empty arrays using an
+     * effectful `Filter`.
+     *
+     * Successful filter results are kept as mapped values. Failed filter results
+     * are removed from the array. Arrays that become empty are discarded. Failures
+     * from the effectful filter fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, B, X, EX, RX>(filter: Filter.FilterEffect<Types.NoInfer<OutElem>, B, X, EX, RX>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<B>, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
     /**
-     * @since 4.0.0
+     * Filters and maps each element inside emitted non-empty arrays using an
+     * effectful `Filter`.
+     *
+     * Successful filter results are kept as mapped values. Failed filter results
+     * are removed from the array. Arrays that become empty are discarded. Failures
+     * from the effectful filter fail the returned channel.
+     *
      * @category Filtering
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X, EX, RX>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.FilterEffect<OutElem, B, X, EX, RX>): Channel<Arr.NonEmptyReadonlyArray<B>, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
 };
 /**
  * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
  *
- * @example
+ * **Example** (Mapping with accumulated state)
+ *
  * ```ts
  * import { Channel, Effect } from "effect"
  *
@@ -2678,14 +3002,15 @@ export declare const filterMapArrayEffect: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const mapAccum: {
     /**
      * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
      *
-     * @example
+     * **Example** (Mapping with accumulated state)
+     *
      * ```ts
      * import { Channel, Effect } from "effect"
      *
@@ -2716,8 +3041,8 @@ export declare const mapAccum: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <S, OutElem, B, E = never, R = never>(initial: LazyArg<S>, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<readonly [state: S, values: ReadonlyArray<B>], E, R> | readonly [state: S, values: ReadonlyArray<B>], options?: {
         readonly onHalt?: ((state: S) => Array<B>) | undefined;
@@ -2725,7 +3050,8 @@ export declare const mapAccum: {
     /**
      * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
      *
-     * @example
+     * **Example** (Mapping with accumulated state)
+     *
      * ```ts
      * import { Channel, Effect } from "effect"
      *
@@ -2756,8 +3082,8 @@ export declare const mapAccum: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, S, B, E = never, R = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, initial: LazyArg<S>, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<readonly [state: S, values: ReadonlyArray<B>], E, R> | readonly [state: S, values: ReadonlyArray<B>], options?: {
         readonly onHalt?: ((state: S) => Array<B>) | undefined;
@@ -2767,7 +3093,8 @@ export declare const mapAccum: {
  * Statefully transforms a channel by scanning over its output with an accumulator function.
  * Emits the intermediate results of the scan operation.
  *
- * @example
+ * **Example** (Scanning channel output)
+ *
  * ```ts
  * import { Channel } from "effect"
  *
@@ -2789,15 +3116,16 @@ export declare const mapAccum: {
  * // Outputs: "", "hello", "hello world", "hello world from", "hello world from effect"
  * ```
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const scan: {
     /**
      * Statefully transforms a channel by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
-     * @example
+     * **Example** (Scanning channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2819,15 +3147,16 @@ export declare const scan: {
      * // Outputs: "", "hello", "hello world", "hello world from", "hello world from effect"
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <S, OutElem>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Statefully transforms a channel by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
-     * @example
+     * **Example** (Scanning channel output)
+     *
      * ```ts
      * import { Channel } from "effect"
      *
@@ -2849,8 +3178,8 @@ export declare const scan: {
      * // Outputs: "", "hello", "hello world", "hello world from", "hello world from effect"
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
@@ -2858,7 +3187,8 @@ export declare const scan: {
  * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
- * @example
+ * **Example** (Scanning channel output with effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -2895,15 +3225,16 @@ export declare const scan: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category Sequencing
+ * @since 2.0.0
  */
 export declare const scanEffect: {
     /**
      * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
-     * @example
+     * **Example** (Scanning channel output with effects)
+     *
      * ```ts
      * import { Channel, Data, Effect } from "effect"
      *
@@ -2940,15 +3271,16 @@ export declare const scanEffect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <S, OutElem, E, R>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<S, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
      * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
-     * @example
+     * **Example** (Scanning channel output with effects)
+     *
      * ```ts
      * import { Channel, Data, Effect } from "effect"
      *
@@ -2985,8 +3317,8 @@ export declare const scanEffect: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category Sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, S, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<S, E, R>): Channel<S, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
@@ -2994,7 +3326,8 @@ export declare const scanEffect: {
  * Catches any cause of failure from the channel and allows recovery by
  * creating a new channel based on the caught cause.
  *
- * @example
+ * **Example** (Recovering from failure causes)
+ *
  * ```ts
  * import { Cause, Channel, Data } from "effect"
  *
@@ -3022,15 +3355,16 @@ export declare const scanEffect: {
  * // The channel recovers gracefully from errors
  * ```
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchCause: {
     /**
      * Catches any cause of failure from the channel and allows recovery by
      * creating a new channel based on the caught cause.
      *
-     * @example
+     * **Example** (Recovering from failure causes)
+     *
      * ```ts
      * import { Cause, Channel, Data } from "effect"
      *
@@ -3058,15 +3392,16 @@ export declare const catchCause: {
      * // The channel recovers gracefully from errors
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(f: (d: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
     /**
      * Catches any cause of failure from the channel and allows recovery by
      * creating a new channel based on the caught cause.
      *
-     * @example
+     * **Example** (Recovering from failure causes)
+     *
      * ```ts
      * import { Cause, Channel, Data } from "effect"
      *
@@ -3094,24 +3429,42 @@ export declare const catchCause: {
      * // The channel recovers gracefully from errors
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
 };
 /**
- * @since 4.0.0
+ * Runs an effect with the full failure `Cause` when the channel fails, then
+ * fails the returned channel with the original cause.
+ *
+ * Use this for observing failures, such as logging or metrics. If the observer
+ * effect fails, that failure can fail the returned channel.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const tapCause: {
     /**
-     * @since 4.0.0
+     * Runs an effect with the full failure `Cause` when the channel fails, then
+     * fails the returned channel with the original cause.
+     *
+     * Use this for observing failures, such as logging or metrics. If the observer
+     * effect fails, that failure can fail the returned channel.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, A, E, R>(f: (d: Cause.Cause<OutErr>) => Effect.Effect<A, E, R>): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone | void, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect with the full failure `Cause` when the channel fails, then
+     * fails the returned channel with the original cause.
+     *
+     * Use this for observing failures, such as logging or metrics. If the observer
+     * effect fails, that failure can fail the returned channel.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: Cause.Cause<OutErr>) => Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone | void, InElem, InErr, InDone, Env | R>;
 };
@@ -3119,40 +3472,58 @@ export declare const tapCause: {
  * Catches causes of failure that match a specific filter, allowing
  * conditional error recovery based on the type of failure.
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchCauseIf: {
     /**
      * Catches causes of failure that match a specific filter, allowing
      * conditional error recovery based on the type of failure.
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(predicate: Predicate.Predicate<Cause.Cause<OutErr>>, f: (cause: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, OutErr | OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
     /**
      * Catches causes of failure that match a specific filter, allowing
      * conditional error recovery based on the type of failure.
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<Cause.Cause<OutErr>>, f: (cause: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr | OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
 };
 /**
- * @since 4.0.0
+ * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
+ *
+ * When the filter succeeds, the recovery function receives the selected value
+ * and the original cause. When the filter fails, the returned channel fails
+ * with the residual cause produced by the filter.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchCauseFilter: {
     /**
-     * @since 4.0.0
+     * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
+     *
+     * When the filter succeeds, the recovery function receives the selected value
+     * and the original cause. When the filter fails, the returned channel fails
+     * with the residual cause produced by the filter.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, EB, X extends Cause.Cause<any>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(filter: Filter.Filter<Cause.Cause<OutErr>, EB, X>, f: (failure: EB, cause: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1, Cause.Cause.Error<X> | OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
     /**
-     * @since 4.0.0
+     * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
+     *
+     * When the filter succeeds, the recovery function receives the selected value
+     * and the original cause. When the filter fails, the returned channel fails
+     * with the residual cause produced by the filter.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB, X extends Cause.Cause<any>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<Cause.Cause<OutErr>, EB, X>, f: (failure: EB, cause: Cause.Cause<OutErr>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, Cause.Cause.Error<X> | OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
 };
@@ -3162,88 +3533,173 @@ declare const catch_: {
 };
 export { 
 /**
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 catch_ as catch };
 /**
- * @since 4.0.0
+ * Runs an effect when the channel fails with a typed error, then preserves the
+ * original channel failure.
+ *
+ * The effect is not run for normal channel completion. If the observer effect
+ * fails, that failure can fail the returned channel.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const tapError: {
     /**
-     * @since 4.0.0
+     * Runs an effect when the channel fails with a typed error, then preserves the
+     * original channel failure.
+     *
+     * The effect is not run for normal channel completion. If the observer effect
+     * fails, that failure can fail the returned channel.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, A, E, R>(f: (d: OutErr) => Effect.Effect<A, E, R>): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone | void, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect when the channel fails with a typed error, then preserves the
+     * original channel failure.
+     *
+     * The effect is not run for normal channel completion. If the observer effect
+     * fails, that failure can fail the returned channel.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: OutErr) => Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone | void, InElem, InErr, InDone, Env | R>;
 };
 /**
- * @since 4.0.0
+ * Recovers from typed channel errors that match a predicate or refinement.
+ *
+ * Matching errors are handled by the recovery function. Non-matching errors
+ * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+ * are re-failed.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchIf: {
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors that match a predicate or refinement.
+     *
+     * Matching errors are handled by the recovery function. Non-matching errors
+     * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+     * are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Exclude<OutErr, EB>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors that match a predicate or refinement.
+     *
+     * Matching errors are handled by the recovery function. Non-matching errors
+     * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+     * are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = OutErr, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors that match a predicate or refinement.
+     *
+     * Matching errors are handled by the recovery function. Non-matching errors
+     * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+     * are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Exclude<OutErr, EB>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors that match a predicate or refinement.
+     *
+     * Matching errors are handled by the recovery function. Non-matching errors
+     * are handled by `orElse` when provided. Without `orElse`, non-matching errors
+     * are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = OutErr, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, predicate: Predicate.Predicate<OutErr>, f: (failure: OutErr) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: OutErr) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
- * @since 4.0.0
+ * Recovers from typed channel errors selected by a `Filter`.
+ *
+ * Successful filter results are handled by the recovery function. Failed
+ * filter results are handled by `orElse` when provided. Without `orElse`,
+ * failed filter results are re-failed.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchFilter: {
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors selected by a `Filter`.
+     *
+     * Successful filter results are handled by the recovery function. Failed
+     * filter results are handled by `orElse` when provided. Without `orElse`,
+     * failed filter results are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = X, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
-     * @since 4.0.0
+     * Recovers from typed channel errors selected by a `Filter`.
+     *
+     * Successful filter results are handled by the recovery function. Failed
+     * filter results are handled by `orElse` when provided. Without `orElse`,
+     * failed filter results are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB, X, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = X, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.Filter<OutErr, EB, X>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: X) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
- * @since 4.0.0
+ * Recovers from tagged channel errors whose `_tag` matches one or more tags.
+ *
+ * Matching tagged errors are handled by the recovery function. Non-matching
+ * errors are handled by `orElse` when provided. Without `orElse`,
+ * non-matching errors are re-failed.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchTag: {
     /**
-     * @since 4.0.0
+     * Recovers from tagged channel errors whose `_tag` matches one or more tags.
+     *
+     * Matching tagged errors are handled by the recovery function. Non-matching
+     * errors are handled by `orElse` when provided. Without `orElse`,
+     * non-matching errors are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
-     * @since 4.0.0
+     * Recovers from tagged channel errors whose `_tag` matches one or more tags.
+     *
+     * Matching tagged errors are handled by the recovery function. Non-matching
+     * errors are handled by `orElse` when provided. Without `orElse`,
+     * non-matching errors are re-failed.
+     *
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, const K extends Types.Tags<OutErr> | Arr.NonEmptyReadonlyArray<Types.Tags<OutErr>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = never, OutErr2 = Types.ExcludeTag<OutErr, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, k: K, f: (e: Types.ExtractTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((e: Types.ExcludeTag<NoInfer<OutErr>, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | OutElem2, OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Catches a specific reason within a tagged error.
  *
- * @example
+ * **Example** (Recovering from nested reasons)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3270,14 +3726,15 @@ export declare const catchTag: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchReason: {
     /**
      * Catches a specific reason within a tagged error.
      *
-     * @example
+     * **Example** (Recovering from nested reasons)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3304,14 +3761,15 @@ export declare const catchReason: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutErr, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Catches a specific reason within a tagged error.
      *
-     * @example
+     * **Example** (Recovering from nested reasons)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3338,23 +3796,23 @@ export declare const catchReason: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends Types.Tags<OutErr>, RK extends Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K, reasonTag: RK, f: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((reason: Types.ExcludeReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.OmitReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, (OutElem2 extends Types.unassigned ? OutErr : Types.ExcludeTag<OutErr, K>) | OutErr1 | OutErr2, OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
 };
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <K extends Types.Tags<OutErr>, OutErr, Cases extends {
         [RK in Types.ReasonTags<Types.ExtractTag<Types.NoInfer<OutErr>, K>>]+?: (reason: Types.ExtractReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<Types.NoInfer<OutErr>, K>, RK>) => Channel<any, any, any, any, any, any, any>;
@@ -3376,8 +3834,8 @@ export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends Types.Tags<OutErr>, Cases extends {
         [RK in Types.ReasonTags<Types.ExtractTag<OutErr, K>>]+?: (reason: Types.ExtractReason<Types.ExtractTag<OutErr, K>, RK>, error: Types.NarrowReason<Types.ExtractTag<OutErr, K>, RK>) => Channel<any, any, any, any, any, any, any>;
@@ -3400,7 +3858,8 @@ export declare const catchReasons: {
 /**
  * Promotes nested reason errors into the channel error, replacing the parent error.
  *
- * @example
+ * **Example** (Promoting nested reasons)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3423,14 +3882,15 @@ export declare const catchReasons: {
  * const unwrapped = channel.pipe(Channel.unwrapReason("AiError"))
  * ```
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const unwrapReason: {
     /**
      * Promotes nested reason errors into the channel error, replacing the parent error.
      *
-     * @example
+     * **Example** (Promoting nested reasons)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3453,14 +3913,15 @@ export declare const unwrapReason: {
      * const unwrapped = channel.pipe(Channel.unwrapReason("AiError"))
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <K extends TagsWithReason<OutErr>, OutErr>(errorTag: K): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, Types.ExcludeTag<OutErr, K> | Types.ReasonOf<Types.ExtractTag<OutErr, K>>, OutDone, InElem, InErr, InDone, Env>;
     /**
      * Promotes nested reason errors into the channel error, replacing the parent error.
      *
-     * @example
+     * **Example** (Promoting nested reasons)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3483,8 +3944,8 @@ export declare const unwrapReason: {
      * const unwrapped = channel.pipe(Channel.unwrapReason("AiError"))
      * ```
      *
-     * @since 4.0.0
      * @category Error handling
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends TagsWithReason<OutErr>>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K): Channel<OutElem, Types.ExcludeTag<OutErr, K> | Types.ReasonOf<Types.ExtractTag<OutErr, K>>, OutDone, InElem, InErr, InDone, Env>;
 };
@@ -3493,8 +3954,8 @@ export declare const unwrapReason: {
  * value of the returned channel is created by applying the specified function
  * to the failure value of this channel.
  *
- * @since 2.0.0
  * @category Error handling
+ * @since 2.0.0
  */
 export declare const mapError: {
     /**
@@ -3502,8 +3963,8 @@ export declare const mapError: {
      * value of the returned channel is created by applying the specified function
      * to the failure value of this channel.
      *
-     * @since 2.0.0
      * @category Error handling
+     * @since 2.0.0
      */
     <OutErr, OutErr2>(f: (err: OutErr) => OutErr2): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr2, OutDone, InElem, InErr, InDone, Env>;
     /**
@@ -3511,8 +3972,8 @@ export declare const mapError: {
      * value of the returned channel is created by applying the specified function
      * to the failure value of this channel.
      *
-     * @since 2.0.0
      * @category Error handling
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutErr2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (err: OutErr) => OutErr2): Channel<OutElem, OutErr2, OutDone, InElem, InErr, InDone, Env>;
 };
@@ -3520,7 +3981,8 @@ export declare const mapError: {
  * Converts all errors in the channel to defects (unrecoverable failures).
  * This is useful when you want to treat errors as programming errors.
  *
- * @example
+ * **Example** (Converting failures to defects)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3537,8 +3999,8 @@ export declare const mapError: {
  * // Any failure will now become a defect (uncaught exception)
  * ```
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const orDie: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, never, OutDone, InElem, InErr, InDone, Env>;
 /**
@@ -3546,8 +4008,8 @@ export declare const orDie: <OutElem, OutErr, OutDone, InElem, InErr, InDone, En
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const ignore: <Arg extends Channel<any, any, any, any, any, any, any> | {
     readonly log?: boolean | Severity | undefined;
@@ -3563,8 +4025,8 @@ export declare const ignore: <Arg extends Channel<any, any, any, any, any, any,
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
- * @since 4.0.0
  * @category Error handling
+ * @since 4.0.0
  */
 export declare const ignoreCause: <Arg extends Channel<any, any, any, any, any, any, any> | {
     readonly log?: boolean | Severity | undefined;
@@ -3579,35 +4041,37 @@ export declare const ignoreCause: <Arg extends Channel<any, any, any, any, any,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const retry: {
     /**
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <SO, OutErr, SE, SR>(schedule: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>) => Schedule.Schedule<SO, OutErr, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>)): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>) => Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
     /**
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, SO, SE, SR>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, schedule: Schedule.Schedule<SO, OutErr, SE, SR> | (($: <SO, SE, SR>(_: Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>) => Schedule.Schedule<SO, OutErr, SE, SR>) => Schedule.Schedule<SO, Types.NoInfer<OutErr>, SE, SR>)): Channel<OutElem, OutErr | SE, OutDone, InElem, InErr, InDone, Env | SR>;
 };
 /**
- * Returns a new channel, which sequentially combines this channel, together
- * with the provided factory function, which creates a second channel based on
- * the output values of this channel. The result is a channel that will first
- * perform the functions of this channel, before performing the functions of
- * the created channel (including yielding its terminal value).
+ * Maps each output element to a channel and emits values from the most recent
+ * active child channels.
+ *
+ * With the default concurrency of `1`, starting a new child channel interrupts
+ * the previous child channel. Use `options.concurrency` to allow more active
+ * child channels. The source channel's done value is preserved.
+ *
+ * **Example** (Switching mapped channels)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3627,18 +4091,20 @@ export declare const retry: {
  * // Outputs: "value-1", "value-2", "value-3"
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const switchMap: {
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element to a channel and emits values from the most recent
+     * active child channels.
+     *
+     * With the default concurrency of `1`, starting a new child channel interrupts
+     * the previous child channel. Use `options.concurrency` to allow more active
+     * child channels. The source channel's done value is preserved.
+     *
+     * **Example** (Switching mapped channels)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3658,21 +4124,23 @@ export declare const switchMap: {
      * // Outputs: "value-1", "value-2", "value-3"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(f: (d: OutElem) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
         readonly bufferSize?: number | undefined;
     }): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem1, OutErr1 | OutErr, OutDone, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
     /**
-     * Returns a new channel, which sequentially combines this channel, together
-     * with the provided factory function, which creates a second channel based on
-     * the output values of this channel. The result is a channel that will first
-     * perform the functions of this channel, before performing the functions of
-     * the created channel (including yielding its terminal value).
+     * Maps each output element to a channel and emits values from the most recent
+     * active child channels.
+     *
+     * With the default concurrency of `1`, starting a new child channel interrupts
+     * the previous child channel. Use `options.concurrency` to allow more active
+     * child channels. The source channel's done value is preserved.
+     *
+     * **Example** (Switching mapped channels)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3692,8 +4160,8 @@ export declare const switchMap: {
      * // Outputs: "value-1", "value-2", "value-3"
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (d: OutElem) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -3703,7 +4171,8 @@ export declare const switchMap: {
 /**
  * Merges multiple channels with specified concurrency and buffering options.
  *
- * @example
+ * **Example** (Merging nested channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3727,14 +4196,15 @@ export declare const switchMap: {
  * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const mergeAll: {
     /**
      * Merges multiple channels with specified concurrency and buffering options.
      *
-     * @example
+     * **Example** (Merging nested channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3758,8 +4228,8 @@ export declare const mergeAll: {
      * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     (options: {
         readonly concurrency: number | "unbounded";
@@ -3769,7 +4239,8 @@ export declare const mergeAll: {
     /**
      * Merges multiple channels with specified concurrency and buffering options.
      *
-     * @example
+     * **Example** (Merging nested channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3793,8 +4264,8 @@ export declare const mergeAll: {
      * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutErr, OutDone, InElem, InErr, InDone, Env>(channels: Channel<Channel<OutElem, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, OutErr, OutDone, InElem, InErr, InDone, Env>, options: {
         readonly concurrency: number | "unbounded";
@@ -3805,7 +4276,8 @@ export declare const mergeAll: {
 /**
  * Represents strategies for halting merged channels when one completes or fails.
  *
- * @example
+ * **Example** (Choosing merge halt strategies)
+ *
  * ```ts
  * import type { Channel } from "effect"
  *
@@ -3816,15 +4288,16 @@ export declare const mergeAll: {
  * const either: Channel.HaltStrategy = "either" // Stop when either channel halts
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type HaltStrategy = "left" | "right" | "both" | "either";
 /**
  * Returns a new channel, which is the merge of this channel and the specified
  * channel.
  *
- * @example
+ * **Example** (Merging channels)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3845,15 +4318,16 @@ export type HaltStrategy = "left" | "right" | "both" | "either";
  * // Order may vary: 1, "a", 2, "b", 3, "c"
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const merge: {
     /**
      * Returns a new channel, which is the merge of this channel and the specified
      * channel.
      *
-     * @example
+     * **Example** (Merging channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3874,8 +4348,8 @@ export declare const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(right: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly haltStrategy?: HaltStrategy | undefined;
@@ -3884,7 +4358,8 @@ export declare const merge: {
      * Returns a new channel, which is the merge of this channel and the specified
      * channel.
      *
-     * @example
+     * **Example** (Merging channels)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -3905,26 +4380,44 @@ export declare const merge: {
      * // Order may vary: 1, "a", 2, "b", 3, "c"
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(left: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, right: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, options?: {
         readonly haltStrategy?: HaltStrategy | undefined;
     } | undefined): Channel<OutElem | OutElem1, OutErr | OutErr1, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env | Env1>;
 };
 /**
- * @since 4.0.0
+ * Runs an effect concurrently with a channel while emitting only the channel's
+ * output elements.
+ *
+ * The effect's successful value is ignored. If the effect fails while the
+ * channel is running, the returned channel fails with that error.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const mergeEffect: {
     /**
-     * @since 4.0.0
+     * Runs an effect concurrently with a channel while emitting only the channel's
+     * output elements.
+     *
+     * The effect's successful value is ignored. If the effect fails while the
+     * channel is running, the returned channel fails with that error.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <X, E, R>(effect: Effect.Effect<X, E, R>): <OutElem, OutDone, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect concurrently with a channel while emitting only the channel's
+     * output elements.
+     *
+     * The effect's successful value is ignored. If the effect fails while the
+     * channel is running, the returned channel fails with that error.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, X, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<X, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
@@ -3938,7 +4431,7 @@ export declare const mergeEffect: {
  * if the stream ends without a terminator the final partial line is still
  * emitted.
  *
- * **Example**
+ * **Example** (Splitting string chunks into lines)
  *
  * ```ts
  * import { Effect, Stream } from "effect"
@@ -3952,18 +4445,27 @@ export declare const mergeEffect: {
  * }))
  * ```
  *
- * @since 2.0.0
  * @category String manipulation
+ * @since 2.0.0
  */
 export declare const splitLines: <Err, Done>() => Channel<Arr.NonEmptyReadonlyArray<string>, Err, Done, Arr.NonEmptyReadonlyArray<string>, Err, Done>;
 /**
- * @since 4.0.0
+ * Decodes incoming `Uint8Array` chunks into strings using `TextDecoder`.
+ *
+ * Each `Uint8Array` inside an emitted array is decoded independently. The
+ * optional `encoding` and `options` are passed to `TextDecoder`.
+ *
  * @category String manipulation
+ * @since 4.0.0
  */
 export declare const decodeText: <Err, Done>(encoding?: string, options?: TextDecoderOptions) => Channel<Arr.NonEmptyReadonlyArray<string>, Err, Done, Arr.NonEmptyReadonlyArray<Uint8Array>, Err, Done>;
 /**
- * @since 4.0.0
+ * Encodes incoming string chunks into `Uint8Array` values using `TextEncoder`.
+ *
+ * Each string inside an emitted array is encoded independently.
+ *
  * @category String manipulation
+ * @since 4.0.0
  */
 export declare const encodeText: <Err, Done>() => Channel<Arr.NonEmptyReadonlyArray<Uint8Array>, Err, Done, Arr.NonEmptyReadonlyArray<string>, Err, Done>;
 /**
@@ -3972,7 +4474,8 @@ export declare const encodeText: <Err, Done>() => Channel<Arr.NonEmptyReadonlyAr
  * and the output type of the specified channel, terminating with the value of
  * the specified channel.
  *
- * @example
+ * **Example** (Piping one channel into another)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -3990,8 +4493,8 @@ export declare const encodeText: <Err, Done>() => Channel<Arr.NonEmptyReadonlyAr
  * // Outputs: 2, 4, 6
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const pipeTo: {
     /**
@@ -4000,7 +4503,8 @@ export declare const pipeTo: {
      * and the output type of the specified channel, terminating with the value of
      * the specified channel.
      *
-     * @example
+     * **Example** (Piping one channel into another)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -4018,8 +4522,8 @@ export declare const pipeTo: {
      * // Outputs: 2, 4, 6
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>(that: Channel<OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>): <InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem2, OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
@@ -4028,7 +4532,8 @@ export declare const pipeTo: {
      * and the output type of the specified channel, terminating with the value of
      * the specified channel.
      *
-     * @example
+     * **Example** (Piping one channel into another)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -4046,8 +4551,8 @@ export declare const pipeTo: {
      * // Outputs: 2, 4, 6
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2, OutErr2, OutDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem2, OutErr2, OutDone2, OutElem, OutErr, OutDone, Env2>): Channel<OutElem2, OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
@@ -4056,7 +4561,8 @@ export declare const pipeTo: {
  * specified channel and preserves this channel's failures without providing
  * them to the other channel for observation.
  *
- * @example
+ * **Example** (Piping while preserving failures)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -4074,8 +4580,8 @@ export declare const pipeTo: {
  * // Source errors are preserved and not sent to transform channel
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const pipeToOrFail: {
     /**
@@ -4083,7 +4589,8 @@ export declare const pipeToOrFail: {
      * specified channel and preserves this channel's failures without providing
      * them to the other channel for observation.
      *
-     * @example
+     * **Example** (Piping while preserving failures)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -4101,8 +4608,8 @@ export declare const pipeToOrFail: {
      * // Source errors are preserved and not sent to transform channel
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem2, OutErr2, OutDone2, OutElem, OutDone, Env2>(that: Channel<OutElem2, OutErr2, OutDone2, OutElem, never, OutDone, Env2>): <OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem2, OutErr | OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
@@ -4110,7 +4617,8 @@ export declare const pipeToOrFail: {
      * specified channel and preserves this channel's failures without providing
      * them to the other channel for observation.
      *
-     * @example
+     * **Example** (Piping while preserving failures)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -4128,8 +4636,8 @@ export declare const pipeToOrFail: {
      * // Source errors are preserved and not sent to transform channel
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem2, OutErr2, OutDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem2, OutErr2, OutDone2, OutElem, never, OutDone, Env2>): Channel<OutElem2, OutErr | OutErr2, OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
@@ -4137,7 +4645,8 @@ export declare const pipeToOrFail: {
  * Constructs a `Channel` from a scoped effect that will result in a
  * `Channel` if successful.
  *
- * @example
+ * **Example** (Unwrapping channel effects)
+ *
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -4156,88 +4665,115 @@ export declare const pipeToOrFail: {
  * // The resulting channel outputs: 1, 2, 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const unwrap: <OutElem, OutErr, OutDone, InElem, InErr, InDone, R2, E, R>(channel: Effect.Effect<Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, R2>, E, R>) => Channel<OutElem, E | OutErr, OutDone, InElem, InErr, InDone, Exclude<R, Scope.Scope> | R2>;
 /**
- * @since 2.0.0
+ * Runs a channel with a scope provided for the duration of the channel
+ * execution, removing the channel's `Scope` requirement.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export declare const scoped: <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, Scope.Scope>>;
 /**
- * Returns a new channel which embeds the given input handler into a Channel.
+ * Runs an input handler against the upstream pull while the wrapped channel
+ * runs without receiving upstream input directly.
  *
- * @example
- * ```ts
- * import { Channel, Data, Effect } from "effect"
+ * The input handler is forked in the channel scope. The wrapped channel is run
+ * with an already-completed input.
  *
- * class EmbedError extends Data.TaggedError("EmbedError")<{
- *   readonly stage: string
- * }> {}
+ * **Example** (Embedding custom input handling)
+ *
+ * ```ts
+ * import { Channel, Effect } from "effect"
  *
  * // Create a base channel
  * const baseChannel = Channel.fromIterable([1, 2, 3])
  *
- * // Embed input handling - simplified example
+ * // Drain the embedded input while the base channel runs
  * const embeddedChannel = Channel.embedInput(
  *   baseChannel,
- *   (_upstream) => Effect.void
+ *   (upstream) =>
+ *     upstream.pipe(
+ *       Effect.tap((message) =>
+ *         Effect.sync(() => console.log(message))
+ *       ),
+ *       Effect.forever,
+ *       Effect.ignore
+ *     )
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const embedInput: {
     /**
-     * Returns a new channel which embeds the given input handler into a Channel.
+     * Runs an input handler against the upstream pull while the wrapped channel
+     * runs without receiving upstream input directly.
      *
-     * @example
-     * ```ts
-     * import { Channel, Data, Effect } from "effect"
+     * The input handler is forked in the channel scope. The wrapped channel is run
+     * with an already-completed input.
      *
-     * class EmbedError extends Data.TaggedError("EmbedError")<{
-     *   readonly stage: string
-     * }> {}
+     * **Example** (Embedding custom input handling)
+     *
+     * ```ts
+     * import { Channel, Effect } from "effect"
      *
      * // Create a base channel
      * const baseChannel = Channel.fromIterable([1, 2, 3])
      *
-     * // Embed input handling - simplified example
+     * // Drain the embedded input while the base channel runs
      * const embeddedChannel = Channel.embedInput(
      *   baseChannel,
-     *   (_upstream) => Effect.void
+     *   (upstream) =>
+     *     upstream.pipe(
+     *       Effect.tap((message) =>
+     *         Effect.sync(() => console.log(message))
+     *       ),
+     *       Effect.forever,
+     *       Effect.ignore
+     *     )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <InElem, InErr, InDone, R>(input: (upstream: Pull.Pull<InElem, InErr, InDone>) => Effect.Effect<void, never, R>): <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * Returns a new channel which embeds the given input handler into a Channel.
+     * Runs an input handler against the upstream pull while the wrapped channel
+     * runs without receiving upstream input directly.
      *
-     * @example
-     * ```ts
-     * import { Channel, Data, Effect } from "effect"
+     * The input handler is forked in the channel scope. The wrapped channel is run
+     * with an already-completed input.
      *
-     * class EmbedError extends Data.TaggedError("EmbedError")<{
-     *   readonly stage: string
-     * }> {}
+     * **Example** (Embedding custom input handling)
+     *
+     * ```ts
+     * import { Channel, Effect } from "effect"
      *
      * // Create a base channel
      * const baseChannel = Channel.fromIterable([1, 2, 3])
      *
-     * // Embed input handling - simplified example
+     * // Drain the embedded input while the base channel runs
      * const embeddedChannel = Channel.embedInput(
      *   baseChannel,
-     *   (_upstream) => Effect.void
+     *   (upstream) =>
+     *     upstream.pipe(
+     *       Effect.tap((message) =>
+     *         Effect.sync(() => console.log(message))
+     *       ),
+     *       Effect.forever,
+     *       Effect.ignore
+     *     )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, Env, InErr, InElem, InDone, R>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, input: (upstream: Pull.Pull<InElem, InErr, InDone>) => Effect.Effect<void, never, R>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>;
 };
@@ -4245,16 +4781,16 @@ export declare const embedInput: {
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
- * @since 2.0.0
  * @category Buffering
+ * @since 2.0.0
  */
 export declare const buffer: {
     /**
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
-     * @since 2.0.0
      * @category Buffering
+     * @since 2.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -4266,8 +4802,8 @@ export declare const buffer: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
-     * @since 2.0.0
      * @category Buffering
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, options: {
         readonly capacity: "unbounded";
@@ -4280,16 +4816,16 @@ export declare const buffer: {
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
- * @since 2.0.0
  * @category Buffering
+ * @since 2.0.0
  */
 export declare const bufferArray: {
     /**
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
-     * @since 2.0.0
      * @category Buffering
+     * @since 2.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -4301,8 +4837,8 @@ export declare const bufferArray: {
      * Allows a faster producer to progress independently of a slower consumer by
      * buffering up to `capacity` elements in a queue.
      *
-     * @since 2.0.0
      * @category Buffering
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, options: {
         readonly capacity: "unbounded";
@@ -4320,8 +4856,8 @@ export declare const bufferArray: {
  * returned channel will yield the success value of the underlying channel as
  * its terminal value.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const interruptWhen: {
     /**
@@ -4333,8 +4869,8 @@ export declare const interruptWhen: {
      * returned channel will yield the success value of the underlying channel as
      * its terminal value.
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
@@ -4346,40 +4882,76 @@ export declare const interruptWhen: {
      * returned channel will yield the success value of the underlying channel as
      * its terminal value.
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2, OutErr2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<OutDone2, OutErr2, Env2>): Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * @since 4.0.0
+ * Halts a channel when the specified effect completes or fails.
+ *
+ * If the effect completes before the channel is done, its success value becomes
+ * the returned channel's done value. If the effect fails, the returned channel
+ * fails with that error. If the channel completes first, the channel's done
+ * value is preserved.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const haltWhen: {
     /**
-     * @since 4.0.0
+     * Halts a channel when the specified effect completes or fails.
+     *
+     * If the effect completes before the channel is done, its success value becomes
+     * the returned channel's done value. If the effect fails, the returned channel
+     * fails with that error. If the channel completes first, the channel's done
+     * value is preserved.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * @since 4.0.0
+     * Halts a channel when the specified effect completes or fails.
+     *
+     * If the effect completes before the channel is done, its success value becomes
+     * the returned channel's done value. If the effect fails, the returned channel
+     * fails with that error. If the channel completes first, the channel's done
+     * value is preserved.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2, OutErr2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<OutDone2, OutErr2, Env2>): Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * @since 4.0.0
+ * Attaches a finalizer that runs only when the channel exits with failure.
+ *
+ * The finalizer receives the failure `Cause`. The original channel failure is
+ * preserved. The finalizer itself must not fail.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const onError: {
     /**
-     * @since 4.0.0
+     * Attaches a finalizer that runs only when the channel exits with failure.
+     *
+     * The finalizer receives the failure `Cause`. The original channel failure is
+     * preserved. The finalizer itself must not fail.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutDone, OutErr, Env2>(finalizer: (cause: Cause.Cause<OutErr>) => Effect.Effect<unknown, never, Env2>): <OutElem, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * @since 4.0.0
+     * Attaches a finalizer that runs only when the channel exits with failure.
+     *
+     * The finalizer receives the failure `Cause`. The original channel failure is
+     * preserved. The finalizer itself must not fail.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: (cause: Cause.Cause<OutErr>) => Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
@@ -4388,7 +4960,8 @@ export declare const onError: {
  * guaranteed to be executed so long as the channel begins execution (and
  * regardless of whether or not it completes).
  *
- * @example
+ * **Example** (Running exit finalizers)
+ *
  * ```ts
  * import { Channel, Console, Data, Exit } from "effect"
  *
@@ -4409,8 +4982,8 @@ export declare const onError: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const onExit: {
     /**
@@ -4418,7 +4991,8 @@ export declare const onExit: {
      * guaranteed to be executed so long as the channel begins execution (and
      * regardless of whether or not it completes).
      *
-     * @example
+     * **Example** (Running exit finalizers)
+     *
      * ```ts
      * import { Channel, Console, Data, Exit } from "effect"
      *
@@ -4439,8 +5013,8 @@ export declare const onExit: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <OutDone, OutErr, Env2>(finalizer: (e: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown, never, Env2>): <OutElem, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
@@ -4448,7 +5022,8 @@ export declare const onExit: {
      * guaranteed to be executed so long as the channel begins execution (and
      * regardless of whether or not it completes).
      *
-     * @example
+     * **Example** (Running exit finalizers)
+     *
      * ```ts
      * import { Channel, Console, Data, Exit } from "effect"
      *
@@ -4469,56 +5044,107 @@ export declare const onExit: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: (e: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * @since 4.0.0
+ * Runs an effect before the channel starts.
+ *
+ * The effect's successful value is ignored. If the effect fails, the returned
+ * channel fails before running the source channel.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const onStart: {
     /**
-     * @since 4.0.0
+     * Runs an effect before the channel starts.
+     *
+     * The effect's successful value is ignored. If the effect fails, the returned
+     * channel fails before running the source channel.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <A, E, R>(onStart: Effect.Effect<A, E, R>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect before the channel starts.
+     *
+     * The effect's successful value is ignored. If the effect fails, the returned
+     * channel fails before running the source channel.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onStart: Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * @since 4.0.0
+ * Runs an effect the first time the channel emits an output element.
+ *
+ * The effect receives the first emitted element. The first element is still
+ * emitted unchanged. The effect is not run if the channel completes without
+ * emitting an element.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const onFirst: {
     /**
-     * @since 4.0.0
+     * Runs an effect the first time the channel emits an output element.
+     *
+     * The effect receives the first emitted element. The first element is still
+     * emitted unchanged. The effect is not run if the channel completes without
+     * emitting an element.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, A, E, R>(onFirst: (element: Types.NoInfer<OutElem>) => Effect.Effect<A, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect the first time the channel emits an output element.
+     *
+     * The effect receives the first emitted element. The first element is still
+     * emitted unchanged. The effect is not run if the channel completes without
+     * emitting an element.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onFirst: (element: Types.NoInfer<OutElem>) => Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * @since 4.0.0
+ * Runs an effect when the channel completes successfully.
+ *
+ * The effect runs before the original done value is propagated. The effect is
+ * not run when the channel fails. If the effect fails, the returned channel
+ * fails with that error.
+ *
  * @category utils
+ * @since 4.0.0
  */
 export declare const onEnd: {
     /**
-     * @since 4.0.0
+     * Runs an effect when the channel completes successfully.
+     *
+     * The effect runs before the original done value is propagated. The effect is
+     * not run when the channel fails. If the effect fails, the returned channel
+     * fails with that error.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <A, E, R>(onEnd: Effect.Effect<A, E, R>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect when the channel completes successfully.
+     *
+     * The effect runs before the original done value is propagated. The effect is
+     * not run when the channel fails. If the effect fails, the returned channel
+     * fails with that error.
+     *
      * @category utils
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onEnd: Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
@@ -4527,7 +5153,8 @@ export declare const onEnd: {
  * guaranteed to be executed so long as the channel begins execution (and
  * regardless of whether or not it completes).
  *
- * @example
+ * **Example** (Ensuring cleanup runs)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -4545,8 +5172,8 @@ export declare const onEnd: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const ensuring: {
     /**
@@ -4554,7 +5181,8 @@ export declare const ensuring: {
      * guaranteed to be executed so long as the channel begins execution (and
      * regardless of whether or not it completes).
      *
-     * @example
+     * **Example** (Ensuring cleanup runs)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -4572,8 +5200,8 @@ export declare const ensuring: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <Env2>(finalizer: Effect.Effect<unknown, never, Env2>): <OutElem, OutDone, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
@@ -4581,7 +5209,8 @@ export declare const ensuring: {
      * guaranteed to be executed so long as the channel begins execution (and
      * regardless of whether or not it completes).
      *
-     * @example
+     * **Example** (Ensuring cleanup runs)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -4599,149 +5228,244 @@ export declare const ensuring: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
  * Create a channel from the specified services.
  *
- * @since 2.0.0
  * @category Services
+ * @since 2.0.0
  */
 export declare const contextWith: <Env, OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2>(f: (context: Context.Context<Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | Env2>;
 /**
- * Provides a layer or context to the channel, removing the corresponding
- * service requirements. Use `options.local` to build the layer every time; by
- * default, layers are shared between provide calls.
+ * Provides a `Context` to the channel, removing the corresponding service
+ * requirements from the returned channel.
  *
- * @since 4.0.0
  * @category Services
+ * @since 4.0.0
  */
 export declare const provideContext: {
     /**
-     * Provides a layer or context to the channel, removing the corresponding
-     * service requirements. Use `options.local` to build the layer every time; by
-     * default, layers are shared between provide calls.
+     * Provides a `Context` to the channel, removing the corresponding service
+     * requirements from the returned channel.
      *
-     * @since 4.0.0
      * @category Services
+     * @since 4.0.0
      */
     <R2>(context: Context.Context<R2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, R2>>;
     /**
-     * Provides a layer or context to the channel, removing the corresponding
-     * service requirements. Use `options.local` to build the layer every time; by
-     * default, layers are shared between provide calls.
+     * Provides a `Context` to the channel, removing the corresponding service
+     * requirements from the returned channel.
      *
-     * @since 4.0.0
      * @category Services
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, R2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, context: Context.Context<R2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, R2>>;
 };
 /**
- * @since 4.0.0
+ * Provides a concrete service for a context key, removing that service
+ * requirement from the returned channel.
+ *
  * @category Services
+ * @since 4.0.0
  */
 export declare const provideService: {
     /**
-     * @since 4.0.0
+     * Provides a concrete service for a context key, removing that service
+     * requirement from the returned channel.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <I, S>(key: Context.Key<I, S>, service: NoInfer<S>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, I>>;
     /**
-     * @since 4.0.0
+     * Provides a concrete service for a context key, removing that service
+     * requirement from the returned channel.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, I, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, key: Context.Key<I, S>, service: NoInfer<S>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, I>>;
 };
 /**
- * @since 4.0.0
+ * Evaluates an effect to obtain a service, then provides that service to the
+ * channel.
+ *
+ * If the service effect fails, the returned channel fails. The provided service
+ * removes the corresponding service requirement from the returned channel.
+ *
  * @category Services
+ * @since 4.0.0
  */
 export declare const provideServiceEffect: {
     /**
-     * @since 4.0.0
+     * Evaluates an effect to obtain a service, then provides that service to the
+     * channel.
+     *
+     * If the service effect fails, the returned channel fails. The provided service
+     * removes the corresponding service requirement from the returned channel.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <I, S, ES, RS>(key: Context.Key<I, S>, service: Effect.Effect<NoInfer<S>, ES, RS>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | ES, OutDone, InElem, InErr, InDone, Exclude<Env, I> | RS>;
     /**
-     * @since 4.0.0
+     * Evaluates an effect to obtain a service, then provides that service to the
+     * channel.
+     *
+     * If the service effect fails, the returned channel fails. The provided service
+     * removes the corresponding service requirement from the returned channel.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, I, S, ES, RS>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, key: Context.Key<I, S>, service: Effect.Effect<NoInfer<S>, ES, RS>): Channel<OutElem, OutErr | ES, OutDone, InElem, InErr, InDone, Exclude<Env, I> | RS>;
 };
 /**
- * @since 4.0.0
+ * Provides a `Layer` or `Context` to the channel, removing the corresponding
+ * service requirements.
+ *
+ * Providing a `Context` delegates to `provideContext`. Providing a `Layer`
+ * builds the layer in the channel scope. Use `options.local` to build a fresh
+ * layer instance for this provision.
+ *
  * @category Services
+ * @since 4.0.0
  */
 export declare const provide: {
     /**
-     * @since 4.0.0
+     * Provides a `Layer` or `Context` to the channel, removing the corresponding
+     * service requirements.
+     *
+     * Providing a `Context` delegates to `provideContext`. Providing a `Layer`
+     * builds the layer in the channel scope. Use `options.local` to build a fresh
+     * layer instance for this provision.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <A, E = never, R = never>(layer: Layer.Layer<A, E, R> | Context.Context<A>, options?: {
         readonly local?: boolean | undefined;
     } | undefined): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Exclude<Env, A> | R>;
     /**
-     * @since 4.0.0
+     * Provides a `Layer` or `Context` to the channel, removing the corresponding
+     * service requirements.
+     *
+     * Providing a `Context` delegates to `provideContext`. Providing a `Layer`
+     * builds the layer in the channel scope. Use `options.local` to build a fresh
+     * layer instance for this provision.
+     *
      * @category Services
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E = never, R = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, layer: Layer.Layer<A, E, R> | Context.Context<A>, options?: {
         readonly local?: boolean | undefined;
     } | undefined): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Exclude<Env, A> | R>;
 };
 /**
- * @since 2.0.0
+ * Transforms the current context before running the channel.
+ *
+ * The function receives the surrounding context and returns the context to
+ * provide to the channel. The returned channel requires the services needed to
+ * build that context.
+ *
  * @category Services
+ * @since 2.0.0
  */
 export declare const updateContext: {
     /**
-     * @since 2.0.0
+     * Transforms the current context before running the channel.
+     *
+     * The function receives the surrounding context and returns the context to
+     * provide to the channel. The returned channel requires the services needed to
+     * build that context.
+     *
      * @category Services
+     * @since 2.0.0
      */
     <Env, R2>(f: (context: Context.Context<R2>) => Context.Context<Env>): <OutElem, OutErr, OutDone, InElem, InErr, InDone>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>) => Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, R2>;
     /**
-     * @since 2.0.0
+     * Transforms the current context before running the channel.
+     *
+     * The function receives the surrounding context and returns the context to
+     * provide to the channel. The returned channel requires the services needed to
+     * build that context.
+     *
      * @category Services
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, R2>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, f: (context: Context.Context<R2>) => Context.Context<Env>): Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, R2>;
 };
 /**
- * @since 2.0.0
+ * Updates a service in the current context before running the channel.
+ *
+ * The existing service is read from the context. The updated service is
+ * provided to the channel under the same key.
+ *
  * @category Services
+ * @since 2.0.0
  */
 export declare const updateService: {
     /**
-     * @since 2.0.0
+     * Updates a service in the current context before running the channel.
+     *
+     * The existing service is read from the context. The updated service is
+     * provided to the channel under the same key.
+     *
      * @category Services
+     * @since 2.0.0
      */
     <I, S>(key: Context.Key<I, S>, f: (service: NoInfer<S>) => S): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>) => Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env | I>;
     /**
-     * @since 2.0.0
+     * Updates a service in the current context before running the channel.
+     *
+     * The existing service is read from the context. The updated service is
+     * provided to the channel under the same key.
+     *
      * @category Services
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, I, S>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, service: Context.Key<I, S>, f: (service: NoInfer<S>) => S): Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env | I>;
 };
 /**
- * @since 4.0.0
+ * Runs the channel inside a tracing span with the specified name and options.
+ *
+ * The created span is provided as the current parent span while the channel
+ * runs. The span is ended with the channel's exit value.
+ *
  * @category Tracing
+ * @since 4.0.0
  */
 export declare const withSpan: {
     /**
-     * @since 4.0.0
+     * Runs the channel inside a tracing span with the specified name and options.
+     *
+     * The created span is provided as the current parent span while the channel
+     * runs. The span is ended with the channel's exit value.
+     *
      * @category Tracing
+     * @since 4.0.0
      */
     (name: string, options?: SpanOptions): <OutElem, OutErr, OutDone, InElem, InErr, InDone, R>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, R>) => Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Exclude<R, ParentSpan>>;
     /**
-     * @since 4.0.0
+     * Runs the channel inside a tracing span with the specified name and options.
+     *
+     * The created span is provided as the current parent span while the channel
+     * runs. The span is ended with the channel's exit value.
+     *
      * @category Tracing
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, R>(self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, R>, name: string, options?: SpanOptions): Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Exclude<R, ParentSpan>>;
 };
 /**
- * @since 4.0.0
+ * The starting channel for Do notation, emitting an empty object.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export declare const Do: Channel<{}>;
 declare const let_: {
@@ -4754,18 +5478,32 @@ declare const let_: {
 };
 export { 
 /**
- * @since 4.0.0
  * @category Do notation
+ * @since 4.0.0
  */
 let_ as let };
 /**
- * @since 4.0.0
+ * Adds a field to each object emitted by a channel by running another channel
+ * derived from that object.
+ *
+ * The field name must not already exist on the emitted object. The derived
+ * channel's output becomes the value of the new field. `options.concurrency`
+ * and `options.bufferSize` control how derived channels are flattened.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export declare const bind: {
     /**
-     * @since 4.0.0
+     * Adds a field to each object emitted by a channel by running another channel
+     * derived from that object.
+     *
+     * The field name must not already exist on the emitted object. The derived
+     * channel's output becomes the value of the new field. `options.concurrency`
+     * and `options.bufferSize` control how derived channels are flattened.
+     *
      * @category Do notation
+     * @since 4.0.0
      */
     <N extends string, OutElem extends object, B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>(name: Exclude<N, keyof OutElem>, f: (a: NoInfer<OutElem>) => Channel<B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -4774,8 +5512,15 @@ export declare const bind: {
         [K in N | keyof OutElem]: K extends keyof OutElem ? OutElem[K] : B;
     }, OutErr2 | OutErr, OutDone, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env2 | Env>;
     /**
-     * @since 4.0.0
+     * Adds a field to each object emitted by a channel by running another channel
+     * derived from that object.
+     *
+     * The field name must not already exist on the emitted object. The derived
+     * channel's output becomes the value of the new field. `options.concurrency`
+     * and `options.bufferSize` control how derived channels are flattened.
+     *
      * @category Do notation
+     * @since 4.0.0
      */
     <OutElem extends object, OutErr, OutDone, InElem, InErr, InDone, Env, N extends string, B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, name: Exclude<N, keyof OutElem>, f: (a: NoInfer<OutElem>) => Channel<B, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, options?: {
         readonly concurrency?: number | "unbounded" | undefined;
@@ -4785,20 +5530,26 @@ export declare const bind: {
     }, OutErr2 | OutErr, OutDone, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env2 | Env>;
 };
 /**
- * @since 4.0.0
+ * Wraps each output element in an object under the specified field name.
+ *
  * @category Do notation
+ * @since 4.0.0
  */
 export declare const bindTo: {
     /**
-     * @since 4.0.0
+     * Wraps each output element in an object under the specified field name.
+     *
      * @category Do notation
+     * @since 4.0.0
      */
     <N extends string>(name: N): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<{
         [K in N]: OutElem;
     }, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * @since 4.0.0
+     * Wraps each output element in an object under the specified field name.
+     *
      * @category Do notation
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, N extends string>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, name: N): Channel<{
         [K in N]: OutElem;
@@ -4807,7 +5558,8 @@ export declare const bindTo: {
 /**
  * Runs a channel and counts the number of elements it outputs.
  *
- * @example
+ * **Example** (Counting channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -4824,14 +5576,15 @@ export declare const bindTo: {
  * // Effect.runSync(countEffect) // Returns: 5
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export declare const runCount: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<void, OutErr, Env>;
 /**
  * Runs a channel and discards all output elements, returning only the final result.
  *
- * @example
+ * **Example** (Draining channel output at runtime)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -4852,14 +5605,15 @@ export declare const runCount: <OutElem, OutErr, OutDone, Env>(self: Channel<Out
  * // Effect.runSync(drainEffect) // Returns: "completed"
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export declare const runDrain: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<OutDone, OutErr, Env>;
 /**
  * Runs a channel and applies an effect to each output element.
  *
- * @example
+ * **Example** (Running effects for each output)
+ *
  * ```ts
  * import { Channel, Console, Data } from "effect"
  *
@@ -4879,14 +5633,15 @@ export declare const runDrain: <OutElem, OutErr, OutDone, Env>(self: Channel<Out
  * // Logs: "Processing: 1", "Processing: 2", "Processing: 3"
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export declare const runForEach: {
     /**
      * Runs a channel and applies an effect to each output element.
      *
-     * @example
+     * **Example** (Running effects for each output)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -4906,14 +5661,15 @@ export declare const runForEach: {
      * // Logs: "Processing: 1", "Processing: 2", "Processing: 3"
      * ```
      *
-     * @since 2.0.0
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, EX, RX>(f: (o: OutElem) => Effect.Effect<void, EX, RX>): <OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<OutDone, OutErr | EX, Env | RX>;
     /**
      * Runs a channel and applies an effect to each output element.
      *
-     * @example
+     * **Example** (Running effects for each output)
+     *
      * ```ts
      * import { Channel, Console, Data } from "effect"
      *
@@ -4933,31 +5689,50 @@ export declare const runForEach: {
      * // Logs: "Processing: 1", "Processing: 2", "Processing: 3"
      * ```
      *
-     * @since 2.0.0
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, Env, EX, RX>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, f: (o: OutElem) => Effect.Effect<void, EX, RX>): Effect.Effect<OutDone, OutErr | EX, Env | RX>;
 };
 /**
- * @since 2.0.0
+ * Runs a channel and applies an effectful predicate to each output element
+ * until the predicate returns `false`.
+ *
+ * Returning `true` continues consuming the channel. Returning `false` stops
+ * consumption early. The returned effect completes with `void`.
+ *
  * @category execution
+ * @since 2.0.0
  */
 export declare const runForEachWhile: {
     /**
-     * @since 2.0.0
+     * Runs a channel and applies an effectful predicate to each output element
+     * until the predicate returns `false`.
+     *
+     * Returning `true` continues consuming the channel. Returning `false` stops
+     * consumption early. The returned effect completes with `void`.
+     *
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, EX, RX>(f: (o: OutElem) => Effect.Effect<boolean, EX, RX>): <OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<void, OutErr | EX, Env | RX>;
     /**
-     * @since 2.0.0
+     * Runs a channel and applies an effectful predicate to each output element
+     * until the predicate returns `false`.
+     *
+     * Returning `true` continues consuming the channel. Returning `false` stops
+     * consumption early. The returned effect completes with `void`.
+     *
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, Env, EX, RX>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, f: (o: OutElem) => Effect.Effect<boolean, EX, RX>): Effect.Effect<void, OutErr | EX, Env | RX>;
 };
 /**
  * Runs a channel and collects all output elements into an array.
  *
- * @example
+ * **Example** (Collecting channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -4974,31 +5749,44 @@ export declare const runForEachWhile: {
  * // Effect.runSync(collectEffect) // Returns: [1, 2, 3, 4, 5]
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export declare const runCollect: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Array<OutElem>, OutErr, Env>;
 /**
  * Runs a channel and outputs the done value.
  *
- * @since 4.0.0
  * @category execution
+ * @since 4.0.0
  */
 export declare const runDone: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<OutDone, OutErr, Env>;
 /**
- * @since 2.0.0
+ * Runs a channel until the first output element is available, returning it in
+ * an `Option`.
+ *
+ * Returns `Option.some` with the first output element, or `Option.none` if the
+ * channel completes without emitting output.
+ *
  * @category execution
+ * @since 2.0.0
  */
 export declare const runHead: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Option.Option<OutElem>, OutErr, Env>;
 /**
- * @since 2.0.0
+ * Runs a channel to completion and returns the last output element in an
+ * `Option`.
+ *
+ * Returns `Option.some` with the last emitted element, or `Option.none` if the
+ * channel completes without emitting output.
+ *
  * @category execution
+ * @since 2.0.0
  */
 export declare const runLast: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Option.Option<OutElem>, OutErr, Env>;
 /**
  * Runs a channel and folds over all output elements with an accumulator.
  *
- * @example
+ * **Example** (Folding channel output)
+ *
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -5015,14 +5803,15 @@ export declare const runLast: <OutElem, OutErr, OutDone, Env>(self: Channel<OutE
  * // Effect.runSync(sumEffect) // Returns: 15
  * ```
  *
- * @since 2.0.0
  * @category execution
+ * @since 2.0.0
  */
 export declare const runFold: {
     /**
      * Runs a channel and folds over all output elements with an accumulator.
      *
-     * @example
+     * **Example** (Folding channel output)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -5039,14 +5828,15 @@ export declare const runFold: {
      * // Effect.runSync(sumEffect) // Returns: 15
      * ```
      *
-     * @since 2.0.0
      * @category execution
+     * @since 2.0.0
      */
     <Z, OutElem>(initial: LazyArg<Z>, f: (acc: Z, o: OutElem) => Z): <OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Z, OutErr, Env>;
     /**
      * Runs a channel and folds over all output elements with an accumulator.
      *
-     * @example
+     * **Example** (Folding channel output)
+     *
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -5063,31 +5853,54 @@ export declare const runFold: {
      * // Effect.runSync(sumEffect) // Returns: 15
      * ```
      *
-     * @since 2.0.0
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, Env, Z>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, initial: LazyArg<Z>, f: (acc: Z, o: OutElem) => Z): Effect.Effect<Z, OutErr, Env>;
 };
 /**
- * @since 2.0.0
+ * Runs a channel and effectfully folds all output elements with an accumulator.
+ *
+ * The initial accumulator is evaluated lazily. Each output element is passed to
+ * the effectful accumulator function. The returned effect succeeds with the
+ * final accumulator value.
+ *
  * @category execution
+ * @since 2.0.0
  */
 export declare const runFoldEffect: {
     /**
-     * @since 2.0.0
+     * Runs a channel and effectfully folds all output elements with an accumulator.
+     *
+     * The initial accumulator is evaluated lazily. Each output element is passed to
+     * the effectful accumulator function. The returned effect succeeds with the
+     * final accumulator value.
+     *
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, Z, E, R>(initial: LazyArg<Z>, f: (acc: Z, o: OutElem) => Effect.Effect<Z, E, R>): <OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Z, OutErr | E, Env | R>;
     /**
-     * @since 2.0.0
+     * Runs a channel and effectfully folds all output elements with an accumulator.
+     *
+     * The initial accumulator is evaluated lazily. Each output element is passed to
+     * the effectful accumulator function. The returned effect succeeds with the
+     * final accumulator value.
+     *
      * @category execution
+     * @since 2.0.0
      */
     <OutElem, OutErr, OutDone, Env, Z, E, R>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, initial: LazyArg<Z>, f: (acc: Z, o: OutElem) => Effect.Effect<Z, E, R>): Effect.Effect<Z, OutErr | E, Env | R>;
 };
 /**
- * Converts a channel to a Pull data structure for low-level consumption.
+ * Converts a channel to a scoped `Pull` for low-level consumption.
+ *
+ * The effect requires a `Scope`. The returned pull should be consumed only
+ * while that scope remains open. Pulls are serialized so only one pull is
+ * evaluated at a time.
+ *
+ * **Example** (Converting channels to pulls)
  *
- * @example
  * ```ts
  * import { Channel, Data, Effect } from "effect"
  *
@@ -5106,14 +5919,15 @@ export declare const runFoldEffect: {
  * // Use the Pull to manually consume elements
  * ```
  *
- * @since 2.0.0
  * @category Destructors
+ * @since 2.0.0
  */
 export declare const toPull: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Pull.Pull<OutElem, OutErr, OutDone>, never, Env | Scope.Scope>;
 /**
  * Converts a channel to a Pull within an existing scope.
  *
- * @example
+ * **Example** (Converting channels to scoped pulls)
+ *
  * ```ts
  * import { Channel, Data, Effect, Scope } from "effect"
  *
@@ -5132,46 +5946,91 @@ export declare const toPull: <OutElem, OutErr, OutDone, Env>(self: Channel<OutEl
  * })
  * ```
  *
- * @since 4.0.0
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toPullScoped: <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, scope: Scope.Scope) => Effect.Effect<Pull.Pull<OutElem, OutErr, OutDone, Env>, never, Env>;
 /**
- * @since 4.0.0
+ * Runs a channel and offers each output element into a queue.
+ *
+ * When the channel completes, the queue is ended. When the channel fails, the
+ * queue is failed with the channel's cause. The returned effect itself
+ * completes with `void`.
+ *
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const runIntoQueue: {
     /**
-     * @since 4.0.0
+     * Runs a channel and offers each output element into a queue.
+     *
+     * When the channel completes, the queue is ended. When the channel fails, the
+     * queue is failed with the channel's cause. The returned effect itself
+     * completes with `void`.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr>(queue: Queue.Queue<OutElem, OutErr | Cause.Done>): <OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<void, never, Env>;
     /**
-     * @since 4.0.0
+     * Runs a channel and offers each output element into a queue.
+     *
+     * When the channel completes, the queue is ended. When the channel fails, the
+     * queue is failed with the channel's cause. The returned effect itself
+     * completes with `void`.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, queue: Queue.Queue<OutElem, OutErr | Cause.Done>): Effect.Effect<void, never, Env>;
 };
 /**
- * @since 4.0.0
+ * Runs a channel that emits non-empty arrays and offers each array element into
+ * a queue.
+ *
+ * When the channel completes, the queue is ended. When the channel fails, the
+ * queue is failed with the channel's cause. The returned effect itself
+ * completes with `void`.
+ *
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const runIntoQueueArray: {
     /**
-     * @since 4.0.0
+     * Runs a channel that emits non-empty arrays and offers each array element into
+     * a queue.
+     *
+     * When the channel completes, the queue is ended. When the channel fails, the
+     * queue is failed with the channel's cause. The returned effect itself
+     * completes with `void`.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr>(queue: Queue.Queue<OutElem, OutErr | Cause.Done>): <OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<void, never, Env>;
     /**
-     * @since 4.0.0
+     * Runs a channel that emits non-empty arrays and offers each array element into
+     * a queue.
+     *
+     * When the channel completes, the queue is ended. When the channel fails, the
+     * queue is failed with the channel's cause. The returned effect itself
+     * completes with `void`.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>, queue: Queue.Queue<OutElem, OutErr | Cause.Done>): Effect.Effect<void, never, Env>;
 };
 /**
- * Converts a channel to a queue for concurrent consumption.
+ * Creates a scoped queue and forks the channel to feed it for concurrent
+ * consumption.
+ *
+ * Output elements are offered to the queue. Channel completion and failure are
+ * signaled through the queue. The queue is shut down when the surrounding scope
+ * closes.
+ *
+ * **Example** (Converting channels to queues)
  *
- * @example
  * ```ts
  * import { Channel, Data } from "effect"
  *
@@ -5189,14 +6048,20 @@ export declare const runIntoQueueArray: {
  * // Multiple consumers can read from the queue
  * ```
  *
- * @since 4.0.0
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toQueue: {
     /**
-     * Converts a channel to a queue for concurrent consumption.
+     * Creates a scoped queue and forks the channel to feed it for concurrent
+     * consumption.
+     *
+     * Output elements are offered to the queue. Channel completion and failure are
+     * signaled through the queue. The queue is shut down when the surrounding scope
+     * closes.
+     *
+     * **Example** (Converting channels to queues)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -5214,8 +6079,8 @@ export declare const toQueue: {
      * // Multiple consumers can read from the queue
      * ```
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -5224,9 +6089,15 @@ export declare const toQueue: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Queue.Dequeue<OutElem, OutErr | Cause.Done>, never, Env | Scope.Scope>;
     /**
-     * Converts a channel to a queue for concurrent consumption.
+     * Creates a scoped queue and forks the channel to feed it for concurrent
+     * consumption.
+     *
+     * Output elements are offered to the queue. Channel completion and failure are
+     * signaled through the queue. The queue is shut down when the surrounding scope
+     * closes.
+     *
+     * **Example** (Converting channels to queues)
      *
-     * @example
      * ```ts
      * import { Channel, Data } from "effect"
      *
@@ -5244,8 +6115,8 @@ export declare const toQueue: {
      * // Multiple consumers can read from the queue
      * ```
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, options: {
         readonly capacity: "unbounded";
@@ -5255,13 +6126,25 @@ export declare const toQueue: {
     }): Effect.Effect<Queue.Dequeue<OutElem, OutErr | Cause.Done>, never, Env | Scope.Scope>;
 };
 /**
- * @since 4.0.0
+ * Creates a scoped queue and forks an array-emitting channel to feed it.
+ *
+ * Each element inside emitted non-empty arrays is offered to the queue. Channel
+ * completion and failure are signaled through the queue. The queue is shut down
+ * when the surrounding scope closes.
+ *
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toQueueArray: {
     /**
-     * @since 4.0.0
+     * Creates a scoped queue and forks an array-emitting channel to feed it.
+     *
+     * Each element inside emitted non-empty arrays is offered to the queue. Channel
+     * completion and failure are signaled through the queue. The queue is shut down
+     * when the surrounding scope closes.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -5270,8 +6153,14 @@ export declare const toQueueArray: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<Queue.Dequeue<OutElem, OutErr | Cause.Done>, never, Env | Scope.Scope>;
     /**
-     * @since 4.0.0
+     * Creates a scoped queue and forks an array-emitting channel to feed it.
+     *
+     * Each element inside emitted non-empty arrays is offered to the queue. Channel
+     * completion and failure are signaled through the queue. The queue is shut down
+     * when the surrounding scope closes.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>, options: {
         readonly capacity: "unbounded";
@@ -5286,8 +6175,8 @@ export declare const toQueueArray: {
  * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
  * channel ends. By default this is `true`.
  *
- * @since 4.0.0
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toPubSub: {
     /**
@@ -5296,8 +6185,8 @@ export declare const toPubSub: {
      * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
      * channel ends. By default this is `true`.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -5315,8 +6204,8 @@ export declare const toPubSub: {
      * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
      * channel ends. By default this is `true`.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, options: {
         readonly capacity: "unbounded";
@@ -5330,43 +6219,62 @@ export declare const toPubSub: {
     }): Effect.Effect<PubSub.PubSub<OutElem>, never, Env | Scope.Scope>;
 };
 /**
- * @since 4.0.0
+ * Runs a channel and publishes each output element to a `PubSub`.
+ *
+ * The channel's output values are published as individual PubSub messages. Use
+ * `options.shutdownOnEnd` to shut down the PubSub when channel execution ends.
+ *
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const runIntoPubSub: {
     /**
-     * @since 4.0.0
+     * Runs a channel and publishes each output element to a `PubSub`.
+     *
+     * The channel's output values are published as individual PubSub messages. Use
+     * `options.shutdownOnEnd` to shut down the PubSub when channel execution ends.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem>(pubsub: PubSub.PubSub<OutElem>, options?: {
         readonly shutdownOnEnd?: boolean | undefined;
     } | undefined): <OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<void, never, Env>;
     /**
-     * @since 4.0.0
+     * Runs a channel and publishes each output element to a `PubSub`.
+     *
+     * The channel's output values are published as individual PubSub messages. Use
+     * `options.shutdownOnEnd` to shut down the PubSub when channel execution ends.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, pubsub: PubSub.PubSub<OutElem>, options?: {
         readonly shutdownOnEnd?: boolean | undefined;
     } | undefined): Effect.Effect<void, never, Env>;
 };
 /**
- * Converts a channel to a PubSub for concurrent consumption.
+ * Converts an array-emitting channel to a scoped `PubSub` for concurrent
+ * consumption.
  *
- * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
- * channel ends. By default this is `true`.
+ * Each element inside emitted non-empty arrays is published as an individual
+ * PubSub message. `shutdownOnEnd` indicates whether the PubSub should be shut
+ * down when the channel ends. By default this is `true`.
  *
- * @since 4.0.0
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toPubSubArray: {
     /**
-     * Converts a channel to a PubSub for concurrent consumption.
+     * Converts an array-emitting channel to a scoped `PubSub` for concurrent
+     * consumption.
      *
-     * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
-     * channel ends. By default this is `true`.
+     * Each element inside emitted non-empty arrays is published as an individual
+     * PubSub message. `shutdownOnEnd` indicates whether the PubSub should be shut
+     * down when the channel ends. By default this is `true`.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -5379,13 +6287,15 @@ export declare const toPubSubArray: {
         readonly shutdownOnEnd?: boolean | undefined;
     }): <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<PubSub.PubSub<OutElem>, never, Env | Scope.Scope>;
     /**
-     * Converts a channel to a PubSub for concurrent consumption.
+     * Converts an array-emitting channel to a scoped `PubSub` for concurrent
+     * consumption.
      *
-     * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
-     * channel ends. By default this is `true`.
+     * Each element inside emitted non-empty arrays is published as an individual
+     * PubSub message. `shutdownOnEnd` indicates whether the PubSub should be shut
+     * down when the channel ends. By default this is `true`.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>, options: {
         readonly capacity: "unbounded";
@@ -5399,37 +6309,66 @@ export declare const toPubSubArray: {
     }): Effect.Effect<PubSub.PubSub<OutElem>, never, Env | Scope.Scope>;
 };
 /**
- * @since 4.0.0
+ * Runs an array-emitting channel and publishes each array element to a
+ * `PubSub`.
+ *
+ * Each element inside emitted non-empty arrays is published as an individual
+ * PubSub message. Use `options.shutdownOnEnd` to shut down the PubSub when
+ * channel execution ends.
+ *
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const runIntoPubSubArray: {
     /**
-     * @since 4.0.0
+     * Runs an array-emitting channel and publishes each array element to a
+     * `PubSub`.
+     *
+     * Each element inside emitted non-empty arrays is published as an individual
+     * PubSub message. Use `options.shutdownOnEnd` to shut down the PubSub when
+     * channel execution ends.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem>(pubsub: PubSub.PubSub<OutElem>, options?: {
         readonly shutdownOnEnd?: boolean | undefined;
     } | undefined): <OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<OutDone, OutErr, Env>;
     /**
-     * @since 4.0.0
+     * Runs an array-emitting channel and publishes each array element to a
+     * `PubSub`.
+     *
+     * Each element inside emitted non-empty arrays is published as an individual
+     * PubSub message. Use `options.shutdownOnEnd` to shut down the PubSub when
+     * channel execution ends.
+     *
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>, pubsub: PubSub.PubSub<OutElem>, options?: {
         readonly shutdownOnEnd?: boolean | undefined;
     } | undefined): Effect.Effect<OutDone, OutErr, Env>;
 };
 /**
- * Converts a channel to a PubSub for concurrent consumption.
+ * Converts a channel to a scoped `PubSub` of `Take` values.
+ *
+ * Emitted non-empty arrays are published as output `Take` values. When the
+ * channel ends, its final `Exit` is published so subscribers can observe
+ * completion or failure.
  *
- * @since 4.0.0
  * @category Destructors
+ * @since 4.0.0
  */
 export declare const toPubSubTake: {
     /**
-     * Converts a channel to a PubSub for concurrent consumption.
+     * Converts a channel to a scoped `PubSub` of `Take` values.
+     *
+     * Emitted non-empty arrays are published as output `Take` values. When the
+     * channel ends, its final `Exit` is published so subscribers can observe
+     * completion or failure.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     (options: {
         readonly capacity: "unbounded";
@@ -5440,10 +6379,14 @@ export declare const toPubSubTake: {
         readonly replay?: number | undefined;
     }): <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutDone>, OutErr, OutDone, unknown, unknown, unknown, Env>) => Effect.Effect<PubSub.PubSub<Take.Take<OutElem, OutErr, OutDone>>, never, Env | Scope.Scope>;
     /**
-     * Converts a channel to a PubSub for concurrent consumption.
+     * Converts a channel to a scoped `PubSub` of `Take` values.
+     *
+     * Emitted non-empty arrays are published as output `Take` values. When the
+     * channel ends, its final `Exit` is published so subscribers can observe
+     * completion or failure.
      *
-     * @since 4.0.0
      * @category Destructors
+     * @since 4.0.0
      */
     <OutElem, OutErr, OutDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, unknown, unknown, unknown, Env>, options: {
         readonly capacity: "unbounded";