@zio.dev/zio-blocks 0.0.32 → 0.0.51

package/reference/{schema-evolution → schema/schema-evolution}/index.md

@@ -18,7 +18,7 @@ Schema evolution is the process of changing data structures over time while keep
 
 ## `Into[A, B]` — One-Way Conversion
 
-[`Into[A, B]`](./into.md) converts a value of type `A` to `Either[SchemaError, B]`. It is the right choice whenever the migration is asymmetric — for example, when adding a field with a default value, removing a field, or transforming data in a way that cannot be reversed.
+[`Into[A, B]`](into.md) converts a value of type `A` to `Either[SchemaError, B]`. It is the right choice whenever the migration is asymmetric — for example, when adding a field with a default value, removing a field, or transforming data in a way that cannot be reversed.
 
 Typical use cases:
 
@@ -28,7 +28,7 @@ Typical use cases:
 
 ## `As[A, B]` — Bidirectional Round-Trip
 
-[`As[A, B]`](./as.md) extends `Into[A, B]` with a `from(b: B): Either[SchemaError, A]` reverse direction. It guarantees that `A → B → A` restores the original value (within the constraints of numeric precision and optional fields). Use `As` when both sides of the conversion must remain in sync.
+[`As[A, B]`](as.md) extends `Into[A, B]` with a `from(b: B): Either[SchemaError, A]` reverse direction. It guarantees that `A → B → A` restores the original value (within the constraints of numeric precision and optional fields). Use `As` when both sides of the conversion must remain in sync.
 
 Typical use cases:
 

package/reference/{schema-evolution → schema/schema-evolution}/into.md

@@ -69,13 +69,13 @@ Compare this to a manual implementation:
 `Into` is part of the `zio-blocks-schema` module:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.32"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
 ```
 
 For Scala.js:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.32"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.51"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.
@@ -915,7 +915,7 @@ backToMap
 
 ## Related Type: `As[A, B]`
 
-`As[A, B]` extends `Into[A, B]` with a reverse direction, enabling round-trip safe bidirectional conversions. Because `As` must guarantee that `A → B → A` restores the original value, it applies stricter derivation constraints than `Into`. See [As](./as.md) for the full reference.
+`As[A, B]` extends `Into[A, B]` with a reverse direction, enabling round-trip safe bidirectional conversions. Because `As` must guarantee that `A → B → A` restores the original value, it applies stricter derivation constraints than `Into`. See [As](as.md) for the full reference.
 
 ## Best Practices
 

package/reference/{schema-expr.md → schema/schema-expr.md}

@@ -3,23 +3,29 @@ id: schema-expr
 title: "SchemaExpr"
 ---
 
-`SchemaExpr[A, +B]` is a **schema-aware expression** that computes a result of type `B` from an input value of type `A`. The input type `A` must be fully described by a [`Schema`](./schema.md), and the expression is built from [optics](./optics.md), literal values, and operators. The fundamental operations are `eval` and `evalDynamic`.
+`SchemaExpr[A, B]` is a **schema-aware expression** that computes a result of type `B` from an input value of type `A`. It is invariant in both type parameters. The input type `A` must be fully described by a [`Schema`](./schema.md), and the expression is built from [optics](./optics.md), literal values, and operators. The fundamental operations are `eval` and `evalDynamic`.
+
+At runtime, `SchemaExpr` is a typed wrapper around `DynamicSchemaExpr`. The typed layer carries the input and output schemas, while the dynamic layer stores the serializable AST. This split is why you will sometimes see both `.dynamic` and `DynamicSchemaExpr` in advanced examples: `SchemaExpr` is the public typed API, and `DynamicSchemaExpr` is the untyped transport/runtime form underneath it.
 
 `SchemaExpr`:
 - represents expressions as a reified AST, enabling introspection and serialization
 - supports relational (`===`, `>`, `<`, `>=`, `<=`, `!=`), logical (`&&`, `||`, `!`), arithmetic (`+`, `-`, `*`), and string (`concat`, `matches`, `length`) operations
 - evaluates to `Either[OpticCheck, Seq[B]]`, handling failures and multi-valued results from traversals
-- is covariant in `B`, the output type
+- preserves both input and output schemas at the type level
 
 ```scala
