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

package/dist/Schedule.d.ts

@@ -79,7 +79,7 @@ export interface Schedule<out Output, in Input = unknown, out Error = never, out
  * })
  * ```
  *
- * @category Metadata
+ * @category metadata
  * @since 4.0.0
  */
 export interface InputMetadata<Input> {
@@ -121,7 +121,7 @@ export interface InputMetadata<Input> {
  * // Output: 2, attempt: 3, elapsed: 200ms
  * ```
  *
- * @category Metadata
+ * @category metadata
  * @since 4.0.0
  */
 export interface Metadata<Output = unknown, Input = unknown> extends InputMetadata<Input> {
@@ -138,7 +138,7 @@ export interface Metadata<Output = unknown, Input = unknown> extends InputMetada
  * input and output values, zero duration, and zeroed timing fields before any
  * schedule step has produced metadata.
  *
- * @category Metadata
+ * @category metadata
  * @since 4.0.0
  */
 export declare const CurrentMetadata: Context.Reference<Metadata<unknown, unknown>>;
@@ -326,8 +326,22 @@ export declare const fromStepWithMetadata: <Input, Output, EnvX, ErrorX, Error,
  */
 export declare const toStep: <Output, Input, Error, Env>(schedule: Schedule<Output, Input, Error, Env>) => Effect<(now: number, input: Input) => Pull.Pull<[Output, Duration.Duration], Error, Output, Env>, never, Env>;
 /**
- * Extracts a step function from a Schedule that provides metadata about each
- * execution. It will also handle sleeping for the computed delay.
+ * Extracts a step function from a `Schedule` that sleeps for each computed
+ * delay and returns metadata for the completed step.
+ *
+ * **When to use**
+ *
+ * Use to drive a schedule manually while preserving the computed output,
+ * delay, input, attempt, and elapsed timing metadata for each step.
+ *
+ * **Details**
+ *
+ * The returned step reads the current time from `Clock` when invoked, calls the
+ * schedule step with that timestamp and input, sleeps for the returned
+ * duration, and then yields `Metadata`.
+ *
+ * @see {@link toStep} for manually supplying the timestamp and handling the returned delay yourself
+ * @see {@link toStepWithSleep} for the same automatic sleeping behavior when only the schedule output is needed
  *
  * @category destructors
  * @since 4.0.0
@@ -366,7 +380,7 @@ export declare const toStepWithMetadata: <Output, Input, Error, Env>(schedule: S
 export declare const toStepWithSleep: <Output, Input, Error, Env>(schedule: Schedule<Output, Input, Error, Env>) => Effect<(input: Input) => Pull.Pull<Output, Error, Output, Env>, never, Env>;
 /**
  * Returns a new `Schedule` that adds the delay computed by the specified
- * effectful function to the the next recurrence of the schedule.
+ * effectful function to the next recurrence of the schedule.
  *
  * **Example** (Adding extra delay to a schedule)
  *
@@ -466,7 +480,7 @@ export declare const toStepWithSleep: <Output, Input, Error, Env>(schedule: Sche
 export declare const addDelay: {
     /**
      * Returns a new `Schedule` that adds the delay computed by the specified
-     * effectful function to the the next recurrence of the schedule.
+     * effectful function to the next recurrence of the schedule.
      *
      * **Example** (Adding extra delay to a schedule)
      *
@@ -566,7 +580,7 @@ export declare const addDelay: {
     <Output, Error2 = never, Env2 = never>(f: (output: Output) => Effect<Duration.Input, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error | Error2, Env | Env2>;
     /**
      * Returns a new `Schedule` that adds the delay computed by the specified
-     * effectful function to the the next recurrence of the schedule.
+     * effectful function to the next recurrence of the schedule.
      *
      * **Example** (Adding extra delay to a schedule)
      *
@@ -666,9 +680,8 @@ export declare const addDelay: {
     <Output, Input, Error, Env, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, f: (output: Output) => Effect<Duration.Input, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
 };
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * merges their outputs.
  *
  * **Example** (Sequencing quick and slow retries)
  *
@@ -708,9 +721,8 @@ export declare const addDelay: {
  */
 export declare const andThen: {
     /**
-     * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-     * schedule to completion. Once the left schedule is complete, the right (i.e.
-     * `other`) schedule will be executed to completion.
+     * Returns a schedule that runs `self` to completion, then runs `other`, and
+     * merges their outputs.
      *
      * **Example** (Sequencing quick and slow retries)
      *
@@ -750,9 +762,8 @@ export declare const andThen: {
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output | Output2, Input & Input2, Error | Error2, Env | Env2>;
     /**
-     * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-     * schedule to completion. Once the left schedule is complete, the right (i.e.
-     * `other`) schedule will be executed to completion.
+     * Returns a schedule that runs `self` to completion, then runs `other`, and
+     * merges their outputs.
      *
      * **Example** (Sequencing quick and slow retries)
      *
@@ -793,9 +804,8 @@ export declare const andThen: {
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Output | Output2, Input & Input2, Error | Error2, Env | Env2>;
 };
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * preserves which schedule produced each output.
  *
  * **Details**
  *
@@ -837,9 +847,8 @@ export declare const andThen: {
  */
 export declare const andThenResult: {
     /**
-     * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-     * schedule to completion. Once the left schedule is complete, the right (i.e.
-     * `other`) schedule will be executed to completion.
+     * Returns a schedule that runs `self` to completion, then runs `other`, and
+     * preserves which schedule produced each output.
      *
      * **Details**
      *
@@ -881,9 +890,8 @@ export declare const andThenResult: {
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Result.Result<Output2, Output>, Input & Input2, Error | Error2, Env | Env2>;
     /**
-     * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-     * schedule to completion. Once the left schedule is complete, the right (i.e.
-     * `other`) schedule will be executed to completion.
+     * Returns a schedule that runs `self` to completion, then runs `other`, and
+     * preserves which schedule produced each output.
      *
      * **Details**
      *
@@ -930,6 +938,12 @@ export declare const andThenResult: {
  * to recur, using the maximum of the two durations between recurrences and
  * outputting a tuple of the outputs of both schedules.
  *
+ * **When to use**
+ *
+ * Use when the combined schedule should continue only while both
+ * schedules still recur. Use `either` when either schedule should be enough to
+ * continue.
+ *
  * **Example** (Combining time and attempt limits)
  *
  * ```ts
@@ -992,6 +1006,8 @@ export declare const andThenResult: {
  * // Compare with either which provides union semantics (OR logic)
  * ```
  *
+ * @see {@link either} for continuing while either schedule still recurs
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -1001,6 +1017,12 @@ export declare const both: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting a tuple of the outputs of both schedules.
      *
+     * **When to use**
+     *
+     * Use when the combined schedule should continue only while both
+     * schedules still recur. Use `either` when either schedule should be enough to
+     * continue.
+     *
      * **Example** (Combining time and attempt limits)
      *
      * ```ts
@@ -1063,6 +1085,8 @@ export declare const both: {
      * // Compare with either which provides union semantics (OR logic)
      * ```
      *
+     * @see {@link either} for continuing while either schedule still recurs
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -1072,6 +1096,12 @@ export declare const both: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting a tuple of the outputs of both schedules.
      *
+     * **When to use**
+     *
+     * Use when the combined schedule should continue only while both
+     * schedules still recur. Use `either` when either schedule should be enough to
+     * continue.
+     *
      * **Example** (Combining time and attempt limits)
      *
      * ```ts
@@ -1134,6 +1164,8 @@ export declare const both: {
      * // Compare with either which provides union semantics (OR logic)
      * ```
      *
+     * @see {@link either} for continuing while either schedule still recurs
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -2187,7 +2219,7 @@ export declare const cron: {
     (expression: string, tz?: string | DateTime.TimeZone): Schedule<Duration.Duration, unknown, Cron.CronParseError>;
 };
 /**
- * Returns a new schedule that outputs the delay between each occurence.
+ * Returns a new schedule that outputs the delay between each occurrence.
  *
  * **Example** (Extracting schedule delays)
  *
@@ -2213,7 +2245,7 @@ export declare const cron: {
  *   )
  * })
  *
- * // Monitor delays from a fibonacci schedule
+ * // Monitor delays from a Fibonacci schedule
  * const fibonacciDelays = Schedule.delays(
  *   Schedule.fibonacci("200 millis").pipe(Schedule.take(8))
  * )
@@ -2274,11 +2306,29 @@ export declare const delays: <Out, In, E, R>(self: Schedule<Out, In, E, R>) => S
 /**
  * Returns a schedule that recurs once after the specified duration.
  *
+ * **When to use**
+ *
+ * Use when you need one delayed recurrence. Use `during` to keep
+ * recurring until a duration has elapsed.
+ *
  * **Details**
  *
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
+ * **Example** (Recurring once after a duration)
+ *
+ * ```ts
+ * import { Console, Effect, Schedule } from "effect"
+ *
+ * const program = Effect.repeat(
+ *   Console.log("runs again after one second"),
+ *   Schedule.duration("1 second")
+ * )
+ * ```
+ *
+ * @see {@link during} for recurring until a duration has elapsed
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -2287,6 +2337,11 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  * Returns a new `Schedule` that will always recur, but only during the
  * specified `duration` of time.
  *
+ * **When to use**
+ *
+ * Use to bound a repeating or retrying schedule by elapsed time. Use
+ * `duration` when you need one delayed recurrence.
+ *
  * **Example** (Repeating work during a duration)
  *
  * ```ts
@@ -2365,6 +2420,8 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  * )
  * ```
  *
+ * @see {@link duration} for one delayed recurrence
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2374,6 +2431,11 @@ export declare const during: (duration: Duration.Input) => Schedule<Duration.Dur
  * to recur, using the minimum of the two durations between recurrences and
  * outputting a tuple of the outputs of both schedules.
  *
+ * **When to use**
+ *
+ * Use when the combined schedule should continue while at least one
+ * schedule still recurs. Use `both` when both schedules must continue.
+ *
  * **Example** (Combining schedules with either semantics)
  *
  * ```ts
@@ -2435,9 +2497,11 @@ export declare const during: (duration: Duration.Input) => Schedule<Duration.Dur
  * })
  *
  * // Either provides union semantics (OR logic)
- * // Compare with intersect which provides intersection semantics (AND logic)
+ * // Compare with both, which provides intersection semantics (AND logic)
  * ```
  *
+ * @see {@link both} for continuing only while both schedules still recur
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -2447,6 +2511,11 @@ export declare const either: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting a tuple of the outputs of both schedules.
      *
+     * **When to use**
+     *
+     * Use when the combined schedule should continue while at least one
+     * schedule still recurs. Use `both` when both schedules must continue.
+     *
      * **Example** (Combining schedules with either semantics)
      *
      * ```ts
@@ -2508,9 +2577,11 @@ export declare const either: {
      * })
      *
      * // Either provides union semantics (OR logic)
-     * // Compare with intersect which provides intersection semantics (AND logic)
+     * // Compare with both, which provides intersection semantics (AND logic)
      * ```
      *
+     * @see {@link both} for continuing only while both schedules still recur
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -2520,6 +2591,11 @@ export declare const either: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting a tuple of the outputs of both schedules.
      *
+     * **When to use**
+     *
+     * Use when the combined schedule should continue while at least one
+     * schedule still recurs. Use `both` when both schedules must continue.
+     *
      * **Example** (Combining schedules with either semantics)
      *
      * ```ts
@@ -2581,9 +2657,11 @@ export declare const either: {
      * })
      *
      * // Either provides union semantics (OR logic)
-     * // Compare with intersect which provides intersection semantics (AND logic)
+     * // Compare with both, which provides intersection semantics (AND logic)
      * ```
      *
+     * @see {@link both} for continuing only while both schedules still recur
+     *
      * @category utils
      * @since 2.0.0
      */
@@ -2932,7 +3010,8 @@ export declare const eitherWith: {
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2, Output3>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>, combine: (selfOutput: Output, otherOutput: Output2) => Output3): Schedule<Output3, Input & Input2, Error | Error2, Env | Env2>;
 };
 /**
- * A schedule that always recurs and returns the total elapsed duration since the first recurrence.
+ * Schedule that always recurs and returns the total elapsed duration since the
+ * first recurrence.
  *
  * **Details**
  *
@@ -2963,7 +3042,7 @@ export declare const eitherWith: {
  */
 export declare const elapsed: Schedule<Duration.Duration>;
 /**
- * A schedule that always recurs, but will wait a certain amount between
+ * Schedule that always recurs, but will wait a certain amount between
  * repetitions, given by `base * factor.pow(n)`, where `n` is the number of
  * repetitions so far. Returns the current duration between recurrences.
  *
@@ -3013,22 +3092,22 @@ export declare const elapsed: Schedule<Duration.Duration>;
  */
 export declare const exponential: (base: Duration.Input, factor?: number) => Schedule<Duration.Duration>;
 /**
- * A schedule that always recurs, increasing delays by summing the preceding
- * two delays (similar to the fibonacci sequence). Returns the current
+ * Schedule that always recurs, increasing delays by summing the preceding
+ * two delays (similar to the Fibonacci sequence). Returns the current
  * duration between recurrences.
  *
- * **Example** (Retrying with fibonacci backoff)
+ * **Example** (Retrying with Fibonacci backoff)
  *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Basic fibonacci schedule starting with 100ms
+ * // Basic Fibonacci schedule starting with 100ms
  * const fibSchedule = Schedule.fibonacci("100 millis")
  * // Delays: 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, 1300ms, ...
  *
- * // Retry with fibonacci backoff for gradual increase
+ * // Retry with Fibonacci backoff for gradual increase
  * const retryWithFib = Effect.gen(function*() {
  *   let attempt = 0
  *
@@ -3052,7 +3131,7 @@ export declare const exponential: (base: Duration.Input, factor?: number) => Sch
  *   yield* Console.log(`Final result: ${result}`)
  * })
  *
- * // Heartbeat with fibonacci intervals (starts fast, gets slower)
+ * // Heartbeat with Fibonacci intervals (starts fast, gets slower)
  * const adaptiveHeartbeat = Effect.gen(function*() {
  *   yield* Console.log("Heartbeat")
  *   return "pulse"
@@ -3084,10 +3163,15 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  * Returns a `Schedule` that recurs on the specified fixed `interval` and
  * outputs the number of repetitions of the schedule so far.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use when recurrences should stay aligned to a regular cadence. Use
+ * `spaced` when each delay should start after the previous action completes.
  *
- * If the action run between updates takes longer than the interval, then the
- * action will be run immediately, but re-runs will not "pile up".
+ * **Gotchas**
+ *
+ * If the action run between recurrences takes longer than the interval, the
+ * next recurrence happens immediately, but missed intervals are not replayed.
  *
  * ```text
  * |-----interval-----|-----interval-----|-----interval-----|
@@ -3099,7 +3183,7 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
- * // Fixed interval schedule - runs exactly every 1 second
+ * // Fixed interval schedule - recurs on a one-second cadence
  * const everySecond = Schedule.fixed("1 second")
  *
  * // Health check that runs at fixed intervals
@@ -3142,6 +3226,8 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  * })
  * ```
  *
+ * @see {@link spaced} for delaying after each action completes
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -3338,7 +3424,7 @@ export declare const map: {
 };
 /**
  * Returns a new `Schedule` that modifies the delay of the next recurrence
- * of the schedule using the specified effectual function.
+ * of the schedule using the specified effectful function.
  *
  * **Example** (Modifying delays from schedule output)
  *
@@ -3372,7 +3458,7 @@ export declare const map: {
 export declare const modifyDelay: {
     /**
      * Returns a new `Schedule` that modifies the delay of the next recurrence
-     * of the schedule using the specified effectual function.
+     * of the schedule using the specified effectful function.
      *
      * **Example** (Modifying delays from schedule output)
      *
@@ -3406,7 +3492,7 @@ export declare const modifyDelay: {
     <Output, Error2 = never, Env2 = never>(f: (output: Output, delay: Duration.Duration) => Effect<Duration.Input, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error | Error2, Env | Env2>;
     /**
      * Returns a new `Schedule` that modifies the delay of the next recurrence
-     * of the schedule using the specified effectual function.
+     * of the schedule using the specified effectful function.
      *
      * **Example** (Modifying delays from schedule output)
      *
@@ -3442,9 +3528,16 @@ export declare const modifyDelay: {
 /**
  * Returns a new `Schedule` that randomly adjusts each recurrence delay.
  *
+ * **When to use**
+ *
+ * Use to add random variation to an existing schedule's recurrence delays while
+ * preserving its output and completion behavior.
+ *
  * **Details**
  *
- * Delays are jittered between `80%` and `120%` of the original delay.
+ * Each recurrence delay is scaled by a random factor between `0.8` and `1.2`.
+ *
+ * @see {@link modifyDelay} for replacing recurrence delays with a custom effectful transformation
  *
  * @category utils
  * @since 2.0.0
@@ -3484,6 +3577,18 @@ export declare const passthrough: <Output, Input, Error, Env>(self: Schedule<Out
  * Returns a `Schedule` which can only be stepped the specified number of
  * `times` before it terminates.
  *
+ * **When to use**
+ *
+ * Use when you need a counter schedule with no additional delay. Use `take`
+ * to limit an existing schedule while preserving its output and delay
+ * behavior.
+ *
+ * **Gotchas**
+ *
+ * `recurs(n)` counts schedule recurrences, not the first evaluation of the
+ * effect being repeated or retried. For retrying, this means one initial
+ * attempt plus at most `n` retries.
+ *
  * **Example** (Limiting recurrences)
  *
  * ```ts
@@ -3517,11 +3622,11 @@ export declare const passthrough: <Output, Input, Error, Env>(self: Schedule<Out
  *
  * // Combining recurs with other schedules for sophisticated retry logic
  * const complexRetry = Schedule.exponential("100 millis").pipe(
- *   Schedule.both(Schedule.recurs(3)) // At most 3 attempts
+ *   Schedule.both(Schedule.recurs(3)) // At most 3 retries
  * )
  *
- * // Repeat an effect exactly 10 times
- * const exactlyTenTimes = Effect.gen(function*() {
+ * // Allow ten recurrences after the initial run
+ * const tenRecurrences = Effect.gen(function*() {
  *   yield* Console.log("Executing task...")
  *   return "completed"
  * }).pipe(
@@ -3534,6 +3639,8 @@ export declare const passthrough: <Output, Input, Error, Env>(self: Schedule<Out
  * )
  * ```
  *
+ * @see {@link take} for limiting an existing schedule
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -3882,6 +3989,12 @@ export declare const reduce: {
  * Returns a schedule that recurs continuously, each repetition spaced the
  * specified duration from the last run.
  *
+ * **When to use**
+ *
+ * Use when each delay should start after the previous action
+ * completes. Use `fixed` when recurrences should stay aligned to a regular
+ * cadence.
+ *
  * **Example** (Repeating with fixed spacing)
  *
  * ```ts
@@ -3925,10 +4038,118 @@ export declare const reduce: {
  * })
  * ```
  *
+ * @see {@link fixed} for recurrence aligned to a regular cadence
+ *
  * @category constructors
  * @since 2.0.0
  */
 export declare const spaced: (duration: Duration.Input) => Schedule<number>;
+/**
+ * Returns a new `Schedule` that allows execution of an effectful function for
+ * every decision of the schedule, but does not alter the inputs and outputs of
+ * the schedule.
+ *
+ * **Details**
+ *
+ * The callback receives the full schedule metadata, including the input, output,
+ * computed delay duration, current attempt, and elapsed timing information.
+ *
+ * **Example** (Tapping schedule metadata)
+ *
+ * ```ts
+ * import { Console, Effect, Schedule } from "effect"
+ *
+ * const monitoredSchedule = Schedule.exponential("100 millis").pipe(
+ *   Schedule.take(5),
+ *   Schedule.tap((metadata) =>
+ *     Console.log(
+ *       `Attempt ${metadata.attempt} produced ${metadata.output} ` +
+ *         `after ${metadata.elapsed}ms; next delay is ${metadata.duration}`
+ *     )
+ *   )
+ * )
+ *
+ * const program = Effect.retry(
+ *   Effect.fail("transient error"),
+ *   monitoredSchedule
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 4.0.0
+ */
+export declare const tap: {
+    /**
+     * Returns a new `Schedule` that allows execution of an effectful function for
+     * every decision of the schedule, but does not alter the inputs and outputs of
+     * the schedule.
+     *
+     * **Details**
+     *
+     * The callback receives the full schedule metadata, including the input, output,
+     * computed delay duration, current attempt, and elapsed timing information.
+     *
+     * **Example** (Tapping schedule metadata)
+     *
+     * ```ts
+     * import { Console, Effect, Schedule } from "effect"
+     *
+     * const monitoredSchedule = Schedule.exponential("100 millis").pipe(
+     *   Schedule.take(5),
+     *   Schedule.tap((metadata) =>
+     *     Console.log(
+     *       `Attempt ${metadata.attempt} produced ${metadata.output} ` +
+     *         `after ${metadata.elapsed}ms; next delay is ${metadata.duration}`
+     *     )
+     *   )
+     * )
+     *
+     * const program = Effect.retry(
+     *   Effect.fail("transient error"),
+     *   monitoredSchedule
+     * )
+     * ```
+     *
+     * @category sequencing
+     * @since 4.0.0
+     */
+    <Output, Input, X, Error2, Env2>(f: (metadata: Metadata<Output, Input>) => Effect<X, Error2, Env2>): <Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error | Error2, Env | Env2>;
+    /**
+     * Returns a new `Schedule` that allows execution of an effectful function for
+     * every decision of the schedule, but does not alter the inputs and outputs of
+     * the schedule.
+     *
+     * **Details**
+     *
+     * The callback receives the full schedule metadata, including the input, output,
+     * computed delay duration, current attempt, and elapsed timing information.
+     *
+     * **Example** (Tapping schedule metadata)
+     *
+     * ```ts
+     * import { Console, Effect, Schedule } from "effect"
+     *
+     * const monitoredSchedule = Schedule.exponential("100 millis").pipe(
+     *   Schedule.take(5),
+     *   Schedule.tap((metadata) =>
+     *     Console.log(
+     *       `Attempt ${metadata.attempt} produced ${metadata.output} ` +
+     *         `after ${metadata.elapsed}ms; next delay is ${metadata.duration}`
+     *     )
+     *   )
+     * )
+     *
+     * const program = Effect.retry(
+     *   Effect.fail("transient error"),
+     *   monitoredSchedule
+     * )
+     * ```
+     *
+     * @category sequencing
+     * @since 4.0.0
+     */
+    <Output, Input, Error, Env, X, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, f: (metadata: Metadata<Output, Input>) => Effect<X, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
+};
 /**
  * Returns a new `Schedule` that allows execution of an effectful function for
  * every input to the schedule, but does not alter the inputs and outputs of
@@ -4578,6 +4799,18 @@ export declare const tapOutput: {
  * from the schedule. Once the specified number of outputs is reached, the
  * schedule will stop.
  *
+ * **When to use**
+ *
+ * Use to limit an existing schedule while preserving its output and
+ * delay behavior. Use `recurs` when you only need an immediate counter
+ * schedule.
+ *
+ * **Gotchas**
+ *
+ * `take(n)` limits schedule outputs. When used with repeat or retry, the
+ * effect is evaluated once before the schedule is stepped, so the total number
+ * of evaluations can be one greater than the number of outputs taken.
+ *
  * **Example** (Taking a limited number of recurrences)
  *
  * ```ts
@@ -4585,9 +4818,9 @@ export declare const tapOutput: {
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Limit an infinite schedule to run only 5 times
+ * // Limit an infinite schedule to five recurrences
  * const limitedHeartbeat = Schedule.spaced("1 second").pipe(
- *   Schedule.take(5) // Will stop after 5 executions
+ *   Schedule.take(5) // Will stop after 5 schedule outputs
  * )
  *
  * const heartbeatProgram = Effect.gen(function*() {
@@ -4633,7 +4866,7 @@ export declare const tapOutput: {
  *
  * // Combine take with other schedule operations
  * const samplingSchedule = Schedule.fixed("500 millis").pipe(
- *   Schedule.take(10), // Sample exactly 10 times
+ *   Schedule.take(10), // Take at most 10 schedule outputs
  *   Schedule.map((count) => Effect.succeed(`Sample #${count + 1}`))
  * )
  *
@@ -4651,6 +4884,8 @@ export declare const tapOutput: {
  * })
  * ```
  *
+ * @see {@link recurs} for creating a count-limited schedule
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -4660,6 +4895,18 @@ export declare const take: {
      * from the schedule. Once the specified number of outputs is reached, the
      * schedule will stop.
      *
+     * **When to use**
+     *
+     * Use to limit an existing schedule while preserving its output and
+     * delay behavior. Use `recurs` when you only need an immediate counter
+     * schedule.
+     *
+     * **Gotchas**
+     *
+     * `take(n)` limits schedule outputs. When used with repeat or retry, the
+     * effect is evaluated once before the schedule is stepped, so the total number
+     * of evaluations can be one greater than the number of outputs taken.
+     *
      * **Example** (Taking a limited number of recurrences)
      *
      * ```ts
@@ -4667,9 +4914,9 @@ export declare const take: {
      *
      * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
      *
-     * // Limit an infinite schedule to run only 5 times
+     * // Limit an infinite schedule to five recurrences
      * const limitedHeartbeat = Schedule.spaced("1 second").pipe(
-     *   Schedule.take(5) // Will stop after 5 executions
+     *   Schedule.take(5) // Will stop after 5 schedule outputs
      * )
      *
      * const heartbeatProgram = Effect.gen(function*() {
@@ -4715,7 +4962,7 @@ export declare const take: {
      *
      * // Combine take with other schedule operations
      * const samplingSchedule = Schedule.fixed("500 millis").pipe(
-     *   Schedule.take(10), // Sample exactly 10 times
+     *   Schedule.take(10), // Take at most 10 schedule outputs
      *   Schedule.map((count) => Effect.succeed(`Sample #${count + 1}`))
      * )
      *
@@ -4733,6 +4980,8 @@ export declare const take: {
      * })
      * ```
      *
+     * @see {@link recurs} for creating a count-limited schedule
+     *
      * @category utils
      * @since 4.0.0
      */
@@ -4742,6 +4991,18 @@ export declare const take: {
      * from the schedule. Once the specified number of outputs is reached, the
      * schedule will stop.
      *
+     * **When to use**
+     *
+     * Use to limit an existing schedule while preserving its output and
+     * delay behavior. Use `recurs` when you only need an immediate counter
+     * schedule.
+     *
+     * **Gotchas**
+     *
+     * `take(n)` limits schedule outputs. When used with repeat or retry, the
+     * effect is evaluated once before the schedule is stepped, so the total number
+     * of evaluations can be one greater than the number of outputs taken.
+     *
      * **Example** (Taking a limited number of recurrences)
      *
      * ```ts
@@ -4749,9 +5010,9 @@ export declare const take: {
      *
      * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
      *
-     * // Limit an infinite schedule to run only 5 times
+     * // Limit an infinite schedule to five recurrences
      * const limitedHeartbeat = Schedule.spaced("1 second").pipe(
-     *   Schedule.take(5) // Will stop after 5 executions
+     *   Schedule.take(5) // Will stop after 5 schedule outputs
      * )
      *
      * const heartbeatProgram = Effect.gen(function*() {
@@ -4797,7 +5058,7 @@ export declare const take: {
      *
      * // Combine take with other schedule operations
      * const samplingSchedule = Schedule.fixed("500 millis").pipe(
-     *   Schedule.take(10), // Sample exactly 10 times
+     *   Schedule.take(10), // Take at most 10 schedule outputs
      *   Schedule.map((count) => Effect.succeed(`Sample #${count + 1}`))
      * )
      *
@@ -4815,6 +5076,8 @@ export declare const take: {
      * })
      * ```
      *
+     * @see {@link recurs} for creating a count-limited schedule
+     *
      * @category utils
      * @since 4.0.0
      */
@@ -4923,20 +5186,28 @@ declare const while_: {
 };
 export { 
 /**
- * Returns a new schedule that passes each input and output of the specified
- * schedule to the provided `predicate`.
+ * Returns a new schedule that continues while the predicate returns `true`.
+ *
+ * **When to use**
+ *
+ * Use to stop an existing schedule based on its full metadata, such as the
+ * current input, output, attempt, delay, or elapsed time.
  *
  * **Details**
  *
- * If the `predicate` returns `true`, the schedule will continue, otherwise
- * the schedule will stop.
+ * The predicate receives `Metadata`, may return `boolean` or an
+ * `Effect<boolean, ...>`, preserves the output and delay when it returns
+ * `true`, and stops the schedule when it returns `false`.
+ *
+ * @see {@link collectWhile} for collecting outputs while using the same predicate
+ * @see {@link take} for stopping after a fixed number of schedule outputs
  *
  * @category utils
  * @since 4.0.0
  */
 while_ as while };
 /**
- * A schedule that divides the timeline to `interval`-long windows, and sleeps
+ * Schedule that divides the timeline to `interval`-long windows, and sleeps
  * until the nearest window boundary every time it recurs.
  *
  * **Details**
@@ -5009,75 +5280,123 @@ export {
 /**
  * Creates a schedule that always recurs, passing inputs directly as outputs.
  *
+ * **When to use**
+ *
+ * Use when you need an infinite schedule that preserves input values as
+ * outputs.
+ *
  * **Details**
  *
  * This schedule runs indefinitely, returning each input value as its output
  * without modification. It effectively acts as a pass-through that simply
  * echoes its input values at each step.
  *
+ * @see {@link forever} for an infinite schedule that returns incrementing step counts
  * @category constructors
  * @since 2.0.0
  */
 identity_ as identity };
 /**
- * Ensures that the provided schedule respects a specified input type.
+ * Ensures that a schedule's input type extends a given type `T`.
+ *
+ * **When to use**
+ *
+ * Use to check an existing schedule input type. Use
+ * `setInputType` to adapt a schedule that does not depend on its input values.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule input types)
  *
  * ```ts
  * import { Schedule } from "effect"
  *
- * // Ensure schedule accepts string inputs
- * const stringSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesInputType<string>()
- * )
+ * declare const StringInputSchedule: Schedule.Schedule<number, string>
+ * declare const NumberInputSchedule: Schedule.Schedule<number, number>
  *
