effect 4.0.4 → 4.0.6

package/src/Effect.ts

@@ -1,3 +1,5 @@
+/// <reference lib="esnext.disposable" preserve="true" />
+
 /**
  * Describes workflows that run only when executed by the Effect runtime.
  *
@@ -20,7 +22,7 @@ import type * as ExecutionPlan from "./ExecutionPlan.ts"
 import * as Exit from "./Exit.ts"
 import type { Fiber } from "./Fiber.ts"
 import type * as Filter from "./Filter.ts"
-import { constant, dual, type LazyArg } from "./Function.ts"
+import { dual, type LazyArg } from "./Function.ts"
 import type { TypeLambda } from "./HKT.ts"
 import type { Inspectable } from "./Inspectable.ts"
 import * as core from "./internal/core.ts"
@@ -1333,8 +1335,9 @@ export 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**
  *
@@ -1344,6 +1347,13 @@ export 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
@@ -1388,9 +1398,10 @@ export const promise: <A>(
  * 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**
  *
@@ -1398,6 +1409,13 @@ export const promise: <A>(
  * 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
@@ -1460,9 +1478,10 @@ export 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**
    *
@@ -1470,6 +1489,13 @@ export 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
@@ -1532,9 +1558,10 @@ export 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**
    *
@@ -1542,6 +1569,13 @@ export 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
@@ -1823,10 +1857,20 @@ export {
  *
  * **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)
  *
@@ -2667,7 +2711,9 @@ export const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A, E> = i
  * `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)
  *
@@ -3747,9 +3793,12 @@ export 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)
  *
@@ -3791,9 +3840,12 @@ export const result: <A, E, R>(self: Effect<A, E, R>) => Effect<Result.Result<A,
  *
  * **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.
@@ -4579,6 +4631,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
@@ -4602,6 +4659,12 @@ export {
  * 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
@@ -4651,6 +4714,12 @@ export 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
@@ -4723,6 +4792,12 @@ export 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
@@ -4800,6 +4875,12 @@ export 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
@@ -4849,6 +4930,12 @@ export 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
@@ -4927,6 +5014,12 @@ export 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
@@ -5005,6 +5098,12 @@ export 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
@@ -5056,6 +5155,12 @@ export 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
@@ -5136,6 +5241,12 @@ export 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
@@ -5203,6 +5314,12 @@ export 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
@@ -5244,6 +5361,12 @@ export 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
@@ -5325,6 +5448,12 @@ export 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
@@ -5707,6 +5836,12 @@ export 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
@@ -5752,6 +5887,12 @@ export 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
@@ -5797,6 +5938,12 @@ export 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
@@ -5839,6 +5986,12 @@ export 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
@@ -5885,6 +6038,12 @@ export 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
@@ -5937,6 +6096,12 @@ export 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
@@ -5989,6 +6154,12 @@ export 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
@@ -6023,7 +6194,7 @@ export const catchIf: {
    */
   <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>,
+    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>
@@ -6040,6 +6211,12 @@ export 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
@@ -6096,6 +6273,12 @@ export 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
@@ -6122,6 +6305,12 @@ export 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
@@ -6154,6 +6343,12 @@ export 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
@@ -6448,6 +6643,9 @@ export 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
@@ -6489,6 +6687,9 @@ export 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
@@ -6530,6 +6731,9 @@ export 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
@@ -6575,6 +6779,9 @@ export 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
@@ -6618,6 +6825,9 @@ export 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
@@ -6663,6 +6873,9 @@ export 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
@@ -7492,7 +7705,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)
  *
@@ -7545,7 +7760,9 @@ export 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)
    *
@@ -7598,7 +7815,9 @@ export 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)
    *
@@ -7651,7 +7870,9 @@ export 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)
    *
@@ -7708,7 +7929,9 @@ export 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)
    *
@@ -7761,7 +7984,9 @@ export 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)
    *
@@ -7814,7 +8039,9 @@ export 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)
    *
@@ -7869,6 +8096,14 @@ export 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
@@ -7924,6 +8159,14 @@ export 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
@@ -7982,6 +8225,14 @@ export 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
@@ -8033,8 +8284,8 @@ export 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)
  *
