@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/streams/{sink.md → core/sink.md}

@@ -1,23 +1,36 @@
 ---
 id: sink
 title: "Sink"
+sidebar_label: "Sink"
+description: "The stream consumer: its dual synchronous and asynchronous drains, the three construction factories, and the async aggregation and transformation combinators."
+keywords:
+  - "Stream Consumer"
+  - "Dual Drain"
+  - "Async Sinks"
+  - "Custom Sink Factories"
+  - "Sink"
 ---
 
-`Sink[+E, -A, +Z]` is a **stream consumer** that reads elements of type `A` and produces a result of type `Z`, potentially failing with an error of type `E`. You pass a sink to [Stream.run](./stream.md) to execute the stream synchronously and get `Either[E, Z]`.
+`Sink[+E, -A, +Z]` is a **stream consumer** that reads elements of type `A` and produces a result of type `Z`, potentially failing with an error of type `E`. Every sink has synchronous and asynchronous drain paths: use cross-platform `Stream.runAsync`, or the JVM-only blocking `Stream.run`.
 
 `Sink`:
 - Is covariant in `E` (error) and `Z` (result) — these are outputs
 - Is contravariant in `A` (input) — a `Sink[_, Any, _]` accepts any element type
-- Participates in JVM primitive specialization for zero-boxing overhead
+- Dispatches on the reader's physical primitive lane, so element pulls avoid boxing
 - Provides `Sink#contramap`, `Sink#map`, and `Sink#mapError` for composable transformations
 
+Built-in sinks implement both drain paths. Asynchronous constructors include `existsAsync`, `findAsync`, `forallAsync`, `foreachAsync`, and `foldLeftAsync`; callbacks are sequential and back-pressured. The result/error combinators `contramapAsync`, `mapAsync`, and `mapErrorAsync` likewise select the native async drain when used by `runAsync`. On the JVM, driving such a sink through a plain blocking terminal blocks while awaiting its async drain; Scala.js has no blocking terminal.
+
 Here is the structural shape of the `Sink` type:
 
 ```scala
 abstract class Sink[+E, -A, +Z] {
-  def contramap[A2](g: A2 => A): Sink[E, A2, Z]
+  def contramap[A0 <: A, A2](g: A2 => A0)(implicit jtA0: JvmType.Infer[A0]): Sink[E, A2, Z]
+  def contramapAsync[A0 <: A, A2](g: A2 => Async[A0])(implicit jtA0: JvmType.Infer[A0]): Sink[E, A2, Z]
   def map[Z2](f: Z => Z2): Sink[E, A, Z2]
-  def mapError[E2](f: E => E2): Sink[E2, A, Z]
+  def mapAsync[Z2](f: Z => Async[Z2]): Sink[E, A, Z2]
+  def mapError[E2](f: E => E2)(implicit isNothing: Sink.IsNothing[E]): Sink[E2, A, Z]
+  def mapErrorAsync[E2](f: E => Async[E2])(implicit isNothing: Sink.IsNothing[E]): Sink[E2, A, Z]
 }
 ```
 
@@ -40,7 +53,83 @@ When you call `stream.run(sink)`:
 2. The sink's internal `Sink#drain` method pulls elements in a tight loop until end-of-stream
 3. On success, the result wraps in `Right(z)`
 4. Typed errors (`E`) surface as `Left(e)`, while untyped defects propagate as exceptions