- * // Ensure schedule accepts number inputs
- * const numberSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesInputType<number>()
- * )
+ * const satisfiesStringInput = Schedule.satisfiesInputType<string>()
+ *
+ * // This works because the schedule input type is string.
+ * const validSchedule = satisfiesStringInput(StringInputSchedule)
  *
- * // Type-level constraint - this would be a compile error:
- * // Schedule.recurs(3).pipe(Schedule.satisfiesInputType<CustomType>())
- * // where CustomType doesn't match the schedule's input type
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesStringInput(NumberInputSchedule)
  * ```
  *
- * @category ensuring types
+ * @see {@link setInputType} for adapting an input-agnostic schedule
+ *
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesInputType: <T>() => <Input extends T, Output = never, Error = never, Env = never>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;
 /**
- * Sets the input type of the provided schedule to a specified type, without
- * altering the schedule's behavior.
+ * Sets the input type of the provided schedule without altering its behavior.
+ *
+ * **When to use**
+ *
+ * Use to adapt a schedule that does not depend on its input
+ * values. Use `satisfiesInputType` to check an existing schedule input type.
  *
- * @category ensuring types
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
+ *
+ * **Example** (Setting a schedule input type)
+ *
+ * ```ts
+ * import { Schedule } from "effect"
+ *
+ * const schedule = Schedule.recurs(3).pipe(
+ *   Schedule.setInputType<string>()
+ * )
+ * ```
+ *
+ * @see {@link satisfiesInputType} for checking an existing input type
+ *
+ * @category utility types
  * @since 4.0.0
  */
 export declare const setInputType: <T>() => <Output, Error, Env>(self: Schedule<Output, T, Error, Env>) => Schedule<Output, T, Error, Env>;
 /**
- * Ensures that the provided schedule respects a specified output type.
+ * Ensures that a schedule's output type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule output types)
  *
  * ```ts
