@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/ringbuffer/mpsc.mdx

@@ -59,7 +59,7 @@ Creates a new MPSC ring buffer with the given capacity. The capacity must be a p
 
 To create an MPSC buffer:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.ringbuffer.MpscRingBuffer
 
 val rb = MpscRingBuffer[java.lang.Long](32)
@@ -119,10 +119,42 @@ Removes up to `limit` elements from the buffer, passing each to the `consumer` c
 
 When multiple threads produce work for a single processor, use `MpscRingBuffer`. This example shows how three producer threads safely offer items to a single consumer.
 
-```scala mdoc:passthrough
-import docs.SourceFile
+```scala title="zio-blocks-examples/src/main/scala/ringbuffer/MpscExample.scala" 
+package ringbuffer
 
-SourceFile.print("zio-blocks-examples/src/main/scala/ringbuffer/MpscExample.scala")
+import zio.blocks.ringbuffer.MpscRingBuffer
+import java.util.concurrent.{CountDownLatch, Thread}
+
+object MpscExample extends App {
+  val buffer = MpscRingBuffer[java.lang.Integer](16)
+  val latch = new CountDownLatch(1)
+
+  val producers = (0 until 3).map { id =>
+    new Thread(() => {
+      for (i <- 1 to 4) {
+        buffer.offer(java.lang.Integer.valueOf(id * 100 + i))
+      }
+    })
+  }
+
+  val consumer = new Thread(() => {
+    var received = 0
+    while (received < 12) {
+      val item = buffer.take()
+      if (item ne null) {
+        println(s"Processed: $item")
+        received += 1
+      }
+    }
+    latch.countDown()
+  })
+
+  producers.foreach(_.start())
+  consumer.start()
+  producers.foreach(_.join())
+  latch.await()
+  println("All items processed")
+}
 ```
 
 ([source](https://github.com/zio/zio-blocks/blob/main/zio-blocks-examples/src/main/scala/ringbuffer/MpscExample.scala))

package/reference/ringbuffer/spmc.mdx

@@ -67,7 +67,7 @@ object SpmcRingBuffer {
 
 The capacity must be a positive power of two. To create an SPMC buffer:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.ringbuffer.SpmcRingBuffer
 
 val rb = SpmcRingBuffer[java.lang.Integer](64)

package/reference/ringbuffer/spsc.mdx

@@ -104,7 +104,7 @@ Creates a new SPSC ring buffer with the given capacity. The capacity must be a p
 
 We create an SPSC buffer as follows:
 
-```scala mdoc:compile-only
+```scala
 import zio.blocks.ringbuffer.SpscRingBuffer
 
 val rb = SpscRingBuffer[String](16)  // capacity must be power of 2
@@ -128,7 +128,7 @@ Inserts the element without blocking. Returns `true` on successful insertion, `f
 
 To handle backpressure by checking if insertion succeeds:
 
-```scala mdoc:silent:reset
+```scala
 import zio.blocks.ringbuffer.SpscRingBuffer
 
 val rb = SpscRingBuffer[String](4)
@@ -136,12 +136,17 @@ val rb = SpscRingBuffer[String](4)
 
 When the buffer becomes full, `offer` returns `false`:
 
-```scala mdoc
+```scala
 val result1 = rb.offer("a")
+// result1: Boolean = true
 val result2 = rb.offer("b")
+// result2: Boolean = true
 val result3 = rb.offer("c")
+// result3: Boolean = true
 val result4 = rb.offer("d")
+// result4: Boolean = true
 val result5 = rb.offer("e")
+// result5: Boolean = false
 ```
 
 ### Removing Elements — `SpscRingBuffer#take`
@@ -158,12 +163,17 @@ Retrieves and removes an element from the front of the buffer. Returns immediate
 
 To retrieve elements in FIFO order:
 
-```scala mdoc
+```scala
 rb.take()
+// res2: String = "a"
 rb.take()
+// res3: String = "b"
 rb.take()
+// res4: String = "c"
 rb.take()
+// res5: String = "d"
 rb.take()