-5. The reader's `close()` runs in a `finally` block, ensuring resource safety
+5. The reader's `close()` runs after the drain whether it succeeded or threw, and a failure from `close()` is attached to the drain's own error rather than replacing it, ensuring resource safety
+
+### Physical Input Lanes and Ownership
+
+A sink consumes either kind of reader. `Reader` is not one type with a mode flag: it splits into `Reader.SyncReader[A]`, whose pulls return values, and `Reader.AsyncReader[A]`, whose pulls return [`Async`](../../async.md) values. [The reader union](../primitives/reader.md#the-reader-union) describes the split from the reader's side. From the sink's side, the consequence is that every sink is drained through one of two entry points, and the terminal decides which — the next section covers that choice.
+
+Whichever kind arrives, a sink discovers its input representation from the materialized reader's `jvmType`, not from the sink's contravariant static input type. Generic sinks dispatch once per drain and then pull `Boolean`, `Byte`, `Char`, `Short`, `Int`, `Long`, `Float`, and `Double` through library-internal physical pulls. The synchronous drain uses `readBooleanPhysical`, `readBytePhysical`, `readCharPhysical`, `readShortPhysical`, `readIntPhysical`, `readLongsPhysical`, `readFloatPhysical`, and `readDoublesPhysical`, respectively; the asynchronous drain differs on two lanes, pulling `Byte` through `readBytesPhysical` and `Float` through `readFloatsPhysical`. These are the internal counterparts of the public `readBoolean`, `readByte`, `readChar`, `readShort`, `readInt`, `readLongs`, `readFloat`, and `readDoubles`, which a generic sink cannot call because all but `readByte` demand `Elem <:< X` evidence it has no way to supply. Reference inputs use generic `read`. In particular, the four small primitive lanes do not share the `Int` pull.
+
+`Long` and `Double` use one-element primitive arrays with `readLongsPhysical(scratch, 0, 1)` and `readDoublesPhysical(scratch, 0, 1)`, and on the asynchronous drain `Byte` and `Float` use one-element arrays in the same way. The returned count carries end-of-stream status out of band, so every `Long` value and every raw `Double` bit pattern—including NaN payloads—remains valid data. The scratch storage is allocated once per drain, not once per element.
+
+The reader owns this physical representation. Consequently, widening a specialized stream (for example, from `Stream[Nothing, Int]` to `Stream[Nothing, AnyVal]`) does not erase its `Int` lane before it reaches a sink. A sink adapter preserves the wrapped reader's lane and forwards every exact pull method. It also preserves ownership: the run terminal owns and closes the materialized reader; a sink or sink adapter does not independently close it. External destinations supplied to I/O sinks remain caller-owned unless a constructor explicitly says otherwise.
+
+## Consuming Asynchronous Readers
+
+Every sink carries two drains, one per reader kind:
+
+```scala
+abstract class Sink[+E, -A, +Z] {
+  private[streams] def drain(reader: Reader.SyncReader[_]): Z
+  private[streams] def drain(reader: Reader.AsyncReader[_]): Async[Z]
+}
+```
+
+They are an overload on the argument type, not a runtime branch inside one method, so the selection is a static one made where the reader is known: at the terminal. Both are `private[streams]`, which means you never call either yourself. The terminal you already chose called one of them for you:
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│      Stream#run  (JVM only)         Stream#runAsync  (JVM and JS)  │
+│                 │ materializes                    │ materializes   │
+│                 ▼                                 ▼                │
+│       Reader.SyncReader[A]              Reader.AsyncReader[A]      │
+│                 │ is handed to                    │ is handed to   │
+│                 ▼                                 ▼                │
+│       drain(SyncReader): Z          drain(AsyncReader): Async[Z]   │
+│                 │ returns                         │ returns        │
+│                 ▼                                 ▼                │
+│           Either[E, Z]                   Async[Either[E, Z]]       │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+The asynchronous drain is a native one, not an adapter: `Stream#runAsync` hands the sink a `Reader.AsyncReader` and never converts it to a blocking reader first, so no thread is parked waiting for a pull. [Async Terminals](../execution-and-compatibility/async-execution.md#async-terminals) covers the terminal family that takes this path, and [The `Async[Either[E, Z]]` convention](../execution-and-compatibility/async-execution.md#the-asynceithere-z-convention) explains why the typed error stays inside the `Either`.
+
+Every built-in sink implements both drains, so nothing on this page is available on only one path. A third member, `drainAsync(reader: Reader.SyncReader[_]): Async[Z]`, is likewise `private[streams]`; it presents a synchronous reader through the asynchronous contract by calling `reader.toAsync`, and exists for internal stages that must expose an asynchronous face over synchronous input.
+
+### Choosing a Factory
+
+Because a `Sink` has two abstract drains and both are `private[streams]`, code outside `zio.blocks.streams` cannot implement them — subclassing `Sink` directly is not a supported route, and the compiler will not let you complete the class. Build custom sinks from one of the three factories instead:
+
+```scala
+object Sink {
+  // JVM and Scala.js
+  def createAsync[E, A, Z](f: Reader.AsyncReader[A] => Async[Z]): Sink[E, A, Z]
+  def createBoth[E, A, Z](
+    sync: Reader.SyncReader[A] => Z,
+    async: Reader.AsyncReader[A] => Async[Z]
+  ): Sink[E, A, Z]
+
+  // JVM only — absent from the Scala.js companion entirely
+  def create[E, A, Z](f: Reader.SyncReader[A] => Z): Sink[E, A, Z]
+}
+```
+
+Each factory fills in the drain you did not write:
+
+| Factory            | Callbacks you write               | Platforms        | Reach for it when                                                    |
+|--------------------|-----------------------------------|------------------|----------------------------------------------------------------------|
+| `Sink.createAsync` | one asynchronous                  | JVM and Scala.js | one implementation is enough, and awaiting per element is acceptable |
+| `Sink.createBoth`  | one synchronous, one asynchronous | JVM and Scala.js | the synchronous path can be cheaper than the asynchronous one        |
+| `Sink.create`      | one synchronous                   | JVM only         | the sink is JVM-only anyway and its callback wants a blocking reader |
+
+`Sink.createAsync` writes the synchronous drain for you by awaiting the asynchronous one at a JVM blocking terminal. `Sink.create` writes the asynchronous drain for you by deferring the blocking callback into a cancellable effect, where cancellation closes the reader — the callback still runs inline on whichever thread drives that effect, so an asynchronous terminal driving a `Sink.create` sink blocks that thread for the duration of the callback. `Sink.createBoth` writes neither: it takes two independent callbacks and the terminal runs exactly one, so the two must agree on how much input they consume and what they produce — nothing compares their results.
+
+:::warning[`Sink.create` does not exist on Scala.js]
+It is declared in the JVM copy of `SinkCompanionPlatformSpecific` and simply absent from the Scala.js copy, so cross-built code that calls it fails to compile for the JS target rather than failing at runtime. [`Sink.create` and Custom Sinks](../execution-and-compatibility/platform-differences.md#sinkcreate-and-custom-sinks) states the platform rule.
+:::
+
+[Custom sink factories](#custom-sink-factories) shows a worked callback against the reader protocol.
 
 ## Predefined Sinks
 
@@ -128,9 +217,9 @@ Sinks are created using factory methods on the companion object. These methods f
 
 Gather elements into collections:
 
-#### `Sink.collectAll[A]` — Collect into a Chunk
+#### `Sink.collectAll[A]` — Collect Into a Chunk
 
-Collects all elements into a `Chunk[A]`:
+Collects all elements into a [`Chunk[A]`](../../chunk.md):
 
 ```scala
 object Sink {
@@ -176,7 +265,7 @@ Folds all elements using an accumulator function, starting from initial value `z
 
 ```scala
 object Sink {
-  def foldLeft[A, Z](z: Z)(f: (Z, A) => Z): Sink[Nothing, A, Z]
+  def foldLeft[A, Z](z: Z)(f: (Z, A) => Z)(implicit jtZ: JvmType.Infer[Z]): Sink[Nothing, A, Z]
 }
 ```
 
@@ -319,6 +408,49 @@ val result = Stream(1, 2, 3).run(Sink.foreach[Int](x => println(s"Got: $x")))
 // result: Either[Nothing, Unit] = Right(())
 ```
 
+### Async Aggregation and Search
+
+Five of the aggregation, search, and effectful sinks have an `*Async` twin whose callback returns `Async` instead of a value. The twin consumes the same input and returns the same result type; only the callback's shape differs:
+
+```scala
+object Sink {
+  def existsAsync[A](pred: A => Async[Boolean]): Sink[Nothing, A, Boolean]
+  def findAsync[A](pred: A => Async[Boolean]): Sink[Nothing, A, Option[A]]
+  def foldLeftAsync[A, Z](z: Z)(f: (Z, A) => Async[Z])(implicit jtZ: JvmType.Infer[Z]): Sink[Nothing, A, Z]
+  def forallAsync[A](pred: A => Async[Boolean]): Sink[Nothing, A, Boolean]
+  def foreachAsync[A](f: A => Async[Unit]): Sink[Nothing, A, Unit]
+}
+```
+
+Each stops where its synchronous twin stops:
+
+| Async sink           | Sync twin       | Result      | Stops pulling at                                             |
+|----------------------|-----------------|-------------|--------------------------------------------------------------|
+| `Sink.existsAsync`   | `Sink.exists`   | `Boolean`   | the first `true`; otherwise end-of-stream, returning `false` |
+| `Sink.findAsync`     | `Sink.find`     | `Option[A]` | the first match; otherwise end-of-stream, returning `None`   |
+| `Sink.foldLeftAsync` | `Sink.foldLeft` | `Z`         | end-of-stream                                                |
+| `Sink.forallAsync`   | `Sink.forall`   | `Boolean`   | the first `false`; otherwise end-of-stream, returning `true` |
+| `Sink.foreachAsync`  | `Sink.foreach`  | `Unit`      | end-of-stream                                                |
+
+Three properties hold across all five. At most one callback effect runs at a time, in encounter order, so these are sequential and back-pressured rather than concurrent — for concurrency, put it in the stream with [`Stream#mapParAsync`](./stream.md#streammapparasync) before the sink. No effect is started for input the sink never pulls, so short-circuiting still costs nothing after the decisive element. And a callback that fails or is cancelled fails or cancels the run as a *defect*, not as a value in the sink's typed error channel `E` — all five have `E = Nothing`.
+
+`Sink.foldLeftAsync` carries the same `JvmType.Infer[Z]` evidence as `Sink.foldLeft`. It keeps the asynchronous fold aligned with the specialized synchronous one; the semantics are identical.
+
+```scala
+import zio.blocks.async._
+import zio.blocks.streams._
+
+val readings = Stream(12, 7, 30, 21, 5)
+
+// Sequential: one predicate effect at a time, stopping at 30.
+val tooHot: Async[Either[Nothing, Boolean]] =
+  readings.runAsync(Sink.existsAsync[Int](c => Async.succeed(c > 25)))
+
+// The fold visits every element; the accumulator is threaded through Async.
+val total: Async[Either[Nothing, Long]] =
+  readings.runAsync(Sink.foldLeftAsync(0L)((sum: Long, c: Int) => Async.succeed(sum + c)))
+```
+
 ### Failing
 
 These sinks can be used to produce typed errors or fail under specific conditions:
@@ -341,7 +473,7 @@ import zio.blocks.streams._
 val sink: Sink[String, Int, Long] =
   if (false) Sink.count
   else Sink.fail("not ready")
-// sink: Sink[String, Int, Long] = zio.blocks.streams.Sink$$anon$8@a09b6b
+// sink: Sink[String, Int, Long] = zio.blocks.streams.Sink$$anon$7@7fdf129
 
 val result = Stream(1, 2, 3).run(sink)
 // result: Either[String, Long] = Left("not ready")
@@ -371,11 +503,11 @@ val bos = new ByteArrayOutputStream()
 
 // Write first batch of bytes
 Stream.fromChunk(zio.blocks.chunk.Chunk[Byte](72, 105)).run(Sink.fromOutputStream(bos))
-// res14: Either[Nothing, Unit] = Right(())
+// res15: Either[Nothing, Unit] = Right(())
 
 // Write second batch to the same stream (reuse it)
 Stream.fromChunk(zio.blocks.chunk.Chunk[Byte](33)).run(Sink.fromOutputStream(bos))
-// res15: Either[Nothing, Unit] = Right(())
+// res16: Either[Nothing, Unit] = Right(())
 
 // When done writing all batches, YOU close the stream
 bos.close()
@@ -408,7 +540,7 @@ val writer = new StringWriter()
 // Write a stream of individual characters
 Stream('H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd')
   .run(Sink.fromJavaWriter(writer))
-// res18: Either[Nothing, Unit] = Right(())
+// res19: Either[Nothing, Unit] = Right(())
 
 // Get the final string
 val result = writer.toString()
@@ -421,18 +553,22 @@ Like `Sink.fromOutputStream`, this sink intentionally does not close the writer.
 
 Advanced low-level use cases with direct reader protocol access:
 
-#### `Sink.create[E, A, Z]` — Escape Hatch
+#### Custom Sink Factories
 
-Creates a sink from a raw function that takes a `Reader[A]` and returns `Z`. This is the low-level escape hatch for writing sinks that cannot be expressed using the built-in factories:
+`createAsync` is the cross-platform escape hatch for a native asynchronous drain. `createBoth` supplies independent native synchronous and asynchronous drains. The plain `create` factory is JVM-only because its callback consumes a blocking `SyncReader`:
 
 ```scala
 object Sink {
-  def create[E, A, Z](f: Reader[A] => Z): Sink[E, A, Z]
+  def createAsync[E, A, Z](f: Reader.AsyncReader[A] => Async[Z]): Sink[E, A, Z]
+  def createBoth[E, A, Z](sync: Reader.SyncReader[A] => Z,
+                           async: Reader.AsyncReader[A] => Async[Z]): Sink[E, A, Z]
+  // JVM only
+  def create[E, A, Z](f: Reader.SyncReader[A] => Z): Sink[E, A, Z]
 }
 ```
 
 :::note
-`Sink.create` gives you direct access to the `Reader`, so you are responsible for using the correct read protocol (`Reader#read(sentinel)` for AnyRef, `Reader#readInt(sentinel)` for Int, etc.). Prefer the built-in sinks when possible.
+These factories give you direct access to the reader protocol. Await asynchronous pulls sequentially and prefer built-in sinks when possible.
 :::
 
 Here's a custom sink that computes the average of all integers in a stream:
@@ -445,7 +581,7 @@ import zio.blocks.streams.io.Reader
 val average = Sink.create[Nothing, Int, Double] { reader =>
   def loop(sum: Long, count: Long): (Long, Long) = {
     val v = reader.readInt(Long.MinValue)
-    if (v.asInstanceOf[Long] == Long.MinValue) (sum, count)
+    if (v == Long.MinValue) (sum, count)
     else {
       val newSum = sum + v
       loop(newSum, count + 1)
@@ -456,7 +592,7 @@ val average = Sink.create[Nothing, Int, Double] { reader =>
 }
 ```
 
-This example shows how `Sink.create` works. The reader reads elements using `Reader#read[Any](null)` — the sentinel protocol — where `null` signals "read the next element" and the function returns `null` when the stream ends. We accumulate the sum and count via recursion, then return the average. You'd use `Sink.create` when no built-in sink provides the exact aggregation or transformation logic you need — it's powerful but requires understanding the low-level [Reader protocol](./reader.md).
+This example shows how `Sink.create` works. `readInt` widens an `Int` to `Long`, leaving `Long.MinValue` available as an out-of-domain end marker. For full-domain `Long` and `Double` inputs, do not choose a data sentinel: allocate a reusable one-element primitive array and use `readLongs` or `readDoubles`, whose returned count reports data or end-of-stream without collisions. You'd use `Sink.create` when no built-in sink provides the exact aggregation or transformation logic you need — it is powerful but requires understanding the low-level [Reader protocol](../primitives/reader.md).
 
 ## Transforming Sinks
 
@@ -467,11 +603,13 @@ Every sink can be transformed using these instance methods:
 Transforms the input elements before they reach the sink. The sink's result and error types are unchanged:
 
 ```scala
-trait Sink[+E, -A, +Z] {
-  def contramap[A2](g: A2 => A): Sink[E, A2, Z]
+abstract class Sink[+E, -A, +Z] {
+  def contramap[A0 <: A, A2](g: A2 => A0)(implicit jtA0: JvmType.Infer[A0]): Sink[E, A2, Z]
 }
 ```
 
+The evidence describes the callback's **result** type `A0`, not the new sink input `A2`. The bound `A0 <: A` is variance-sound for contravariant `A`, while invariant `JvmType.Infer[A0]` lets the mapped reader advertise the callback's exact physical result lane. Primitive results therefore retain their exact lane; the `AnyRef` fallback deliberately uses the boxed reference lane. `contramapAsync` has the same evidence and representation rules for `A2 => Async[A0]`. Both adapters transform only elements requested by the wrapped sink, preserve short-circuiting, and leave reader closure to the run terminal.
+
 `Sink#contramap` is the dual of `Sink#map`: it transforms what goes *in*, not what comes *out*:
 
 ```scala
@@ -479,8 +617,8 @@ import zio.blocks.streams._
 
 // A sink that counts the length of strings
 val totalLength: Sink[Nothing, String, Long] =
-  Sink.sumInt.contramap[String](_.length)
-// totalLength: Sink[Nothing, String, Long] = zio.blocks.streams.Sink$Contramapped@5360fe09
+  Sink.sumInt.contramap[Int, String](_.length)
+// totalLength: Sink[Nothing, String, Long] = zio.blocks.streams.Sink$Contramapped@288bf077
 
 val result = Stream("hello", "world").run(totalLength)
 // result: Either[Nothing, Long] = Right(10L)
@@ -491,7 +629,7 @@ val result = Stream("hello", "world").run(totalLength)
 Transforms the result after the sink finishes draining:
 
 ```scala
-trait Sink[+E, -A, +Z] {
+abstract class Sink[+E, -A, +Z] {
   def map[Z2](f: Z => Z2): Sink[E, A, Z2]
 }
 ```
@@ -503,7 +641,7 @@ import zio.blocks.streams._
 
 val countAsString: Sink[Nothing, Any, String] =
   Sink.count.map(n => s"Total: $n elements")
-// countAsString: Sink[Nothing, Any, String] = zio.blocks.streams.Sink$Mapped@96f085b
+// countAsString: Sink[Nothing, Any, String] = zio.blocks.streams.Sink$Mapped@36040911
 
 val result = Stream(1, 2, 3).run(countAsString)
 // result: Either[Nothing, String] = Right("Total: 3 elements")
@@ -514,12 +652,12 @@ val result = Stream(1, 2, 3).run(countAsString)
 Transforms the error channel of a sink:
 
 ```scala
-trait Sink[+E, -A, +Z] {
-  inline def mapError[E2](f: E => E2): Sink[E2, A, Z]
+abstract class Sink[+E, -A, +Z] {
+  def mapError[E2](f: E => E2)(implicit isNothing: Sink.IsNothing[E]): Sink[E2, A, Z]
 }
 ```
 
-This method uses Scala 3's `inline` + `summonFrom` to perform a compile-time check: if `E` is `Nothing` (the sink never fails), the compiler elides the wrapper entirely and returns `this` cast to the new type with zero allocation:
+The `IsNothing` evidence records whether `E` is `Nothing`. For an infallible sink the method returns the same sink without allocating a wrapper; otherwise it maps typed errors:
 
 ```scala
 import zio.blocks.streams._
@@ -532,6 +670,76 @@ val mapped = Sink.drain.mapError[String](_.toString)
 val failing = Sink.fail("oops").mapError[RuntimeException](new RuntimeException(_))
 ```
 
+### `Sink#contramapAsync[A2]` — Pre-Process Input Asynchronously
+
+Applies an asynchronous function to each element before it reaches the sink:
+
+```scala
+abstract class Sink[+E, -A, +Z] {
+  def contramapAsync[A0 <: A, A2](g: A2 => Async[A0])(implicit jtA0: JvmType.Infer[A0]): Sink[E, A2, Z]
+}
+```
+
+The evidence is the same as `Sink#contramap`'s and targets the callback's **result** type `A0`, not the new sink input `A2`. `g` runs sequentially, one effect at a time, as the wrapped sink requests elements, so short-circuiting is unchanged and `g` is never started for input the sink does not pull. A failed or cancelled `g` fails or cancels the run as a defect and stops pulling input; it does not appear in the sink's typed error channel.
+
+```scala
+import zio.blocks.async._
+import zio.blocks.streams._
+
+// Resolve each identifier to a length before counting it
+val totalLength: Sink[Nothing, String, Long] =
+  Sink.sumInt.contramapAsync[Int, String](id => Async.succeed(id.length))
+
+val result: Async[Either[Nothing, Long]] =
+  Stream("hello", "world").runAsync(totalLength)
+```
+
+### `Sink#mapAsync[Z2]` — Transform Result Asynchronously
+
+Transforms the result asynchronously after the sink finishes draining:
+
+```scala
+abstract class Sink[+E, -A, +Z] {
+  def mapAsync[Z2](f: Z => Async[Z2]): Sink[E, A, Z2]
+}
+```
+
+`f` runs once, after the drain completes, so it does not change input consumption. When the sink fails, `f` is never started. Failure or cancellation of `f` fails or cancels the run as a defect.
+
+```scala
+import zio.blocks.async._
+import zio.blocks.streams._
+
+val persistedCount: Sink[Nothing, Any, String] =
+  Sink.count.mapAsync(n => Async.succeed(s"Total: $n elements"))
+
+val result: Async[Either[Nothing, String]] =
+  Stream(1, 2, 3).runAsync(persistedCount)
+```
+
+### `Sink#mapErrorAsync[E2]` — Transform Error Asynchronously
+
+Transforms the typed error channel asynchronously:
+
+```scala
+abstract class Sink[+E, -A, +Z] {
+  def mapErrorAsync[E2](f: E => Async[E2])(implicit isNothing: Sink.IsNothing[E]): Sink[E2, A, Z]
+}
+```
+
+It carries the same `IsNothing` evidence as `Sink#mapError`: for an infallible sink (`E = Nothing`) the method returns the same sink without allocating a wrapper, and `f` can never be evaluated. Successful results, upstream stream errors, and defects pass through untransformed; only the sink's own typed error reaches `f`. Failure or cancellation of `f` is a defect.
+
+```scala
+import zio.blocks.async._
+import zio.blocks.streams._
+
+// Infallible: no wrapper is allocated and `f` can never run
+val mapped = Sink.drain.mapErrorAsync[String](e => Async.succeed(e.toString))
+
+// Fallible: the typed error is transformed before it reaches the `Left`
+val failing = Sink.fail("oops").mapErrorAsync[RuntimeException](e => Async.succeed(new RuntimeException(e)))
+```
+
 ## Integration with Stream
 
 `Stream.run(sink)` is the primary entry point. ZIO Blocks also provides convenience methods on `Stream` that delegate to built-in sinks:
@@ -564,7 +772,7 @@ import zio.blocks.chunk.Chunk
 val cleanAndCollect: Sink[Nothing, String, Chunk[String]] =
   Pipeline.map[String, String](_.trim.toLowerCase)
     .andThenSink(Sink.collectAll[String])
-// cleanAndCollect: Sink[Nothing, String, Chunk[String]] = zio.blocks.streams.Sink$Contramapped@2d273af9
+// cleanAndCollect: Sink[Nothing, String, Chunk[String]] = zio.blocks.streams.Sink$Contramapped@5d54c379
 
 val result = Stream("  Hello ", " WORLD  ").run(cleanAndCollect)
 // result: Either[Nothing, Chunk[String]] = Right(IndexedSeq("hello", "world"))
@@ -576,11 +784,13 @@ See [Pipeline — Applying to a Sink](./pipeline.md#applying-to-a-sink) for more
 
 ## JVM NIO Sinks
 
-The `NioSinks` object (JVM-only) provides sinks for Java NIO (`java.nio`) buffers and channels. These exist because NIO is the standard high-performance I/O mechanism on the JVM: non-blocking, memory-efficient, and capable of handling thousands of concurrent connections. When you're writing to network sockets, memory-mapped files, or other NIO-based resources, these sinks give you a convenient way to drain streams directly into NIO data structures without intermediate allocation or copying.
+The `NioSinks` object (JVM-only) provides sinks for Java NIO (`java.nio`) buffers and channels. NIO offers efficient buffers and both blocking and selector-based channel APIs, but these sinks use blocking channel writes; they do not expose selector-based non-blocking output. When you're writing to network sockets, files, or other NIO-based resources, these sinks give you a convenient way to drain streams directly into NIO data structures.
 
-Traditional Java I/O (`OutputStream`, `Writer`) blocks threads and requires manual buffering for efficiency. NIO provides non-blocking channels, but using them directly requires buffer allocation, position management, and explicit flushing. `NioSinks` bridges this gap: `NioSinks.fromChannel` handles buffering automatically (default 8KB), while typed variants like `NioSinks.fromByteBufferInt` and `NioSinks.fromByteBufferLong` eliminate boxing overhead by writing primitives directly to buffers you provide.
+Traditional Java I/O (`OutputStream`, `Writer`) blocks threads and requires manual buffering for efficiency. `NioSinks.fromChannel` also blocks, but handles buffer allocation, position management, and flushing automatically (default 8KB), while typed variants like `NioSinks.fromByteBufferInt` and `NioSinks.fromByteBufferLong` eliminate boxing overhead by writing primitives directly to buffers you provide.
 
-Choose `NioSinks.fromChannel` when you need to write to network sockets or files and cannot afford to block threads. Choose typed variants when you control buffer allocation and are streaming millions of primitives where boxing would degrade performance. **Important:** Read the Sentinel Value Limitation section below—it describes a hard constraint that affects your choice depending on whether your data can contain specific values.
+Choose `NioSinks.fromChannel` when blocking channel output is acceptable and you want automatic buffering for network sockets or files. Choose typed variants when you control buffer allocation and are streaming millions of primitives where boxing would degrade performance.
+
+Each of these sinks implements both drains, so NIO output works under the blocking `Stream#run` and under `Stream#runAsync` alike. What the asynchronous drain removes is the thread parked waiting for stream *input*; the destination writes are the same blocking `java.nio` calls on either path. `NioSinks.fromChannel` does budget its asynchronous flush loop: when a channel write makes no progress it yields instead of spinning, so a stalled channel does not monopolise the caller. [Reader](../primitives/reader.md#from-native-asynchronous-sources) covers the NIO adapters on the source side in full, and this page does not duplicate them.
 
 Here are the available NIO sinks:
 
@@ -598,8 +808,8 @@ object NioSinks {
 ### From ByteBuffer Sinks
 
 **`NioSinks.fromByteBuffer` and typed variants** — Write primitive streams directly into a pre-allocated NIO ByteBuffer:
-- `NioSinks.fromByteBuffer` — writes individual `Byte` elements using a read sentinel of `-1`. Use only for unstructured byte data.
-- `NioSinks.fromByteBufferInt`, `NioSinks.fromByteBufferLong`, `NioSinks.fromByteBufferFloat`, `NioSinks.fromByteBufferDouble` — write primitives directly using the buffer's native methods (`putInt`, `putLong`, etc.). These avoid boxing and are faster than the byte variant.
+- `NioSinks.fromByteBuffer` — writes individual `Byte` elements.
+- `NioSinks.fromByteBufferInt`, `NioSinks.fromByteBufferLong`, `NioSinks.fromByteBufferFloat`, `NioSinks.fromByteBufferDouble` — write primitives directly using the buffer's native methods (`putInt`, `putLong`, etc.), one buffer write per element rather than one per byte.
 
 Here's an example using ByteBuffer with typed primitive writes:
 
@@ -614,11 +824,11 @@ val buffer = ByteBuffer.allocate(32).order(ByteOrder.BIG_ENDIAN)
 
 // Write a stream of Longs to the buffer
 Stream(1L, 2L, 3L, 4L).run(NioSinks.fromByteBufferLong(buffer))
-// res25: Either[Nothing, Unit] = Right(())
+// res29: Either[Nothing, Unit] = Right(())
 
 // After writing, rewind to read
 buffer.rewind()
-// res26: ByteBuffer = java.nio.HeapByteBuffer[pos=32 lim=32 cap=32]
+// res30: ByteBuffer = java.nio.HeapByteBuffer[pos=32 lim=32 cap=32]
 
 val readBack = List(
   buffer.getLong(),
@@ -629,29 +839,13 @@ val readBack = List(
 // readBack: List[Long] = List(1L, 2L, 3L, 4L)
 ```
 
-This example allocates a 32-byte buffer (4 Longs × 8 bytes each), writes four `Long` values using `NioSinks.fromByteBufferLong` (which efficiently calls `putLong` on each element), then rewinds and reads them back to verify. The typed variant is significantly faster than `NioSinks.fromByteBuffer` because it operates at the primitive level — no boxing, no element-by-element byte writing.
+This example allocates a 32-byte buffer (4 Longs × 8 bytes each), writes four `Long` values using `NioSinks.fromByteBufferLong` (which calls `putLong` on each element), then rewinds and reads them back to verify. The typed variant writes one 8-byte buffer operation per element, where the byte variant would require the stream to carry each byte separately.
 
-The following example shows streaming voltage sensor readings through a calibration curve and buffering them for downstream computation. When processing sensor arrays or scientific measurements, pre-allocated buffers with typed sinks enable zero-copy batch processing.
+The following example shows streaming voltage sensor readings through a calibration curve and buffering them for downstream computation. When processing sensor arrays or scientific measurements, pre-allocated buffers with typed sinks let each element be written through its exact primitive lane without boxing.
 
 Here is the complete example:
 
 ```scala title="streams-examples/src/main/scala/sink/SinkScientificComputingExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package sink
 
 import zio.blocks.streams.*
@@ -737,165 +931,11 @@ sbt "streams-examples/runMain sink.SinkScientificComputingExample"
 
 This use case is typical in scientific instrumentation, machine learning data preprocessing, and signal processing pipelines where you need to efficiently batch-process numerical streams into memory-efficient structures for downstream computation.
 
-:::warning[Sentinel Collisions Throw — Never Silently Truncate]
-
-These typed sinks achieve **zero-boxing performance** by using a special "sentinel" value to signal end-of-stream, rather than allocating wrapper objects or checking for `null`. This design eliminates allocations entirely, keeping the read loop a **single primitive comparison per element**. This loop shape is a deliberate, protected performance choice (see the repository's `AGENTS.md`, "Sentinel performance policy"): no per-element flag checks, rawbits conversions, boxing, or extra branches are permitted in it.
-
-A natural question: what happens if the stream *contains* the sentinel value (e.g. a `Long.MaxValue` element streamed into `NioSinks.fromByteBufferLong`)? The sink **throws `IllegalArgumentException`** — your data is never silently dropped. Detection costs nothing on the hot path: every read records an out-of-band `lastReadWasEOF` flag on the reader, and the sink consults it **once, after the drain loop exits**, to distinguish genuine end-of-stream from a real sentinel-valued element:
-
-```scala
-// fromByteBufferLong - tight loop with primitives only
-val s = Long.MaxValue
-var v = reader.readLong(s)(using unsafeEvidence)
-while (v != s) { // single primitive comparison per element
-  buf.putLong(v)
-  v = reader.readLong(s)(using unsafeEvidence)
-}
-if (!reader.lastReadWasEOF) // consulted once, post-loop: zero hot-path cost
-  throw new IllegalArgumentException("stream contains Long.MaxValue ...")
-```
-
-**Sentinels per typed sink:**
-| Method | Input Type | Sentinel Value | Collision behavior |
-|--------|-----------|---|---|
-| `NioSinks.fromByteBuffer` | `Byte` | `-1` (as `Int`) | No collision possible — bytes are widened to [0, 255] |
-| `NioSinks.fromByteBufferInt` | `Int` | `Long.MinValue` | No collision possible — outside Int range |
-| `NioSinks.fromByteBufferLong` | `Long` | `Long.MaxValue` | Throws `IllegalArgumentException` |
-| `NioSinks.fromByteBufferFloat` | `Float` | `Double.MaxValue` | No collision possible — outside Float range |
-| `NioSinks.fromByteBufferDouble` | `Double` | `Double.MaxValue` | Throws `IllegalArgumentException` |
-
-**If your data may contain the sentinel value**, use a generic sink instead — these use an out-of-band object sentinel and handle every value:
-- `Sink.collectAll[A]` — collects into a Chunk
-- `Sink.foreach[A](f: A => Unit)` — processes each element individually
-- `Sink.foldLeft[A, Z](z: Z)(f: (Z, A) => Z)` — accumulates
-- `Sink.create[E, A, Z](f: Reader[A] => Z)` — manual control
-
-For a runnable demonstration of the guard, see the example below:
-
-```scala title="streams-examples/src/main/scala/sink/SinkSentinelGuardExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package sink
-
-import zio.blocks.streams.*
-import zio.blocks.streams.NioSinks
-import java.nio.ByteBuffer
-
-object SinkSentinelGuardExample extends App {
-  println("=== Sentinel Collisions Are Rejected Loudly (Never Silently) ===\n")
-
-  println("Context: the typed NIO sinks use a primitive sentinel (e.g. Long.MaxValue for")
-  println("fromByteBufferLong) to detect end-of-stream, keeping the drain loop a single")
-  println("primitive comparison per element — zero boxing, zero allocation. This is a")
-  println("deliberate performance choice (see AGENTS.md, Sentinel performance policy).")
-  println("If your stream contains the sentinel value itself, the sink does NOT silently")
-  println("truncate: it detects the collision at zero hot-path cost (one out-of-band EOF")
-  println("flag check after the loop exits) and throws IllegalArgumentException.\n")
-
-  // Example 1: normal data drains at full speed
-  println("Test 1: Stream without sentinel values drains completely")
-  println("-" * 60)
-
-  val safeData = List(100L, 200L, 300L, 400L, 500L)
-  val buffer1  = ByteBuffer.allocate(safeData.length * 8)
-  Stream.fromIterable(safeData).run(NioSinks.fromByteBufferLong(buffer1))
-  buffer1.flip()
-
-  var count1 = 0
-  while (buffer1.hasRemaining) {
-    println(f"  [$count1] ${buffer1.getLong()}")
-    count1 += 1
-  }
-  println(f"\n✓ All ${count1} values written\n")
-
-  // Example 2: a sentinel-valued element is rejected with a clear error
-  println("Test 2: Stream containing Long.MaxValue is rejected, not truncated")
-  println("-" * 60)
-
-  val riskyData = List(100L, 200L, Long.MaxValue, 300L, 400L)
-  println(
-    f"Stream data: ${riskyData.map(v => if (v == Long.MaxValue) "Long.MaxValue" else v.toString).mkString(", ")}\n"
-  )
-
-  val buffer2 = ByteBuffer.allocate(riskyData.length * 8)
-  try {
-    Stream.fromIterable(riskyData).run(NioSinks.fromByteBufferLong(buffer2))
-    println("✗ UNEXPECTED: drain completed without error")
-  } catch {
-    case e: IllegalArgumentException =>
-      println(s"✓ Rejected loudly: ${e.getMessage}")
-  }
-
-  // Recommendations
-  println("\n=== Recommendations ===")
-  println("1. If your data might contain the sentinel value (Long.MaxValue for the Long")
-  println("   sink, Double.MaxValue for the Double sink):")
-  println("   → Use a generic sink (Sink.collectAll, Sink.foreach, Sink.foldLeft) — these")
-  println("     use an out-of-band object sentinel and handle every value")
-  println("2. Otherwise the typed sinks are maximally fast: a single primitive comparison")
-  println("   per element, zero boxing, zero allocation")
-  println("3. Either way, data is never silently dropped — a collision throws")
-  println()
-  println("Sentinels per typed sink:")
-  println("   → fromByteBufferInt: sentinel = Long.MinValue (outside Int range — no collision possible)")
-  println("   → fromByteBufferLong: sentinel = Long.MaxValue (collision throws)")
-  println("   → fromByteBufferFloat: sentinel = Double.MaxValue (outside Float range — no collision possible)")
-  println("   → fromByteBufferDouble: sentinel = Double.MaxValue (collision throws)")
-}
-```
-
-
-Run it with:
-
-```bash
-sbt "streams-examples/runMain sink.SinkSentinelGuardExample"
-```
-:::
-
-You might ask: **Why not use a sentinel object like generic sinks do, instead of primitive values?** The answer reveals a fundamental performance trade-off.
-
-Generic sinks use object sentinels to signal end-of-stream:
-
-```scala
-// Sink.collectAll - uses object reference for end-of-stream
-def loop(v: Any): Unit =
-  if (v.asInstanceOf[AnyRef] ne EndOfStream) {
-    b += v.asInstanceOf[A]
-    loop(reader.read(EndOfStream))
-  }
-val firstValue = reader.read(EndOfStream)  // EndOfStream is an object
-loop(firstValue)
-```
-
-**Performance Impact:**
-- **Typed sinks:** Direct primitive comparison, zero allocations, tight loop optimizable by JVM
-- **Generic sinks:** Object casting, reference equality check, one `EndOfStream` object per stream
-
-For a stream processing **millions of elements**, the typed sink approach has measurably better performance because:
-1. No casting overhead per iteration
-2. Primitive values are faster than object references
-3. JIT compiler can better optimize tight primitive loops
-4. Zero per-element allocation pressure
-
-Neither approach silently drops data: the generic sinks use a reference-unique object that no stream element can equal, and the typed sinks detect a value/sentinel collision via the out-of-band EOF flag (consulted once, post-loop) and throw rather than truncate.
+The typed sinks dispatch through their exact primitive lanes. `Long` and `Double` use collision-free bulk-count status, so `Long.MinValue`, `Long.MaxValue`, every finite or infinite `Double`, signed zero, and every raw NaN payload are written as ordinary data. There is no sentinel-value truncation restriction. The supplied buffer remains caller-owned and is not flipped, rewound, or closed by the sink. [Zero-Boxing Streams](../execution-and-compatibility/zero-boxing.md) carries the per-lane end-of-stream table this rests on.
 
 ### From Channel Sink
 
-The **`Sink.fromChannel`**  constructor performs buffered writes to a `WritableByteChannel` (e.g., a network socket or file channel). This is the general-purpose NIO sink: it accumulates bytes in an internal buffer of size `bufSize` (default 8192), flushes when the buffer is full, and flushes again at end-of-stream.
+The **`NioSinks.fromChannel`** constructor performs buffered writes to a `WritableByteChannel` (e.g., a network socket or file channel). This is the general-purpose NIO sink: it accumulates bytes in an internal buffer of size `bufSize` (default 8192), flushes when the buffer is full, and flushes again at end-of-stream. It does not close the caller-owned channel.
 
 It handles `IOException` as a typed error, so failures surface as `Left(IOException)` from `Stream.run`. Use this for network I/O or when you can't pre-allocate a buffer. The channel I/O is blocking—NIO's non-blocking advantage comes when using selectors across many channels, which this sink does not expose.
 
@@ -904,22 +944,6 @@ Suppose you're collecting metrics from thousands of sensors (temperature, pressu
 Here is the complete example:
 
 ```scala title="streams-examples/src/main/scala/sink/SinkTelemetryExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package sink
 
 import zio.blocks.streams.*
@@ -1032,22 +1056,6 @@ Run individual examples with sbt:
 This example demonstrates the most commonly used built-in sinks: `Sink.drain`, `Sink.count`, `Sink.collectAll`, `Sink.head`, `Sink.last`, and `Sink.take`:
 
 ```scala title="streams-examples/src/main/scala/sink/SinkBasicUsageExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package sink
 
 import zio.blocks.streams.*
@@ -1114,22 +1122,6 @@ sbt "streams-examples/runMain sink.SinkBasicUsageExample"
 This example shows aggregation sinks (`Sink.foldLeft`, `Sink.sumInt`, `Sink.sumDouble`) and search sinks (`Sink.exists`, `Sink.forall`, `Sink.find`, `Sink.foreach`):
 
 ```scala title="streams-examples/src/main/scala/sink/SinkAggregationExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package sink
 
 import zio.blocks.streams.*
@@ -1213,22 +1205,6 @@ sbt "streams-examples/runMain sink.SinkAggregationExample"
 This example demonstrates `Sink#contramap`, `Sink#map`, `Sink#mapError`, `Sink.fail`, `Sink.create`, and `Pipeline#andThenSink`:
 
 ```scala title="streams-examples/src/main/scala/sink/SinkTransformationExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package sink
 
 import zio.blocks.streams.*
@@ -1240,14 +1216,14 @@ object SinkTransformationExample extends App {
   // 1. contramap — pre-process input
   println("1. Sink.contramap — pre-process input elements:")
   val stringLengthSum: Sink[Nothing, String, Long] =
-    Sink.sumInt.contramap[String](_.length)
+    Sink.sumInt.contramap[Int, String](_.length)
 
   show(Stream("hello", "world").run(stringLengthSum))
 
   // 2. contramap — change element type
   println("\n2. contramap to convert types:")
   val parseInts: Sink[Nothing, String, Long] =
-    Sink.sumInt.contramap[String](_.toInt)
+    Sink.sumInt.contramap[Int, String](_.toInt)
 
   show(Stream("10", "20", "30").run(parseInts))
 
@@ -1261,7 +1237,7 @@ object SinkTransformationExample extends App {
   // 4. Chaining contramap + map
   println("\n4. Chaining contramap + map:")
   val pipeline = Sink.sumInt
-    .contramap[String](_.length)
+    .contramap[Int, String](_.length)
     .map(total => s"Total chars: $total")
 
   show(Stream("hi", "hello").run(pipeline))
@@ -1329,98 +1305,100 @@ Run this example with:
 sbt "streams-examples/runMain sink.SinkTransformationExample"
 ```
 
-### Sentinel Guard (NIO Typed Sinks)
+### Async Sinks End to End
 
-This example demonstrates that the typed NIO sinks (`NioSinks.fromByteBufferLong`, `NioSinks.fromByteBufferDouble`) reject streams containing their sentinel value (e.g., `Long.MaxValue` for `NioSinks.fromByteBufferLong`) with an `IllegalArgumentException` instead of silently truncating — detected at zero hot-path cost via the reader's out-of-band EOF flag, consulted once after the drain loop exits:
+This example builds a custom mean sink with `Sink.createBoth` — a `while` loop for the synchronous drain, an `Async#flatMap` recursion for the asynchronous one — then drives it and `Sink.existsAsync` through `Stream#runAsync`, unwrapping each `Either` at the end. It is JVM-only, because it finishes with `.block` to turn the `Async` into a value for `main`:
 
-```scala title="streams-examples/src/main/scala/sink/SinkSentinelGuardExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
+```scala title="streams-examples/src/main/scala/sink/SinkAsyncExample.scala" 
+package sink
+
+import zio.blocks.async._
+import zio.blocks.streams._
+import zio.blocks.streams.io.Reader
+
+/**
+ * A custom sink built with `Sink.createBoth`, plus one of the `*Async`
+ * combinators, both driven from the cross-platform asynchronous terminal
+ * `Stream#runAsync`.
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * `createBoth` supplies two independent drains. The terminal picks exactly one:
+ * `runAsync` takes the asynchronous callback, and the JVM-only blocking `run`
+ * takes the synchronous one. Both must agree on what they consume and what they
+ * return.
  *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * JVM only, because it ends in `.block` to turn the `Async` into a value for
+ * `main`.
  */
+object SinkAsyncExample {
+
+  /**
+   * Mean of an `Int` lane. The synchronous callback is a plain `while` loop
+   * over `readInt`, which allocates no `Async` per element; the asynchronous
+   * callback threads the same accumulator through `flatMap`.
+   */
+  val meanCelsius: Sink[Nothing, Int, Double] =
+    Sink.createBoth[Nothing, Int, Double](
+      sync = { (reader: Reader.SyncReader[Int]) =>
+        var sum   = 0L
+        var count = 0L
+        var value = reader.readInt(Long.MinValue)
+        while (value != Long.MinValue) {
+          sum += value
+          count += 1L
+          value = reader.readInt(Long.MinValue)
+        }
+        mean(sum, count)
+      },
+      async = { (reader: Reader.AsyncReader[Int]) =>
+        def loop(sum: Long, count: Long): Async[Double] =
+          reader.readInt(Long.MinValue).flatMap { value =>
+            if (value == Long.MinValue) Async.succeed(mean(sum, count))
+            else loop(sum + value, count + 1L)
+          }
+
+        loop(0L, 0L)
+      }
+    )
 
-package sink
-
-import zio.blocks.streams.*
-import zio.blocks.streams.NioSinks
-import java.nio.ByteBuffer
+  private def mean(sum: Long, count: Long): Double =
+    if (count == 0L) 0.0 else sum.toDouble / count.toDouble
 
-object SinkSentinelGuardExample extends App {
-  println("=== Sentinel Collisions Are Rejected Loudly (Never Silently) ===\n")
-
-  println("Context: the typed NIO sinks use a primitive sentinel (e.g. Long.MaxValue for")
-  println("fromByteBufferLong) to detect end-of-stream, keeping the drain loop a single")
-  println("primitive comparison per element — zero boxing, zero allocation. This is a")
-  println("deliberate performance choice (see AGENTS.md, Sentinel performance policy).")
-  println("If your stream contains the sentinel value itself, the sink does NOT silently")
-  println("truncate: it detects the collision at zero hot-path cost (one out-of-band EOF")
-  println("flag check after the loop exits) and throws IllegalArgumentException.\n")
-
-  // Example 1: normal data drains at full speed
-  println("Test 1: Stream without sentinel values drains completely")
-  println("-" * 60)
-
-  val safeData = List(100L, 200L, 300L, 400L, 500L)
-  val buffer1  = ByteBuffer.allocate(safeData.length * 8)
-  Stream.fromIterable(safeData).run(NioSinks.fromByteBufferLong(buffer1))
-  buffer1.flip()
-
-  var count1 = 0
-  while (buffer1.hasRemaining) {
-    println(f"  [$count1] ${buffer1.getLong()}")
-    count1 += 1
-  }
-  println(f"\n✓ All ${count1} values written\n")
+  def main(args: Array[String]): Unit = {
+    val celsius: Stream[Nothing, Int] = Stream(12, 7, 30, 21, 5)
 
-  // Example 2: a sentinel-valued element is rejected with a clear error
-  println("Test 2: Stream containing Long.MaxValue is rejected, not truncated")
-  println("-" * 60)
+    // Nothing has run yet: both terminals are descriptions.
+    val average: Async[Either[Nothing, Double]] = celsius.runAsync(meanCelsius)
 
-  val riskyData = List(100L, 200L, Long.MaxValue, 300L, 400L)
-  println(
-    f"Stream data: ${riskyData.map(v => if (v == Long.MaxValue) "Long.MaxValue" else v.toString).mkString(", ")}\n"
-  )
+    // `existsAsync` runs at most one predicate effect at a time and stops at
+    // the first `true`; 30 matches, so 21 and 5 are never pulled.
+    val tooHot: Async[Either[Nothing, Boolean]] =
+      celsius.runAsync(Sink.existsAsync[Int](c => Async.succeed(c > 25)))
 
-  val buffer2 = ByteBuffer.allocate(riskyData.length * 8)
-  try {
-    Stream.fromIterable(riskyData).run(NioSinks.fromByteBufferLong(buffer2))
-    println("✗ UNEXPECTED: drain completed without error")
-  } catch {
-    case e: IllegalArgumentException =>
-      println(s"✓ Rejected loudly: ${e.getMessage}")
+    // `.block` parks the calling thread until the value arrives. It belongs
+    // here, at the edge of a JVM `main`, and nowhere else.
+    report("createBoth mean", average.block)
+    report("existsAsync (> 25)", tooHot.block)
   }
 
-  // Recommendations
-  println("\n=== Recommendations ===")
-  println("1. If your data might contain the sentinel value (Long.MaxValue for the Long")
-  println("   sink, Double.MaxValue for the Double sink):")
-  println("   → Use a generic sink (Sink.collectAll, Sink.foreach, Sink.foldLeft) — these")
-  println("     use an out-of-band object sentinel and handle every value")
-  println("2. Otherwise the typed sinks are maximally fast: a single primitive comparison")
-  println("   per element, zero boxing, zero allocation")
-  println("3. Either way, data is never silently dropped — a collision throws")
-  println()
-  println("Sentinels per typed sink:")
-  println("   → fromByteBufferInt: sentinel = Long.MinValue (outside Int range — no collision possible)")
-  println("   → fromByteBufferLong: sentinel = Long.MaxValue (collision throws)")
-  println("   → fromByteBufferFloat: sentinel = Double.MaxValue (outside Float range — no collision possible)")
-  println("   → fromByteBufferDouble: sentinel = Double.MaxValue (collision throws)")
+  private def report[E, Z](label: String, result: Either[E, Z]): Unit =
+    result match {
+      case Right(value) => println(s"$label -> $value")
+      case Left(error)  => println(s"$label -> typed error: $error")
+    }
 }
 ```
 
-Run it with this command:
+Run this example with:
 
 ```bash
-sbt "streams-examples/runMain sink.SinkSentinelGuardExample"
+sbt "streams-examples/runMain sink.SinkAsyncExample"
 ```
+
+## See Also
+
+- [Asynchronous Stream Execution](../execution-and-compatibility/async-execution.md#async-terminals) — the terminals that select a sink's asynchronous drain, and the `Async[Either[E, Z]]` convention
+- [Platform Differences](../execution-and-compatibility/platform-differences.md#sinkcreate-and-custom-sinks) — why `Sink.create` is JVM-only and what replaces it in shared source
+- [Reader](../primitives/reader.md#the-reader-union) — the two reader kinds a sink drains, from the reader's side
+- [Zero-Boxing Streams](../execution-and-compatibility/zero-boxing.md) — how a primitive lane is chosen, and the per-lane end-of-stream table
+- [Stream](./stream.md) — the producer a sink consumes
+- [Pipeline](./pipeline.md) — transformations that can be attached to a sink's input