- * import { Effect, Schedule } from "effect"
+ * import { Schedule } from "effect"
  *
- * // satisfiesOutputType is a type-level function for compile-time constraints
- * // It ensures that a schedule's output type matches the specified type
+ * declare const StringOutputSchedule: Schedule.Schedule<string>
+ * declare const NumberOutputSchedule: Schedule.Schedule<number>
  *
- * // Example with string output
- * const stringSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.map(() => Effect.succeed("hello")),
- *   Schedule.satisfiesOutputType<string>()
- * )
+ * const satisfiesStringOutput = Schedule.satisfiesOutputType<string>()
+ *
+ * // This works because the schedule output type is string.
+ * const validSchedule = satisfiesStringOutput(StringOutputSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesStringOutput(NumberOutputSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesOutputType: <T>() => <Output extends T, Error = never, Input = unknown, Env = never>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;
 /**
- * Ensures that the provided schedule respects a specified error type.
+ * Ensures that a schedule's error type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule error types)
  *
@@ -5089,50 +5408,52 @@ export declare const satisfiesOutputType: <T>() => <Output extends T, Error = ne
  *   message: string
  * }> {}
  *
- * // Ensure schedule handles CustomError types
- * const errorSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesErrorType<CustomError>()
- * )
+ * declare const CustomErrorSchedule: Schedule.Schedule<number, unknown, CustomError>
+ * declare const StringErrorSchedule: Schedule.Schedule<number, unknown, string>
  *
- * // Ensure schedule handles never errors (no errors)
- * const safeSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesErrorType<never>()
- * )
+ * const satisfiesCustomError = Schedule.satisfiesErrorType<CustomError>()
+ *
+ * // This works because the schedule error type is CustomError.
+ * const validSchedule = satisfiesCustomError(CustomErrorSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesCustomError(StringErrorSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesErrorType: <T>() => <Error extends T, Output = never, Input = unknown, Env = never>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;
 /**
- * Ensures that the provided schedule respects a specified context type.
+ * Ensures that a schedule's context type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule service types)
  *
  * ```ts
- * import { Effect, Schedule } from "effect"
+ * import { Schedule } from "effect"
  *
- * // Define service interfaces (type-level only)
  * interface Logger {
  *   readonly log: (message: string) => void
  * }
  *
- * interface Database {
- *   readonly query: (sql: string) => Effect.Effect<ReadonlyArray<unknown>>
- * }
+ * declare const LoggerSchedule: Schedule.Schedule<number, unknown, never, Logger>
+ * declare const NumberSchedule: Schedule.Schedule<number, unknown, never, number>
  *
- * // Ensure schedule requires Logger service
- * const loggerSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesServicesType<Logger>()
- * )
+ * const satisfiesLogger = Schedule.satisfiesServicesType<Logger>()
  *
- * // Ensure schedule requires both Logger and Database services
- * const multiServiceSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesServicesType<Logger | Database>()
- * )
+ * // This works because the schedule context type is Logger.
+ * const validSchedule = satisfiesLogger(LoggerSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesLogger(NumberSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export declare const satisfiesServicesType: <T>() => <Env extends T, Output = never, Input = unknown, Error = never>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;