effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Schedule.d.ts

@@ -12,9 +12,14 @@ declare const TypeId = "~effect/Schedule";
 /**
  * A Schedule defines a strategy for repeating or retrying effects based on some policy.
  *
- * @example
+ * **Example** (Defining retry and repeat schedules)
+ *
  * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * import { Console, Data, Effect, Schedule } from "effect"
+ *
+ * class NetworkError extends Data.TaggedError("NetworkError")<{
+ *   readonly attempt: number
+ * }> {}
  *
  * // Basic retry schedule - retry up to 3 times with exponential backoff
  * const retrySchedule = Schedule.exponential("100 millis").pipe(
@@ -25,32 +30,37 @@ declare const TypeId = "~effect/Schedule";
  * const repeatSchedule: Schedule.Schedule<number, unknown, never> = Schedule
  *   .spaced("30 seconds")
  *
- * // Advanced schedule with custom logic
- * const smartRetry = Schedule.exponential("1 second")
- *
  * const program = Effect.gen(function*() {
- *   // Using retry schedule
+ *   let attempts = 0
+ *
  *   const result1 = yield* Effect.retry(
- *     Effect.suspend(() => Math.random() > 0.5 ? Effect.fail("temporary error") : Effect.succeed("Success")),
+ *     Effect.gen(function*() {
+ *       attempts++
+ *       if (attempts < 3) {
+ *         return yield* Effect.fail(new NetworkError({ attempt: attempts }))
+ *       }
+ *       return "Success"
+ *     }),
  *     retrySchedule
  *   )
+ *   console.log(result1) // "Success"
  *
- *   // Using repeat schedule
  *   yield* Console.log("heartbeat").pipe(
  *     Effect.repeat(repeatSchedule.pipe(Schedule.take(5)))
  *   )
  * })
  * ```
  *
+ * @category models
  * @since 2.0.0
- * @category Models
  */
 export interface Schedule<out Output, in Input = unknown, out Error = never, out Env = never> extends Schedule.Variance<Output, Input, Error, Env>, Pipeable {
 }
 /**
  * Metadata provided to schedule functions containing timing and input information.
  *
- * @example
+ * **Example** (Reading schedule input metadata)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -69,8 +79,8 @@ export interface Schedule<out Output, in Input = unknown, out Error = never, out
  * })
  * ```
  *
- * @since 4.0.0
  * @category Metadata
+ * @since 4.0.0
  */
 export interface InputMetadata<Input> {
     readonly input: Input;
@@ -83,18 +93,19 @@ export interface InputMetadata<Input> {
 /**
  * Extended metadata that includes both input metadata and the output value from the schedule.
  *
- * @example
+ * **Example** (Logging schedule output metadata)
+ *
  * ```ts
  * import { Console, Duration, Effect, Schedule } from "effect"
  *
- * // Custom schedule that logs metadata including output
+ * // Custom schedule that logs metadata and output for each recurrence
  * const loggingSchedule = Schedule.unfold(0, (n) => Effect.succeed(n + 1)).pipe(
  *   Schedule.addDelay(() => Effect.succeed(Duration.millis(100))),
- *   Schedule.tapOutput((output) => {
- *     return Console.log(
- *       `Output: ${output}`
- *     )
- *   })
+ *   Schedule.collectWhile((metadata) =>
+ *     Console.log(
+ *       `Output: ${metadata.output}, attempt: ${metadata.attempt}, elapsed: ${metadata.elapsed}ms`
+ *     ).pipe(Effect.as(metadata.attempt <= 3))
+ *   )
  * )
  *
  * const program = Effect.gen(function*() {
@@ -105,27 +116,36 @@ export interface InputMetadata<Input> {
  * })
  *
  * // Output logs will show:
- * // "Output: 0, Attempt: 1, Elapsed: 0ms, Since previous: 0ms"
- * // "Output: 1, Attempt: 2, Elapsed: 100ms, Since previous: 100ms"
- * // "Output: 2, Attempt: 3, Elapsed: 200ms, Since previous: 100ms"
+ * // Output: 0, attempt: 1, elapsed: 0ms
+ * // Output: 1, attempt: 2, elapsed: 100ms
+ * // Output: 2, attempt: 3, elapsed: 200ms
  * ```
  *
- * @since 4.0.0
  * @category Metadata
+ * @since 4.0.0
  */
 export interface Metadata<Output = unknown, Input = unknown> extends InputMetadata<Input> {
     readonly output: Output;
     readonly duration: Duration.Duration;
 }
 /**
- * @since 4.0.0
+ * Context reference containing metadata for the currently running schedule step.
+ *
+ * **Details**
+ * Repeat, retry, stream, and channel scheduling operations provide this service
+ * to effects run between schedule steps. The default value contains undefined
+ * input and output values, zero duration, and zeroed timing fields before any
+ * schedule step has produced metadata.
+ *
  * @category Metadata
+ * @since 4.0.0
  */
 export declare const CurrentMetadata: Context.Reference<Metadata<unknown, unknown>>;
 /**
  * The Schedule namespace contains types and utilities for working with schedules.
  *
- * @example
+ * **Example** (Creating custom schedules with the namespace)
+ *
  * ```ts
  * import { Duration, Effect, Schedule } from "effect"
  *
@@ -153,13 +173,13 @@ export declare const CurrentMetadata: Context.Reference<Metadata<unknown, unknow
  * ```
  *
  * @since 2.0.0
- * @category models
  */
 export declare namespace Schedule {
     /**
      * Variance interface that defines the type parameter relationships for Schedule.
      *
-     * @example
+     * **Example** (Understanding schedule variance)
+     *
      * ```ts
      * import { Effect, Schedule } from "effect"
      *
@@ -183,43 +203,22 @@ export declare namespace Schedule {
      * const serviceSchedule = Schedule.spaced("5 seconds")
      * ```
      *
+     * @category models
      * @since 2.0.0
-     * @category Models
      */
     interface Variance<out Output, in Input, out Error, out Env> {
         readonly [TypeId]: VarianceStruct<Output, Input, Error, Env>;
     }
     /**
-     * Internal structure that holds the variance annotations for Schedule type parameters.
-     *
-     * @example
-     * ```ts
-     * import { Effect, Schedule } from "effect"
+     * Type-level marker used by `Schedule.Variance` to record the variance of
+     * `Schedule` type parameters.
      *
-     * // The variance struct defines how Schedule's type parameters behave
-     * // This internal interface is used for type variance annotations
+     * **Notes**
+     * This interface exists for TypeScript inference and assignability. Users
+     * normally do not construct or inspect it directly.
      *
-     * // Example showing variance relationships:
-     * interface Animal {
-     *   name: string
-     * }
-     * interface Dog extends Animal {
-     *   breed: string
-     * }
-     *
-     * // Output is covariant - more specific types can be substituted
-     * const stringSchedule = Schedule.spaced("1 second").pipe(
-     *   Schedule.map(() => Effect.succeed("output"))
-     * )
-     *
-     * // Input is contravariant - more general types can be accepted
-     * const numberSchedule = Schedule.exponential("100 millis")
-     *
-     * // This enables proper type relationships where schedules can be composed safely
-     * ```
-     *
-     * @since 2.0.0
-     * @category Models
+     * @category models
+     * @since 4.0.0
      */
     interface VarianceStruct<out Output, in Input, out Error, out Env> {
         readonly _Out: Covariant<Output>;
@@ -231,7 +230,8 @@ export declare namespace Schedule {
 /**
  * Type guard that checks if a value is a Schedule.
  *
- * @example
+ * **Example** (Checking for schedules)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -244,64 +244,63 @@ export declare namespace Schedule {
  * console.log(Schedule.isSchedule(undefined)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isSchedule: (u: unknown) => u is Schedule<unknown, never, unknown, unknown>;
 /**
  * Creates a Schedule from a step function that returns a Pull.
  *
- * @example
- * ```ts
- * import { Schedule } from "effect"
+ * **Example** (Creating a custom schedule from a step function)
  *
- * // fromStep is an advanced function for creating custom schedules
- * // It requires a step function that returns a Pull value
+ * ```ts
+ * import { Cause, Duration, Effect, Schedule } from "effect"
  *
- * // Most users should use simpler schedule constructors like:
- * const simpleSchedule = Schedule.exponential("100 millis")
- * const spacedSchedule = Schedule.spaced("1 second")
- * const recurringSchedule = Schedule.recurs(5)
+ * const schedule = Schedule.fromStep(Effect.sync(() => {
+ *   let count = 0
  *
- * // These can be combined and transformed as needed
- * const complexSchedule = simpleSchedule.pipe(
- *   Schedule.both(Schedule.recurs(3))
- * )
+ *   return (_now: number, _input: string) => {
+ *     if (count >= 3) {
+ *       return Cause.done(count)
+ *     }
+ *     return Effect.succeed([count++, Duration.millis(100)] as [number, Duration.Duration])
+ *   }
+ * }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromStep: <Input, Output, EnvX, Error, ErrorX, Env>(step: Effect<(now: number, input: Input) => Pull.Pull<[Output, Duration.Duration], ErrorX, Output, EnvX>, Error, Env>) => Schedule<Output, Input, Error | Pull.ExcludeDone<ErrorX>, Env | EnvX>;
 /**
  * Creates a Schedule from a step function that receives metadata about the schedule's execution.
  *
- * @example
- * ```ts
- * import { Effect, Schedule } from "effect"
+ * **Example** (Creating a metadata-aware schedule)
  *
- * // fromStepWithMetadata is an advanced function for creating schedules
- * // that need access to execution metadata like timing and recurrence count
+ * ```ts
+ * import { Cause, Duration, Effect, Schedule } from "effect"
  *
- * // Most users should use simpler metadata-aware functions like:
- * const metadataSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.collectWhile((metadata) => Effect.succeed(metadata.attempt <= 5))
- * )
+ * const firstThreeInputs = Schedule.fromStepWithMetadata(Effect.succeed((metadata: Schedule.InputMetadata<string>) => {
+ *   if (metadata.attempt > 3) {
+ *     return Cause.done("finished")
+ *   }
  *
- * // Or use existing schedules with metadata transformations:
- * const conditionalSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.tapOutput((output) => Effect.log(`Output: ${output}`))
- * )
+ *   return Effect.succeed([
+ *     `attempt ${metadata.attempt}: ${metadata.input}`,
+ *     Duration.millis(250)
+ *   ] as [string, Duration.Duration])
+ * }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromStepWithMetadata: <Input, Output, EnvX, ErrorX, Error, Env>(step: Effect<(options: InputMetadata<Input>) => Pull.Pull<[Output, Duration.Duration], ErrorX, Output, EnvX>, Error, Env>) => Schedule<Output, Input, Error | Pull.ExcludeDone<ErrorX>, Env | EnvX>;
 /**
  * Extracts the step function from a Schedule.
  *
- * @example
+ * **Example** (Extracting a schedule step function)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -311,30 +310,32 @@ export declare const fromStepWithMetadata: <Input, Output, EnvX, ErrorX, Error,
  * const program = Effect.gen(function*() {
  *   const stepFn = yield* Schedule.toStep(schedule)
  *
- *   // Use the step function directly for custom logic
- *   const now = Date.now()
+ *   // Use the step function directly for custom logic. The timestamp is
+ *   // supplied by the caller, so tests can pass a deterministic value.
+ *   const now = 0
  *   const result = yield* stepFn(now, "input")
  *
  *   console.log(`Step result: ${result}`)
  * })
  * ```
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 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.
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 export declare const toStepWithMetadata: <Output, Input, Error, Env>(schedule: Schedule<Output, Input, Error, Env>) => Effect<(input: Input) => Pull.Pull<Metadata<Output, Input>, Error, Output, Env>, never, Env>;
 /**
  * Extracts a step function from a Schedule that automatically handles sleep delays.
  *
- * @example
+ * **Example** (Extracting a sleeping step function)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -357,37 +358,34 @@ export declare const toStepWithMetadata: <Output, Input, Error, Env>(schedule: S
  * })
  * ```
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 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.
  *
- * @example
+ * **Example** (Adding extra delay to a schedule)
+ *
  * ```ts
  * import { Console, Data, Duration, Effect, Schedule } from "effect"
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Add random jitter to schedule delays
- * const jitteredSchedule = Schedule.addDelay(
+ * // Add a deterministic extra delay based on the schedule output
+ * const delayedSchedule = Schedule.addDelay(
  *   Schedule.exponential("100 millis").pipe(Schedule.take(5)),
  *   (output) =>
- *     // Add random jitter between 0-50ms
- *     Effect.succeed(Duration.millis(Math.random() * 50))
+ *     Effect.succeed(Duration.millis(Duration.toMillis(output) * 0.25))
  * )
  *
- * const jitterProgram = Effect.gen(function*() {
+ * const repeatProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
- *       return "jittered task"
- *     }),
- *     jitteredSchedule.pipe(
+ *     Effect.succeed("delayed task"),
+ *     delayedSchedule.pipe(
  *       Schedule.tapOutput((delay) =>
- *         Console.log(`Base delay with jitter applied`)
+ *         Console.log(`Base delay: ${delay}`)
  *       )
  *     )
  *   )
@@ -415,12 +413,15 @@ export declare const toStepWithSleep: <Output, Input, Error, Env>(schedule: Sche
  *   )
  * })
  *
- * // Add effectful delay computation
+ * // Add effectful delay computation from deterministic service data
+ * const loadByExecution = [1, 3, 2, 4] as const
+ *
  * const dynamicSchedule = Schedule.addDelay(
  *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
- *   (executionNumber) =>
- *     // Simulate checking system load and return additional delay
- *     Effect.succeed(Duration.millis(Math.random() > 0.7 ? 2000 : 500))
+ *   (executionNumber) => {
+ *     const load = loadByExecution[executionNumber] ?? 1
+ *     return Effect.succeed(Duration.millis(load * 100))
+ *   }
  * )
  *
  * const dynamicProgram = Effect.gen(function*() {
@@ -433,25 +434,6 @@ export declare const toStepWithSleep: <Output, Input, Error, Env>(schedule: Sche
  *   )
  * })
  *
- * // Add delay based on previous execution results (30% extra)
- * const resultBasedSchedule = Schedule.addDelay(
- *   Schedule.fibonacci("200 millis").pipe(Schedule.take(5)),
- *   (fibonacciDelay) =>
- *     Effect.succeed(Duration.millis(Duration.toMillis(fibonacciDelay) * 0.3))
- * )
- *
- * const resultProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Result-based delay task")
- *       return Math.random()
- *     }),
- *     resultBasedSchedule.pipe(
- *       Schedule.tapOutput((delay) => Console.log(`Fibonacci delay: ${delay}`))
- *     )
- *   )
- * })
- *
  * // Combine with retry for progressive backoff
  * const progressiveRetrySchedule = Schedule.addDelay(
  *   Schedule.exponential("50 millis").pipe(Schedule.take(4)),
@@ -476,37 +458,34 @@ export declare const toStepWithSleep: <Output, Input, Error, Env>(schedule: Sche
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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.
      *
-     * @example
+     * **Example** (Adding extra delay to a schedule)
+     *
      * ```ts
      * import { Console, Data, Duration, Effect, Schedule } from "effect"
      *
      * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
      *
-     * // Add random jitter to schedule delays
-     * const jitteredSchedule = Schedule.addDelay(
+     * // Add a deterministic extra delay based on the schedule output
+     * const delayedSchedule = Schedule.addDelay(
      *   Schedule.exponential("100 millis").pipe(Schedule.take(5)),
      *   (output) =>
-     *     // Add random jitter between 0-50ms
-     *     Effect.succeed(Duration.millis(Math.random() * 50))
+     *     Effect.succeed(Duration.millis(Duration.toMillis(output) * 0.25))
      * )
      *
-     * const jitterProgram = Effect.gen(function*() {
+     * const repeatProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
-     *       return "jittered task"
-     *     }),
-     *     jitteredSchedule.pipe(
+     *     Effect.succeed("delayed task"),
+     *     delayedSchedule.pipe(
      *       Schedule.tapOutput((delay) =>
-     *         Console.log(`Base delay with jitter applied`)
+     *         Console.log(`Base delay: ${delay}`)
      *       )
      *     )
      *   )
@@ -534,12 +513,15 @@ export declare const addDelay: {
      *   )
      * })
      *
-     * // Add effectful delay computation
+     * // Add effectful delay computation from deterministic service data
+     * const loadByExecution = [1, 3, 2, 4] as const
+     *
      * const dynamicSchedule = Schedule.addDelay(
      *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
-     *   (executionNumber) =>
-     *     // Simulate checking system load and return additional delay
-     *     Effect.succeed(Duration.millis(Math.random() > 0.7 ? 2000 : 500))
+     *   (executionNumber) => {
+     *     const load = loadByExecution[executionNumber] ?? 1
+     *     return Effect.succeed(Duration.millis(load * 100))
+     *   }
      * )
      *
      * const dynamicProgram = Effect.gen(function*() {
@@ -552,25 +534,6 @@ export declare const addDelay: {
      *   )
      * })
      *
-     * // Add delay based on previous execution results (30% extra)
-     * const resultBasedSchedule = Schedule.addDelay(
-     *   Schedule.fibonacci("200 millis").pipe(Schedule.take(5)),
-     *   (fibonacciDelay) =>
-     *     Effect.succeed(Duration.millis(Duration.toMillis(fibonacciDelay) * 0.3))
-     * )
-     *
-     * const resultProgram = Effect.gen(function*() {
-     *   yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       yield* Console.log("Result-based delay task")
-     *       return Math.random()
-     *     }),
-     *     resultBasedSchedule.pipe(
-     *       Schedule.tapOutput((delay) => Console.log(`Fibonacci delay: ${delay}`))
-     *     )
-     *   )
-     * })
-     *
      * // Combine with retry for progressive backoff
      * const progressiveRetrySchedule = Schedule.addDelay(
      *   Schedule.exponential("50 millis").pipe(Schedule.take(4)),
@@ -595,37 +558,34 @@ export declare const addDelay: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <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.
      *
-     * @example
+     * **Example** (Adding extra delay to a schedule)
+     *
      * ```ts
      * import { Console, Data, Duration, Effect, Schedule } from "effect"
      *
      * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
      *
-     * // Add random jitter to schedule delays
-     * const jitteredSchedule = Schedule.addDelay(
+     * // Add a deterministic extra delay based on the schedule output
+     * const delayedSchedule = Schedule.addDelay(
      *   Schedule.exponential("100 millis").pipe(Schedule.take(5)),
      *   (output) =>
-     *     // Add random jitter between 0-50ms
-     *     Effect.succeed(Duration.millis(Math.random() * 50))
+     *     Effect.succeed(Duration.millis(Duration.toMillis(output) * 0.25))
      * )
      *
-     * const jitterProgram = Effect.gen(function*() {
+     * const repeatProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
-     *       return "jittered task"
-     *     }),
-     *     jitteredSchedule.pipe(
+     *     Effect.succeed("delayed task"),
+     *     delayedSchedule.pipe(
      *       Schedule.tapOutput((delay) =>
-     *         Console.log(`Base delay with jitter applied`)
+     *         Console.log(`Base delay: ${delay}`)
      *       )
      *     )
      *   )
@@ -653,12 +613,15 @@ export declare const addDelay: {
      *   )
      * })
      *
-     * // Add effectful delay computation
+     * // Add effectful delay computation from deterministic service data
+     * const loadByExecution = [1, 3, 2, 4] as const
+     *
      * const dynamicSchedule = Schedule.addDelay(
      *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
-     *   (executionNumber) =>
-     *     // Simulate checking system load and return additional delay
-     *     Effect.succeed(Duration.millis(Math.random() > 0.7 ? 2000 : 500))
+     *   (executionNumber) => {
+     *     const load = loadByExecution[executionNumber] ?? 1
+     *     return Effect.succeed(Duration.millis(load * 100))
+     *   }
      * )
      *
      * const dynamicProgram = Effect.gen(function*() {
@@ -671,25 +634,6 @@ export declare const addDelay: {
      *   )
      * })
      *
-     * // Add delay based on previous execution results (30% extra)
-     * const resultBasedSchedule = Schedule.addDelay(
-     *   Schedule.fibonacci("200 millis").pipe(Schedule.take(5)),
-     *   (fibonacciDelay) =>
-     *     Effect.succeed(Duration.millis(Duration.toMillis(fibonacciDelay) * 0.3))
-     * )
-     *
-     * const resultProgram = Effect.gen(function*() {
-     *   yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       yield* Console.log("Result-based delay task")
-     *       return Math.random()
-     *     }),
-     *     resultBasedSchedule.pipe(
-     *       Schedule.tapOutput((delay) => Console.log(`Fibonacci delay: ${delay}`))
-     *     )
-     *   )
-     * })
-     *
      * // Combine with retry for progressive backoff
      * const progressiveRetrySchedule = Schedule.addDelay(
      *   Schedule.exponential("50 millis").pipe(Schedule.take(4)),
@@ -714,8 +658,8 @@ export declare const addDelay: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <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>;
 };
@@ -724,7 +668,8 @@ export declare const addDelay: {
  * schedule to completion. Once the left schedule is complete, the right (i.e.
  * `other`) schedule will be executed to completion.
  *
- * @example
+ * **Example** (Sequencing quick and slow retries)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -756,8 +701,8 @@ export declare const addDelay: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const andThen: {
     /**
@@ -765,7 +710,8 @@ export declare const andThen: {
      * schedule to completion. Once the left schedule is complete, the right (i.e.
      * `other`) schedule will be executed to completion.
      *
-     * @example
+     * **Example** (Sequencing quick and slow retries)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -797,8 +743,8 @@ export declare const andThen: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <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>;
     /**
@@ -806,7 +752,8 @@ export declare const andThen: {
      * schedule to completion. Once the left schedule is complete, the right (i.e.
      * `other`) schedule will be executed to completion.
      *
-     * @example
+     * **Example** (Sequencing quick and slow retries)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -838,8 +785,8 @@ export declare const andThen: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <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>;
 };
@@ -848,11 +795,12 @@ export declare const andThen: {
  * schedule to completion. Once the left schedule is complete, the right (i.e.
  * `other`) schedule will be executed to completion.
  *
- * The output of the resulting schedule is a `Result` where outputs of the
- * left schedule are emitted as `Result.Err<Output>` and outputs of the right
- * schedule are emitted as `Result.Ok<Output>`.
+ * The resulting schedule emits a `Result` to indicate which phase produced
+ * each output: outputs from `self` are emitted as `Failure`, and outputs from
+ * `other` are emitted as `Success`.
+ *
+ * **Example** (Tracking sequential schedule phases)
  *
- * @example
  * ```ts
  * import { Console, Effect, Result, Schedule } from "effect"
  *
@@ -880,8 +828,8 @@ export declare const andThen: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export declare const andThenResult: {
     /**
@@ -889,11 +837,12 @@ export declare const andThenResult: {
      * schedule to completion. Once the left schedule is complete, the right (i.e.
      * `other`) schedule will be executed to completion.
      *
-     * The output of the resulting schedule is a `Result` where outputs of the
-     * left schedule are emitted as `Result.Err<Output>` and outputs of the right
-     * schedule are emitted as `Result.Ok<Output>`.
+     * The resulting schedule emits a `Result` to indicate which phase produced
+     * each output: outputs from `self` are emitted as `Failure`, and outputs from
+     * `other` are emitted as `Success`.
+     *
+     * **Example** (Tracking sequential schedule phases)
      *
-     * @example
      * ```ts
      * import { Console, Effect, Result, Schedule } from "effect"
      *
@@ -921,8 +870,8 @@ export declare const andThenResult: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <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>;
     /**
@@ -930,11 +879,12 @@ export declare const andThenResult: {
      * schedule to completion. Once the left schedule is complete, the right (i.e.
      * `other`) schedule will be executed to completion.
      *
-     * The output of the resulting schedule is a `Result` where outputs of the
-     * left schedule are emitted as `Result.Err<Output>` and outputs of the right
-     * schedule are emitted as `Result.Ok<Output>`.
+     * The resulting schedule emits a `Result` to indicate which phase produced
+     * each output: outputs from `self` are emitted as `Failure`, and outputs from
+     * `other` are emitted as `Success`.
+     *
+     * **Example** (Tracking sequential schedule phases)
      *
-     * @example
      * ```ts
      * import { Console, Effect, Result, Schedule } from "effect"
      *
@@ -962,8 +912,8 @@ export declare const andThenResult: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 4.0.0
      */
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Result.Result<Output2, Output>, Input & Input2, Error | Error2, Env | Env2>;
 };
@@ -972,7 +922,8 @@ 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.
  *
- * @example
+ * **Example** (Combining time and attempt limits)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -989,7 +940,7 @@ export declare const andThenResult: {
  * const program = Effect.gen(function*() {
  *   const results = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+ *       yield* Console.log("Task executed")
  *       return "task completed"
  *     }),
  *     bothSchedule.pipe(
@@ -1033,8 +984,8 @@ export declare const andThenResult: {
  * // Compare with either which provides union semantics (OR logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const both: {
     /**
@@ -1042,7 +993,8 @@ 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.
      *
-     * @example
+     * **Example** (Combining time and attempt limits)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -1059,7 +1011,7 @@ export declare const both: {
      * const program = Effect.gen(function*() {
      *   const results = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+     *       yield* Console.log("Task executed")
      *       return "task completed"
      *     }),
      *     bothSchedule.pipe(
@@ -1103,8 +1055,8 @@ export declare const both: {
      * // Compare with either which provides union semantics (OR logic)
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output2, Input2, Error2, Env2, Output>(other: Schedule<Output2, Input2, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<[Output, Output2], Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -1112,7 +1064,8 @@ 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.
      *
-     * @example
+     * **Example** (Combining time and attempt limits)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -1129,7 +1082,7 @@ export declare const both: {
      * const program = Effect.gen(function*() {
      *   const results = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+     *       yield* Console.log("Task executed")
      *       return "task completed"
      *     }),
      *     bothSchedule.pipe(
@@ -1173,8 +1126,8 @@ export declare const both: {
      * // Compare with either which provides union semantics (OR logic)
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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>;
 };
@@ -1183,7 +1136,8 @@ export declare const both: {
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
- * @example
+ * **Example** (Combining schedules and keeping the left output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1206,8 +1160,8 @@ export declare const both: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const bothLeft: {
     /**
@@ -1215,7 +1169,8 @@ export declare const bothLeft: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting the result of the left schedule (i.e. `self`).
      *
-     * @example
+     * **Example** (Combining schedules and keeping the left output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1238,8 +1193,8 @@ export declare const bothLeft: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -1247,7 +1202,8 @@ export declare const bothLeft: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting the result of the left schedule (i.e. `self`).
      *
-     * @example
+     * **Example** (Combining schedules and keeping the left output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1270,8 +1226,8 @@ export declare const bothLeft: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
 };
@@ -1280,7 +1236,8 @@ export declare const bothLeft: {
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
- * @example
+ * **Example** (Combining schedules and keeping the right output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1305,8 +1262,8 @@ export declare const bothLeft: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const bothRight: {
     /**
@@ -1314,7 +1271,8 @@ export declare const bothRight: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting the result of the right schedule (i.e. `other`).
      *
-     * @example
+     * **Example** (Combining schedules and keeping the right output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1339,8 +1297,8 @@ export declare const bothRight: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -1348,7 +1306,8 @@ export declare const bothRight: {
      * to recur, using the maximum of the two durations between recurrences and
      * outputting the result of the right schedule (i.e. `other`).
      *
-     * @example
+     * **Example** (Combining schedules and keeping the right output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1373,8 +1332,8 @@ export declare const bothRight: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
 };
@@ -1384,7 +1343,8 @@ export declare const bothRight: {
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
- * @example
+ * **Example** (Combining schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1413,8 +1373,8 @@ export declare const bothRight: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const bothWith: {
     /**
@@ -1423,7 +1383,8 @@ export declare const bothWith: {
      * outputting the result of the combination of both schedule outputs using the
      * specified `combine` function.
      *
-     * @example
+     * **Example** (Combining schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1452,8 +1413,8 @@ export declare const bothWith: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output2, Input2, Error2, Env2, Output, Output3>(other: Schedule<Output2, Input2, Error2, Env2>, combine: (selfOutput: Output, otherOutput: Output2) => Output3): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output3, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -1462,7 +1423,8 @@ export declare const bothWith: {
      * outputting the result of the combination of both schedule outputs using the
      * specified `combine` function.
      *
-     * @example
+     * **Example** (Combining schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -1491,16 +1453,21 @@ export declare const bothWith: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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>;
 };
 /**
- * Returns a new `Schedule` that always recurs, collecting all inputs of the
- * schedule into an array.
+ * Returns a new `Schedule` that follows `self` and outputs the inputs seen so
+ * far as an array.
+ *
+ * **Details**
+ * This does not make the schedule run forever. The collected schedule stops
+ * when `self` stops and fails when `self` fails.
+ *
+ * **Example** (Collecting schedule inputs)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1522,15 +1489,20 @@ export declare const bothWith: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const collectInputs: <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Array<Input>, Input, Error, Env>;
 /**
- * Returns a new `Schedule` that always recurs, collecting all outputs of the
- * schedule into an array.
+ * Returns a new `Schedule` that follows `self` and outputs the schedule outputs
+ * seen so far as an array.
+ *
+ * **Details**
+ * This does not make the schedule run forever. The collected schedule stops
+ * when `self` stops and fails when `self` fails.
+ *
+ * **Example** (Collecting schedule outputs)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1550,39 +1522,19 @@ export declare const collectInputs: <Output, Input, Error, Env>(self: Schedule<O
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const collectOutputs: <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Array<Output>, Input, Error, Env>;
 /**
  * Returns a new `Schedule` that recurs as long as the specified `predicate`
  * returns `true`, collecting all outputs of the schedule into an array.
  *
- * @example
+ * **Example** (Collecting outputs while a condition holds)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
- * // Collect outputs while under time limit
- * const collectForTime = Schedule.collectWhile(
- *   Schedule.spaced("500 millis"),
- *   (metadata) => Effect.succeed(metadata.elapsed < 3000) // Stop after 3 seconds
- * )
- *
- * const timeBasedProgram = Effect.gen(function*() {
- *   const results = yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       const value = Math.floor(Math.random() * 100)
- *       yield* Console.log(`Generated value: ${value}`)
- *       return value
- *     }),
- *     collectForTime
- *   )
- *
- *   yield* Console.log(
- *     `Collected ${results.length} values: [${results.join(", ")}]`
- *   )
- * })
- *
  * // Collect outputs while condition is met
  * const collectWhileSmall = Schedule.collectWhile(
  *   Schedule.exponential("100 millis"),
@@ -1593,16 +1545,16 @@ export declare const collectOutputs: <Output, Input, Error, Env>(self: Schedule<
  * const conditionalProgram = Effect.gen(function*() {
  *   let attempt = 0
  *
- *   const delays = yield* Effect.repeat(
+ *   const attempts = yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       attempt++
  *       yield* Console.log(`Retry attempt ${attempt}`)
- *       return `${Date.now()}`
+ *       return `attempt-${attempt}`
  *     }),
  *     collectWhileSmall
  *   )
  *
- *   yield* Console.log(`Collected attempts: [${delays.join(", ")}]`)
+ *   yield* Console.log(`Collected attempts: [${attempts.join(", ")}]`)
  * })
  *
  * // Collect with effectful predicate
@@ -1619,19 +1571,17 @@ export declare const collectOutputs: <Output, Input, Error, Env>(self: Schedule<
  * )
  *
  * const effectfulProgram = Effect.gen(function*() {
- *   const timestamps = yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       const now = new Date().toISOString()
- *       yield* Console.log(`Task at ${now}`)
- *       return now
- *     }),
+ *   const results = yield* Effect.repeat(
+ *     Effect.succeed("checked"),
  *     collectWithCheck
  *   )
  *
- *   yield* Console.log(`Final collection: ${timestamps.length} items`)
+ *   yield* Console.log(`Final collection: ${results.length} items`)
  * })
  *
  * // Collect samples with condition
+ * const samples = [12, 18, 24, 30, 36]
+ *
  * const collectSamples = Schedule.collectWhile(
  *   Schedule.spaced("200 millis"),
  *   (metadata) =>
@@ -1639,55 +1589,36 @@ export declare const collectOutputs: <Output, Input, Error, Env>(self: Schedule<
  * )
  *
  * const samplingProgram = Effect.gen(function*() {
- *   const samples = yield* Effect.repeat(
+ *   let index = 0
+ *   const collected = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const sample = Math.random() * 100
- *       yield* Console.log(`Sample: ${sample.toFixed(1)}`)
+ *       const sample = samples[index++]
+ *       yield* Console.log(`Sample: ${sample}`)
  *       return sample
  *     }),
  *     collectSamples
  *   )
  *
- *   const average = samples.reduce((sum, s) => sum + s, 0) / samples.length
+ *   const average = collected.reduce((sum, s) => sum + s, 0) / collected.length
  *   yield* Console.log(
- *     `Collected ${samples.length} samples, average: ${average.toFixed(1)}`
+ *     `Collected ${collected.length} samples, average: ${average.toFixed(1)}`
  *   )
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const collectWhile: {
     /**
      * Returns a new `Schedule` that recurs as long as the specified `predicate`
      * returns `true`, collecting all outputs of the schedule into an array.
      *
-     * @example
+     * **Example** (Collecting outputs while a condition holds)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
-     * // Collect outputs while under time limit
-     * const collectForTime = Schedule.collectWhile(
-     *   Schedule.spaced("500 millis"),
-     *   (metadata) => Effect.succeed(metadata.elapsed < 3000) // Stop after 3 seconds
-     * )
-     *
-     * const timeBasedProgram = Effect.gen(function*() {
-     *   const results = yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       const value = Math.floor(Math.random() * 100)
-     *       yield* Console.log(`Generated value: ${value}`)
-     *       return value
-     *     }),
-     *     collectForTime
-     *   )
-     *
-     *   yield* Console.log(
-     *     `Collected ${results.length} values: [${results.join(", ")}]`
-     *   )
-     * })
-     *
      * // Collect outputs while condition is met
      * const collectWhileSmall = Schedule.collectWhile(
      *   Schedule.exponential("100 millis"),
@@ -1698,16 +1629,16 @@ export declare const collectWhile: {
      * const conditionalProgram = Effect.gen(function*() {
      *   let attempt = 0
      *
-     *   const delays = yield* Effect.repeat(
+     *   const attempts = yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       attempt++
      *       yield* Console.log(`Retry attempt ${attempt}`)
-     *       return `${Date.now()}`
+     *       return `attempt-${attempt}`
      *     }),
      *     collectWhileSmall
      *   )
      *
-     *   yield* Console.log(`Collected attempts: [${delays.join(", ")}]`)
+     *   yield* Console.log(`Collected attempts: [${attempts.join(", ")}]`)
      * })
      *
      * // Collect with effectful predicate
@@ -1724,19 +1655,17 @@ export declare const collectWhile: {
      * )
      *
      * const effectfulProgram = Effect.gen(function*() {
-     *   const timestamps = yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       const now = new Date().toISOString()
-     *       yield* Console.log(`Task at ${now}`)
-     *       return now
-     *     }),
+     *   const results = yield* Effect.repeat(
+     *     Effect.succeed("checked"),
      *     collectWithCheck
      *   )
      *
-     *   yield* Console.log(`Final collection: ${timestamps.length} items`)
+     *   yield* Console.log(`Final collection: ${results.length} items`)
      * })
      *
      * // Collect samples with condition
+     * const samples = [12, 18, 24, 30, 36]
+     *
      * const collectSamples = Schedule.collectWhile(
      *   Schedule.spaced("200 millis"),
      *   (metadata) =>
@@ -1744,55 +1673,36 @@ export declare const collectWhile: {
      * )
      *
      * const samplingProgram = Effect.gen(function*() {
-     *   const samples = yield* Effect.repeat(
+     *   let index = 0
+     *   const collected = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       const sample = Math.random() * 100
-     *       yield* Console.log(`Sample: ${sample.toFixed(1)}`)
+     *       const sample = samples[index++]
+     *       yield* Console.log(`Sample: ${sample}`)
      *       return sample
      *     }),
      *     collectSamples
      *   )
      *
-     *   const average = samples.reduce((sum, s) => sum + s, 0) / samples.length
+     *   const average = collected.reduce((sum, s) => sum + s, 0) / collected.length
      *   yield* Console.log(
-     *     `Collected ${samples.length} samples, average: ${average.toFixed(1)}`
+     *     `Collected ${collected.length} samples, average: ${average.toFixed(1)}`
      *   )
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Input, Output, Error2 = never, Env2 = never>(predicate: (metadata: Metadata<Output, Input>) => boolean | Effect<boolean, Error2, Env2>): <Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Array<Output>, Input, Error | Error2, Env | Env2>;
     /**
      * Returns a new `Schedule` that recurs as long as the specified `predicate`
      * returns `true`, collecting all outputs of the schedule into an array.
      *
-     * @example
+     * **Example** (Collecting outputs while a condition holds)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
-     * // Collect outputs while under time limit
-     * const collectForTime = Schedule.collectWhile(
-     *   Schedule.spaced("500 millis"),
-     *   (metadata) => Effect.succeed(metadata.elapsed < 3000) // Stop after 3 seconds
-     * )
-     *
-     * const timeBasedProgram = Effect.gen(function*() {
-     *   const results = yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       const value = Math.floor(Math.random() * 100)
-     *       yield* Console.log(`Generated value: ${value}`)
-     *       return value
-     *     }),
-     *     collectForTime
-     *   )
-     *
-     *   yield* Console.log(
-     *     `Collected ${results.length} values: [${results.join(", ")}]`
-     *   )
-     * })
-     *
      * // Collect outputs while condition is met
      * const collectWhileSmall = Schedule.collectWhile(
      *   Schedule.exponential("100 millis"),
@@ -1803,16 +1713,16 @@ export declare const collectWhile: {
      * const conditionalProgram = Effect.gen(function*() {
      *   let attempt = 0
      *
-     *   const delays = yield* Effect.repeat(
+     *   const attempts = yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       attempt++
      *       yield* Console.log(`Retry attempt ${attempt}`)
-     *       return `${Date.now()}`
+     *       return `attempt-${attempt}`
      *     }),
      *     collectWhileSmall
      *   )
      *
-     *   yield* Console.log(`Collected attempts: [${delays.join(", ")}]`)
+     *   yield* Console.log(`Collected attempts: [${attempts.join(", ")}]`)
      * })
      *
      * // Collect with effectful predicate
@@ -1829,19 +1739,17 @@ export declare const collectWhile: {
      * )
      *
      * const effectfulProgram = Effect.gen(function*() {
-     *   const timestamps = yield* Effect.repeat(
-     *     Effect.gen(function*() {
-     *       const now = new Date().toISOString()
-     *       yield* Console.log(`Task at ${now}`)
-     *       return now
-     *     }),
+     *   const results = yield* Effect.repeat(
+     *     Effect.succeed("checked"),
      *     collectWithCheck
      *   )
      *
-     *   yield* Console.log(`Final collection: ${timestamps.length} items`)
+     *   yield* Console.log(`Final collection: ${results.length} items`)
      * })
      *
      * // Collect samples with condition
+     * const samples = [12, 18, 24, 30, 36]
+     *
      * const collectSamples = Schedule.collectWhile(
      *   Schedule.spaced("200 millis"),
      *   (metadata) =>
@@ -1849,24 +1757,25 @@ export declare const collectWhile: {
      * )
      *
      * const samplingProgram = Effect.gen(function*() {
-     *   const samples = yield* Effect.repeat(
+     *   let index = 0
+     *   const collected = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       const sample = Math.random() * 100
-     *       yield* Console.log(`Sample: ${sample.toFixed(1)}`)
+     *       const sample = samples[index++]
+     *       yield* Console.log(`Sample: ${sample}`)
      *       return sample
      *     }),
      *     collectSamples
      *   )
      *
-     *   const average = samples.reduce((sum, s) => sum + s, 0) / samples.length
+     *   const average = collected.reduce((sum, s) => sum + s, 0) / collected.length
      *   yield* Console.log(
-     *     `Collected ${samples.length} samples, average: ${average.toFixed(1)}`
+     *     `Collected ${collected.length} samples, average: ${average.toFixed(1)}`
      *   )
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output, Input, Error, Env, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, predicate: (metadata: Metadata<Output, Input>) => boolean | Effect<boolean, Error2, Env2>): Schedule<Array<Output>, Input, Error | Error2, Env | Env2>;
 };
@@ -1874,7 +1783,8 @@ export declare const collectWhile: {
  * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
  * outputs the duration between recurrences.
  *
- * @example
+ * **Example** (Scheduling work with cron expressions)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1886,7 +1796,7 @@ export declare const collectWhile: {
  * const minutelyProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Minutely task at ${new Date().toISOString()}`)
+ *       yield* Console.log("Running minutely task")
  *       return "minute"
  *     }),
  *     everyMinute.pipe(
@@ -1924,8 +1834,8 @@ export declare const collectWhile: {
  *     Effect.gen(function*() {
  *       yield* Console.log("Generating weekly report...")
  *       const report = {
- *         week: Math.floor(Date.now() / (7 * 24 * 60 * 60 * 1000)),
- *         timestamp: new Date().toISOString()
+ *         week: 42,
+ *         status: "ready" as const
  *       }
  *       yield* Console.log(`Report generated: ${JSON.stringify(report)}`)
  *       return report
@@ -1938,10 +1848,13 @@ export declare const collectWhile: {
  * const businessHoursCheck = Schedule.cron("0,15,30,45 9-17 * * 1-5")
  *
  * const businessProgram = Effect.gen(function*() {
+ *   const statuses = ["healthy", "healthy", "degraded", "healthy"] as const
+ *   let index = 0
+ *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Business hours health check...")
- *       const status = Math.random() > 0.1 ? "healthy" : "degraded"
+ *       const status = statuses[index++]
  *       yield* Console.log(`System status: ${status}`)
  *       return status
  *     }),
@@ -1958,9 +1871,9 @@ export declare const collectWhile: {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Processing monthly invoices...")
- *       const invoiceCount = Math.floor(Math.random() * 100) + 50
+ *       const invoiceCount = 72
  *       yield* Console.log(`Processed ${invoiceCount} invoices`)
- *       return { count: invoiceCount, date: new Date().toISOString() }
+ *       return { count: invoiceCount, batch: "2024-01-a" }
  *     }),
  *     monthlyInvoice.pipe(Schedule.take(1))
  *   )
@@ -1974,11 +1887,13 @@ export declare const collectWhile: {
  * )
  *
  * const robustProgram = Effect.gen(function*() {
+ *   let attempt = 0
+ *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
+ *       attempt++
  *       yield* Console.log("Complex scheduled task...")
- *       // Simulate occasional failures
- *       if (Math.random() < 0.3) {
+ *       if (attempt === 1) {
  *         return yield* Effect.fail(new ScheduledTaskError({ message: "Scheduled task failed" }))
  *       }
  *       return "success"
@@ -1992,15 +1907,16 @@ export declare const collectWhile: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const cron: {
     /**
      * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
      * outputs the duration between recurrences.
      *
-     * @example
+     * **Example** (Scheduling work with cron expressions)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -2012,7 +1928,7 @@ export declare const cron: {
      * const minutelyProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Minutely task at ${new Date().toISOString()}`)
+     *       yield* Console.log("Running minutely task")
      *       return "minute"
      *     }),
      *     everyMinute.pipe(
@@ -2050,8 +1966,8 @@ export declare const cron: {
      *     Effect.gen(function*() {
      *       yield* Console.log("Generating weekly report...")
      *       const report = {
-     *         week: Math.floor(Date.now() / (7 * 24 * 60 * 60 * 1000)),
-     *         timestamp: new Date().toISOString()
+     *         week: 42,
+     *         status: "ready" as const
      *       }
      *       yield* Console.log(`Report generated: ${JSON.stringify(report)}`)
      *       return report
@@ -2064,10 +1980,13 @@ export declare const cron: {
      * const businessHoursCheck = Schedule.cron("0,15,30,45 9-17 * * 1-5")
      *
      * const businessProgram = Effect.gen(function*() {
+     *   const statuses = ["healthy", "healthy", "degraded", "healthy"] as const
+     *   let index = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Business hours health check...")
-     *       const status = Math.random() > 0.1 ? "healthy" : "degraded"
+     *       const status = statuses[index++]
      *       yield* Console.log(`System status: ${status}`)
      *       return status
      *     }),
@@ -2084,9 +2003,9 @@ export declare const cron: {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Processing monthly invoices...")
-     *       const invoiceCount = Math.floor(Math.random() * 100) + 50
+     *       const invoiceCount = 72
      *       yield* Console.log(`Processed ${invoiceCount} invoices`)
-     *       return { count: invoiceCount, date: new Date().toISOString() }
+     *       return { count: invoiceCount, batch: "2024-01-a" }
      *     }),
      *     monthlyInvoice.pipe(Schedule.take(1))
      *   )
@@ -2100,11 +2019,13 @@ export declare const cron: {
      * )
      *
      * const robustProgram = Effect.gen(function*() {
+     *   let attempt = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
+     *       attempt++
      *       yield* Console.log("Complex scheduled task...")
-     *       // Simulate occasional failures
-     *       if (Math.random() < 0.3) {
+     *       if (attempt === 1) {
      *         return yield* Effect.fail(new ScheduledTaskError({ message: "Scheduled task failed" }))
      *       }
      *       return "success"
@@ -2118,15 +2039,16 @@ export declare const cron: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 2.0.0
      */
     (expression: Cron.Cron): Schedule<Duration.Duration, unknown, Cron.CronParseError>;
     /**
      * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
      * outputs the duration between recurrences.
      *
-     * @example
+     * **Example** (Scheduling work with cron expressions)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -2138,7 +2060,7 @@ export declare const cron: {
      * const minutelyProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Minutely task at ${new Date().toISOString()}`)
+     *       yield* Console.log("Running minutely task")
      *       return "minute"
      *     }),
      *     everyMinute.pipe(
@@ -2176,8 +2098,8 @@ export declare const cron: {
      *     Effect.gen(function*() {
      *       yield* Console.log("Generating weekly report...")
      *       const report = {
-     *         week: Math.floor(Date.now() / (7 * 24 * 60 * 60 * 1000)),
-     *         timestamp: new Date().toISOString()
+     *         week: 42,
+     *         status: "ready" as const
      *       }
      *       yield* Console.log(`Report generated: ${JSON.stringify(report)}`)
      *       return report
@@ -2190,10 +2112,13 @@ export declare const cron: {
      * const businessHoursCheck = Schedule.cron("0,15,30,45 9-17 * * 1-5")
      *
      * const businessProgram = Effect.gen(function*() {
+     *   const statuses = ["healthy", "healthy", "degraded", "healthy"] as const
+     *   let index = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Business hours health check...")
-     *       const status = Math.random() > 0.1 ? "healthy" : "degraded"
+     *       const status = statuses[index++]
      *       yield* Console.log(`System status: ${status}`)
      *       return status
      *     }),
@@ -2210,9 +2135,9 @@ export declare const cron: {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Processing monthly invoices...")
-     *       const invoiceCount = Math.floor(Math.random() * 100) + 50
+     *       const invoiceCount = 72
      *       yield* Console.log(`Processed ${invoiceCount} invoices`)
-     *       return { count: invoiceCount, date: new Date().toISOString() }
+     *       return { count: invoiceCount, batch: "2024-01-a" }
      *     }),
      *     monthlyInvoice.pipe(Schedule.take(1))
      *   )
@@ -2226,11 +2151,13 @@ export declare const cron: {
      * )
      *
      * const robustProgram = Effect.gen(function*() {
+     *   let attempt = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
+     *       attempt++
      *       yield* Console.log("Complex scheduled task...")
-     *       // Simulate occasional failures
-     *       if (Math.random() < 0.3) {
+     *       if (attempt === 1) {
      *         return yield* Effect.fail(new ScheduledTaskError({ message: "Scheduled task failed" }))
      *       }
      *       return "success"
@@ -2244,15 +2171,16 @@ export declare const cron: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 2.0.0
      */
     (expression: string, tz?: string | DateTime.TimeZone): Schedule<Duration.Duration, unknown, Cron.CronParseError>;
 };
 /**
  * Returns a new schedule that outputs the delay between each occurence.
  *
- * @example
+ * **Example** (Extracting schedule delays)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2312,7 +2240,7 @@ export declare const cron: {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Adaptive task execution")
- *       return Date.now()
+ *       return "completed"
  *     }),
  *     adaptiveDelays.pipe(
  *       Schedule.tapOutput((delay) => Console.log(`Adaptive delay: ${delay}`))
@@ -2329,8 +2257,8 @@ export declare const cron: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const delays: <Out, In, E, R>(self: Schedule<Out, In, E, R>) => Schedule<Duration.Duration, In, E, R>;
 /**
@@ -2339,15 +2267,16 @@ export declare const delays: <Out, In, E, R>(self: Schedule<Out, In, E, R>) => S
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const duration: (durationInput: Duration.Input) => Schedule<Duration.Duration>;
 /**
  * Returns a new `Schedule` that will always recur, but only during the
  * specified `duration` of time.
  *
- * @example
+ * **Example** (Repeating work during a duration)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2357,12 +2286,9 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  * const fiveSecondSchedule = Schedule.during("5 seconds")
  *
  * const timedProgram = Effect.gen(function*() {
- *   const startTime = Date.now()
- *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const elapsed = Date.now() - startTime
- *       yield* Console.log(`Task executed after ${elapsed}ms`)
+ *       yield* Console.log("Task executed inside the time window")
  *       yield* Effect.sleep("500 millis") // Each task takes 500ms
  *       return "task done"
  *     }),
@@ -2390,8 +2316,8 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Burst task at ${new Date().toISOString()}`)
- *       return Math.random()
+ *       yield* Console.log("Burst task")
+ *       return "burst"
  *     }),
  *     burstWindow
  *   )
@@ -2412,7 +2338,7 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  *       attempt++
  *       yield* Console.log(`Retry attempt ${attempt}`)
  *
- *       if (Math.random() < 0.8) { // 80% failure rate
+ *       if (attempt < 4) {
  *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
  *       }
  *
@@ -2427,8 +2353,8 @@ export declare const duration: (durationInput: Duration.Input) => Schedule<Durat
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const during: (duration: Duration.Input) => Schedule<Duration.Duration>;
 /**
@@ -2436,7 +2362,8 @@ 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.
  *
- * @example
+ * **Example** (Combining schedules with either semantics)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2453,7 +2380,7 @@ export declare const during: (duration: Duration.Input) => Schedule<Duration.Dur
  * const program = Effect.gen(function*() {
  *   const results = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+ *       yield* Console.log("Task executed")
  *       return "task completed"
  *     }),
  *     eitherSchedule.pipe(
@@ -2499,8 +2426,8 @@ export declare const during: (duration: Duration.Input) => Schedule<Duration.Dur
  * // Compare with intersect which provides intersection semantics (AND logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const either: {
     /**
@@ -2508,7 +2435,8 @@ 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.
      *
-     * @example
+     * **Example** (Combining schedules with either semantics)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -2525,7 +2453,7 @@ export declare const either: {
      * const program = Effect.gen(function*() {
      *   const results = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+     *       yield* Console.log("Task executed")
      *       return "task completed"
      *     }),
      *     eitherSchedule.pipe(
@@ -2571,8 +2499,8 @@ export declare const either: {
      * // Compare with intersect which provides intersection semantics (AND logic)
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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>;
     /**
@@ -2580,7 +2508,8 @@ 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.
      *
-     * @example
+     * **Example** (Combining schedules with either semantics)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -2597,7 +2526,7 @@ export declare const either: {
      * const program = Effect.gen(function*() {
      *   const results = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+     *       yield* Console.log("Task executed")
      *       return "task completed"
      *     }),
      *     eitherSchedule.pipe(
@@ -2643,8 +2572,8 @@ export declare const either: {
      * // Compare with intersect which provides intersection semantics (AND logic)
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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>;
 };
@@ -2653,7 +2582,8 @@ export declare const either: {
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
- * @example
+ * **Example** (Combining either schedules and keeping the left output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2679,8 +2609,8 @@ export declare const either: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const eitherLeft: {
     /**
@@ -2688,7 +2618,8 @@ export declare const eitherLeft: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting the result of the left schedule (i.e. `self`).
      *
-     * @example
+     * **Example** (Combining either schedules and keeping the left output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2714,8 +2645,8 @@ export declare const eitherLeft: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -2723,7 +2654,8 @@ export declare const eitherLeft: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting the result of the left schedule (i.e. `self`).
      *
-     * @example
+     * **Example** (Combining either schedules and keeping the left output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2749,8 +2681,8 @@ export declare const eitherLeft: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Output, Input & Input2, Error | Error2, Env | Env2>;
 };
@@ -2759,7 +2691,8 @@ export declare const eitherLeft: {
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
- * @example
+ * **Example** (Combining either schedules and keeping the right output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2785,8 +2718,8 @@ export declare const eitherLeft: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const eitherRight: {
     /**
@@ -2794,7 +2727,8 @@ export declare const eitherRight: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting the result of the right schedule (i.e. `other`).
      *
-     * @example
+     * **Example** (Combining either schedules and keeping the right output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2820,8 +2754,8 @@ export declare const eitherRight: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output2, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -2829,7 +2763,8 @@ export declare const eitherRight: {
      * to recur, using the minimum of the two durations between recurrences and
      * outputting the result of the right schedule (i.e. `other`).
      *
-     * @example
+     * **Example** (Combining either schedules and keeping the right output)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2855,8 +2790,8 @@ export declare const eitherRight: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, other: Schedule<Output2, Input2, Error2, Env2>): Schedule<Output2, Input & Input2, Error | Error2, Env | Env2>;
 };
@@ -2866,7 +2801,8 @@ export declare const eitherRight: {
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
- * @example
+ * **Example** (Combining either schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2896,8 +2832,8 @@ export declare const eitherRight: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const eitherWith: {
     /**
@@ -2906,7 +2842,8 @@ export declare const eitherWith: {
      * outputting the result of the combination of both schedule outputs using the
      * specified `combine` function.
      *
-     * @example
+     * **Example** (Combining either schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2936,8 +2873,8 @@ export declare const eitherWith: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output2, Input2, Error2, Env2, Output, Output3>(other: Schedule<Output2, Input2, Error2, Env2>, combine: (selfOutput: Output, otherOutput: Output2) => Output3): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output3, Input & Input2, Error | Error2, Env | Env2>;
     /**
@@ -2946,7 +2883,8 @@ export declare const eitherWith: {
      * outputting the result of the combination of both schedule outputs using the
      * specified `combine` function.
      *
-     * @example
+     * **Example** (Combining either schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -2976,8 +2914,8 @@ export declare const eitherWith: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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>;
 };
@@ -2987,9 +2925,8 @@ export declare const eitherWith: {
  * This schedule never stops and outputs the cumulative time that has passed since the schedule
  * started executing. Useful for tracking execution time or implementing time-based logic.
  *
- * @returns A schedule that outputs the elapsed duration and never stops
+ * **Example** (Measuring elapsed schedule time)
  *
- * @example
  * ```ts
  * import { Console, Duration, Effect, Schedule } from "effect"
  *
@@ -3007,8 +2944,8 @@ export declare const eitherWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const elapsed: Schedule<Duration.Duration>;
 /**
@@ -3016,7 +2953,8 @@ export declare const elapsed: Schedule<Duration.Duration>;
  * repetitions, given by `base * factor.pow(n)`, where `n` is the number of
  * repetitions so far. Returns the current duration between recurrences.
  *
- * @example
+ * **Example** (Retrying with exponential backoff)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -3056,8 +2994,8 @@ export declare const elapsed: Schedule<Duration.Duration>;
  * // Will retry with delays: 50ms, 100ms, 200ms before success
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const exponential: (base: Duration.Input, factor?: number) => Schedule<Duration.Duration>;
 /**
@@ -3065,7 +3003,8 @@ export declare const exponential: (base: Duration.Input, factor?: number) => Sch
  * two delays (similar to the fibonacci sequence). Returns the current
  * duration between recurrences.
  *
- * @example
+ * **Example** (Retrying with fibonacci backoff)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -3101,7 +3040,7 @@ export declare const exponential: (base: Duration.Input, factor?: number) => Sch
  *
  * // Heartbeat with fibonacci intervals (starts fast, gets slower)
  * const adaptiveHeartbeat = Effect.gen(function*() {
- *   yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *   yield* Console.log("Heartbeat")
  *   return "pulse"
  * }).pipe(
  *   Effect.repeat(
@@ -3123,8 +3062,8 @@ export declare const exponential: (base: Duration.Input, factor?: number) => Sch
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Duration>;
 /**
@@ -3139,7 +3078,8 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  * |---------action--------||action|-----|action|-----------|
  * ```
  *
- * @example
+ * **Example** (Repeating on fixed intervals)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3148,7 +3088,7 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  *
  * // Health check that runs at fixed intervals
  * const healthCheck = Effect.gen(function*() {
- *   yield* Console.log(`Health check at ${new Date().toISOString()}`)
+ *   yield* Console.log("Health check")
  *   yield* Effect.sleep("200 millis") // simulate health check work
  *   return "healthy"
  * }).pipe(
@@ -3186,15 +3126,16 @@ export declare const fibonacci: (one: Duration.Input) => Schedule<Duration.Durat
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fixed: (interval: Duration.Input) => Schedule<number>;
 /**
  * Returns a new `Schedule` that maps the output of this schedule using the
  * specified function.
  *
- * @example
+ * **Example** (Mapping schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3212,7 +3153,6 @@ export declare const fixed: (interval: Duration.Input) => Schedule<number>;
  * const structuredSchedule = Schedule.spaced("1 second").pipe(
  *   Schedule.map((recurrence) => Effect.succeed({
  *     iteration: recurrence + 1,
- *     timestamp: new Date().toISOString(),
  *     phase: recurrence < 5 ? "warmup" as const : "steady" as const
  *   }))
  * )
@@ -3224,7 +3164,7 @@ export declare const fixed: (interval: Duration.Input) => Schedule<number>;
  *       Schedule.take(8),
  *       Schedule.tapOutput((info) =>
  *         Console.log(
- *           `${info.phase} phase - iteration ${info.iteration} at ${info.timestamp}`
+ *           `${info.phase} phase - iteration ${info.iteration}`
  *         )
  *       )
  *     )
@@ -3249,15 +3189,16 @@ export declare const fixed: (interval: Duration.Input) => Schedule<number>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const map: {
     /**
      * Returns a new `Schedule` that maps the output of this schedule using the
      * specified function.
      *
-     * @example
+     * **Example** (Mapping schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -3275,7 +3216,6 @@ export declare const map: {
      * const structuredSchedule = Schedule.spaced("1 second").pipe(
      *   Schedule.map((recurrence) => Effect.succeed({
      *     iteration: recurrence + 1,
-     *     timestamp: new Date().toISOString(),
      *     phase: recurrence < 5 ? "warmup" as const : "steady" as const
      *   }))
      * )
@@ -3287,7 +3227,7 @@ export declare const map: {
      *       Schedule.take(8),
      *       Schedule.tapOutput((info) =>
      *         Console.log(
-     *           `${info.phase} phase - iteration ${info.iteration} at ${info.timestamp}`
+     *           `${info.phase} phase - iteration ${info.iteration}`
      *         )
      *       )
      *     )
@@ -3312,15 +3252,16 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <Output, Output2, Error2 = never, Env2 = never>(f: (output: Output) => Output2 | Effect<Output2, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output2, Input, Error | Error2, Env | Env2>;
     /**
      * Returns a new `Schedule` that maps the output of this schedule using the
      * specified function.
      *
-     * @example
+     * **Example** (Mapping schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -3338,7 +3279,6 @@ export declare const map: {
      * const structuredSchedule = Schedule.spaced("1 second").pipe(
      *   Schedule.map((recurrence) => Effect.succeed({
      *     iteration: recurrence + 1,
-     *     timestamp: new Date().toISOString(),
      *     phase: recurrence < 5 ? "warmup" as const : "steady" as const
      *   }))
      * )
@@ -3350,7 +3290,7 @@ export declare const map: {
      *       Schedule.take(8),
      *       Schedule.tapOutput((info) =>
      *         Console.log(
-     *           `${info.phase} phase - iteration ${info.iteration} at ${info.timestamp}`
+     *           `${info.phase} phase - iteration ${info.iteration}`
      *         )
      *       )
      *     )
@@ -3375,8 +3315,8 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <Output, Input, Error, Env, Output2, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, f: (output: Output) => Output2 | Effect<Output2, Error2, Env2>): Schedule<Output2, Input, Error | Error2, Env | Env2>;
 };
@@ -3384,7 +3324,8 @@ export declare const map: {
  * Returns a new `Schedule` that modifies the delay of the next recurrence
  * of the schedule using the specified effectual function.
  *
- * @example
+ * **Example** (Modifying delays from schedule output)
+ *
  * ```ts
  * import { Console, Duration, Effect, Schedule } from "effect"
  *
@@ -3409,15 +3350,16 @@ export declare const map: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const modifyDelay: {
     /**
      * Returns a new `Schedule` that modifies the delay of the next recurrence
      * of the schedule using the specified effectual function.
      *
-     * @example
+     * **Example** (Modifying delays from schedule output)
+     *
      * ```ts
      * import { Console, Duration, Effect, Schedule } from "effect"
      *
@@ -3442,15 +3384,16 @@ export declare const modifyDelay: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <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.
      *
-     * @example
+     * **Example** (Modifying delays from schedule output)
+     *
      * ```ts
      * import { Console, Duration, Effect, Schedule } from "effect"
      *
@@ -3475,8 +3418,8 @@ export declare const modifyDelay: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output, Input, Error, Env, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, f: (output: Output, delay: Duration.Input) => Effect<Duration.Input, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
 };
@@ -3485,14 +3428,15 @@ export declare const modifyDelay: {
  *
  * Delays are jittered between `80%` and `120%` of the original delay.
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const jittered: <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;
 /**
  * Returns a new `Schedule` that outputs the inputs of the specified schedule.
  *
- * @example
+ * **Example** (Passing inputs through as outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3514,15 +3458,16 @@ export declare const jittered: <Output, Input, Error, Env>(self: Schedule<Output
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const passthrough: <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Input, Input, Error, Env>;
 /**
  * Returns a `Schedule` which can only be stepped the specified number of
  * `times` before it terminates.
  *
- * @example
+ * **Example** (Limiting recurrences)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -3560,7 +3505,7 @@ export declare const passthrough: <Output, Input, Error, Env>(self: Schedule<Out
  * // Repeat an effect exactly 10 times
  * const exactlyTenTimes = Effect.gen(function*() {
  *   yield* Console.log("Executing task...")
- *   return Math.random()
+ *   return "completed"
  * }).pipe(
  *   Effect.repeat(Schedule.recurs(10))
  * )
@@ -3580,7 +3525,8 @@ export declare const recurs: (times: number) => Schedule<number>;
  * using the specified effectful `combine` function and starting from the
  * specified `initial` state.
  *
- * @example
+ * **Example** (Reducing schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3605,24 +3551,24 @@ export declare const recurs: (times: number) => Schedule<number>;
  *   yield* Console.log(`Final sum: ${finalSum}`)
  * })
  *
- * // Build a history of execution times
+ * // Build a history of execution counts
  * const historySchedule = Schedule.reduce(
  *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
  *   () => [] as Array<number>, // Initial empty array
- *   (history, executionNumber) => Effect.succeed([...history, Date.now()])
+ *   (history, executionNumber) => Effect.succeed([...history, executionNumber])
  * )
  *
  * const historyProgram = Effect.gen(function*() {
  *   const timeline = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log("Recording timestamp...")
+ *       yield* Console.log("Recording execution...")
  *       return "recorded"
  *     }),
  *     historySchedule
  *   )
  *
  *   yield* Console.log(
- *     `Execution timeline: ${timeline.length} timestamps recorded`
+ *     `Execution timeline: ${timeline.join(", ")}`
  *   )
  * })
  *
@@ -3683,8 +3629,8 @@ export declare const recurs: (times: number) => Schedule<number>;
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export declare const reduce: {
     /**
@@ -3692,7 +3638,8 @@ export declare const reduce: {
      * using the specified effectful `combine` function and starting from the
      * specified `initial` state.
      *
-     * @example
+     * **Example** (Reducing schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -3717,24 +3664,24 @@ export declare const reduce: {
      *   yield* Console.log(`Final sum: ${finalSum}`)
      * })
      *
-     * // Build a history of execution times
+     * // Build a history of execution counts
      * const historySchedule = Schedule.reduce(
      *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
      *   () => [] as Array<number>, // Initial empty array
-     *   (history, executionNumber) => Effect.succeed([...history, Date.now()])
+     *   (history, executionNumber) => Effect.succeed([...history, executionNumber])
      * )
      *
      * const historyProgram = Effect.gen(function*() {
      *   const timeline = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log("Recording timestamp...")
+     *       yield* Console.log("Recording execution...")
      *       return "recorded"
      *     }),
      *     historySchedule
      *   )
      *
      *   yield* Console.log(
-     *     `Execution timeline: ${timeline.length} timestamps recorded`
+     *     `Execution timeline: ${timeline.join(", ")}`
      *   )
      * })
      *
@@ -3795,8 +3742,8 @@ export declare const reduce: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <State, Output, Error2 = never, Env2 = never>(initial: LazyArg<State>, combine: (state: State, output: Output) => State | Effect<State, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<State, Input, Error | Error2, Env | Env2>;
     /**
@@ -3804,7 +3751,8 @@ export declare const reduce: {
      * using the specified effectful `combine` function and starting from the
      * specified `initial` state.
      *
-     * @example
+     * **Example** (Reducing schedule outputs)
+     *
      * ```ts
      * import { Console, Effect, Schedule } from "effect"
      *
@@ -3829,24 +3777,24 @@ export declare const reduce: {
      *   yield* Console.log(`Final sum: ${finalSum}`)
      * })
      *
-     * // Build a history of execution times
+     * // Build a history of execution counts
      * const historySchedule = Schedule.reduce(
      *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
      *   () => [] as Array<number>, // Initial empty array
-     *   (history, executionNumber) => Effect.succeed([...history, Date.now()])
+     *   (history, executionNumber) => Effect.succeed([...history, executionNumber])
      * )
      *
      * const historyProgram = Effect.gen(function*() {
      *   const timeline = yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log("Recording timestamp...")
+     *       yield* Console.log("Recording execution...")
      *       return "recorded"
      *     }),
      *     historySchedule
      *   )
      *
      *   yield* Console.log(
-     *     `Execution timeline: ${timeline.length} timestamps recorded`
+     *     `Execution timeline: ${timeline.join(", ")}`
      *   )
      * })
      *
@@ -3907,8 +3855,8 @@ export declare const reduce: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category utilities
      */
     <Output, Input, Error, Env, State, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, initial: LazyArg<State>, combine: (state: State, output: Output) => State | Effect<State, Error2, Env2>): Schedule<State, Input, Error | Error2, Env | Env2>;
 };
@@ -3916,7 +3864,8 @@ export declare const reduce: {
  * Returns a schedule that recurs continuously, each repetition spaced the
  * specified duration from the last run.
  *
- * @example
+ * **Example** (Repeating with fixed spacing)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3925,7 +3874,7 @@ export declare const reduce: {
  *
  * // Heartbeat that runs indefinitely with fixed spacing
  * const heartbeat = Effect.gen(function*() {
- *   yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *   yield* Console.log("Heartbeat")
  * }).pipe(
  *   Effect.repeat(everyTwoSeconds)
  * )
@@ -3958,8 +3907,8 @@ export declare const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const spaced: (duration: Duration.Input) => Schedule<number>;
 /**
@@ -3967,7 +3916,8 @@ export declare const spaced: (duration: Duration.Input) => Schedule<number>;
  * every input to the schedule, but does not alter the inputs and outputs of
  * the schedule.
  *
- * @example
+ * **Example** (Tapping retry inputs)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -4003,7 +3953,6 @@ export declare const spaced: (duration: Duration.Input) => Schedule<number>;
  *   Schedule.take(5),
  *   Schedule.tapInput((input: unknown) =>
  *     Effect.gen(function*() {
- *       yield* Console.log(`Processing input at ${new Date().toISOString()}`)
  *       yield* Console.log(`Input type: ${typeof input}`)
  *       // In real applications, might send metrics to monitoring system
  *     })
@@ -4025,10 +3974,13 @@ export declare const spaced: (duration: Duration.Input) => Schedule<number>;
  * )
  *
  * const validationProgram = Effect.gen(function*() {
+ *   let count = 0
+ *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
+ *       count++
  *       yield* Console.log("Task with validation")
- *       return { data: Math.random(), timestamp: Date.now() }
+ *       return { data: `sample-${count}` }
  *     }),
  *     validatingSchedule
  *   )
@@ -4040,10 +3992,10 @@ export declare const spaced: (duration: Duration.Input) => Schedule<number>;
  *   Schedule.tapInput((error: RetryError) =>
  *     Effect.gen(function*() {
  *       if (String(error).includes("critical")) {
- *         yield* Console.log(`🚨 CRITICAL ERROR: ${String(error)}`)
+ *         yield* Console.log(`Critical error: ${String(error)}`)
  *         // In real applications, might trigger alerts or notifications
  *       } else {
- *         yield* Console.log(`ℹ️ Regular error: ${String(error)}`)
+ *         yield* Console.log(`Regular error: ${String(error)}`)
  *       }
  *     })
  *   )
@@ -4077,14 +4029,14 @@ export declare const spaced: (duration: Duration.Input) => Schedule<number>;
  *   ),
  *   Schedule.tapInput((error: RetryError) =>
  *     String(error).length > 20
- *       ? Console.log("📝 Long error message detected")
+ *       ? Console.log("Long error message detected")
  *       : Effect.void
  *   )
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const tapInput: {
     /**
@@ -4092,7 +4044,8 @@ export declare const tapInput: {
      * every input to the schedule, but does not alter the inputs and outputs of
      * the schedule.
      *
-     * @example
+     * **Example** (Tapping retry inputs)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4128,7 +4081,6 @@ export declare const tapInput: {
      *   Schedule.take(5),
      *   Schedule.tapInput((input: unknown) =>
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Processing input at ${new Date().toISOString()}`)
      *       yield* Console.log(`Input type: ${typeof input}`)
      *       // In real applications, might send metrics to monitoring system
      *     })
@@ -4150,10 +4102,13 @@ export declare const tapInput: {
      * )
      *
      * const validationProgram = Effect.gen(function*() {
+     *   let count = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
+     *       count++
      *       yield* Console.log("Task with validation")
-     *       return { data: Math.random(), timestamp: Date.now() }
+     *       return { data: `sample-${count}` }
      *     }),
      *     validatingSchedule
      *   )
@@ -4165,10 +4120,10 @@ export declare const tapInput: {
      *   Schedule.tapInput((error: RetryError) =>
      *     Effect.gen(function*() {
      *       if (String(error).includes("critical")) {
-     *         yield* Console.log(`🚨 CRITICAL ERROR: ${String(error)}`)
+     *         yield* Console.log(`Critical error: ${String(error)}`)
      *         // In real applications, might trigger alerts or notifications
      *       } else {
-     *         yield* Console.log(`ℹ️ Regular error: ${String(error)}`)
+     *         yield* Console.log(`Regular error: ${String(error)}`)
      *       }
      *     })
      *   )
@@ -4202,14 +4157,14 @@ export declare const tapInput: {
      *   ),
      *   Schedule.tapInput((error: RetryError) =>
      *     String(error).length > 20
-     *       ? Console.log("📝 Long error message detected")
+     *       ? Console.log("Long error message detected")
      *       : Effect.void
      *   )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <Input, X, Error2, Env2>(f: (input: Input) => Effect<X, Error2, Env2>): <Output, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error | Error2, Env | Env2>;
     /**
@@ -4217,7 +4172,8 @@ export declare const tapInput: {
      * every input to the schedule, but does not alter the inputs and outputs of
      * the schedule.
      *
-     * @example
+     * **Example** (Tapping retry inputs)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4253,7 +4209,6 @@ export declare const tapInput: {
      *   Schedule.take(5),
      *   Schedule.tapInput((input: unknown) =>
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Processing input at ${new Date().toISOString()}`)
      *       yield* Console.log(`Input type: ${typeof input}`)
      *       // In real applications, might send metrics to monitoring system
      *     })
@@ -4275,10 +4230,13 @@ export declare const tapInput: {
      * )
      *
      * const validationProgram = Effect.gen(function*() {
+     *   let count = 0
+     *
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
+     *       count++
      *       yield* Console.log("Task with validation")
-     *       return { data: Math.random(), timestamp: Date.now() }
+     *       return { data: `sample-${count}` }
      *     }),
      *     validatingSchedule
      *   )
@@ -4290,10 +4248,10 @@ export declare const tapInput: {
      *   Schedule.tapInput((error: RetryError) =>
      *     Effect.gen(function*() {
      *       if (String(error).includes("critical")) {
-     *         yield* Console.log(`🚨 CRITICAL ERROR: ${String(error)}`)
+     *         yield* Console.log(`Critical error: ${String(error)}`)
      *         // In real applications, might trigger alerts or notifications
      *       } else {
-     *         yield* Console.log(`ℹ️ Regular error: ${String(error)}`)
+     *         yield* Console.log(`Regular error: ${String(error)}`)
      *       }
      *     })
      *   )
@@ -4327,14 +4285,14 @@ export declare const tapInput: {
      *   ),
      *   Schedule.tapInput((error: RetryError) =>
      *     String(error).length > 20
-     *       ? Console.log("📝 Long error message detected")
+     *       ? Console.log("Long error message detected")
      *       : Effect.void
      *   )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <Output, Input, Error, Env, X, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, f: (input: Input) => Effect<X, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
 };
@@ -4343,7 +4301,8 @@ export declare const tapInput: {
  * every output of the schedule, but does not alter the inputs and outputs of
  * the schedule.
  *
- * @example
+ * **Example** (Tapping schedule outputs)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -4391,7 +4350,7 @@ export declare const tapInput: {
  *     Effect.gen(function*() {
  *       const delayMs = delay.toString()
  *       if (delayMs.includes("1000")) { // Alert on delays >= 1 second
- *         yield* Console.log(`🚨 High delay detected: ${delay}`)
+ *         yield* Console.log(`High delay detected: ${delay}`)
  *       }
  *     })
  *   )
@@ -4401,8 +4360,7 @@ export declare const tapInput: {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Performing health check...")
- *       // Simulate health check
- *       return Math.random() > 0.7 ? "healthy" : "degraded"
+ *       return "healthy"
  *     }),
  *     alertingSchedule
  *   )
@@ -4414,14 +4372,14 @@ export declare const tapInput: {
  *   Schedule.tapOutput((count) => Console.log(`Execution ${count + 1}`)),
  *   Schedule.tapOutput((count) =>
  *     count % 3 === 0
- *       ? Console.log("🎯 Checkpoint reached!")
+ *       ? Console.log("Checkpoint reached")
  *       : Effect.void
  *   )
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const tapOutput: {
     /**
@@ -4429,7 +4387,8 @@ export declare const tapOutput: {
      * every output of the schedule, but does not alter the inputs and outputs of
      * the schedule.
      *
-     * @example
+     * **Example** (Tapping schedule outputs)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4477,7 +4436,7 @@ export declare const tapOutput: {
      *     Effect.gen(function*() {
      *       const delayMs = delay.toString()
      *       if (delayMs.includes("1000")) { // Alert on delays >= 1 second
-     *         yield* Console.log(`🚨 High delay detected: ${delay}`)
+     *         yield* Console.log(`High delay detected: ${delay}`)
      *       }
      *     })
      *   )
@@ -4487,8 +4446,7 @@ export declare const tapOutput: {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Performing health check...")
-     *       // Simulate health check
-     *       return Math.random() > 0.7 ? "healthy" : "degraded"
+     *       return "healthy"
      *     }),
      *     alertingSchedule
      *   )
@@ -4500,14 +4458,14 @@ export declare const tapOutput: {
      *   Schedule.tapOutput((count) => Console.log(`Execution ${count + 1}`)),
      *   Schedule.tapOutput((count) =>
      *     count % 3 === 0
-     *       ? Console.log("🎯 Checkpoint reached!")
+     *       ? Console.log("Checkpoint reached")
      *       : Effect.void
      *   )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <Output, X, Error2, Env2>(f: (output: Output) => Effect<X, Error2, Env2>): <Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error | Error2, Env | Env2>;
     /**
@@ -4515,7 +4473,8 @@ export declare const tapOutput: {
      * every output of the schedule, but does not alter the inputs and outputs of
      * the schedule.
      *
-     * @example
+     * **Example** (Tapping schedule outputs)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4563,7 +4522,7 @@ export declare const tapOutput: {
      *     Effect.gen(function*() {
      *       const delayMs = delay.toString()
      *       if (delayMs.includes("1000")) { // Alert on delays >= 1 second
-     *         yield* Console.log(`🚨 High delay detected: ${delay}`)
+     *         yield* Console.log(`High delay detected: ${delay}`)
      *       }
      *     })
      *   )
@@ -4573,8 +4532,7 @@ export declare const tapOutput: {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
      *       yield* Console.log("Performing health check...")
-     *       // Simulate health check
-     *       return Math.random() > 0.7 ? "healthy" : "degraded"
+     *       return "healthy"
      *     }),
      *     alertingSchedule
      *   )
@@ -4586,14 +4544,14 @@ export declare const tapOutput: {
      *   Schedule.tapOutput((count) => Console.log(`Execution ${count + 1}`)),
      *   Schedule.tapOutput((count) =>
      *     count % 3 === 0
-     *       ? Console.log("🎯 Checkpoint reached!")
+     *       ? Console.log("Checkpoint reached")
      *       : Effect.void
      *   )
      * )
      * ```
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <Output, Input, Error, Env, X, Error2, Env2>(self: Schedule<Output, Input, Error, Env>, f: (output: Output) => Effect<X, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
 };
@@ -4602,7 +4560,8 @@ export declare const tapOutput: {
  * from the schedule. Once the specified number of outputs is reached, the
  * schedule will stop.
  *
- * @example
+ * **Example** (Taking a limited number of recurrences)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -4616,7 +4575,7 @@ export declare const tapOutput: {
  * const heartbeatProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *       yield* Console.log("Heartbeat")
  *       return "pulse"
  *     }),
  *     limitedHeartbeat
@@ -4663,8 +4622,8 @@ export declare const tapOutput: {
  * const samplingProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const value = Math.random()
- *       yield* Console.log(`Sampled value: ${value.toFixed(3)}`)
+ *       const value = "sample"
+ *       yield* Console.log(`Sampled value: ${value}`)
  *       return value
  *     }),
  *     samplingSchedule.pipe(
@@ -4674,8 +4633,8 @@ export declare const tapOutput: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const take: {
     /**
@@ -4683,7 +4642,8 @@ export declare const take: {
      * from the schedule. Once the specified number of outputs is reached, the
      * schedule will stop.
      *
-     * @example
+     * **Example** (Taking a limited number of recurrences)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4697,7 +4657,7 @@ export declare const take: {
      * const heartbeatProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+     *       yield* Console.log("Heartbeat")
      *       return "pulse"
      *     }),
      *     limitedHeartbeat
@@ -4744,8 +4704,8 @@ export declare const take: {
      * const samplingProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       const value = Math.random()
-     *       yield* Console.log(`Sampled value: ${value.toFixed(3)}`)
+     *       const value = "sample"
+     *       yield* Console.log(`Sampled value: ${value}`)
      *       return value
      *     }),
      *     samplingSchedule.pipe(
@@ -4755,8 +4715,8 @@ export declare const take: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     (n: number): <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error, Env>;
     /**
@@ -4764,7 +4724,8 @@ export declare const take: {
      * from the schedule. Once the specified number of outputs is reached, the
      * schedule will stop.
      *
-     * @example
+     * **Example** (Taking a limited number of recurrences)
+     *
      * ```ts
      * import { Console, Data, Effect, Schedule } from "effect"
      *
@@ -4778,7 +4739,7 @@ export declare const take: {
      * const heartbeatProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+     *       yield* Console.log("Heartbeat")
      *       return "pulse"
      *     }),
      *     limitedHeartbeat
@@ -4825,8 +4786,8 @@ export declare const take: {
      * const samplingProgram = Effect.gen(function*() {
      *   yield* Effect.repeat(
      *     Effect.gen(function*() {
-     *       const value = Math.random()
-     *       yield* Console.log(`Sampled value: ${value.toFixed(3)}`)
+     *       const value = "sample"
+     *       yield* Console.log(`Sampled value: ${value}`)
      *       return value
      *     }),
      *     samplingSchedule.pipe(
@@ -4836,8 +4797,8 @@ export declare const take: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category utilities
+     * @category utils
+     * @since 4.0.0
      */
     <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>, n: number): Schedule<Output, Input, Error, Env>;
 };
@@ -4845,7 +4806,8 @@ export declare const take: {
  * Creates a schedule that unfolds a state by repeatedly applying a function,
  * outputting the current state and computing the next state.
  *
- * @example
+ * **Example** (Unfolding schedule state)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -4893,15 +4855,14 @@ export declare const take: {
  *     })
  * )
  *
- * // Random jitter schedule
- * const jitteredSchedule = Schedule.unfold(
- *   1000,
- *   (baseDelay) =>
+ * // Deterministic delay adjustment schedule
+ * const adjustedDelaySchedule = Schedule.unfold(
+ *   { delay: 1000, adjustment: 100 },
+ *   ({ delay, adjustment }) =>
  *     Effect.gen(function*() {
- *       const jitter = Math.random() * 200 - 100 // ±100ms jitter
- *       const nextDelay = Math.max(100, baseDelay + jitter)
- *       yield* Console.log(`Jittered delay: ${nextDelay.toFixed(0)}ms`)
- *       return nextDelay
+ *       const nextDelay = Math.max(100, delay + adjustment)
+ *       yield* Console.log(`Adjusted delay: ${nextDelay}ms`)
+ *       return { delay: nextDelay, adjustment: adjustment * -1 }
  *     })
  * )
  *
@@ -4934,8 +4895,8 @@ export declare const take: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const unfold: <State, Error = never, Env = never>(initial: State, next: (state: State) => Effect<State, Error, Env>) => Schedule<State, unknown, Error, Env>;
 declare const while_: {
@@ -4950,8 +4911,8 @@ export {
  * If the `predicate` returns `true`, the schedule will continue, otherwise
  * the schedule will stop.
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 while_ as while };
 /**
@@ -4967,7 +4928,8 @@ while_ as while };
  * |action------|sleep---|act|-sleep|action----|
  * ```
  *
- * @example
+ * **Example** (Repeating on aligned windows)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -4977,8 +4939,7 @@ while_ as while };
  * const program = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const now = new Date().toISOString()
- *       yield* Console.log(`Window task executed at: ${now}`)
+ *       yield* Console.log("Window task executed")
  *       return "window-task"
  *     }),
  *     windowSchedule.pipe(Schedule.take(4))
@@ -4986,8 +4947,8 @@ while_ as while };
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const windowed: (interval: Duration.Input) => Schedule<number>;
 /**
@@ -4996,7 +4957,8 @@ export declare const windowed: (interval: Duration.Input) => Schedule<number>;
  * The output of the schedule is the current count of its repetitions thus far
  * (i.e. `0, 1, 2, ...`).
  *
- * @example
+ * **Example** (Repeating forever)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -5014,8 +4976,8 @@ export declare const windowed: (interval: Duration.Input) => Schedule<number>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const forever: Schedule<number>;
 declare const identity_: <A>() => Schedule<A, A>;
@@ -5029,14 +4991,15 @@ export {
  * without modification. It effectively acts as a pass-through that simply
  * echoes its input values at each step.
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 identity_ as identity };
 /**
  * Ensures that the provided schedule respects a specified input type.
  *
- * @example
+ * **Example** (Constraining schedule input types)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -5055,22 +5018,23 @@ identity_ as identity };
  * // where CustomType doesn't match the schedule's input type
  * ```
  *
- * @since 2.0.0
  * @category ensuring 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.
  *
- * @since 2.0.0
  * @category ensuring 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.
  *
- * @example
+ * **Example** (Constraining schedule output types)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -5084,14 +5048,15 @@ export declare const setInputType: <T>() => <Output, Error, Env>(self: Schedule<
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring 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.
  *
- * @example
+ * **Example** (Constraining schedule error types)
+ *
  * ```ts
  * import { Data, Schedule } from "effect"
  *
@@ -5111,16 +5076,17 @@ export declare const satisfiesOutputType: <T>() => <Output extends T, Error = ne
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring 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.
  *
- * @example
+ * **Example** (Constraining schedule service types)
+ *
  * ```ts
- * import { Schedule } from "effect"
+ * import { Effect, Schedule } from "effect"
  *
  * // Define service interfaces (type-level only)
  * interface Logger {
@@ -5128,7 +5094,7 @@ export declare const satisfiesErrorType: <T>() => <Error extends T, Output = nev
  * }
  *
  * interface Database {
- *   readonly query: (sql: string) => Promise<unknown>
+ *   readonly query: (sql: string) => Effect.Effect<ReadonlyArray<unknown>>
  * }
  *
  * // Ensure schedule requires Logger service
@@ -5142,8 +5108,8 @@ export declare const satisfiesErrorType: <T>() => <Error extends T, Output = nev
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring 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>;
 //# sourceMappingURL=Schedule.d.ts.map