-sealed trait SchemaExpr[A, +B] {
+final case class SchemaExpr[A, B](
+  dynamic: DynamicSchemaExpr,
+  inputSchema: Schema[A],
+  outputSchema: Schema[B]
+) {
   def eval(input: A): Either[OpticCheck, Seq[B]]
   def evalDynamic(input: A): Either[OpticCheck, Seq[DynamicValue]]
 }
 ```
 
 :::tip
-For practical walkthroughs of building with `SchemaExpr`, see [Query DSL Part 1: Expressions](../guides/query-dsl-reified-optics.md), [Part 2: SQL Generation](../guides/query-dsl-sql.md), and [Part 3: Extending the Expression Language](../guides/query-dsl-extending.md).
+For practical walkthroughs of building with `SchemaExpr`, see [Query DSL Part 1: Expressions](../../guides/query-dsl-reified-optics.md), [Part 2: SQL Generation](../../guides/query-dsl-sql.md), and [Part 3: Extending the Expression Language](../../guides/query-dsl-extending.md).
 :::
 
 ## Motivation
@@ -70,13 +76,13 @@ val result: Either[OpticCheck, Seq[Boolean]] = combined.eval(alice)
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.32"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
 ```
 
 For cross-platform (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.32"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.51"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.
@@ -85,6 +91,12 @@ Supported Scala versions: 2.13.x and 3.x.
 
 `SchemaExpr` instances are typically created through **operator syntax on optics** rather than by constructing AST nodes directly. Each operator on `Optic[S, A]` returns a `SchemaExpr[S, B]`.
 
+There are three common construction styles:
+
+- optic/operator syntax such as `Person.age >= 18`
+- literal expressions such as `SchemaExpr.literal[Person, Int](18)`
+- advanced direct construction when you intentionally need to work with the underlying dynamic AST
+
 ### Via Relational Operators on Optics
 
 The comparison operators `===`, `>`, `>=`, `<`, `<=`, and `!=` on `Optic[S, A]` create `SchemaExpr.Relational` nodes. Each operator has two overloads — one comparing against a literal value, and one comparing against another optic:
@@ -204,7 +216,7 @@ val adultOrAlice: SchemaExpr[Person, Boolean] = isAdult || isAlice
 
 ### Via Direct AST Construction
 
-For advanced use cases, we can construct `SchemaExpr` nodes directly:
+For advanced use cases, you can construct `SchemaExpr` values directly. In most application code, prefer optic/operator syntax or `SchemaExpr.literal` because they preserve the typed surface and are easier to read.
 
 ```scala
 import zio.blocks.schema._
@@ -217,16 +229,20 @@ object Item extends CompanionOptics[Item] {
   val price: Lens[Item, Int] = $(_.price)
 }
 
-// Construct AST nodes directly
-val lit: SchemaExpr[Item, Int] = new SchemaExpr.Literal(42, Schema[Int])
-val opticExpr: SchemaExpr[Item, Int] = new SchemaExpr.Optic(Item.price)
-val comparison: SchemaExpr[Item, Boolean] = new SchemaExpr.Relational(
+// Construct via factory methods
+val lit: SchemaExpr[Item, Int] = SchemaExpr.literal[Item, Int](42)
+val opticExpr: SchemaExpr[Item, Int] = SchemaExpr.optic[Item, Int](Item.price.toDynamic, Item.schema)
+val comparison: SchemaExpr[Item, Boolean] = SchemaExpr.relational(
   opticExpr,
   lit,
   SchemaExpr.RelationalOperator.GreaterThan
 )
 ```
 
+`SchemaExpr.literal` is the normal way to inject constants into an expression tree. It produces a typed `SchemaExpr[S, A]`, while storing the value internally as a `DynamicSchemaExpr.Literal`. That is usually what you want in user code, including migration builders.
+
+If you need the raw dynamic form for serialization, transport, or custom interpreters, use `.dynamic` on an existing `SchemaExpr` rather than constructing `DynamicSchemaExpr` directly unless you are working on expression internals.
+
 ## Core Operations
 
 ### Evaluation
@@ -236,7 +252,7 @@ val comparison: SchemaExpr[Item, Boolean] = new SchemaExpr.Relational(
 Evaluates the expression against an input value, returning the typed result. The result is a `Seq[B]` because traversal-based expressions can produce multiple values.
 
 ```scala
-trait SchemaExpr[A, +B] {
+trait SchemaExprLike[A, B] {
   def eval(input: A): Either[OpticCheck, Seq[B]]
 }
 ```
@@ -272,7 +288,7 @@ When an expression wraps a `Traversal` optic, `eval` returns multiple values —
 Like `eval`, but converts the result to [`DynamicValue`](./dynamic-value.md) instances. This is useful for serialization or when working with schema-agnostic code.
 
 ```scala
-trait SchemaExpr[A, +B] {
+trait SchemaExprLike[A, B] {
   def evalDynamic(input: A): Either[OpticCheck, Seq[DynamicValue]]
 }
 ```
@@ -290,7 +306,7 @@ object Person extends CompanionOptics[Person] {
   val name: Lens[Person, String] = $(_.name)
 }
 
-val nameExpr = new SchemaExpr.Optic(Person.name)
+val nameExpr = SchemaExpr.optic[Person, String](Person.name.toDynamic, Person.schema)
 val result = nameExpr.evalDynamic(Person("Alice", 30))
 // Right(List(DynamicValue.Primitive(PrimitiveValue.String("Alice"))))
 ```
@@ -301,9 +317,13 @@ val result = nameExpr.evalDynamic(Person("Alice", 30))
 
 Combines two boolean-typed expressions with logical AND. Both operands must produce `Boolean` results.
 
+`&&` and `||` are provided via `SchemaExpr.BooleanOps`, an implicit class in the `SchemaExpr` companion, rather than as direct methods on `SchemaExpr`. This lets downstream libraries supply their own `&&`/`||` overloads (e.g. returning a DDB- or SQL-specific expression type) by bringing in their own implicit class via an explicit import, which takes priority over the companion-scope implicit in Scala 2 and 3.
+
 ```scala
-trait SchemaExpr[A, +B] {
-  def &&[B2](that: SchemaExpr[A, B2])(implicit ev: B <:< Boolean, ev2: B2 =:= Boolean): SchemaExpr[A, Boolean]
+// In SchemaExpr companion:
+implicit final class BooleanOps[A, B](val self: SchemaExpr[A, B]) extends AnyVal {
+  def and(that: SchemaExpr[A, Boolean])(implicit ev: B <:< Boolean): SchemaExpr[A, Boolean]
+  def &&(that: SchemaExpr[A, Boolean])(implicit ev: B <:< Boolean): SchemaExpr[A, Boolean]
 }
 ```
 
@@ -331,8 +351,10 @@ val result = isAdultAlice.eval(Person("Alice", 30))
 Combines two boolean-typed expressions with logical OR.
 
 ```scala
-trait SchemaExpr[A, +B] {
-  def ||[B2](that: SchemaExpr[A, B2])(implicit ev: B <:< Boolean, ev2: B2 =:= Boolean): SchemaExpr[A, Boolean]
+// In SchemaExpr companion:
+implicit final class BooleanOps[A, B](val self: SchemaExpr[A, B]) extends AnyVal {
+  def or(that: SchemaExpr[A, Boolean])(implicit ev: B <:< Boolean): SchemaExpr[A, Boolean]
+  def ||(that: SchemaExpr[A, Boolean])(implicit ev: B <:< Boolean): SchemaExpr[A, Boolean]
 }
 ```
 
@@ -355,50 +377,43 @@ val result = isAdultOrAlice.eval(Person("Alice", 12))
 // Right(List(true)) — Alice, even though not adult
 ```
 
-## Subtypes
+## Structure
 
-`SchemaExpr` is a sealed trait with a rich set of case classes representing different expression nodes. These form an **expression AST** that can be inspected, serialized, or translated to other query languages.
+`SchemaExpr` is a typed wrapper. The actual expression AST lives in `DynamicSchemaExpr`, which is a sealed trait of serializable expression nodes. `SchemaExpr` adds the input and output schemas needed to convert between typed values and [`DynamicValue`](./dynamic-value.md).
 
-### Leaf Nodes
+### `DynamicSchemaExpr` leaf nodes
 
-#### `SchemaExpr.Literal`
+#### `DynamicSchemaExpr.Literal`
 
-A constant value that ignores the input and always produces the same result.
+A constant value represented directly as a `DynamicValue`.
 
 ```scala
-object SchemaExpr {
-  case class Literal[S, A](value: A, schema: Schema[A]) extends SchemaExpr[S, A]
+object DynamicSchemaExpr {
+  final case class Literal(value: DynamicValue, schema: Schema[_]) extends DynamicSchemaExpr
 }
 ```
 
-The `Literal#eval` always returns `Right(Seq(value))` regardless of the input. The `Literal#schema` parameter enables conversion to `DynamicValue` via `evalDynamic`.
+#### `DynamicSchemaExpr.Select`
 
-#### `SchemaExpr.Optic`
-
-Wraps an [`Optic[A, B]`](./optics.md) to extract values from the input. The behavior depends on the optic type:
+Selects values from the input using a [`DynamicOptic`](./dynamic-optic.md).
 
 ```scala
-object SchemaExpr {
-  case class Optic[A, B](optic: zio.blocks.schema.Optic[A, B]) extends SchemaExpr[A, B]
+object DynamicSchemaExpr {
+  final case class Select(path: DynamicOptic) extends DynamicSchemaExpr
 }
 ```
 
-| Optic Type  | `SchemaExpr.Optic#eval` Behavior                                                      |
-|-------------|---------------------------------------------------------------------------------------|
-| `Lens`      | Always succeeds with a single value                                                   |
-| `Prism`     | Succeeds if the input matches the expected case; otherwise returns `Left(OpticCheck)` |
-| `Optional`  | Succeeds if the value is present; otherwise returns `Left(OpticCheck)`                |
-| `Traversal` | Returns all elements; returns `Left(OpticCheck)` if the collection is empty           |
+`SchemaExpr.optic(...)` and optic operator syntax eventually produce `DynamicSchemaExpr.Select` nodes.
 
-### Unary Operations
+### Unary operations
 
-#### `SchemaExpr.Not`
+#### `DynamicSchemaExpr.Not`
 
 Negates a boolean expression.
 
 ```scala
-object SchemaExpr {
-  case class Not[A](expr: SchemaExpr[A, Boolean]) extends UnaryOp[A, Boolean](expr)
+object DynamicSchemaExpr {
+  final case class Not(expr: DynamicSchemaExpr) extends DynamicSchemaExpr
 }
 ```
 
@@ -421,21 +436,21 @@ val result = inactive.eval(User(active = true))
 // Right(List(false))
 ```
 
-### Binary Operations
+### Binary operations
 
-`Relational`, `Logical`, `Arithmetic`, and `StringConcat` extend `BinaryOp[A, B, C]`, which provides `left` and `right` sub-expressions. `StringRegexMatch` and `StringLength` extend `SchemaExpr` directly — see [Other Operations](#other-operations) below.
+`Relational`, `Logical`, `Arithmetic`, `Bitwise`, and the string binary operations are all represented as `DynamicSchemaExpr` nodes holding child expressions.
 
-#### `SchemaExpr.Relational`
+#### `DynamicSchemaExpr.Relational`
 
 Compares two expressions using a `RelationalOperator`. Returns a boolean result.
 
 ```scala
-object SchemaExpr {
-  case class Relational[A, B](
-    left: SchemaExpr[A, B],
-    right: SchemaExpr[A, B],
+object DynamicSchemaExpr {
+  final case class Relational(
+    left: DynamicSchemaExpr,
+    right: DynamicSchemaExpr,
     operator: RelationalOperator
-  ) extends SchemaExpr[A, Boolean]
+  ) extends DynamicSchemaExpr
 }
 ```
 
@@ -454,17 +469,17 @@ The available `RelationalOperator` values are:
 Equality and inequality (`===`, `!=`) compare values directly. Ordering operators (`<`, `<=`, `>`, `>=`) compare via `DynamicValue` ordering internally.
 :::
 
-#### `SchemaExpr.Logical`
+#### `DynamicSchemaExpr.Logical`
 
 Combines two boolean expressions with a `LogicalOperator`.
 
 ```scala
-object SchemaExpr {
-  case class Logical[A](
-    left: SchemaExpr[A, Boolean],
-    right: SchemaExpr[A, Boolean],
+object DynamicSchemaExpr {
+  final case class Logical(
+    left: DynamicSchemaExpr,
+    right: DynamicSchemaExpr,
     operator: LogicalOperator
-  ) extends SchemaExpr[A, Boolean]
+  ) extends DynamicSchemaExpr
 }
 ```
 
@@ -475,18 +490,18 @@ The available `LogicalOperator` values are:
 | `And`    | `&&`   | Logical conjunction |
 | `Or`     | `\|\|` | Logical disjunction |
 
-#### `SchemaExpr.Arithmetic`
+#### `DynamicSchemaExpr.Arithmetic`
 
 Performs arithmetic on two numeric expressions using an `ArithmeticOperator`. Requires an `IsNumeric[A]` type class instance.
 
 ```scala
-object SchemaExpr {
-  case class Arithmetic[S, A](
-    left: SchemaExpr[S, A],
-    right: SchemaExpr[S, A],
+object DynamicSchemaExpr {
+  final case class Arithmetic(
+    left: DynamicSchemaExpr,
+    right: DynamicSchemaExpr,
     operator: ArithmeticOperator,
-    isNumeric: IsNumeric[A]
-  ) extends SchemaExpr[S, A]
+    numericType: NumericTypeTag
+  ) extends DynamicSchemaExpr
 }
 ```
 
@@ -498,112 +513,29 @@ The available `ArithmeticOperator` values are:
 | `Subtract` | `-`          | Subtraction    |
 | `Multiply` | `*`          | Multiplication |
 
-Supported numeric types via `IsNumeric`: `Byte`, `Short`, `Int`, `Long`, `Float`, `Double`, `BigInt`, `BigDecimal`.
-
-#### `SchemaExpr.StringConcat`
-
-Concatenates two string expressions.
-
-```scala
-object SchemaExpr {
-  case class StringConcat[A](
-    left: SchemaExpr[A, String],
-    right: SchemaExpr[A, String]
-  ) extends SchemaExpr[A, String]
-}
-```
-
-Created via the `concat` method on string optics:
-
-```scala
-import zio.blocks.schema._
-
-case class Greeting(prefix: String)
-
-object Greeting extends CompanionOptics[Greeting] {
-  implicit val schema: Schema[Greeting] = Schema.derived
-
-  val prefix: Lens[Greeting, String] = $(_.prefix)
-}
-
-val withName = Greeting.prefix.concat(", World!")
-val result = withName.eval(Greeting("Hello"))
-// Right(List("Hello, World!"))
-```
-
-### Other Operations
-
-`StringRegexMatch` and `StringLength` extend `SchemaExpr` directly rather than through `UnaryOp` or `BinaryOp`.
-
-#### `SchemaExpr.StringRegexMatch`
-
-Tests whether a string matches a regular expression pattern. Despite having two operands (`regex` and `string`), it extends `SchemaExpr[A, Boolean]` directly.
-
-```scala
-object SchemaExpr {
-  case class StringRegexMatch[A](
-    regex: SchemaExpr[A, String],
-    string: SchemaExpr[A, String]
-  ) extends SchemaExpr[A, Boolean]
-}
-```
-
-Created via the `matches` method on string optics:
-
-```scala
-import zio.blocks.schema._
-
-case class Email(address: String)
-
-object Email extends CompanionOptics[Email] {
-  implicit val schema: Schema[Email] = Schema.derived
-
-  val address: Lens[Email, String] = $(_.address)
-}
+Supported numeric types include `Byte`, `Short`, `Int`, `Long`, `Float`, `Double`, `BigInt`, and `BigDecimal`.
 
-val isValid = Email.address.matches("^[^@]+@[^@]+\\.[^@]+$")
-val result = isValid.eval(Email("alice@example.com"))
-// Right(List(true))
-```
+#### Other string and bitwise operations
 
-#### `SchemaExpr.StringLength`
+`DynamicSchemaExpr` also includes:
 
-Computes the length of a string expression. This is a unary operation but extends `SchemaExpr[A, Int]` directly rather than `UnaryOp`.
+- `StringConcat`
+- `StringRegexMatch`
+- `StringLength`
+- `StringSubstring`
+- `StringTrim`
+- `StringToUpperCase`
+- `StringToLowerCase`
+- `StringReplace`
+- `StringStartsWith`
+- `StringEndsWith`
+- `StringContains`
+- `StringIndexOf`
+- `PrimitiveConversion`
+- `Bitwise`
+- `BitwiseNot`
 
-```scala
-object SchemaExpr {
-  case class StringLength[A](
-    string: SchemaExpr[A, String]
-  ) extends SchemaExpr[A, Int]
-}
-```
-
-Created via the `length` method on string optics:
-
-```scala
-import zio.blocks.schema._
-
-case class Message(body: String)
-
-object Message extends CompanionOptics[Message] {
-  implicit val schema: Schema[Message] = Schema.derived
-
-  val body: Lens[Message, String] = $(_.body)
-}
-
-val bodyLength = Message.body.length
-val result = bodyLength.eval(Message("Hello!"))
-// Right(List(6))
-```
-
-### Abstract Intermediate Traits
-
-Two sealed traits categorize some expressions by arity:
-
-- **`UnaryOp[A, B]`** — has a single `expr: SchemaExpr[A, B]`. Extended by `Not`.
-- **`BinaryOp[A, B, C]`** — has `left: SchemaExpr[A, B]` and `right: SchemaExpr[A, B]`. Extended by `Relational`, `Logical`, `Arithmetic`, and `StringConcat`.
-
-Not all expression nodes use these traits — `StringRegexMatch` and `StringLength` extend `SchemaExpr` directly. These intermediate traits are useful for pattern matching when you need to generically process the expression tree.
+These are the cases downstream interpreters should consider when translating `SchemaExpr.dynamic` into SQL, filters, or other query languages.
 
 ## Error Handling
 
@@ -631,19 +563,22 @@ result match {
 
 ## Advanced Usage: Building Query DSLs
 
-Because `SchemaExpr` is a sealed, inspectable AST, third-party libraries can pattern-match on the expression tree to translate it into other languages. For example, a database library could translate `SchemaExpr` into SQL:
+Because `SchemaExpr.dynamic` is a sealed, inspectable AST, third-party libraries can translate expressions into other languages. The public entry point should still accept `SchemaExpr`; only the interpreter internals need to cross into `DynamicSchemaExpr`.
 
 ```scala
-// Pseudocode — illustrates the concept
-def toSql[A](expr: SchemaExpr[A, Boolean]): String = expr match {
-  case SchemaExpr.Relational(left, right, op) =>
+// Pseudocode — keeps SchemaExpr as the public API
+def toSql[A, B](expr: SchemaExpr[A, B]): String =
+  toSqlDynamic(expr.dynamic)
+
+def toSqlDynamic(expr: DynamicSchemaExpr): String = expr match {
+  case DynamicSchemaExpr.Relational(left, right, op) =>
     s"${toSqlValue(left)} ${opToSql(op)} ${toSqlValue(right)}"
-  case SchemaExpr.Logical(left, right, SchemaExpr.LogicalOperator.And) =>
-    s"(${toSql(left)}) AND (${toSql(right)})"
-  case SchemaExpr.Logical(left, right, SchemaExpr.LogicalOperator.Or) =>
-    s"(${toSql(left)}) OR (${toSql(right)})"
-  case SchemaExpr.Not(inner) =>
-    s"NOT (${toSql(inner)})"
+  case DynamicSchemaExpr.Logical(left, right, DynamicSchemaExpr.LogicalOperator.And) =>
+    s"(${toSqlDynamic(left)}) AND (${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Logical(left, right, DynamicSchemaExpr.LogicalOperator.Or) =>
+    s"(${toSqlDynamic(left)}) OR (${toSqlDynamic(right)})"
+  case DynamicSchemaExpr.Not(inner) =>
+    s"NOT (${toSqlDynamic(inner)})"
   // ...
 }
 ```
@@ -658,7 +593,7 @@ This is the key advantage of reified expressions over plain functions — the sa
 
 ### Schema
 
-[Schema](./schema.md) provides the type information needed by `SchemaExpr.Literal` to convert values to `DynamicValue` via `Literal#evalDynamic`. The `IsNumeric` type class (used by `Arithmetic`) also derives from `Schema`.
+[Schema](./schema.md) provides the type information needed to construct typed `SchemaExpr` values and to convert typed results to and from `DynamicValue` during evaluation.
 
 ### DynamicValue
 

package/reference/{schema.md → schema/schema.md}

@@ -1,5 +1,6 @@
 ---
 id: schema
+slug: schema
 title: "Schema"
 ---
 
@@ -186,6 +187,17 @@ import zio.blocks.schema.Schema
 Schema[Option[A]]  // Generic option for reference types
 ```
 
+### Either Values
+
+An `Either[A, B]` schema is available whenever both branch types have schemas. Primitive values and primitive-backed wrappers use specialized primitive register layouts, while other values use the layouts described by their schemas:
+
+```scala
+import zio.blocks.schema.Schema
+
+Schema[Either[String, Int]]
+Schema[Either[Int, Long]]
+```
+
 ### Collection Types
 
 ZIO Blocks also provides polymorphic schemas for standard Scala collections. You can summon schemas for collections of any element type `A` (and key/value types `K`/`V` for maps):
@@ -588,7 +600,7 @@ ZIO Blocks provides the `transform` method for creating schemas for wrapper type
 
 ```scala
 final case class Schema[A](reflect: Reflect.Bound[A]) {
-  def transform[B](to: A => B, from: B => A): Schema[B] = ???
+  def transform[B](to: A => B, from: B => A)(implicit typeId: TypeId[B]): Schema[B] = ???
 }
 ```
 

package/reference/{structural-types.md → schema/structural-types.md}

@@ -294,7 +294,7 @@ Structural types integrate seamlessly with ZIO Blocks' broader ecosystem:
 
 ### With Schema Evolution Macros
 
-Structural schemas work with [Schema Evolution](./schema-evolution/into.md) macros for cross-type conversion. When two types share the same structural shape, the conversion machinery can work across type boundaries:
+Structural schemas work with [Schema Evolution](schema-evolution/into.md) macros for cross-type conversion. When two types share the same structural shape, the conversion machinery can work across type boundaries:
 
 ```scala
 import zio.blocks.schema.Schema

package/reference/{type-class-derivation.md → schema/type-class-derivation.md}

@@ -167,6 +167,68 @@ import zio.blocks.schema.json._
 val jsonCodec = Person.schema.derive(JsonFormat)
 ```
 
+## Customizing Derivation with Instance and Modifier Overrides
+
+By default, `Deriver` automatically derives codecs for all types. But sometimes you need to customize how specific types are encoded or decoded—for example, encoding `LocalDate` as `"dd/MM/yyyy"` instead of ISO format.
+
+ZIO Blocks provides three levels of customization, in progressive order:
+
+1. **Type-level override** (`Deriver.withInstance`) — Override the codec for ALL occurrences of a type. Configure once, use everywhere:
+
+```scala
+import java.time.LocalDate
+import java.time.format.DateTimeFormatter
+
+// Create a custom JsonCodec for LocalDate
+val customDateCodec: JsonCodec[LocalDate] = new JsonCodec[LocalDate] {
+  private val fmt = DateTimeFormatter.ofPattern("dd/MM/yyyy")
+  def decodeValue(in: JsonReader): LocalDate = LocalDate.parse(in.readString(), fmt)
+  def encodeValue(x: LocalDate, out: JsonWriter): Unit = out.writeVal(fmt.format(x))
+  // ... AST overrides ...
+}
+
+// Configure the deriver once
+val myDeriver = JsonCodecDeriver.withInstance[LocalDate](customDateCodec)
+
+// Use everywhere — all LocalDate fields use the custom codec
+val codec1 = Schema[Event].deriving(myDeriver).derive
+val codec2 = Schema[Meeting].deriving(myDeriver).derive
+```
+
+2. **Field-level override** (`Deriver.withInstance` with typeId + termName) — Override a specific field only:
+
+```scala
+// Only Event.date uses custom format; other LocalDate fields are unchanged
+val deriver = JsonCodecDeriver.withInstance[Event, LocalDate](
+  TypeId.of[Event], "date", customDateCodec
+)
+```
+
+3. **Modifier override** (`Deriver.withModifier`) — Rename fields, add aliases:
+
+```scala
+val deriver = JsonCodecDeriver.withModifier(
+  TypeId.of[Person], "firstName", Modifier.rename("first_name")
+)
+```
+
+### Chaining Overrides
+
+Overrides compose, allowing you to build complex derivers incrementally:
+
+```scala
+val myDeriver = JsonCodecDeriver
+  .withInstance[LocalDate](customDateCodec)
+  .withModifier(TypeId.of[Event], "name", Modifier.rename("title"))
+```
+
+### Important Notes
+
+- `withInstance` and `withModifier` return a NEW deriver (they are immutable).
+- When combined with `DerivationBuilder`, deriver-level instance overrides take precedence over builder-level instance overrides. Modifier override precedence is order-sensitive and should not be assumed to follow the same rule.
+- Unknown `termName` values are silently ignored.
+- The `B` type parameter in field-level `withInstance` is not statically checked against the actual field type.
+
 ## Example 1: Deriving a `Show` Type Class Instance
 
 Let's say we want to derive a `Show` type class instance for any type of type `A`:
@@ -1455,7 +1517,7 @@ Now we can use the derived `Gen[Person]` instance to generate random `Person` va
 
 ```scala
 val random = new Random(42) // Seeded for reproducible output
-// random: Random = scala.util.Random@195c6b05
+// random: Random = scala.util.Random@d903a4c
 
 Person.gen.generate(random)
 // res14: Person = Person(name = "p", age = -1360544799)