effect 4.0.5 → 4.0.6

package/dist/Effect.d.ts

@@ -1,3 +1,4 @@
+/// <reference lib="esnext.disposable" preserve="true" />
 /**
  * Describes workflows that run only when executed by the Effect runtime.
  *
@@ -1175,8 +1176,9 @@ export declare const whileLoop: <A, E, R>(options: {
  *
  * **Details**
  *
- * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped `Promise` API.
+ * If `evaluate` declares a parameter, it receives an `AbortSignal` that is
+ * aborted if the effect is interrupted. Zero-argument thunks do not allocate
+ * an `AbortController`.
  *
  * **Gotchas**
  *
@@ -1186,6 +1188,13 @@ export declare const whileLoop: <A, E, R>(options: {
  * Interruption aborts the provided `AbortSignal`, but the underlying
  * asynchronous operation only stops if it observes that signal.
  *
+ * The parameter check reads the `length` property of `evaluate`, which does
+ * not count a rest parameter or any parameter from the first default value
+ * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+ * receive `undefined` instead of a signal, as do wrappers that forward
+ * arguments through rest parameters. Declare the signal as an ordinary
+ * parameter: `(signal) => ...`.
+ *
  * **Example** (Wrapping a non-rejecting Promise)
  *
  * ```ts import.meta.vitest
@@ -1227,9 +1236,10 @@ export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike
  * Passing `{ try, catch }` uses `catch` to map failures to an error of type
  * `E`.
  *
- * The thunk receives an `AbortSignal` that is aborted if the effect is
- * interrupted. The underlying asynchronous operation only stops if it observes
- * that signal.
+ * If the thunk declares a parameter, it receives an `AbortSignal` that is
+ * aborted if the effect is interrupted. The underlying asynchronous operation
+ * only stops if it observes that signal. Zero-argument thunks do not allocate
+ * an `AbortController`.
  *
  * **Gotchas**
  *
@@ -1237,6 +1247,13 @@ export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike
  * defect. Return the error value you want in the error channel instead of
  * throwing it.
  *
+ * The parameter check reads the thunk's `length` property, which does not
+ * count a rest parameter or any parameter from the first default value
+ * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+ * receive `undefined` instead of a signal, as do wrappers that forward
+ * arguments through rest parameters. Declare the signal as an ordinary
+ * parameter: `(signal) => ...`.
+ *
  * **Example** (Wrapping a fetch request that may fail)
  *
  * ```ts import.meta.vitest
@@ -1299,9 +1316,10 @@ export declare const tryPromise: {
      * Passing `{ try, catch }` uses `catch` to map failures to an error of type
      * `E`.
      *
-     * The thunk receives an `AbortSignal` that is aborted if the effect is
-     * interrupted. The underlying asynchronous operation only stops if it observes
-     * that signal.
+     * If the thunk declares a parameter, it receives an `AbortSignal` that is
+     * aborted if the effect is interrupted. The underlying asynchronous operation
+     * only stops if it observes that signal. Zero-argument thunks do not allocate
+     * an `AbortController`.
      *
      * **Gotchas**
      *
@@ -1309,6 +1327,13 @@ export declare const tryPromise: {
      * defect. Return the error value you want in the error channel instead of
      * throwing it.
      *
+     * The parameter check reads the thunk's `length` property, which does not
+     * count a rest parameter or any parameter from the first default value
+     * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+     * receive `undefined` instead of a signal, as do wrappers that forward
+     * arguments through rest parameters. Declare the signal as an ordinary
+     * parameter: `(signal) => ...`.
+     *
      * **Example** (Wrapping a fetch request that may fail)
      *
      * ```ts import.meta.vitest
@@ -1371,9 +1396,10 @@ export declare const tryPromise: {
      * Passing `{ try, catch }` uses `catch` to map failures to an error of type
      * `E`.
      *
-     * The thunk receives an `AbortSignal` that is aborted if the effect is
-     * interrupted. The underlying asynchronous operation only stops if it observes
-     * that signal.
+     * If the thunk declares a parameter, it receives an `AbortSignal` that is
+     * aborted if the effect is interrupted. The underlying asynchronous operation
+     * only stops if it observes that signal. Zero-argument thunks do not allocate
+     * an `AbortController`.
      *
      * **Gotchas**
      *
@@ -1381,6 +1407,13 @@ export declare const tryPromise: {
      * defect. Return the error value you want in the error channel instead of
      * throwing it.
      *
+     * The parameter check reads the thunk's `length` property, which does not
+     * count a rest parameter or any parameter from the first default value
+     * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+     * receive `undefined` instead of a signal, as do wrappers that forward
+     * arguments through rest parameters. Declare the signal as an ordinary
+     * parameter: `(signal) => ...`.
+     *
      * **Example** (Wrapping a fetch request that may fail)
      *
      * ```ts import.meta.vitest
@@ -1651,10 +1684,20 @@ undefined_ as undefined };
  *
  * **Details**
  *
- * The registration function receives a `resume` callback and, when requested,
- * an `AbortSignal`. Call `resume` at most once with the effect that should
- * complete the fiber; later calls are ignored. Return an optional cleanup
- * effect from the registration function to run if the fiber is interrupted.
+ * The registration function receives a `resume` callback and, if it declares
+ * a second parameter, an `AbortSignal` that is aborted if the fiber is
+ * interrupted. Call `resume` at most once with the effect that should complete
+ * the fiber; later calls are ignored. Return an optional cleanup effect from
+ * the registration function to run if the fiber is interrupted.
+ *
+ * **Gotchas**
+ *
+ * The parameter check reads the registration function's `length` property,
+ * which must be at least `2` and does not count a rest parameter or any
+ * parameter from the first default value onward. `(...args) => ...` and
+ * `(resume, signal = fallback) => ...` therefore receive `undefined` instead
+ * of a signal, as do wrappers that forward arguments through rest parameters.
+ * Declare both as ordinary parameters: `(resume, signal) => ...`.
  *
  * **Example** (Integrating callback APIs)
  *
@@ -2438,7 +2481,9 @@ export declare const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A
  * `Option.some` becomes a successful effect with the contained value, while
  * `Option.none` becomes a failed effect. By default the failure is a
  * `NoSuchElementError`, but you can provide an `onNone` callback to customize
- * the error value.
+ * the error value. For `Option.none`, `onNone` is evaluated on each execution,
+ * not when the effect is constructed. It is never called for `Option.some`.
+ * If `onNone` throws, the effect dies with the thrown value as a defect.
  *
  * **Example** (Converting an Option into an Effect)
  *
@@ -3482,9 +3527,12 @@ export declare const tap: {
  *
  * **Gotchas**
  *
- * `result` only captures typed, recoverable failures. Defects and
- * interruptions are not captured inside the `Result` and still fail the
- * effect.
+ * `result` only captures typed, recoverable failures. If the cause contains a
+ * defect, nothing is captured and every typed error is converted to a defect,
+ * preserving reason order and interrupts. A cause with only interruptions
+ * still fails the effect, but an interruption alongside a typed error does not
+ * prevent capture. The first typed error becomes a `Result.Failure` and the
+ * interruption is discarded.
  *
  * **Example** (Capturing success or failure as Result)
  *
@@ -3525,9 +3573,12 @@ export declare const result: <A, E, R>(self: Effect<A, E, R>) => Effect<Result.R
  *
  * **Gotchas**
  *
- * `option` only captures typed, recoverable failures as `Option.none`.
- * Defects and interruptions are not captured inside the `Option` and still
- * fail the effect.
+ * `option` only captures typed, recoverable failures as `Option.none`. If the
+ * cause contains a defect, nothing is captured and every typed error is
+ * converted to a defect, preserving reason order and interrupts. A cause with
+ * only interruptions still fails the effect, but an interruption alongside a
+ * typed error does not prevent capture. The effect succeeds with
+ * `Option.none()` and the interruption is discarded.
  *
  * `option` also discards typed failure values. Use `result` if the failure
  * value matters.
@@ -4272,6 +4323,11 @@ export {
  * `catch` only handles recoverable errors. It will not recover from
  * unrecoverable defects.
  *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the handler does not run and the failure is propagated with every
+ * typed error converted to a defect. An interruption alongside a typed error
+ * does not prevent recovery.
+ *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
  * @stability stable
@@ -4293,6 +4349,12 @@ catch_ as catch };
  * The error type must have a readonly `_tag` field. `catchTag` matches that
  * field and only handles errors with the requested tag.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling a tagged error)
  *
  * ```ts import.meta.vitest
@@ -4342,6 +4404,12 @@ export declare const catchTag: {
      * The error type must have a readonly `_tag` field. `catchTag` matches that
      * field and only handles errors with the requested tag.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling a tagged error)
      *
      * ```ts import.meta.vitest
@@ -4391,6 +4459,12 @@ export declare const catchTag: {
      * The error type must have a readonly `_tag` field. `catchTag` matches that
      * field and only handles errors with the requested tag.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling a tagged error)
      *
      * ```ts import.meta.vitest
@@ -4443,6 +4517,12 @@ export declare const catchTag: {
  * The error type must have a readonly `_tag` field to use `catchTags`. This
  * field is used to identify and match errors.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling multiple tagged errors)
  *
  * ```ts import.meta.vitest
@@ -4492,6 +4572,12 @@ export declare const catchTags: {
      * The error type must have a readonly `_tag` field to use `catchTags`. This
      * field is used to identify and match errors.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling multiple tagged errors)
      *
      * ```ts import.meta.vitest
@@ -4561,6 +4647,12 @@ export declare const catchTags: {
      * The error type must have a readonly `_tag` field to use `catchTags`. This
      * field is used to identify and match errors.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling multiple tagged errors)
      *
      * ```ts import.meta.vitest
@@ -4628,6 +4720,12 @@ export declare const catchTags: {
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling an error reason)
  *
  * ```ts import.meta.vitest
@@ -4679,6 +4777,12 @@ export declare const catchReason: {
      * Use this to handle nested error causes without removing the parent error
      * from the error channel. The handler receives the unwrapped reason.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling an error reason)
      *
      * ```ts import.meta.vitest
@@ -4730,6 +4834,12 @@ export declare const catchReason: {
      * Use this to handle nested error causes without removing the parent error
      * from the error channel. The handler receives the unwrapped reason.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling an error reason)
      *
      * ```ts import.meta.vitest
@@ -4772,6 +4882,12 @@ export declare const catchReason: {
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling multiple error reasons)
  *
  * ```ts import.meta.vitest
@@ -4813,6 +4929,12 @@ export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling multiple error reasons)
      *
      * ```ts import.meta.vitest
@@ -4862,6 +4984,12 @@ export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Handling multiple error reasons)
      *
      * ```ts import.meta.vitest
@@ -5199,6 +5327,12 @@ export declare const catchCause: {
  * they often indicate serious issues. In some cases, such as dynamically loaded
  * plugins, controlled recovery may be needed.
  *
+ * **Gotchas**
+ *
+ * `catchDefect` recovers any cause that contains a defect, including causes
+ * that also contain typed errors. Typed error handlers such as `catch` skip
+ * those causes, so defects always take precedence.
+ *
  * **Example** (Recovering from defects)
  *
  * ```ts import.meta.vitest
@@ -5244,6 +5378,12 @@ export declare const catchDefect: {
      * they often indicate serious issues. In some cases, such as dynamically loaded
      * plugins, controlled recovery may be needed.
      *
+     * **Gotchas**
+     *
+     * `catchDefect` recovers any cause that contains a defect, including causes
+     * that also contain typed errors. Typed error handlers such as `catch` skip
+     * those causes, so defects always take precedence.
+     *
      * **Example** (Recovering from defects)
      *
      * ```ts import.meta.vitest
@@ -5289,6 +5429,12 @@ export declare const catchDefect: {
      * they often indicate serious issues. In some cases, such as dynamically loaded
      * plugins, controlled recovery may be needed.
      *
+     * **Gotchas**
+     *
+     * `catchDefect` recovers any cause that contains a defect, including causes
+     * that also contain typed errors. Typed error handlers such as `catch` skip
+     * those causes, so defects always take precedence.
+     *
      * **Example** (Recovering from defects)
      *
      * ```ts import.meta.vitest
@@ -5330,6 +5476,12 @@ export declare const catchDefect: {
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Recovering when a predicate matches)
  *
  * ```ts import.meta.vitest
@@ -5376,6 +5528,12 @@ export declare const catchIf: {
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering when a predicate matches)
      *
      * ```ts import.meta.vitest
@@ -5422,6 +5580,12 @@ export declare const catchIf: {
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering when a predicate matches)
      *
      * ```ts import.meta.vitest
@@ -5468,6 +5632,12 @@ export declare const catchIf: {
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering when a predicate matches)
      *
      * ```ts import.meta.vitest
@@ -5500,7 +5670,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 2.0.0
      */
