effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/TxQueue.ts

@@ -26,6 +26,8 @@ import type * as Types from "./Types.ts"
 /**
  * Represents the state of a transactional queue with sophisticated lifecycle management.
  *
+ * **Details**
+ *
  * The queue progresses through three states:
  * - **Open**: Accepting offers and serving takes normally
  * - **Closing**: No new offers accepted, serving remaining items until empty
@@ -335,8 +337,9 @@ const TxQueueProto = {
 /**
  * Creates a new bounded `TxQueue` with the specified capacity.
  *
- * **Return behavior**: This function returns a new TxQueue reference with
- * the specified capacity. No existing TxQueue instances are modified.
+ * **Details**
+ *
+ * This function returns a new TxQueue reference with the specified capacity. No existing TxQueue instances are modified.
  *
  * **Example** (Creating bounded queues)
  *
@@ -380,8 +383,9 @@ export const bounded = <A = never, E = never>(
 /**
  * Creates a new unbounded `TxQueue` with unlimited capacity.
  *
- * **Return behavior**: This function returns a new TxQueue reference with
- * unlimited capacity. No existing TxQueue instances are modified.
+ * **Details**
+ *
+ * This function returns a new TxQueue reference with unlimited capacity. No existing TxQueue instances are modified.
  *
  * **Example** (Creating unbounded queues)
  *
@@ -423,8 +427,9 @@ export const unbounded = <A = never, E = never>(): Effect.Effect<TxQueue<A, E>>
 /**
  * Creates a new dropping `TxQueue` with the specified capacity that drops new items when full.
  *
- * **Return behavior**: This function returns a new TxQueue reference with
- * dropping strategy. No existing TxQueue instances are modified.
+ * **Details**
+ *
+ * This function returns a new TxQueue reference with dropping strategy. No existing TxQueue instances are modified.
  *
  * **Example** (Creating dropping queues)
  *
@@ -466,8 +471,9 @@ export const dropping = <A = never, E = never>(
 /**
  * Creates a new sliding `TxQueue` with the specified capacity that evicts old items when full.
  *
- * **Return behavior**: This function returns a new TxQueue reference with
- * sliding strategy. No existing TxQueue instances are modified.
+ * **Details**
+ *
+ * This function returns a new TxQueue reference with sliding strategy. No existing TxQueue instances are modified.
  *
  * **Example** (Creating sliding queues)
  *
@@ -515,12 +521,9 @@ export const sliding = <A = never, E = never>(
 /**
  * Offers an item to the queue and returns whether it was accepted.
  *
- * Open unbounded queues always accept; open bounded queues retry while full;
- * dropping queues return `false` when full; sliding queues evict the oldest item
- * when full. Closing or done queues return `false`.
+ * **Details**
  *
- * **Mutation behavior**: This function mutates the original TxQueue by adding
- * the item according to the queue's strategy. It does not return a new TxQueue reference.
+ * Open unbounded queues always accept; open bounded queues retry while full; dropping queues return `false` when full; sliding queues evict the oldest item when full. Closing or done queues return `false`. This function mutates the original TxQueue by adding the item according to the queue's strategy. It does not return a new TxQueue reference.
  *
  * **Example** (Offering a value)
  *
@@ -547,12 +550,9 @@ export const offer: {
   /**
    * Offers an item to the queue and returns whether it was accepted.
    *
-   * Open unbounded queues always accept; open bounded queues retry while full;
-   * dropping queues return `false` when full; sliding queues evict the oldest item
-   * when full. Closing or done queues return `false`.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by adding
-   * the item according to the queue's strategy. It does not return a new TxQueue reference.
+   * Open unbounded queues always accept; open bounded queues retry while full; dropping queues return `false` when full; sliding queues evict the oldest item when full. Closing or done queues return `false`. This function mutates the original TxQueue by adding the item according to the queue's strategy. It does not return a new TxQueue reference.
    *
    * **Example** (Offering a value)
    *
@@ -579,12 +579,9 @@ export const offer: {
   /**
    * Offers an item to the queue and returns whether it was accepted.
    *
-   * Open unbounded queues always accept; open bounded queues retry while full;
-   * dropping queues return `false` when full; sliding queues evict the oldest item
-   * when full. Closing or done queues return `false`.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by adding
-   * the item according to the queue's strategy. It does not return a new TxQueue reference.
+   * Open unbounded queues always accept; open bounded queues retry while full; dropping queues return `false` when full; sliding queues evict the oldest item when full. Closing or done queues return `false`. This function mutates the original TxQueue by adding the item according to the queue's strategy. It does not return a new TxQueue reference.
    *
    * **Example** (Offering a value)
    *
@@ -647,12 +644,9 @@ export const offer: {
  * Offers multiple items to the queue, returning the items that were not
  * accepted.
  *
- * Each item follows `offer` semantics: bounded queues retry while full,
- * dropping queues reject new items when full, sliding queues evict old items to
- * accept new items, and closing or done queues reject all items.
+ * **Details**
  *
- * **Mutation behavior**: This function mutates the original TxQueue by adding
- * items according to the queue's strategy. It does not return a new TxQueue reference.
+ * Each item follows `offer` semantics: bounded queues retry while full, dropping queues reject new items when full, sliding queues evict old items to accept new items, and closing or done queues reject all items. This function mutates the original TxQueue by adding items according to the queue's strategy. It does not return a new TxQueue reference.
  *
  * **Example** (Offering multiple values)
  *
@@ -677,12 +671,9 @@ export const offerAll: {
    * Offers multiple items to the queue, returning the items that were not
    * accepted.
    *
-   * Each item follows `offer` semantics: bounded queues retry while full,
-   * dropping queues reject new items when full, sliding queues evict old items to
-   * accept new items, and closing or done queues reject all items.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by adding
-   * items according to the queue's strategy. It does not return a new TxQueue reference.
+   * Each item follows `offer` semantics: bounded queues retry while full, dropping queues reject new items when full, sliding queues evict old items to accept new items, and closing or done queues reject all items. This function mutates the original TxQueue by adding items according to the queue's strategy. It does not return a new TxQueue reference.
    *
    * **Example** (Offering multiple values)
    *
@@ -707,12 +698,9 @@ export const offerAll: {
    * Offers multiple items to the queue, returning the items that were not
    * accepted.
    *
-   * Each item follows `offer` semantics: bounded queues retry while full,
-   * dropping queues reject new items when full, sliding queues evict old items to
-   * accept new items, and closing or done queues reject all items.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by adding
-   * items according to the queue's strategy. It does not return a new TxQueue reference.
+   * Each item follows `offer` semantics: bounded queues retry while full, dropping queues reject new items when full, sliding queues evict old items to accept new items, and closing or done queues reject all items. This function mutates the original TxQueue by adding items according to the queue's strategy. It does not return a new TxQueue reference.
    *
    * **Example** (Offering multiple values)
    *
@@ -754,10 +742,9 @@ export const offerAll: {
  * Takes the next item from the queue, retrying the transaction while the queue
  * is empty.
  *
- * If the queue is done, the effect fails with the queue's completion cause.
+ * **Details**
  *
- * **Mutation behavior**: This function mutates the original TxQueue by removing
- * the first item. It does not return a new TxQueue reference.
+ * If the queue is done, the effect fails with the queue's completion cause. This function mutates the original TxQueue by removing the first item. It does not return a new TxQueue reference.
  *
  * **Example** (Taking a value)
  *
@@ -857,13 +844,9 @@ export const poll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Option.Option<A
 /**
  * Takes all items from the queue. Blocks if the queue is empty.
  *
- * If the queue is already in a failed state, the error is propagated through the E-channel.
- * Follows the same patterns as `take` - waits when there are no elements.
+ * **Details**
  *
- * Returns a non-empty array since it blocks until at least one item is available.
- *
- * **Mutation behavior**: This function mutates the original TxQueue by removing
- * all items. It does not return a new TxQueue reference.
+ * If the queue is already in a failed state, the error is propagated through the E-channel. This follows the same patterns as `take` and waits when there are no elements. It returns a non-empty array because it blocks until at least one item is available. This function mutates the original TxQueue by removing all items. It does not return a new TxQueue reference.
  *
  * **Example** (Taking all queued values)
  *
@@ -926,14 +909,9 @@ export const takeAll = <A, E>(self: TxDequeue<A, E>): Effect.Effect<Arr.NonEmpty
 /**
  * Takes up to `n` items from the queue in a single transaction.
  *
- * For an open queue, waits until `min(n, capacity)` items are available, then
- * removes that many items. If `n` is less than or equal to zero, returns an
- * empty array without modifying the queue. If the queue is closing, drains the
- * currently available items and transitions to `Done`. If the queue is already
- * done, the effect fails with the queue's completion cause.
+ * **Details**
  *
- * **Mutation behavior**: This function mutates the original TxQueue by removing
- * the taken items. It does not return a new TxQueue reference.
+ * For an open queue, waits until `min(n, capacity)` items are available, then removes that many items. If `n` is less than or equal to zero, returns an empty array without modifying the queue. If the queue is closing, drains the currently available items and transitions to `Done`. If the queue is already done, the effect fails with the queue's completion cause. This function mutates the original TxQueue by removing the taken items. It does not return a new TxQueue reference.
  *
  * **Example** (Taking a fixed number of values)
  *
@@ -961,14 +939,9 @@ export const takeN: {
   /**
    * Takes up to `n` items from the queue in a single transaction.
    *
-   * For an open queue, waits until `min(n, capacity)` items are available, then
-   * removes that many items. If `n` is less than or equal to zero, returns an
-   * empty array without modifying the queue. If the queue is closing, drains the
-   * currently available items and transitions to `Done`. If the queue is already
-   * done, the effect fails with the queue's completion cause.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by removing
-   * the taken items. It does not return a new TxQueue reference.
+   * For an open queue, waits until `min(n, capacity)` items are available, then removes that many items. If `n` is less than or equal to zero, returns an empty array without modifying the queue. If the queue is closing, drains the currently available items and transitions to `Done`. If the queue is already done, the effect fails with the queue's completion cause. This function mutates the original TxQueue by removing the taken items. It does not return a new TxQueue reference.
    *
    * **Example** (Taking a fixed number of values)
    *
@@ -996,14 +969,9 @@ export const takeN: {
   /**
    * Takes up to `n` items from the queue in a single transaction.
    *
-   * For an open queue, waits until `min(n, capacity)` items are available, then
-   * removes that many items. If `n` is less than or equal to zero, returns an
-   * empty array without modifying the queue. If the queue is closing, drains the
-   * currently available items and transitions to `Done`. If the queue is already
-   * done, the effect fails with the queue's completion cause.
+   * **Details**
    *
-   * **Mutation behavior**: This function mutates the original TxQueue by removing
-   * the taken items. It does not return a new TxQueue reference.
+   * For an open queue, waits until `min(n, capacity)` items are available, then removes that many items. If `n` is less than or equal to zero, returns an empty array without modifying the queue. If the queue is closing, drains the currently available items and transitions to `Done`. If the queue is already done, the effect fails with the queue's completion cause. This function mutates the original TxQueue by removing the taken items. It does not return a new TxQueue reference.
    *
    * **Example** (Taking a fixed number of values)
    *
@@ -1089,10 +1057,9 @@ export const takeN: {
  * Takes between `min` and `max` currently available items, waiting for `min` on
  * an open queue.
  *
- * If the queue is closing, drains the currently available items even when fewer
- * than `min` are available and transitions to `Done`. Invalid ranges
- * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
- * is already done, the effect fails with the queue's completion cause.
+ * **Details**
+ *
+ * If the queue is closing, drains the currently available items even when fewer than `min` are available and transitions to `Done`. Invalid ranges (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue is already done, the effect fails with the queue's completion cause.
  *
  * **Example** (Taking batches within bounds)
  *
@@ -1124,10 +1091,9 @@ export const takeBetween: {
    * Takes between `min` and `max` currently available items, waiting for `min` on
    * an open queue.
    *
-   * If the queue is closing, drains the currently available items even when fewer
-   * than `min` are available and transitions to `Done`. Invalid ranges
-   * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
-   * is already done, the effect fails with the queue's completion cause.
+   * **Details**
+   *
+   * If the queue is closing, drains the currently available items even when fewer than `min` are available and transitions to `Done`. Invalid ranges (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue is already done, the effect fails with the queue's completion cause.
    *
    * **Example** (Taking batches within bounds)
    *
@@ -1159,10 +1125,9 @@ export const takeBetween: {
    * Takes between `min` and `max` currently available items, waiting for `min` on
    * an open queue.
    *
-   * If the queue is closing, drains the currently available items even when fewer
-   * than `min` are available and transitions to `Done`. Invalid ranges
-   * (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue
-   * is already done, the effect fails with the queue's completion cause.
+   * **Details**
+   *
+   * If the queue is closing, drains the currently available items even when fewer than `min` are available and transitions to `Done`. Invalid ranges (`min <= 0`, `max <= 0`, or `min > max`) return an empty array. If the queue is already done, the effect fails with the queue's completion cause.
    *
    * **Example** (Taking batches within bounds)
    *
@@ -1246,9 +1211,9 @@ export const takeBetween: {
 /**
  * Waits transactionally for the next item and returns it without removing it.
  *
- * If the queue is open but empty, the transaction retries until an item is
- * available or the queue completes. If the queue is done, the queue's
- * completion cause is propagated through the error channel.
+ * **Details**
+ *
+ * If the queue is open but empty, the transaction retries until an item is available or the queue completes. If the queue is done, the queue's completion cause is propagated through the error channel.
  *
  * **Example** (Peeking without removing values)
  *
@@ -1376,10 +1341,9 @@ export const isFull = (self: TxQueueState): Effect.Effect<boolean> =>
 /**
  * Gracefully interrupts the queue with the current fiber's interruption cause.
  *
- * If the queue still contains items, it enters the closing state so buffered
- * items can be drained before consumers observe the interruption. If it is
- * empty, it transitions directly to done. Returns `false` if the queue was
- * already closing or done.
+ * **Details**
+ *
+ * If the queue still contains items, it enters the closing state so buffered items can be drained before consumers observe the interruption. If it is empty, it transitions directly to done. Returns `false` if the queue was already closing or done.
  *
  * **Example** (Interrupting queues)
  *
@@ -1405,8 +1369,9 @@ export const interrupt = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<boolean> =
 /**
  * Fails the queue with the specified error, discarding any buffered items.
  *
- * The queue transitions directly to done with `Cause.fail(error)`. Returns
- * `false` if the queue was already closing or done.
+ * **Details**
+ *
+ * The queue transitions directly to done with `Cause.fail(error)`. Returns `false` if the queue was already closing or done.
  *
  * **Example** (Failing queues)
  *
@@ -1429,8 +1394,9 @@ export const fail: {
   /**
    * Fails the queue with the specified error, discarding any buffered items.
    *
-   * The queue transitions directly to done with `Cause.fail(error)`. Returns
-   * `false` if the queue was already closing or done.
+   * **Details**
+   *
+   * The queue transitions directly to done with `Cause.fail(error)`. Returns `false` if the queue was already closing or done.
    *
    * **Example** (Failing queues)
    *
@@ -1453,8 +1419,9 @@ export const fail: {
   /**
    * Fails the queue with the specified error, discarding any buffered items.
    *
-   * The queue transitions directly to done with `Cause.fail(error)`. Returns
-   * `false` if the queue was already closing or done.
+   * **Details**
+   *
+   * The queue transitions directly to done with `Cause.fail(error)`. Returns `false` if the queue was already closing or done.
    *
    * **Example** (Failing queues)
    *
@@ -1495,9 +1462,9 @@ export const fail: {
 /**
  * Completes the queue with the specified cause.
  *
- * If the queue is empty, it transitions directly to done. If it still contains
- * items, it enters the closing state so buffered items can be drained before the
- * cause is observed. Returns `false` if the queue was already closing or done.
+ * **Details**
+ *
+ * If the queue is empty, it transitions directly to done. If it still contains items, it enters the closing state so buffered items can be drained before the cause is observed. Returns `false` if the queue was already closing or done.
  *
  * **Example** (Failing queues with causes)
  *
@@ -1521,9 +1488,9 @@ export const failCause: {
   /**
    * Completes the queue with the specified cause.
    *
-   * If the queue is empty, it transitions directly to done. If it still contains
-   * items, it enters the closing state so buffered items can be drained before the
-   * cause is observed. Returns `false` if the queue was already closing or done.
+   * **Details**
+   *
+   * If the queue is empty, it transitions directly to done. If it still contains items, it enters the closing state so buffered items can be drained before the cause is observed. Returns `false` if the queue was already closing or done.
    *
    * **Example** (Failing queues with causes)
    *
@@ -1547,9 +1514,9 @@ export const failCause: {
   /**
    * Completes the queue with the specified cause.
    *
-   * If the queue is empty, it transitions directly to done. If it still contains
-   * items, it enters the closing state so buffered items can be drained before the
-   * cause is observed. Returns `false` if the queue was already closing or done.
+   * **Details**
+   *
+   * If the queue is empty, it transitions directly to done. If it still contains items, it enters the closing state so buffered items can be drained before the cause is observed. Returns `false` if the queue was already closing or done.
    *
    * **Example** (Failing queues with causes)
    *
@@ -1595,10 +1562,9 @@ export const failCause: {
 /**
  * Ends a queue by signaling completion with a `Cause.Done` error.
  *
- * This is a convenience wrapper around `failCause` for queues whose error
- * channel can contain `Cause.Done`. If buffered items remain, the queue enters
- * the closing state and those items may still be consumed before later `take` or
- * `peek` operations fail with `Cause.Done`.
+ * **Details**
+ *
+ * This is a convenience wrapper around `failCause` for queues whose error channel can contain `Cause.Done`. If buffered items remain, the queue enters the closing state and those items may still be consumed before later `take` or `peek` operations fail with `Cause.Done`.
  *
  * **Example** (Ending queues)
  *
@@ -1631,9 +1597,9 @@ export const end = <A, E>(self: TxEnqueue<A, E | Cause.Done>): Effect.Effect<boo
  * Removes and returns all currently buffered elements without changing the
  * queue state.
  *
- * If the queue is already done with a `Cause.Done` error, returns an empty
- * array. If the queue is done for any other cause, including interruption or
- * failure, that cause is propagated.
+ * **Details**
+ *
+ * If the queue is already done with a `Cause.Done` error, returns an empty array. If the queue is done for any other cause, including interruption or failure, that cause is propagated.
  *
  * **Example** (Clearing queues)
  *
@@ -1676,12 +1642,9 @@ export const clear = <A, E>(self: TxEnqueue<A, E>): Effect.Effect<Array<A>, Excl
 /**
  * Shuts down the queue immediately by clearing all items and interrupting it (legacy compatibility).
  *
- * This operation performs two atomic steps:
- * 1. **Clears** all items from the queue using `clear()`
- * 2. **Interrupts** the queue using `interrupt()`
+ * **Details**
  *
- * **Mutation behavior**: This function mutates the original TxQueue by clearing
- * its contents and marking it as shutdown. It does not return a new TxQueue reference.
+ * This operation clears all items from the queue using `clear`, then interrupts the queue using `interrupt`. This function mutates the original TxQueue by clearing its contents and marking it as shutdown. It does not return a new TxQueue reference.
  *
  * **Example** (Shutting down queues)
  *

package/src/TxRef.ts

@@ -19,6 +19,8 @@ const TypeId = "~effect/transactions/TxRef"
 /**
  * TxRef is a transactional value, it can be read and modified within the body of a transaction.
  *
+ * **Details**
+ *
  * Accessed values are tracked by the transaction in order to detect conflicts and in order to
  * track changes, a transaction will retry whenever a conflict is detected or whenever the
  * transaction explicitely calls to `Effect.txRetry` and any of the accessed TxRef values
@@ -87,6 +89,8 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
 /**
  * Synchronously creates a new `TxRef` with the specified initial value.
  *
+ * **When to use**
+ *
  * Prefer `make` in Effect code so allocation stays inside the Effect workflow.
  * Use `makeUnsafe` only when a `TxRef` must be constructed outside an effect.
  *

package/src/TxSemaphore.ts

@@ -32,10 +32,10 @@ import * as TxRef from "./TxRef.ts"
 const TypeId = "~effect/transactions/TxSemaphore"
 
 /**
- * A transactional semaphore that manages permits using Software Transactional Memory (STM) semantics.
- *
- * TxSemaphore provides atomic permit acquisition and release operations within Effect transactions,
- * ensuring thread-safe concurrency control for limited resources.
+ * A transactional semaphore that manages permits using Software Transactional
+ * Memory (STM) semantics, providing atomic permit acquisition and release
+ * operations within Effect transactions for concurrency control over limited
+ * resources.
  *
  * **Example** (Managing permits transactionally)
  *
@@ -223,10 +223,15 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
 /**
  * Acquires the specified number of permits from the semaphore.
  *
+ * **Details**
+ *
  * If fewer than `n` permits are available, the transaction retries until enough
- * permits are released. Passing a non-positive `n` dies with a defect. Passing a
- * value greater than the semaphore capacity will wait forever unless the
- * semaphore's capacity can somehow be changed externally.
+ * permits are released.
+ *
+ * **Gotchas**
+ *
+ * Passing a non-positive `n` dies with a defect. Passing a value greater than
+ * the semaphore capacity can wait forever because the capacity is fixed.
  *
  * **Example** (Acquiring multiple permits)
  *
@@ -262,8 +267,8 @@ export const acquireN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
 }
 
 /**
- * Tries to acquire a single permit from the semaphore without blocking.
- * Returns true if successful, false if no permits are available.
+ * Tries to acquire a single permit from the semaphore without blocking,
+ * returning `true` if successful or `false` if no permits are available.
  *
  * **Example** (Trying to acquire a permit)
  *
@@ -295,8 +300,9 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
   })
 
 /**
- * Tries to acquire the specified number of permits from the semaphore without blocking.
- * Returns true if successful, false if not enough permits are available.
+ * Tries to acquire the specified number of permits from the semaphore without
+ * blocking, returning `true` if successful or `false` if not enough permits are
+ * available.
  *
  * **Example** (Trying to acquire multiple permits)
  *
@@ -335,6 +341,8 @@ export const tryAcquireN = (self: TxSemaphore, n: number): Effect.Effect<boolean
  * Releases one permit back to the semaphore, making it available for
  * acquisition.
  *
+ * **Details**
+ *
  * If the semaphore is already at capacity, this operation leaves the permit
  * count unchanged.
  *
@@ -367,8 +375,13 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
 /**
  * Releases the specified number of permits back to the semaphore.
  *
- * The available permit count is capped at the semaphore capacity. Passing a
- * non-positive `n` dies with a defect.
+ * **Details**
+ *
+ * The available permit count is capped at the semaphore capacity.
+ *
+ * **Gotchas**
+ *
+ * Passing a non-positive `n` dies with a defect.
  *
  * **Example** (Releasing multiple permits)
  *
@@ -408,8 +421,10 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void> => {
  * automatically acquired before execution and released afterwards, even if the
  * effect fails or is interrupted.
  *
- * **Note**: The permit acquisition and release operations use atomic semantics
- * to ensure proper resource management with Effect's scoped operations.
+ * **Details**
+ *
+ * The permit acquisition and release operations use atomic semantics to ensure
+ * proper resource management with Effect's scoped operations.
  *
  * **Example** (Running an effect with a permit)
  *
@@ -444,8 +459,10 @@ export const withPermit: {
    * automatically acquired before execution and released afterwards, even if the
    * effect fails or is interrupted.
    *
-   * **Note**: The permit acquisition and release operations use atomic semantics
-   * to ensure proper resource management with Effect's scoped operations.
+   * **Details**
+   *
+   * The permit acquisition and release operations use atomic semantics to ensure
+   * proper resource management with Effect's scoped operations.
    *
    * **Example** (Running an effect with a permit)
    *
@@ -480,8 +497,10 @@ export const withPermit: {
    * automatically acquired before execution and released afterwards, even if the
    * effect fails or is interrupted.
    *
-   * **Note**: The permit acquisition and release operations use atomic semantics
-   * to ensure proper resource management with Effect's scoped operations.
+   * **Details**
+   *
+   * The permit acquisition and release operations use atomic semantics to ensure
+   * proper resource management with Effect's scoped operations.
    *
    * **Example** (Running an effect with a permit)
    *
@@ -533,9 +552,15 @@ export const withPermit: {
  * Runs an effect while holding the specified number of permits from the
  * semaphore.
  *
+ * **Details**
+ *
  * The permits are acquired before the effect starts and released after it
- * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
- * defect; passing a value greater than the semaphore capacity can wait forever.
+ * completes, fails, or is interrupted.
+ *
+ * **Gotchas**
+ *
+ * Passing a non-positive `n` dies with a defect. Passing a value greater than
+ * the semaphore capacity can wait forever.
  *
  * **Example** (Running an effect with multiple permits)
  *
@@ -569,9 +594,15 @@ export const withPermits: {
    * Runs an effect while holding the specified number of permits from the
    * semaphore.
    *
+   * **Details**
+   *
    * The permits are acquired before the effect starts and released after it
-   * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
-   * defect; passing a value greater than the semaphore capacity can wait forever.
+   * completes, fails, or is interrupted.
+   *
+   * **Gotchas**
+   *
+   * Passing a non-positive `n` dies with a defect. Passing a value greater than
+   * the semaphore capacity can wait forever.
    *
    * **Example** (Running an effect with multiple permits)
    *
@@ -605,9 +636,15 @@ export const withPermits: {
    * Runs an effect while holding the specified number of permits from the
    * semaphore.
    *
+   * **Details**
+   *
    * The permits are acquired before the effect starts and released after it
-   * completes, fails, or is interrupted. Passing a non-positive `n` dies with a
-   * defect; passing a value greater than the semaphore capacity can wait forever.
+   * completes, fails, or is interrupted.
+   *
+   * **Gotchas**
+   *
+   * Passing a non-positive `n` dies with a defect. Passing a value greater than
+   * the semaphore capacity can wait forever.
    *
    * **Example** (Running an effect with multiple permits)
    *
@@ -660,8 +697,10 @@ export const withPermits: {
  * will be automatically released when the scope is closed, even if effects
  * within the scope fail or are interrupted.
  *
- * **Note**: The permit acquisition and release operations use atomic semantics
- * to ensure proper resource management with Effect's scoped operations.
+ * **Details**
+ *
+ * The permit acquisition and release operations use atomic semantics to ensure
+ * proper resource management with Effect's scoped operations.
  *
  * **Example** (Acquiring a scoped permit)
  *