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

package/src/Schedule.ts

@@ -6,7 +6,8 @@
  * along with a delay duration. Schedules can be combined, transformed, and used to implement
  * sophisticated retry and repetition logic.
  *
- * @example
+ * **Example** (Retrying and repeating effects)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -53,9 +54,14 @@ const randomNext: Effect<number> = random.Random.useSync((random) => random.next
 /**
  * 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(
@@ -66,25 +72,29 @@ const randomNext: Effect<number> = random.Random.useSync((random) => random.next
  * 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
@@ -93,7 +103,8 @@ export interface Schedule<out Output, in Input = unknown, out Error = never, out
 /**
  * Metadata provided to schedule functions containing timing and input information.
  *
- * @example
+ * **Example** (Reading schedule input metadata)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -112,8 +123,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
@@ -127,18 +138,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*() {
@@ -149,13 +161,13 @@ 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
@@ -163,8 +175,16 @@ export interface Metadata<Output = unknown, Input = unknown> extends InputMetada
 }
 
 /**
- * @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 const CurrentMetadata = Context.Reference<Metadata>("effect/Schedule/CurrentMetadata", {
   defaultValue: constant({
@@ -182,7 +202,8 @@ export const CurrentMetadata = Context.Reference<Metadata>("effect/Schedule/Curr
 /**
  * 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"
  *
@@ -210,13 +231,13 @@ export const CurrentMetadata = Context.Reference<Metadata>("effect/Schedule/Curr
  * ```
  *
  * @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"
    *
@@ -240,44 +261,23 @@ export declare namespace Schedule {
    * const serviceSchedule = Schedule.spaced("5 seconds")
    * ```
    *
+   * @category models
    * @since 2.0.0
-   * @category Models
    */
   export 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
    */
   export interface VarianceStruct<out Output, in Input, out Error, out Env> {
     readonly _Out: Covariant<Output>
@@ -301,7 +301,8 @@ const ScheduleProto = {
 /**
  * Type guard that checks if a value is a Schedule.
  *
- * @example
+ * **Example** (Checking for schedules)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -314,34 +315,33 @@ const ScheduleProto = {
  * console.log(Schedule.isSchedule(undefined)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isSchedule = (u: unknown): u is Schedule<unknown, never, unknown, unknown> => hasProperty(u, TypeId)
 
 /**
  * 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 const fromStep = <Input, Output, EnvX, Error, ErrorX, Env>(
   step: Effect<
@@ -371,26 +371,25 @@ const metadataFn = () => {
 /**
  * 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 const fromStepWithMetadata = <Input, Output, EnvX, ErrorX, Error, Env>(
   step: Effect<
@@ -407,7 +406,8 @@ export const fromStepWithMetadata = <Input, Output, EnvX, ErrorX, Error, Env>(
 /**
  * Extracts the step function from a Schedule.
  *
- * @example
+ * **Example** (Extracting a schedule step function)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -417,16 +417,17 @@ export const fromStepWithMetadata = <Input, Output, EnvX, ErrorX, Error, Env>(
  * 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 const toStep = <Output, Input, Error, Env>(
   schedule: Schedule<Output, Input, Error, Env>
@@ -444,8 +445,8 @@ export const toStep = <Output, Input, Error, 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 const toStepWithMetadata = <Output, Input, Error, Env>(
   schedule: Schedule<Output, Input, Error, Env>
@@ -479,7 +480,8 @@ export const toStepWithMetadata = <Output, Input, Error, 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"
  *
@@ -502,8 +504,8 @@ export const toStepWithMetadata = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 export const toStepWithSleep = <Output, Input, Error, Env>(
   schedule: Schedule<Output, Input, Error, Env>
@@ -521,29 +523,26 @@ export const toStepWithSleep = <Output, Input, Error, 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}`)
  *       )
  *     )
  *   )
@@ -571,12 +570,15 @@ export const toStepWithSleep = <Output, Input, Error, Env>(
  *   )
  * })
  *
- * // 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*() {
@@ -589,25 +591,6 @@ export const toStepWithSleep = <Output, Input, Error, Env>(
  *   )
  * })
  *
- * // 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)),
@@ -632,37 +615,34 @@ export const toStepWithSleep = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export 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}`)
    *       )
    *     )
    *   )
@@ -690,12 +670,15 @@ export 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*() {
@@ -708,25 +691,6 @@ export 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)),
@@ -751,8 +715,8 @@ export 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>
@@ -761,29 +725,26 @@ export 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}`)
    *       )
    *     )
    *   )
@@ -811,12 +772,15 @@ export 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*() {
@@ -829,25 +793,6 @@ export 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)),
@@ -872,8 +817,8 @@ export 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>,
@@ -894,7 +839,8 @@ export 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"
  *
@@ -926,8 +872,8 @@ export const addDelay: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const andThen: {
   /**
@@ -935,7 +881,8 @@ export 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"
    *
@@ -967,8 +914,8 @@ export 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>
@@ -978,7 +925,8 @@ export 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"
    *
@@ -1010,8 +958,8 @@ export 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>,
@@ -1028,11 +976,12 @@ export 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"
  *
@@ -1060,8 +1009,8 @@ export const andThen: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const andThenResult: {
   /**
@@ -1069,11 +1018,12 @@ export 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"
    *
@@ -1101,8 +1051,8 @@ export 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>
@@ -1112,11 +1062,12 @@ export 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"
    *
@@ -1144,8 +1095,8 @@ export 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>,
@@ -1183,11 +1134,12 @@ export 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"
          *
@@ -1215,8 +1167,8 @@ export const andThenResult: {
          * })
          * ```
          *
-         * @since 2.0.0
          * @category sequencing
+         * @since 4.0.0
          */
         Result.Result<Output, Output2>,
         /**
@@ -1224,11 +1176,12 @@ export 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"
          *
@@ -1256,8 +1209,8 @@ export const andThenResult: {
          * })
          * ```
          *
-         * @since 2.0.0
          * @category sequencing
+         * @since 4.0.0
          */
         Input & Input2,
         /**
@@ -1265,11 +1218,12 @@ export 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"
          *
@@ -1297,8 +1251,8 @@ export const andThenResult: {
          * })
          * ```
          *
-         * @since 2.0.0
          * @category sequencing
+         * @since 4.0.0
          */
         Error | Error2,
         /**
@@ -1306,11 +1260,12 @@ export 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"
          *
@@ -1338,8 +1293,8 @@ export const andThenResult: {
          * })
          * ```
          *
-         * @since 2.0.0
          * @category sequencing
+         * @since 4.0.0
          */
         Env | Env2
       >(currentSide === 0 ? left : right).pipe(
@@ -1365,7 +1320,8 @@ export 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"
  *
@@ -1382,7 +1338,7 @@ export 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(
@@ -1426,8 +1382,8 @@ export const andThenResult: {
  * // Compare with either which provides union semantics (OR logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const both: {
   /**
@@ -1435,7 +1391,8 @@ export 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"
    *
@@ -1452,7 +1409,7 @@ export 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(
@@ -1496,8 +1453,8 @@ export 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>
@@ -1507,7 +1464,8 @@ export 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"
    *
@@ -1524,7 +1482,7 @@ export 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(
@@ -1568,8 +1526,8 @@ export 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>,
@@ -1586,7 +1544,8 @@ export 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"
  *
@@ -1609,8 +1568,8 @@ export const both: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothLeft: {
   /**
@@ -1618,7 +1577,8 @@ export 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"
    *
@@ -1641,8 +1601,8 @@ export 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>
@@ -1652,7 +1612,8 @@ export 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"
    *
@@ -1675,8 +1636,8 @@ export const bothLeft: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
     self: Schedule<Output, Input, Error, Env>,
@@ -1692,7 +1653,8 @@ export 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"
  *
@@ -1717,8 +1679,8 @@ export const bothLeft: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothRight: {
   /**
@@ -1726,7 +1688,8 @@ export 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"
    *
@@ -1751,8 +1714,8 @@ export 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>
@@ -1762,7 +1725,8 @@ export 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"
    *
@@ -1787,8 +1751,8 @@ export const bothRight: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
     self: Schedule<Output, Input, Error, Env>,
@@ -1805,7 +1769,8 @@ export 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"
  *
@@ -1834,8 +1799,8 @@ export const bothRight: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothWith: {
   /**
@@ -1844,7 +1809,8 @@ export 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"
    *
@@ -1873,8 +1839,8 @@ export const bothWith: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output2, Input2, Error2, Env2, Output, Output3>(
     other: Schedule<Output2, Input2, Error2, Env2>,
@@ -1888,7 +1854,8 @@ export 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"
    *
@@ -1917,8 +1884,8 @@ export 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>,
@@ -1954,10 +1921,15 @@ export const bothWith: {
   )))
 
 /**
- * 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"
  *
@@ -1979,18 +1951,23 @@ export const bothWith: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const collectInputs = <Output, Input, Error, Env>(
   self: Schedule<Output, Input, Error, Env>
 ): Schedule<Array<Input>, Input, Error, Env> => collectWhile(passthrough(self), () => effect.succeed(true))
 
 /**
- * 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"
  *
@@ -2010,8 +1987,8 @@ export const collectInputs = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const collectOutputs = <Output, Input, Error, Env>(
   self: Schedule<Output, Input, Error, Env>
@@ -2021,31 +1998,11 @@ export const collectOutputs = <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"),
@@ -2056,16 +2013,16 @@ export const collectOutputs = <Output, Input, Error, Env>(
  * 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
@@ -2082,19 +2039,17 @@ export const collectOutputs = <Output, Input, Error, Env>(
  * )
  *
  * 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) =>
@@ -2102,55 +2057,36 @@ export const collectOutputs = <Output, Input, Error, Env>(
  * )
  *
  * 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 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"),
@@ -2161,16 +2097,16 @@ export 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
@@ -2187,19 +2123,17 @@ export 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) =>
@@ -2207,24 +2141,25 @@ export 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: (
@@ -2237,31 +2172,11 @@ export 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"),
@@ -2272,16 +2187,16 @@ export 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
@@ -2298,19 +2213,17 @@ export 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) =>
@@ -2318,24 +2231,25 @@ export 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>,
@@ -2358,7 +2272,8 @@ export 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"
  *
@@ -2370,7 +2285,7 @@ export 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(
@@ -2408,8 +2323,8 @@ export 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
@@ -2422,10 +2337,13 @@ export 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
  *     }),
@@ -2442,9 +2360,9 @@ export 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))
  *   )
@@ -2458,11 +2376,13 @@ export 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"
@@ -2476,15 +2396,16 @@ export const collectWhile: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export 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"
    *
@@ -2496,7 +2417,7 @@ export 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(
@@ -2534,8 +2455,8 @@ export 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
@@ -2548,10 +2469,13 @@ export 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
    *     }),
@@ -2568,9 +2492,9 @@ export 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))
    *   )
@@ -2584,11 +2508,13 @@ export 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"
@@ -2602,15 +2528,16 @@ export 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"
    *
@@ -2622,7 +2549,7 @@ export 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(
@@ -2660,8 +2587,8 @@ export 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
@@ -2674,10 +2601,13 @@ export 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
    *     }),
@@ -2694,9 +2624,9 @@ export 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))
    *   )
@@ -2710,11 +2640,13 @@ export 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"
@@ -2728,8 +2660,8 @@ export const cron: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category constructors
+   * @since 2.0.0
    */
   (expression: string, tz?: string | DateTime.TimeZone): Schedule<Duration.Duration, unknown, Cron.CronParseError>
 } = (expression: string | Cron.Cron, tz?: string | DateTime.TimeZone) => {
@@ -2745,7 +2677,8 @@ export const cron: {
 /**
  * Returns a new schedule that outputs the delay between each occurence.
  *
- * @example
+ * **Example** (Extracting schedule delays)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2805,7 +2738,7 @@ export 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}`))
@@ -2822,8 +2755,8 @@ export const cron: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const delays = <Out, In, E, R>(self: Schedule<Out, In, E, R>): Schedule<Duration.Duration, In, E, R> =>
   fromStep(
@@ -2843,8 +2776,8 @@ export const delays = <Out, In, E, R>(self: Schedule<Out, In, E, R>): Schedule<D
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const duration = (durationInput: Duration.Input): Schedule<Duration.Duration> => {
   const duration = Duration.fromInputUnsafe(durationInput)
@@ -2859,7 +2792,8 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.Durat
  * 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"
  *
@@ -2869,12 +2803,9 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.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"
  *     }),
@@ -2902,8 +2833,8 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.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
  *   )
@@ -2924,7 +2855,7 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.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` }))
  *       }
  *
@@ -2939,8 +2870,8 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.Durat
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
   while_(
@@ -2953,7 +2884,8 @@ export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
  * 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"
  *
@@ -2970,7 +2902,7 @@ export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
  * 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(
@@ -3016,8 +2948,8 @@ export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
  * // Compare with intersect which provides intersection semantics (AND logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const either: {
   /**
@@ -3025,7 +2957,8 @@ export 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"
    *
@@ -3042,7 +2975,7 @@ export 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(
@@ -3088,8 +3021,8 @@ export 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>
@@ -3099,7 +3032,8 @@ export 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"
    *
@@ -3116,7 +3050,7 @@ export 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(
@@ -3162,8 +3096,8 @@ export 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>,
@@ -3180,7 +3114,8 @@ export 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"
  *
@@ -3206,8 +3141,8 @@ export const either: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const eitherLeft: {
   /**
@@ -3215,7 +3150,8 @@ export 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"
    *
@@ -3241,8 +3177,8 @@ export 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>
@@ -3252,7 +3188,8 @@ export 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"
    *
@@ -3278,8 +3215,8 @@ export 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>,
@@ -3295,7 +3232,8 @@ export 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"
  *
@@ -3321,8 +3259,8 @@ export const eitherLeft: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const eitherRight: {
   /**
@@ -3330,7 +3268,8 @@ export 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"
    *
@@ -3356,8 +3295,8 @@ export 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>
@@ -3367,7 +3306,8 @@ export 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"
    *
@@ -3393,8 +3333,8 @@ export 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>,
@@ -3411,7 +3351,8 @@ export 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"
  *
@@ -3441,8 +3382,8 @@ export const eitherRight: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const eitherWith: {
   /**
@@ -3451,7 +3392,8 @@ export 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"
    *
@@ -3481,8 +3423,8 @@ export const eitherWith: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output2, Input2, Error2, Env2, Output, Output3>(
     other: Schedule<Output2, Input2, Error2, Env2>,
@@ -3496,7 +3438,8 @@ export 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"
    *
@@ -3526,8 +3469,8 @@ export 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>,
@@ -3558,7 +3501,8 @@ export 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"
                *
@@ -3588,8 +3532,8 @@ export const eitherWith: {
                * })
                * ```
                *
+               * @category utils
                * @since 2.0.0
-               * @category utilities
                */
               [Output3, Duration.Duration]>([
                 combine(leftResult[0], rightDone as Output2),
@@ -3617,9 +3561,8 @@ export 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"
  *
@@ -3637,8 +3580,8 @@ export const eitherWith: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const elapsed: Schedule<Duration.Duration> = fromStepWithMetadata(
   effect.succeed((meta) => effect.succeed([Duration.millis(meta.elapsed), Duration.zero] as const))
@@ -3649,7 +3592,8 @@ export const elapsed: Schedule<Duration.Duration> = fromStepWithMetadata(
  * 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"
  *
@@ -3689,8 +3633,8 @@ export const elapsed: Schedule<Duration.Duration> = fromStepWithMetadata(
  * // Will retry with delays: 50ms, 100ms, 200ms before success
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const exponential = (
   base: Duration.Input,
@@ -3708,7 +3652,8 @@ export const exponential = (
  * 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"
  *
@@ -3744,7 +3689,7 @@ export const exponential = (
  *
  * // 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(
@@ -3766,8 +3711,8 @@ export const exponential = (
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
   const oneMillis = Duration.toMillis(Duration.fromInputUnsafe(one))
@@ -3796,7 +3741,8 @@ export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
  * |---------action--------||action|-----|action|-----------|
  * ```
  *
- * @example
+ * **Example** (Repeating on fixed intervals)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -3805,7 +3751,7 @@ export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
  *
  * // 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(
@@ -3843,8 +3789,8 @@ export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fixed = (interval: Duration.Input): Schedule<number> => {
   const window = Duration.toMillis(Duration.fromInputUnsafe(interval))
@@ -3874,7 +3820,8 @@ export 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"
  *
@@ -3892,7 +3839,6 @@ export 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
  *   }))
  * )
@@ -3904,7 +3850,7 @@ export 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}`
  *         )
  *       )
  *     )
@@ -3929,15 +3875,16 @@ export const fixed = (interval: Duration.Input): Schedule<number> => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export 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"
    *
@@ -3955,7 +3902,6 @@ export 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
    *   }))
    * )
@@ -3967,7 +3913,7 @@ export 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}`
    *         )
    *       )
    *     )
@@ -3992,8 +3938,8 @@ export 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>
@@ -4002,7 +3948,8 @@ export 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"
    *
@@ -4020,7 +3967,6 @@ export 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
    *   }))
    * )
@@ -4032,7 +3978,7 @@ export 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}`
    *         )
    *       )
    *     )
@@ -4057,8 +4003,8 @@ export 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>,
@@ -4088,7 +4034,8 @@ export 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"
  *
@@ -4113,15 +4060,16 @@ export const map: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export 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"
    *
@@ -4146,8 +4094,8 @@ export const modifyDelay: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output, Error2 = never, Env2 = never>(
     f: (
@@ -4161,7 +4109,8 @@ export 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"
    *
@@ -4186,8 +4135,8 @@ export const modifyDelay: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <Output, Input, Error, Env, Error2 = never, Env2 = never>(
     self: Schedule<Output, Input, Error, Env>,
@@ -4214,8 +4163,8 @@ export const modifyDelay: {
  *
  * Delays are jittered between `80%` and `120%` of the original delay.
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const jittered = <Output, Input, Error, Env>(
   self: Schedule<Output, Input, Error, Env>
@@ -4229,7 +4178,8 @@ export const jittered = <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"
  *
@@ -4251,8 +4201,8 @@ export const jittered = <Output, Input, Error, Env>(
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const passthrough = <Output, Input, Error, Env>(
   self: Schedule<Output, Input, Error, Env>
@@ -4268,7 +4218,8 @@ export const passthrough = <Output, 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"
  *
@@ -4306,7 +4257,7 @@ export const passthrough = <Output, Input, Error, Env>(
  * // 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))
  * )
@@ -4328,7 +4279,8 @@ export 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"
  *
@@ -4353,24 +4305,24 @@ export 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(", ")}`
  *   )
  * })
  *
@@ -4431,8 +4383,8 @@ export const recurs = (times: number): Schedule<number> =>
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const reduce: {
   /**
@@ -4440,7 +4392,8 @@ export 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"
    *
@@ -4465,24 +4418,24 @@ export 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(", ")}`
    *   )
    * })
    *
@@ -4543,8 +4496,8 @@ export const reduce: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <State, Output, Error2 = never, Env2 = never>(
     initial: LazyArg<State>,
@@ -4557,7 +4510,8 @@ export 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"
    *
@@ -4582,24 +4536,24 @@ export 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(", ")}`
    *   )
    * })
    *
@@ -4660,8 +4614,8 @@ export 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>,
@@ -4700,7 +4654,8 @@ export 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"
  *
@@ -4709,7 +4664,7 @@ export 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)
  * )
@@ -4742,8 +4697,8 @@ export const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const spaced = (duration: Duration.Input): Schedule<number> => {
   const decoded = Duration.fromInputUnsafe(duration)
@@ -4755,7 +4710,8 @@ export 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"
  *
@@ -4791,7 +4747,6 @@ export 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
  *     })
@@ -4813,10 +4768,13 @@ export 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
  *   )
@@ -4828,10 +4786,10 @@ export 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)}`)
  *       }
  *     })
  *   )
@@ -4865,14 +4823,14 @@ export 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 const tapInput: {
   /**
@@ -4880,7 +4838,8 @@ export 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"
    *
@@ -4916,7 +4875,6 @@ export 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
    *     })
@@ -4938,10 +4896,13 @@ export 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
    *   )
@@ -4953,10 +4914,10 @@ export 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)}`)
    *       }
    *     })
    *   )
@@ -4990,14 +4951,14 @@ export 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>
@@ -5007,7 +4968,8 @@ export 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"
    *
@@ -5043,7 +5005,6 @@ export 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
    *     })
@@ -5065,10 +5026,13 @@ export 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
    *   )
@@ -5080,10 +5044,10 @@ export 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)}`)
    *       }
    *     })
    *   )
@@ -5117,14 +5081,14 @@ export 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>,
@@ -5144,7 +5108,8 @@ export 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"
  *
@@ -5192,7 +5157,7 @@ export 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}`)
  *       }
  *     })
  *   )
@@ -5202,8 +5167,7 @@ export 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
  *   )
@@ -5215,14 +5179,14 @@ export 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 const tapOutput: {
   /**
@@ -5230,7 +5194,8 @@ export 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"
    *
@@ -5278,7 +5243,7 @@ export 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}`)
    *       }
    *     })
    *   )
@@ -5288,8 +5253,7 @@ export 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
    *   )
@@ -5301,14 +5265,14 @@ export 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>
@@ -5318,7 +5282,8 @@ export 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"
    *
@@ -5366,7 +5331,7 @@ export 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}`)
    *       }
    *     })
    *   )
@@ -5376,8 +5341,7 @@ export 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
    *   )
@@ -5389,14 +5353,14 @@ export 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>,
@@ -5416,7 +5380,8 @@ export 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"
  *
@@ -5430,7 +5395,7 @@ export 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
@@ -5477,8 +5442,8 @@ export 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(
@@ -5488,8 +5453,8 @@ export const tapOutput: {
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const take: {
   /**
@@ -5497,7 +5462,8 @@ export 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"
    *
@@ -5511,7 +5477,7 @@ export 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
@@ -5558,8 +5524,8 @@ export 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(
@@ -5569,8 +5535,8 @@ export 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>
@@ -5580,7 +5546,8 @@ export 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"
    *
@@ -5594,7 +5561,7 @@ export 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
@@ -5641,8 +5608,8 @@ export 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(
@@ -5652,8 +5619,8 @@ export 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>
 } = dual(2, <Output, Input, Error, Env>(
@@ -5665,7 +5632,8 @@ export 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"
  *
@@ -5713,15 +5681,14 @@ export 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 }
  *     })
  * )
  *
@@ -5754,8 +5721,8 @@ export const take: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const unfold = <State, Error = never, Env = never>(
   initial: State,
@@ -5814,8 +5781,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
 }
@@ -5833,7 +5800,8 @@ export {
  * |action------|sleep---|act|-sleep|action----|
  * ```
  *
- * @example
+ * **Example** (Repeating on aligned windows)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -5843,8 +5811,7 @@ export {
  * 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))
@@ -5852,8 +5819,8 @@ export {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const windowed = (interval: Duration.Input): Schedule<number> => {
   const window = Duration.toMillis(Duration.fromInputUnsafe(interval))
@@ -5871,7 +5838,8 @@ export 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"
  *
@@ -5889,8 +5857,8 @@ export const windowed = (interval: Duration.Input): Schedule<number> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const forever: Schedule<number> = spaced(Duration.zero)
 
@@ -5910,8 +5878,8 @@ 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
 }
@@ -5919,7 +5887,8 @@ export {
 /**
  * Ensures that the provided schedule respects a specified input type.
  *
- * @example
+ * **Example** (Constraining schedule input types)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -5938,8 +5907,8 @@ export {
  * // where CustomType doesn't match the schedule's input type
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesInputType = <T>() =>
 <Input extends T, Output = never, Error = never, Env = never>(
@@ -5950,8 +5919,8 @@ export const satisfiesInputType = <T>() =>
  * 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 const setInputType =
   <T>() => <Output, Error, Env>(self: Schedule<Output, T, Error, Env>): Schedule<Output, T, Error, Env> => self
@@ -5959,7 +5928,8 @@ export const setInputType =
 /**
  * Ensures that the provided schedule respects a specified output type.
  *
- * @example
+ * **Example** (Constraining schedule output types)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -5973,8 +5943,8 @@ export const setInputType =
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesOutputType = <T>() =>
 <Output extends T, Error = never, Input = unknown, Env = never>(
@@ -5984,7 +5954,8 @@ export const satisfiesOutputType = <T>() =>
 /**
  * Ensures that the provided schedule respects a specified error type.
  *
- * @example
+ * **Example** (Constraining schedule error types)
+ *
  * ```ts
  * import { Data, Schedule } from "effect"
  *
@@ -6004,8 +5975,8 @@ export const satisfiesOutputType = <T>() =>
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesErrorType = <T>() =>
 <Error extends T, Output = never, Input = unknown, Env = never>(
@@ -6015,9 +5986,10 @@ export const satisfiesErrorType = <T>() =>
 /**
  * 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 {
@@ -6025,7 +5997,7 @@ export const satisfiesErrorType = <T>() =>
  * }
  *
  * interface Database {
- *   readonly query: (sql: string) => Promise<unknown>
+ *   readonly query: (sql: string) => Effect.Effect<ReadonlyArray<unknown>>
  * }
  *
  * // Ensure schedule requires Logger service
@@ -6039,8 +6011,8 @@ export const satisfiesErrorType = <T>() =>
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesServicesType = <T>() =>
 <Env extends T, Output = never, Input = unknown, Error = never>(