-    <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Effect<A, E, R>, refinement: Predicate.Refinement<E, EB>, f: (e: EB) => Effect<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Effect<A3, E3, R3>) | undefined): Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
+    <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Effect<A, E, R>, refinement: Predicate.Refinement<NoInfer<E>, EB>, f: (e: EB) => Effect<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Effect<A3, E3, R3>) | undefined): Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
     /**
      * Recovers from specific errors using a `Predicate` or `Refinement`.
      *
@@ -5514,6 +5684,12 @@ export declare const catchIf: {
      * matching. Non-matching errors re-fail with the original cause. Defects and
      * interrupts are not caught.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering when a predicate matches)
      *
      * ```ts import.meta.vitest
@@ -5564,6 +5740,12 @@ export declare const catchIf: {
  * `orElse` when provided. Without `orElse`, the original failure cause is
  * preserved.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * @see {@link catchIf} for predicate-based recovery from typed errors
  * @see {@link catchTag} for recovering from a single tagged error
  * @see {@link catchTags} for recovering from several tagged errors
@@ -5590,6 +5772,12 @@ export declare const catchFilter: {
      * `orElse` when provided. Without `orElse`, the original failure cause is
      * preserved.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * @see {@link catchIf} for predicate-based recovery from typed errors
      * @see {@link catchTag} for recovering from a single tagged error
      * @see {@link catchTags} for recovering from several tagged errors
@@ -5616,6 +5804,12 @@ export declare const catchFilter: {
      * `orElse` when provided. Without `orElse`, the original failure cause is
      * preserved.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * @see {@link catchIf} for predicate-based recovery from typed errors
      * @see {@link catchTag} for recovering from a single tagged error
      * @see {@link catchTags} for recovering from several tagged errors
@@ -5885,6 +6079,9 @@ export declare const catchCauseFilter: {
  * Only the failure channel is transformed. The success channel and requirements
  * are preserved.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Transforming the error channel)
  *
  * ```ts import.meta.vitest
@@ -5926,6 +6123,9 @@ export declare const mapError: {
      * Only the failure channel is transformed. The success channel and requirements
      * are preserved.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Transforming the error channel)
      *
      * ```ts import.meta.vitest
@@ -5967,6 +6167,9 @@ export declare const mapError: {
      * Only the failure channel is transformed. The success channel and requirements
      * are preserved.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Transforming the error channel)
      *
      * ```ts import.meta.vitest
@@ -6011,6 +6214,9 @@ export declare const mapError: {
  * the error and the success values without altering the overall success or
  * failure status of the effect.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Transforming success and failure channels)
  *
  * ```ts import.meta.vitest
@@ -6054,6 +6260,9 @@ export declare const mapBoth: {
      * the error and the success values without altering the overall success or
      * failure status of the effect.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Transforming success and failure channels)
      *
      * ```ts import.meta.vitest
@@ -6100,6 +6309,9 @@ export declare const mapBoth: {
      * the error and the success values without altering the overall success or
      * failure status of the effect.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Transforming success and failure channels)
      *
      * ```ts import.meta.vitest
@@ -6884,7 +7096,9 @@ export declare namespace Retry {
  * applied. For example, `Schedule.recurs(3)` allows up to three retries after
  * the initial attempt.
  *
- * Defects and interruptions are not retried.
+ * Defects take precedence over typed errors. A failure whose cause contains a
+ * defect is not retried and is propagated with every typed error converted to a
+ * defect. A typed error alongside an interruption is retried.
  *
  * **Example** (Retrying with a schedule)
  *
@@ -6937,7 +7151,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -6990,7 +7206,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -7043,7 +7261,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -7096,7 +7316,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -7149,7 +7371,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -7202,7 +7426,9 @@ export declare const retry: {
      * applied. For example, `Schedule.recurs(3)` allows up to three retries after
      * the initial attempt.
      *
-     * Defects and interruptions are not retried.
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
      *
      * **Example** (Retrying with a schedule)
      *
@@ -7251,6 +7477,14 @@ export declare const retry: {
  * If the retries are exhausted and the effect still fails, it runs a fallback
  * effect instead.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. A failure whose cause contains a
+ * defect is not retried and is propagated with every typed error converted to a
+ * defect. A typed error alongside an interruption is retried. When the cause
+ * contains a defect, `orElse` does not run.
+ * This applies to source failures only; policy failures propagate unchanged.
+ *
  * **Example** (Falling back after retries are exhausted)
  *
  * ```ts import.meta.vitest
@@ -7306,6 +7540,14 @@ export declare const retryOrElse: {
      * If the retries are exhausted and the effect still fails, it runs a fallback
      * effect instead.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried. When the cause
+     * contains a defect, `orElse` does not run.
+     * This applies to source failures only; policy failures propagate unchanged.
+     *
      * **Example** (Falling back after retries are exhausted)
      *
      * ```ts import.meta.vitest
@@ -7361,6 +7603,14 @@ export declare const retryOrElse: {
      * If the retries are exhausted and the effect still fails, it runs a fallback
      * effect instead.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried. When the cause
+     * contains a defect, `orElse` does not run.
+     * This applies to source failures only; policy failures propagate unchanged.
+     *
      * **Example** (Falling back after retries are exhausted)
      *
      * ```ts import.meta.vitest
@@ -7407,8 +7657,8 @@ export declare const retryOrElse: {
  * **Details**
  *
  * Use `sandbox` when downstream error handling needs to distinguish typed
- * failures, defects, and interruptions. Use `unsandbox` to restore the original
- * typed error channel after cause-level handling.
+ * failures, defects, and interruptions. Use `Effect.catch(Effect.failCause)` to
+ * restore the original typed error channel after cause-level handling.
  *
  * **Example** (Exposing failures as causes)
  *
@@ -7444,6 +7694,13 @@ export declare const sandbox: <A, E, R>(self: Effect<A, E, R>) => Effect<A, Caus
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the failure is not ignored and is propagated with every typed error
+ * converted to a defect. An interruption alongside a typed error does not
+ * prevent the error from being ignored.
+ *
  * **Example** (Discarding success and failure values)
  *
  * ```ts import.meta.vitest
@@ -7799,6 +8056,12 @@ export declare const withErrorReporting: <Arg extends Effect<any, any, any> | {
  *
  * Defects and interruptions are not recovered by this operator.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Replacing failures with a value)
  *
  * ```ts import.meta.vitest
@@ -7836,6 +8099,12 @@ export declare const orElseSucceed: {
      *
      * Defects and interruptions are not recovered by this operator.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Replacing failures with a value)
      *
      * ```ts import.meta.vitest
@@ -7873,6 +8142,12 @@ export declare const orElseSucceed: {
      *
      * Defects and interruptions are not recovered by this operator.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Replacing failures with a value)
      *
      * ```ts import.meta.vitest
@@ -9799,6 +10074,12 @@ export declare const when: {
  * to process the result if the effect succeeds, or handle the error if the
  * effect fails.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Matching success and failure values)
  *
  * ```ts import.meta.vitest
@@ -9851,6 +10132,12 @@ export declare const match: {
      * to process the result if the effect succeeds, or handle the error if the
      * effect fails.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Matching success and failure values)
      *
      * ```ts import.meta.vitest
@@ -9906,6 +10193,12 @@ export declare const match: {
      * to process the result if the effect succeeds, or handle the error if the
      * effect fails.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Matching success and failure values)
      *
      * ```ts import.meta.vitest
@@ -9962,6 +10255,12 @@ export declare const match: {
  * the handlers immediately without fiber scheduling. For unresolved effects,
  * it falls back to the regular `match` behavior.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Pattern matching eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -10003,6 +10302,12 @@ export declare const matchEager: {
      * the handlers immediately without fiber scheduling. For unresolved effects,
      * it falls back to the regular `match` behavior.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Pattern matching eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -10047,6 +10352,12 @@ export declare const matchEager: {
      * the handlers immediately without fiber scheduling. For unresolved effects,
      * it falls back to the regular `match` behavior.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Pattern matching eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -10565,6 +10876,12 @@ export declare const matchCauseEffect: {
  * performing logging, recovery, notification, or other effectful work. The
  * returned effect succeeds or fails according to the handler that is run.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Matching success and failure with effectful handlers)
  *
  * ```ts import.meta.vitest
@@ -10617,6 +10934,12 @@ export declare const matchEffect: {
      * performing logging, recovery, notification, or other effectful work. The
      * returned effect succeeds or fails according to the handler that is run.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Matching success and failure with effectful handlers)
      *
      * ```ts import.meta.vitest
@@ -10672,6 +10995,12 @@ export declare const matchEffect: {
      * performing logging, recovery, notification, or other effectful work. The
      * returned effect succeeds or fails according to the handler that is run.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Matching success and failure with effectful handlers)
      *
      * ```ts import.meta.vitest
@@ -10884,9 +11213,9 @@ export declare const context: <R = never>() => Effect<Context.Context<R>, never,
  */
 export declare const contextWith: <R, A, E, R2>(f: (context: Context.Context<R>) => Effect<A, E, R2>) => Effect<A, E, R | R2>;
 /**
- * Provides dependencies to an effect using layers or a context. Use `options.local`
- * to build the layer every time; by default, layers are shared between provide
- * calls.
+ * Provides dependencies to an effect using layers or a context. A layer already
+ * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+ * build their own copies. Use `options.local` to build a fresh layer subtree.
  *
  * **Example** (Providing dependencies with a layer)
  *
@@ -10919,9 +11248,9 @@ export declare const contextWith: <R, A, E, R2>(f: (context: Context.Context<R>)
  */
 export declare const provide: {
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -10956,9 +11285,9 @@ export declare const provide: {
         readonly local?: boolean | undefined;
     } | undefined): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | Layer.Error<Layers[number]>, Layer.Services<Layers[number]> | Exclude<R, Layer.Success<Layers[number]>>>;
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -10993,9 +11322,9 @@ export declare const provide: {
         readonly local?: boolean | undefined;
     } | undefined): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, RIn | Exclude<R, ROut>>;
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -11028,9 +11357,9 @@ export declare const provide: {
      */
     <R2>(context: Context.Context<R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, R2>>;
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -11065,9 +11394,9 @@ export declare const provide: {
         readonly local?: boolean | undefined;
     } | undefined): Effect<A, E | Layer.Error<Layers[number]>, Layer.Services<Layers[number]> | Exclude<R, Layer.Success<Layers[number]>>>;
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -11102,9 +11431,9 @@ export declare const provide: {
         readonly local?: boolean | undefined;
     } | undefined): Effect<A, E | E2, RIn | Exclude<R, ROut>>;
     /**
-     * Provides dependencies to an effect using layers or a context. Use `options.local`
-     * to build the layer every time; by default, layers are shared between provide
-     * calls.
+     * Provides dependencies to an effect using layers or a context. A layer already
+     * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+     * build their own copies. Use `options.local` to build a fresh layer subtree.
      *
      * **Example** (Providing dependencies with a layer)
      *
@@ -11885,103 +12214,7 @@ export declare const provideService: {
      * @since 2.0.0
      */
     <I, S>(service: Context.Key<I, S>): {
-        /**
-         * Provides one concrete service implementation to an effect.
-         *
-         * **When to use**
-         *
-         * Use to satisfy one service requirement with an already-built implementation.
-         *
-         * **Details**
-         *
-         * The service requirement identified by the `Context.Key` is removed from the
-         * effect requirements after the implementation is provided.
-         *
-         * **Example** (Providing a service value)
-         *
-         * ```ts import.meta.vitest
-         * import { Context, Effect } from "effect"
-         * const output: Array<unknown> = []
-         *
-         * // Define a service for configuration
-         * const Config = Context.Service<{
-         *   apiUrl: string
-         *   timeout: number
-         * }>("Config")
-         *
-         * const fetchData = Effect.gen(function*() {
-         *   const config = yield* Effect.service(Config)
-         *   yield* Effect.sync(() => { output.push(`Fetching from: ${config.apiUrl}`) })
-         *   yield* Effect.sync(() => { output.push(`Timeout: ${config.timeout}ms`) })
-         *   return "data"
-         * })
-         *
-         * // Provide the service implementation
-         * const program = Effect.provideService(fetchData, Config, {
-         *   apiUrl: "https://api.example.com",
-         *   timeout: 5000
-         * })
-         *
-         * void output.push(Effect.runSync(program))
-         * output // => ["Fetching from: https://api.example.com", "Timeout: 5000ms", "data"]
-         * ```
-         *
-         * @see {@link provide} for providing multiple layers to an effect.
-         * @see {@link provideServiceEffect} for acquiring the service implementation effectfully.
-         * @see {@link provideContext} for providing a complete context.
-         * @stability stable
-         * @category providing services
-         * @since 2.0.0
-         */
         (implementation: S): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, I>>;
-        /**
-         * Provides one concrete service implementation to an effect.
-         *
-         * **When to use**
-         *
-         * Use to satisfy one service requirement with an already-built implementation.
-         *
-         * **Details**
-         *
-         * The service requirement identified by the `Context.Key` is removed from the
-         * effect requirements after the implementation is provided.
-         *
-         * **Example** (Providing a service value)
-         *
-         * ```ts import.meta.vitest
-         * import { Context, Effect } from "effect"
-         * const output: Array<unknown> = []
-         *
-         * // Define a service for configuration
-         * const Config = Context.Service<{
-         *   apiUrl: string
-         *   timeout: number
-         * }>("Config")
-         *
-         * const fetchData = Effect.gen(function*() {
-         *   const config = yield* Effect.service(Config)
-         *   yield* Effect.sync(() => { output.push(`Fetching from: ${config.apiUrl}`) })
-         *   yield* Effect.sync(() => { output.push(`Timeout: ${config.timeout}ms`) })
-         *   return "data"
-         * })
-         *
-         * // Provide the service implementation
-         * const program = Effect.provideService(fetchData, Config, {
-         *   apiUrl: "https://api.example.com",
-         *   timeout: 5000
-         * })
-         *
-         * void output.push(Effect.runSync(program))
-         * output // => ["Fetching from: https://api.example.com", "Timeout: 5000ms", "data"]
-         * ```
-         *
-         * @see {@link provide} for providing multiple layers to an effect.
-         * @see {@link provideServiceEffect} for acquiring the service implementation effectfully.
-         * @see {@link provideContext} for providing a complete context.
-         * @stability stable
-         * @category providing services
-         * @since 2.0.0
-         */
         <A, E, R>(self: Effect<A, E, R>, implementation: S): Effect<A, E, Exclude<R, I>>;
     };
     /**
@@ -14364,6 +14597,10 @@ export declare const forever: <Arg extends Effect<any, any, any> | {
  * The source effect is always evaluated once before the schedule is stepped.
  * The schedule controls additional repetitions, not the initial execution.
  *
+ * If the effect or policy fails with a cause that contains a defect, the
+ * failure is propagated with every typed error converted to a defect.
+ * An interruption alongside a typed error does not block the typed error path.
+ *
  * **Example** (Repeating successful effects with a schedule)
  *
  * ```ts import.meta.vitest
@@ -14446,6 +14683,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14528,6 +14769,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14610,6 +14855,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14692,6 +14941,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14774,6 +15027,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14856,6 +15113,10 @@ export declare const repeat: {
      * The source effect is always evaluated once before the schedule is stepped.
      * The schedule controls additional repetitions, not the initial execution.
      *
+     * If the effect or policy fails with a cause that contains a defect, the
+     * failure is propagated with every typed error converted to a defect.
+     * An interruption alongside a typed error does not block the typed error path.
+     *
      * **Example** (Repeating successful effects with a schedule)
      *
      * ```ts import.meta.vitest
@@ -14924,6 +15185,13 @@ export declare const repeat: {
  * otherwise it receives `None`. If the schedule completes normally, the
  * returned effect succeeds with the schedule's output.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors from either the effect or policy.
+ * If the cause contains a defect, `orElse` does not run and every typed error
+ * is converted to a defect. An interruption alongside a typed error does not
+ * prevent `orElse` from running.
+ *
  * **Example** (Recovering after repetition stops)
  *
  * ```ts import.meta.vitest
@@ -14977,6 +15245,13 @@ export declare const repeatOrElse: {
      * otherwise it receives `None`. If the schedule completes normally, the
      * returned effect succeeds with the schedule's output.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors from either the effect or policy.
+     * If the cause contains a defect, `orElse` does not run and every typed error
+     * is converted to a defect. An interruption alongside a typed error does not
+     * prevent `orElse` from running.
+     *
      * **Example** (Recovering after repetition stops)
      *
      * ```ts import.meta.vitest
@@ -15030,6 +15305,13 @@ export declare const repeatOrElse: {
      * otherwise it receives `None`. If the schedule completes normally, the
      * returned effect succeeds with the schedule's output.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors from either the effect or policy.
+     * If the cause contains a defect, `orElse` does not run and every typed error
+     * is converted to a defect. An interruption alongside a typed error does not
+     * prevent `orElse` from running.
+     *
      * **Example** (Recovering after repetition stops)
      *
      * ```ts import.meta.vitest
@@ -16765,8 +17047,8 @@ export declare const requestUnsafe: <A extends Request.Any>(self: A, options: {
  * You can use the `forkChild` method whenever you want to execute an effect in a
  * new fiber, concurrently and without "blocking" the fiber executing other
  * effects. Using fibers can be tricky, so instead of using this method
- * directly, consider other higher-level methods, such as `raceWith`,
- * `zipPar`, and so forth.
+ * directly, consider higher-level methods such as `Effect.race`,
+ * `Effect.raceFirst`, or `Effect.all` with a concurrency option.
  *
  * The fiber returned by this method has methods to interrupt the fiber and to
  * wait for it to finish executing the effect. See `Fiber` for more
@@ -16936,9 +17218,14 @@ export declare const forkScoped: <Arg extends Effect<any, any, any> | {
     readonly uninterruptible?: boolean | "inherit" | undefined;
 } | undefined) => [Arg] extends [Effect<infer _A, infer _E, infer _R>] ? Effect<Fiber<_A, _E>, never, _R | Scope> : <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R | Scope>;
 /**
- * Forks the effect into a new fiber attached to the global scope. Because the
- * new fiber is attached to the global scope, when the fiber executing the
- * returned effect terminates, the forked fiber will continue running.
+ * Forks the effect into a new fiber with no parent and no scope, so its lifetime
+ * is independent of the forking fiber.
+ *
+ * **Details**
+ *
+ * The detached fiber inherits the forking fiber's context. It continues running
+ * until it completes or is explicitly interrupted through the returned handle,
+ * even after the forking fiber terminates.
  *
  * **Example** (Forking a detached fiber)
  *
@@ -17081,11 +17368,11 @@ export interface RunOptions {
  * import { Effect, Fiber } from "effect"
  * const output: Array<unknown> = []
  *
- * //      ┌─── Effect<number, never, never>
+ * //      ┌─── Effect<string, never, never>
  * //      ▼
  * const program = Effect.sync(() => { output.push("running...") }).pipe(Effect.as("done"))
  *
- * //      ┌─── RuntimeFiber<number, never>
+ * //      ┌─── Fiber<string, never>
  * //      ▼
  * const fiber = Effect.runFork(program)
  *
@@ -17394,9 +17681,10 @@ export declare const runPromiseExitWith: <R>(context: Context.Context<R>) => <A,
  *
  * **Details**
  *
- * If the effect fails, dies, is interrupted, or performs asynchronous work,
- * `runSync` throws a `FiberFailure` instead of returning a value. Use
- * `runSyncExit` when you want the failure captured as an `Exit`.
+ * If the effect fails, dies, or is interrupted, `runSync` throws the squashed
+ * cause instead of returning a value. Typed errors can be thrown directly,
+ * including non-Error values. Asynchronous work throws `Cause.AsyncFiberError`.
+ * Use `runSyncExit` when you want the failure captured as an `Exit`.
  *
  * **Example** (Running a synchronous effect)
  *
@@ -20803,7 +21091,7 @@ type EffectifyArgs<F extends (...args: Array<any>) => any> = Parameters<F> exten
  * **Details**
  *
  * The original function is called with the supplied arguments plus a final
- * callback. A non-null callback error fails the returned effect, while a
+ * callback. A truthy callback error fails the returned effect, while a
  * successful callback value becomes the effect success. Use `onError` to map
  * callback errors and `onSyncError` to turn synchronous throws into typed
  * failures; otherwise synchronous throws become defects.
@@ -20857,7 +21145,7 @@ export declare const effectify: {
      * **Details**
      *
      * The original function is called with the supplied arguments plus a final
-     * callback. A non-null callback error fails the returned effect, while a
+     * callback. A truthy callback error fails the returned effect, while a
      * successful callback value becomes the effect success. Use `onError` to map
      * callback errors and `onSyncError` to turn synchronous throws into typed
      * failures; otherwise synchronous throws become defects.
@@ -20911,7 +21199,7 @@ export declare const effectify: {
      * **Details**
      *
      * The original function is called with the supplied arguments plus a final
-     * callback. A non-null callback error fails the returned effect, while a
+     * callback. A truthy callback error fails the returned effect, while a
      * successful callback value becomes the effect success. Use `onError` to map
      * callback errors and `onSyncError` to turn synchronous throws into typed
      * failures; otherwise synchronous throws become defects.
@@ -20965,7 +21253,7 @@ export declare const effectify: {
      * **Details**
      *
      * The original function is called with the supplied arguments plus a final
-     * callback. A non-null callback error fails the returned effect, while a
+     * callback. A truthy callback error fails the returned effect, while a
      * successful callback value becomes the effect success. Use `onError` to map
      * callback errors and `onSyncError` to turn synchronous throws into typed
      * failures; otherwise synchronous throws become defects.
@@ -21225,6 +21513,9 @@ export declare const mapEager: {
  * transform. Failure effects apply the mapping function immediately, and
  * pending effects fall back to regular `mapError` behavior.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping errors eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -21269,6 +21560,9 @@ export declare const mapErrorEager: {
      * transform. Failure effects apply the mapping function immediately, and
      * pending effects fall back to regular `mapError` behavior.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping errors eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -21313,6 +21607,9 @@ export declare const mapErrorEager: {
      * transform. Failure effects apply the mapping function immediately, and
      * pending effects fall back to regular `mapError` behavior.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping errors eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -21357,6 +21654,9 @@ export declare const mapErrorEager: {
  * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
  * behavior.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping both channels eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -21400,6 +21700,9 @@ export declare const mapBothEager: {
      * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
      * behavior.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping both channels eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -21446,6 +21749,9 @@ export declare const mapBothEager: {
      * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
      * behavior.
      *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping both channels eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -21608,6 +21914,12 @@ export declare const flatMapEager: {
  * Failure effects apply the catch function immediately, and pending effects
  * fall back to regular `catch` behavior.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching failures eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -21662,6 +21974,12 @@ export declare const catchEager: {
      * Failure effects apply the catch function immediately, and pending effects
      * fall back to regular `catch` behavior.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching failures eagerly when possible)
      *
      * ```ts import.meta.vitest
@@ -21716,6 +22034,12 @@ export declare const catchEager: {
      * Failure effects apply the catch function immediately, and pending effects
      * fall back to regular `catch` behavior.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching failures eagerly when possible)
      *
      * ```ts import.meta.vitest