+// res6: String = null
 ```
 
 ### Checking State — `size`, `isEmpty`, `isFull`
@@ -202,7 +212,7 @@ Returns `true` if the buffer is at capacity (approximate). O(1).
 
 All four implementations provide the same three methods. To check state after operations:
 
-```scala mdoc:silent:reset
+```scala
 import zio.blocks.ringbuffer.SpscRingBuffer
 
 val rb2 = SpscRingBuffer[String](8)
@@ -210,13 +220,18 @@ val rb2 = SpscRingBuffer[String](8)
 
 State queries are cheap but approximate under concurrency:
 
-```scala mdoc
+```scala
 rb2.offer("x")
+// res8: Boolean = true
 rb2.offer("y")
+// res9: Boolean = true
 
 rb2.size
+// res10: Int = 2
 rb2.isEmpty
+// res11: Boolean = false
 rb2.isFull
+// res12: Boolean = false
 ```
 
 ### Batch Operations — `SpscRingBuffer#drain` and `SpscRingBuffer#fill`
@@ -243,7 +258,7 @@ Inserts up to `limit` elements by calling the `supplier` for each new element. R
 
 Batch operations amortize synchronization costs. To drain multiple elements at once:
 
-```scala mdoc:silent:reset
+```scala
 import zio.blocks.ringbuffer.SpscRingBuffer
 
 val rb3 = SpscRingBuffer[java.lang.Integer](16)
@@ -257,7 +272,7 @@ println(s"Drained items: ${collected.mkString(", ")}")
 
 To avoid repeated `offer` calls when producing elements, use fill:
 
-```scala mdoc:silent:reset
+```scala
 import zio.blocks.ringbuffer.SpscRingBuffer
 import java.util.concurrent.atomic.AtomicInteger
 
@@ -288,7 +303,7 @@ In addition, each primitive variant exposes two methods for **in-band end-of-str
 
 `pollPacked` is intended for advanced consumers that want a single atomic operation distinguishing empty / data / DONE. Most application code that simply needs primitive throughput is fine using the higher-level concurrent stream operators below.
 
-```scala mdoc:silent:reset
+```scala
 import zio.blocks.ringbuffer.{IntSpscRingBuffer, LongSpscRingBuffer, DoubleSpscRingBuffer}
 
 val ints = new IntSpscRingBuffer(16)