@@ -8073,6 +8324,13 @@ export const sandbox: <A, E, R>(
  * 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
@@ -8449,6 +8707,12 @@ export const withErrorReporting: <
  *
  * 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
@@ -8490,6 +8754,12 @@ export 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
@@ -8531,6 +8801,12 @@ export 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
@@ -10602,6 +10878,12 @@ export 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
@@ -10658,6 +10940,12 @@ export 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
@@ -10719,6 +11007,12 @@ export 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
@@ -10779,6 +11073,12 @@ export 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
@@ -10820,6 +11120,12 @@ export 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
@@ -10866,6 +11172,12 @@ export 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
@@ -11412,6 +11724,12 @@ export 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
@@ -11464,6 +11782,12 @@ export 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
@@ -11521,6 +11845,12 @@ export 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
@@ -11751,9 +12081,9 @@ export const contextWith: <R, A, E, R2>(
 ) => Effect<A, E, R | R2> = internal.contextWith
 
 /**
- * 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)
  *
@@ -11786,9 +12116,9 @@ export const contextWith: <R, A, E, R2>(
  */
 export 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)
    *
@@ -11832,9 +12162,9 @@ export const provide: {
     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)
    *
@@ -11874,9 +12204,9 @@ export const provide: {
     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)
    *
@@ -11909,9 +12239,9 @@ export 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)
    *
@@ -11954,9 +12284,9 @@ export const provide: {
     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)
    *
@@ -11995,9 +12325,9 @@ export const provide: {
     } | 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)
    *
@@ -12797,103 +13127,7 @@ export 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>>
   }
   /**
@@ -15412,6 +15646,10 @@ export const forever: <
  * 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
@@ -15494,6 +15732,10 @@ export 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
@@ -15576,6 +15818,10 @@ export 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
@@ -15658,6 +15904,10 @@ export 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
@@ -15744,6 +15994,10 @@ export 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
@@ -15826,6 +16080,10 @@ export 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
@@ -15911,6 +16169,10 @@ export 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
@@ -15985,6 +16247,13 @@ export 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
@@ -16038,6 +16307,13 @@ export 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
@@ -16094,6 +16370,13 @@ export 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
@@ -17912,8 +18195,8 @@ export const requestUnsafe: <A extends Request.Any>(
  * 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
@@ -18105,9 +18388,14 @@ export const forkScoped: <
   : <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R | Scope> = internal.forkScoped
 
 /**
- * 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)
  *
@@ -18265,11 +18553,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)
  *
@@ -18604,9 +18892,10 @@ export const runPromiseExitWith: <R>(
  *
  * **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)
  *
@@ -25245,50 +25534,113 @@ export const trackDuration: {
 // Transactions
 // -----------------------------------------------------------------------------
 
+/**
+ * Why the current transaction attempt started after a previous attempt did not commit.
+ *
+ * **Details**
+ *
+ * `"retry"` means the previous attempt called {@link txRetry}. `"conflict"`
+ * means an accessed `TxRef` changed before commit. The first attempt has no
+ * retry reason.
+ *
+ * @stability stable
+ * @category models
+ * @since 4.0.0
+ */
+export type TransactionRetryReason = "retry" | "conflict"
+
+/**
+ * Journal and attempt metadata for an Effect transaction.
+ *
+ * **When to use**
+ *
+ * Use to type the value provided by {@link Transaction}.
+ *
+ * **Details**
+ *
+ * `attempt` starts at `1` and counts each run of the outermost transaction body.
+ * `retryReason` is `"retry"` after {@link txRetry} and `"conflict"` after an
+ * accessed `TxRef` changes before commit; it is unset on the first attempt.
+ * `start`, `now`, `elapsed`, and `elapsedSincePrevious` are millisecond
+ * timestamps and durations for the current attempt, matching {@link Schedule}
+ * metadata. Each journal entry stores the observed version and value of a
+ * `TxRef`. `written` is true when this transaction has updated that ref.
+ *
+ * @see {@link Transaction} for the context service that provides this metadata
+ * @see {@link TransactionRetryReason} for the retry-reason tags recorded on later attempts
+ *
+ * @stability stable
+ * @category models
+ * @since 4.0.0
+ */
+export interface TransactionMeta {
+  readonly journal: ReadonlyMap<
+    TxRef<any>,
+    {
+      readonly version: number
+      readonly value: any
+      readonly written: boolean
+    }
+  >
+  readonly attempt: number
+  readonly retryReason: TransactionRetryReason | undefined
+  readonly start: number
+  readonly now: number
+  readonly elapsed: number
+  readonly elapsedSincePrevious: number
+}
+
+/** @internal */
+export interface TransactionMetaInner {
+  retry: boolean
+  journal: Map<
+    TxRef<any>,
+    {
+      readonly version: number
+      value: any
+      written: boolean
+    }
+  >
+  attempt: number
+  retryReason: TransactionRetryReason | undefined
+  start: number
+  now: number
+  elapsed: number
+  elapsedSincePrevious: number
+}
+
 /**
  * Service that holds the current transaction state.
  *
  * **Details**
  *
- * It includes a journal that stores non-committed changes to `TxRef` values and
- * a retry flag that records whether the transaction should be retried.
+ * Nested {@link tx} calls reuse this same service instance. Yield it inside a
+ * transaction body to read {@link TransactionMeta} fields such as `attempt`
+ * and `retryReason`.
  *
- * **Example** (Building transactions)
+ * **Example** (Reading transaction metadata)
  *
  * ```ts import.meta.vitest
  * import { Effect } from "effect"
  *
- * // Transaction class for software transactional memory operations
- * const txEffect = Effect.gen(function*() {
+ * const program = Effect.tx(Effect.gen(function*() {
  *   const tx = yield* Effect.Transaction
- *   // Use transaction for coordinated state changes
- *   return "Transaction complete"
- * })
+ *   return [tx.attempt, tx.retryReason, tx.elapsed, tx.elapsedSincePrevious]
+ * }))
  *
- * const runnable = Effect.provideService(txEffect, Effect.Transaction, {
- *   retry: false,
- *   journal: new Map()
- * })
- * Effect.runSync(runnable) // => "Transaction complete"
+ * Effect.runSync(program) // => [1, undefined, 0, 0]
  * ```
  *
+ * @see {@link tx} for the outermost transaction boundary that creates this service
+ * @see {@link TransactionMeta} for the journal and attempt metadata
+ *
  * @stability stable
  * @category transactions
  * @since 4.0.0
  */
 export class Transaction extends Context.Service<
   Transaction,
-  {
-    retry: boolean
-    readonly journal: Map<
-      TxRef<any>,
-      {
-        readonly version: number
-        value: any
-        written: boolean
-      }
-    >
-  }
+  TransactionMeta
 >()("effect/Effect/Transaction") {}
 
 /**
@@ -25342,52 +25694,75 @@ export const tx = <A, E, R>(
   effect: Effect<A, E, R>
 ): Effect<A, E, Exclude<R, Transaction>> =>
   withFiber((fiber) => {
-    let state = Context.getOrUndefined(fiber.context, Transaction)
+    const state = Context.getOrUndefined(fiber.context, Transaction)
     if (state && !completedTransactions.has(state)) {
       return effect as Effect<A, E, Exclude<R, Transaction>>
     }
+    const clock = fiber.getRef(internal.ClockRef)
+    const now = clock.currentTimeMillisUnsafe()
     // Create transaction state only at the outermost boundary
-    state = { journal: new Map(), retry: false }
+    const mutable: TransactionMetaInner = {
+      journal: new Map(),
+      retry: false,
+      attempt: 1,
+      retryReason: undefined,
+      start: now,
+      now,
+      elapsed: 0,
+      elapsedSincePrevious: 0
+    }
     let result: Exit.Exit<A, E> | undefined
-    return uninterruptibleMask((restore) =>
-      flatMap(
+    return uninterruptibleMask((restore) => {
+      const run = restore(effect).pipe(
+        provideService(Transaction, mutable),
+        tapCause((cause) => {
+          if (!mutable.retry) return void_
+          // txRetry interrupts the body; any other reason in the cause is a real failure.
+          // Roll back now so the step below fails instead of waiting or rerunning.
+          if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(mutable))
+          return restore(awaitPendingTransaction(mutable))
+        }),
+        exit
+      )
+      return flatMap(
         whileLoop({
           while: () => !result,
-          body: constant(
-            restore(effect).pipe(
-              provideService(Transaction, state),
-              tapCause((cause) => {
-                if (!state.retry) return void_
-                // txRetry interrupts the body; any other reason in the cause is a real failure.
-                // Roll back now so the step below fails instead of waiting or rerunning.
-                if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(state))
-                return restore(awaitPendingTransaction(state))
-              }),
-              exit
-            )
-          ),
+          body: () => {
+            if (mutable.attempt > 1) {
+              stampTransaction(mutable, clock.currentTimeMillisUnsafe())
+            }
+            return run
+          },
           step(exit: Exit.Exit<A, E>) {
-            if (state.retry || !isTransactionConsistent(state)) {
-              return clearTransaction(state)
+            if (mutable.retry || !isTransactionConsistent(mutable)) {
+              mutable.attempt++
+              mutable.retryReason = mutable.retry ? "retry" : "conflict"
+              return clearTransaction(mutable)
             }
             if (Exit.isSuccess(exit)) {
-              commitTransaction(fiber, state)
+              commitTransaction(fiber, mutable)
             }
-            clearTransaction(state)
-            completedTransactions.add(state)
+            clearTransaction(mutable)
+            completedTransactions.add(mutable)
             result = exit
           }
         }),
         () => result!
       )
-    )
+    })
   })
 
 // Child fibers inherit the boundary's state, so mark it completed once the
 // boundary finishes and let later `tx` calls start a fresh boundary.
 const completedTransactions = new WeakSet<Transaction["Service"]>()
 
-const isTransactionConsistent = (state: Transaction["Service"]) => {
+const stampTransaction = (state: TransactionMetaInner, now: number) => {
+  state.elapsedSincePrevious = now - state.now
+  state.now = now
+  state.elapsed = now - state.start
+}
+
+const isTransactionConsistent = (state: TransactionMeta) => {
   for (const [ref, { version }] of state.journal) {
     if (ref.version !== version) {
       return false
@@ -25396,7 +25771,7 @@ const isTransactionConsistent = (state: Transaction["Service"]) => {
   return true
 }
 
-const awaitPendingTransaction = (state: Transaction["Service"]) =>
+const awaitPendingTransaction = (state: TransactionMeta) =>
   callback<void>((resume) => {
     // Validate the read set and register the waiter in one synchronous step.
     // A commit that landed after the reads has already signalled its waiters
@@ -25421,7 +25796,7 @@ const awaitPendingTransaction = (state: Transaction["Service"]) =>
     return sync(clearPending)
   })
 
-function commitTransaction(fiber: Fiber<unknown, unknown>, state: Transaction["Service"]) {
+function commitTransaction(fiber: Fiber<unknown, unknown>, state: TransactionMeta) {
   for (const [ref, { value, written }] of state.journal) {
     if (!written) continue
     if (!Object.is(value, ref.value)) {
@@ -25435,7 +25810,7 @@ function commitTransaction(fiber: Fiber<unknown, unknown>, state: Transaction["S
   }
 }
 
-function clearTransaction(state: Transaction["Service"]) {
+function clearTransaction(state: TransactionMetaInner) {
   state.retry = false
   state.journal.clear()
 }
@@ -25480,7 +25855,8 @@ function clearTransaction(state: Transaction["Service"]) {
 export const txRetry: Effect<never, never, Transaction> = flatMap(
   Transaction,
   (state) => {
-    state.retry = true
+    const mutable = state as TransactionMetaInner
+    mutable.retry = true
     return interrupt
   }
 )
@@ -25742,7 +26118,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.
@@ -25796,7 +26172,7 @@ export 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.
@@ -25850,7 +26226,7 @@ export 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.
@@ -25907,7 +26283,7 @@ export 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.
@@ -25962,16 +26338,26 @@ export const effectify: {
   (<A>(fn: Function, onError?: (e: any, args: any) => any, onSyncError?: (e: any, args: any) => any) =>
   (...args: Array<any>) =>
     callback<A, globalThis.Error>((resume) => {
+      let synchronous = true
+      let pending: Effect<A, globalThis.Error> | undefined
       try {
         fn(...args, (err: globalThis.Error | null, result: A) => {
-          if (err) {
-            resume(onError ? suspend(() => fail(onError(err, args))) : fail(err))
+          const effect = err
+            ? onError ? suspend(() => fail(onError(err, args))) : fail(err)
+            : succeed(result)
+          if (synchronous) {
+            // Keep the first callback result until registration succeeds.
+            pending ??= effect
           } else {
-            resume(succeed(result))
+            resume(effect)
           }
         })
       } catch (err) {
-        resume(onSyncError ? fail(onSyncError(err, args)) : die(err))
+        pending = onSyncError ? fail(onSyncError(err, args)) : die(err)
+      }
+      synchronous = false
+      if (pending) {
+        resume(pending)
       }
     })) as any
 
@@ -26195,6 +26581,9 @@ export 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
@@ -26239,6 +26628,9 @@ export 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
@@ -26283,6 +26675,9 @@ export 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
@@ -26328,6 +26723,9 @@ export 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
@@ -26371,6 +26769,9 @@ export 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
@@ -26416,6 +26817,9 @@ export 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
@@ -26580,6 +26984,12 @@ export 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
@@ -26634,6 +27044,12 @@ export 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
@@ -26688,6 +27104,12 @@ export 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