@@ -315,10 +330,36 @@ These variants underpin the primitive-specialized concurrent stream operators (`
 
 In a single-producer, single-consumer setup, use `SpscRingBuffer` for maximum throughput. This example demonstrates how two threads communicate efficiently using FastFlow signaling.
 
-```scala mdoc:passthrough
-import docs.SourceFile
+```scala title="zio-blocks-examples/src/main/scala/ringbuffer/SpscExample.scala" 
+package ringbuffer
 
-SourceFile.print("zio-blocks-examples/src/main/scala/ringbuffer/SpscExample.scala")
+import zio.blocks.ringbuffer.SpscRingBuffer
+import java.util.concurrent.{CountDownLatch, Thread}
+
+object SpscExample extends App {
+  val buffer = SpscRingBuffer[String](8)
+  val latch = new CountDownLatch(1)
+
+  val producer = new Thread(() => {
+    for (i <- 1 to 5) {
+      buffer.offer(s"message-$i")
+    }
+  })
+
+  val consumer = new Thread(() => {
+    for (_ <- 1 to 5) {
+      var msg: String = null
+      while ({ msg = buffer.take(); msg.eq(null) }) {}
+      println(s"Received: $msg")
+    }
+    latch.countDown()
+  })
+
+  producer.start()
+  consumer.start()
+  latch.await()
+  println("Done")
+}
 ```
 
 ([source](https://github.com/zio/zio-blocks/blob/main/zio-blocks-examples/src/main/scala/ringbuffer/SpscExample.scala))
@@ -331,10 +372,41 @@ sbt "zio-blocks-examples/runMain ringbuffer.SpscExample"
 
 Use `fill` and `drain` for efficient batch operations. This example shows how to amortize synchronization costs by processing multiple elements at once.
 
-```scala mdoc:passthrough
-import docs.SourceFile
+```scala title="zio-blocks-examples/src/main/scala/ringbuffer/BatchExample.scala" 
+package ringbuffer
 
-SourceFile.print("zio-blocks-examples/src/main/scala/ringbuffer/BatchExample.scala")
+import zio.blocks.ringbuffer.SpscRingBuffer
+import java.util.concurrent.{CountDownLatch, Thread}
+
+object BatchExample extends App {
+  val buffer = SpscRingBuffer[java.lang.Integer](64)
+  val latch = new CountDownLatch(1)
+
+  val producer = new Thread(() => {
+    var batch = 1
+    while (batch <= 3) {
+      val currentBatch = batch
+      val count = buffer.fill(() => java.lang.Integer.valueOf(currentBatch * 100), 10)
+      println(s"Filled $count items in batch $currentBatch")
+      batch += 1
+    }
+  })
+
+  val consumer = new Thread(() => {
+    val items = scala.collection.mutable.Buffer[java.lang.Integer]()
+    while (items.size < 30) {
+      val drained = buffer.drain(items += _, 10)
+      if (drained > 0) println(s"Drained $drained items")
+    }
+    println(s"Total items consumed: ${items.size}")
+    latch.countDown()
+  })
+
+  producer.start()
+  consumer.start()
+  latch.await()
+  println("Done")
+}
 ```
 
 ([source](https://github.com/zio/zio-blocks/blob/main/zio-blocks-examples/src/main/scala/ringbuffer/BatchExample.scala))

package/reference/schema/allows.md

@@ -584,22 +584,6 @@ sbt "schema-examples/runMain comptime.AllowsCsvExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsCsvExample.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 comptime
 
 import zio.blocks.schema._
@@ -708,22 +692,6 @@ sbt "schema-examples/runMain comptime.AllowsEventBusExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsEventBusExample.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 comptime
 
 import zio.blocks.schema._
@@ -830,22 +798,6 @@ sbt "schema-examples/runMain comptime.AllowsGraphQLTreeExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsGraphQLTreeExample.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 comptime
 
 import zio.blocks.schema._
@@ -970,22 +922,6 @@ sbt "schema-examples/runMain comptime.AllowsSealedTraitExample"
 ```
 
 ```scala title="schema-examples/src/main/scala/comptime/AllowsSealedTraitExample.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 comptime
 
 import zio.blocks.schema._
@@ -1081,22 +1017,6 @@ object AllowsSealedTraitExample extends App {
 Demonstrates how Allows constraints are verified at compile time — the code below shows valid examples that compile successfully, and includes comments showing which patterns would be rejected:
 
 ```scala title="schema-examples/src/main/scala/comptime/RdbmsExample.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 comptime
 
 import zio.blocks.schema._
@@ -1290,22 +1210,6 @@ object RdbmsDemo {
 Demonstrates how Allows enforces recursive schema constraints at compile time:
 
 ```scala title="schema-examples/src/main/scala/comptime/DocumentStoreExample.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 comptime
 
 import zio.blocks.schema._

package/reference/schema/binding.md

@@ -336,9 +336,9 @@ Used when the schema of the data is not known at compile time, such as JSON payl
 When `F[_, _] = NoBinding` in `Reflect[F[_, _], A]` the `Reflect` structure contains only pure data (no functions) and becomes fully serializable. This enables:
 
 1. **Schema serialization**: Convert schemas to JSON Schema or other formats, making them portable
-2. **Schema rebinding**: Deserialize a schema and rebind it using a `TypeRegistry`, so it becomes type-safe and operational again
+2. **Schema rebinding**: Deserialize a schema and rebind it using a `BindingResolver`, so it becomes type-safe and operational again
 
-We will cover schema serialization and rebinding in more detail in the `Reflect` data type documentation page. For the full API of the binding lookup mechanism used during rebinding, see [BindingResolver](binding-resolver.md).
+[ReflectTransformer](./reflect-transformer.md) covers schema serialization and rebinding in full detail — the transformer that strips bindings, the one that reattaches them, and how each is exposed as `Schema#toDynamicSchema`/`DynamicSchema#rebind`. For the full API of the binding lookup mechanism used during rebinding, see [BindingResolver](binding-resolver.md).
 
 ## Summary
 

package/reference/schema/built-in-codecs/avro.md

@@ -26,7 +26,7 @@ Rather than writing custom encoders or relying on string-based Avro schema confi
 Add the module to your `build.sbt` (JVM-only, not available for Scala.js):
 
 ```sbt
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-avro" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x
@@ -341,7 +341,7 @@ object Person {
 }
 
 val codec = Person.schema.derive(AvroFormat)
-// codec: AvroCodec[Person] = zio.blocks.schema.avro.AvroCodecDeriver$$anon$4@3d8dcca9
+// codec: AvroCodec[Person] = zio.blocks.schema.avro.AvroCodecDeriver$$anon$4@601650a
 ```
 
 ### Primitive Type Support

package/reference/schema/built-in-codecs/bson.md

@@ -5,7 +5,7 @@ title: "BSON Codec Module"
 
 `zio-blocks-schema-bson` is a **schema-driven BSON codec module** for serializing and deserializing Scala types to and from BSON (Binary JSON) format. It provides comprehensive encoding and decoding with support for 27 primitive types, records, variants, sequences, maps, and recursive types. 
 
-Core types: `BsonCodec`, `BsonEncoder`, `BsonDecoder`, `BsonSchemaCodec`.
+Core types: `BsonCodec`, `BsonEncoder`, `BsonDecoder`, `BsonCodecDeriver`, and the compatibility facade `BsonSchemaCodec`.
 
 The module integrates with org.bson to provide native BSON type support including special handling for `ObjectId`, `Decimal128`, and other BSON-specific types.
 
@@ -27,7 +27,7 @@ Rather than writing custom encoders or relying on string-based configuration, yo
 Add the module to your `build.sbt`:
 
 ```sbt
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-bson" % "0.0.55"
 ```
 
 **Note:** This module is JVM-only and is not available for Scala.js.
@@ -39,7 +39,7 @@ Supported Scala versions: 2.13.x and 3.x
 The module provides a complete pipeline for BSON codec derivation and usage:
 
 1. **Define your type** — Any Scala type with a `Schema` instance
-2. **Derive a codec** — Use `BsonSchemaCodec.bsonCodec(schema)` to obtain a `BsonCodec[A]`
+2. **Derive a codec** — Use `schema.derive(BsonCodecDeriver)` to obtain a `BsonCodec[A]`
 3. **Encode or decode** — Call `codec.encoder.toBsonValue()` or `codec.decoder.fromBsonValue()`
 4. **Handle errors** — Catch `BsonDecoder.Error` with location traces showing where the error occurred
 
@@ -52,9 +52,9 @@ The BSON codec pipeline flows through these layers:
 ```
 1. User defines Schema[A] for their type
                  ↓
-2. BsonSchemaCodec.bsonCodec(schema) creates BsonCodec[A]
+2. Schema[A].derive(BsonCodecDeriver) creates BsonCodec[A]
                  ↓
-3. BsonSchemaCodec derives Encoder and Decoder implementations
+3. DerivationBuilder traverses the schema and BsonCodecDeriver composes Encoder and Decoder implementations
    - For primitives: type-specific BSON encoders/decoders
    - For records: field-by-field composition
    - For variants: discriminator-based selection
@@ -64,7 +64,7 @@ The BSON codec pipeline flows through these layers:
 4. BsonEncoder writes values to BsonValue or BsonWriter
    BsonDecoder reads BsonValue or BsonReader to values
                  ↓
-5. BsonSchemaCodec.Config customizes behavior
+5. BsonCodecDeriver configuration methods customize behavior
    - Sum type handling (discriminator, wrapper, or none)
    - Field name mapping for MongoDB conventions
    - ObjectId detection and native BSON encoding
@@ -83,7 +83,7 @@ User type (e.g., case class Person)
     ↓
 Schema.derived (automatic via macro)
     ↓
-BsonSchemaCodec.bsonCodec(schema, config) → BsonCodec[Person]
+schema.derive(configuredBsonCodecDeriver) → BsonCodec[Person]
     ↓
 Use codec.encoder.toBsonValue(person) to serialize
 Use codec.decoder.fromBsonValue(bsonValue) to deserialize
@@ -110,7 +110,7 @@ object Person {
   implicit val schema: Schema[Person] = Schema.derived
 }
 
-val codec = BsonSchemaCodec.bsonCodec(Person.schema)
+val codec = Person.schema.derive(BsonCodecDeriver)
 val person = Person("Alice", 30, "alice@example.com")
 val bsonValue = codec.encoder.toBsonValue(person)
 ```
@@ -342,13 +342,11 @@ val rendered = BsonTrace.render(trace) // ".user[0].age"
 
 ---
 
-## BsonSchemaCodec
+## BsonCodecDeriver and BsonSchemaCodec
 
-Configuration and derivation system for creating `BsonCodec[A]` instances from `Schema[A]`.
+`BsonCodecDeriver` implements the shared `Deriver[BsonCodec]` contract. It supports direct derivation as well as `Schema.deriving` instance and modifier overrides by type, exact optic, or parent type and term name.
 
-### Overview
-
-`BsonSchemaCodec` provides the `bsonCodec()` method to derive codecs, along with configurable behavior for sum types, field mapping, and ObjectId handling.
+`BsonSchemaCodec` retains `bsonCodec`, `bsonEncoder`, `bsonDecoder`, and `Config` as compatibility and convenience APIs. These methods delegate to `BsonCodecDeriver`, so both entry points have the same BSON behavior.
 
 ### Configuration
 
@@ -396,18 +394,50 @@ object Person {
   implicit val schema: Schema[Person] = Schema.derived
 }
 
-val codec = BsonSchemaCodec.bsonCodec(Person.schema)
+val codec = Person.schema.derive(BsonCodecDeriver)
 // codec: BsonCodec[Person] = BsonCodec(
-//   encoder = zio.blocks.schema.bson.BsonSchemaCodec$$anon$4@77dddeaa,
-//   decoder = zio.blocks.schema.bson.BsonSchemaCodec$$anon$5@1692f6db
+//   encoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$5@75f2c0f,
+//   decoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$6@5b87f051
 // )
-val customCodec = BsonSchemaCodec.bsonCodec(Person.schema, BsonSchemaCodec.Config)
-// customCodec: BsonCodec[Person] = BsonCodec(
-//   encoder = zio.blocks.schema.bson.BsonSchemaCodec$$anon$4@3497a5ea,
-//   decoder = zio.blocks.schema.bson.BsonSchemaCodec$$anon$5@2d26055c
+val configuredCodec = Person.schema.derive(BsonCodecDeriver.withIgnoreExtraFields(false))
+// configuredCodec: BsonCodec[Person] = BsonCodec(
+//   encoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$5@117db32c,
+//   decoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$6@6fbcca58
+// )
+
+// Compatibility facade
+val compatibleCodec = BsonSchemaCodec.bsonCodec(Person.schema)
+// compatibleCodec: BsonCodec[Person] = BsonCodec(
+//   encoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$5@79d7f29,
+//   decoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$6@7b055825
 // )
+val configuredCompatibleCodec = BsonSchemaCodec.bsonCodec(Person.schema, BsonSchemaCodec.Config)
+// configuredCompatibleCodec: BsonCodec[Person] = BsonCodec(
+//   encoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$5@148d2e57,
+//   decoder = zio.blocks.schema.bson.BsonCodecDeriver$$anon$6@78856fd8
+// )
+```
+
+### Derivation overrides
+
+Use `Schema.deriving` when part of a schema needs a custom codec or runtime modifier:
+
+```scala
+val codec = Person.schema
+  .deriving(BsonCodecDeriver)
+  .instance(Person.schema.reflect.typeId, "age", customIntCodec)
+  .modifier(Person.schema.reflect.typeId, "name", Modifier.rename("fullName"))
+  .derive
 ```
 
+Type-level overrides affect every matching occurrence. Parent-type and term-name overloads are also available for fields and variant cases. String map keys remain BSON document field names; override map values or the whole map codec when custom map behavior is needed.
+
+Record-level `Modifier.fieldNaming` and `Modifier.noExtraFields` annotations override the corresponding default BSON behavior. Variant-level `Modifier.caseNaming` and `Modifier.discriminator` annotations override class-name mapping and sum-type handling for the annotated variant.
+
+### Semantic Json values
+
+`zio.blocks.schema.json.Json` objects, arrays, scalars, and nulls map directly to their semantic BSON equivalents. Finite BSON doubles other than signed zero retain their exact value when converted through `Json`; BSON signed zero is normalized to JSON zero because `Json.Number` does not retain its sign. Duplicate `Json.Object` field names are rejected because `BsonDocument` cannot represent them without data loss.
+
 ---
 
 ## BsonTrace

package/reference/schema/built-in-codecs/csv.md

@@ -37,13 +37,13 @@ Rather than writing custom parsers or relying on string-based configuration, you
 Add the module to your `build.sbt`:
 
 ```sbt
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-csv" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-csv" % "0.0.55"
 ```
 
 For Scala.js, use `%%%` instead of `%%`:
 
 ```sbt
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema-csv" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema-csv" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x

package/reference/schema/built-in-codecs/index.md

@@ -4,17 +4,17 @@ title: "Built-in Formats and Codecs"
 sidebar_label: "Built-in Formats and Codecs"
 ---
 
-ZIO Blocks Schema provides codec derivation for multiple serialization formats. Once you have a `Schema[A]` for your data type, you can derive codecs for most formats using the unified `Schema.derive(Format)` pattern. BSON uses a different API: `BsonSchemaCodec.bsonCodec(schema)`. See the [Format documentation](../format.md) for details on how formats work.
+ZIO Blocks Schema provides codec derivation for multiple serialization formats. Once you have a `Schema[A]`, formats can be passed to `Schema.derive`, while BSON is derived with `Schema[A].derive(BsonCodecDeriver)`. The older `BsonSchemaCodec.bsonCodec(schema)` API remains a compatibility facade. See the [Format documentation](../format.md) for details.
 
 ## Built-in Codecs
 
-Here's a summary of the codecs currently supported by ZIO Blocks. Most codecs provide a `BinaryFormat` or `TextFormat` object that can be passed to `derive`. BSON uses a different API (see below). See the dedicated codec documentation for installation, usage examples, and detailed type mappings:
+Here's a summary of the codecs currently supported by ZIO Blocks. Most codecs provide a `BinaryFormat` or `TextFormat`; BSON provides a `Deriver` because it operates on native BSON readers, writers, and values. See the dedicated documentation for details:
 
 | Derivation API      | Codec Type            | MIME Type             | Module                          | Documentation                   |
 |---------------------|-----------------------|-----------------------|---------------------------------|---------------------------------|
 | `JsonFormat`        | `JsonCodec[A]`        | `application/json`    | `zio-blocks-schema`             | [JSON](./json/index.md)         |
 | `AvroFormat`        | `AvroCodec[A]`        | `application/avro`    | `zio-blocks-schema-avro`        | [Avro](./avro.md)               |
-| `BsonSchemaCodec`   | `BsonCodec[A]`        | `application/bson`    | `zio-blocks-schema-bson`        | [BSON](./bson.md)               |
+| `BsonCodecDeriver`  | `BsonCodec[A]`        | `application/bson`    | `zio-blocks-schema-bson`        | [BSON](./bson.md)               |
 | `CsvFormat`         | `CsvCodec[A]`         | `text/csv`            | `zio-blocks-schema-csv`         | [CSV](./csv.md)                 |
 | `MessagePackFormat` | `MessagePackCodec[A]` | `application/msgpack` | `zio-blocks-schema-messagepack` | [MessagePack](./messagepack.md) |
 | `ThriftFormat`      | `ThriftCodec[A]`      | `application/thrift`  | `zio-blocks-schema-thrift`      | [Thrift](./thrift.md)           |

package/reference/schema/built-in-codecs/json/index.md

@@ -36,13 +36,13 @@ schema.conforms(person)  // true
 The JSON codec is included in the ZIO Blocks Schema module. Add it to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.55"
 ```
 
 For Scala.js projects, use `%%%` instead:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.55"
 ```
 
 **Supported Scala versions:** 2.13.x and 3.x

package/reference/schema/built-in-codecs/messagepack.md

@@ -27,13 +27,13 @@ Rather than writing custom encoders or relying on string-based schema configurat
 Add the module to your `build.sbt`:
 
 ```sbt
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-messagepack" % "0.0.55"
 ```
 
 For Scala.js, use `%%%` instead of `%%`:
 
 ```sbt
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema-messagepack" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema-messagepack" % "0.0.55"
 ```
 
 Supported Scala versions: 2.13.x and 3.x
@@ -338,7 +338,7 @@ object Person {
 }
 
 val codec = Person.schema.derive(MessagePackFormat)
-// codec: MessagePackCodec[Person] = zio.blocks.schema.msgpack.MessagePackCodecDeriver$$anon$3@7752c755
+// codec: MessagePackCodec[Person] = zio.blocks.schema.msgpack.MessagePackCodecDeriver$$anon$3@2bd1156b
 ```
 
 ### Primitive Type Support

package/reference/schema/built-in-codecs/thrift.md

@@ -26,7 +26,7 @@ Rather than writing custom encoders or relying on code generation from .thrift f
 Add the module to your `build.sbt`:
 
 ```sbt
-libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema-thrift" % "0.0.55"
 ```
 
 **Note:** This module is JVM-only and is not available for Scala.js.
@@ -323,7 +323,7 @@ object Person {
 }
 
 val codec = Person.schema.derive(ThriftFormat)
-// codec: ThriftCodec[Person] = zio.blocks.schema.thrift.ThriftCodecDeriver$$anon$3@52aa2c93
+// codec: ThriftCodec[Person] = zio.blocks.schema.thrift.ThriftCodecDeriver$$anon$3@3a518fc7
 ```
 
 ### Primitive Type Support