@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/combinators.md

@@ -3,19 +3,24 @@ id: combinators
 title: "Combinators"
 ---
 
-The `combinators` module provides compile-time typeclasses for composing and decomposing values in type-safe ways. Each module focuses on a specific domain: tuples, Either types, and union types.
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The `combinators` module provides compile-time typeclasses for composing and decomposing values in type-safe ways. Each module focuses on a specific domain: tuples, choices, concatenation widening, Either types, and union types.
 
 ## Overview
 
-The combinators module consists of three core modules:
+The combinators module consists of five core modules:
 
 - **Tuples** - Tuple composition with automatic flattening and separation
+- **Choices** - Cross-version branch construction and elimination over `|`
+- **Concat** - Scala-2-only union-aware widening for sequential composition
 - **Eithers** - Either canonicalization to left-nested form
 - **Unions** - Union type operations (Scala 3 only)
 
 Each module provides:
-- A unified typeclass (e.g., `Tuples.Tuples[L, R]`) that provides both `combine` and `separate` operations
-- A convenience method `combine` (the `separate` operation is available on the typeclass instance)
+- A unified typeclass (e.g., `Tuples.Tuples[L, R]`) that provides both `Tuples.Tuples#combine` and `Tuples.Tuples#separate` operations
+- A convenience function like `Tuples.combine` (the `Tuples#separate` operation is available on the typeclass instance)
 
 All typeclasses are derived automatically via compile-time resolution and provide zero-cost abstractions.
 
@@ -23,39 +28,148 @@ All typeclasses are derived automatically via compile-time resolution and provid
 
 Add the following to your `build.sbt`:
 
-```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-combinators" % "<version>"
+```sbt
+libraryDependencies += "dev.zio" %% "zio-blocks-combinators" % "0.0.51"
 ```
 
 For cross-platform projects (Scala.js):
 
-```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-combinators" % "<version>"
+```sbt
+libraryDependencies += "dev.zio" %%% "zio-blocks-combinators" % "0.0.51"
 ```
 
 Supported platforms:
-- **Tuples, Eithers**: JVM, Scala.js (Scala 2.13 and 3.x)
+- **Tuples, Choices, Eithers**: JVM, Scala.js (Scala 2.13 and 3.x)
+- **Concat**: Scala 2.13 only
 - **Unions**: JVM, Scala.js (Scala 3 only)
 
+## Motivation
+
+Building type-safe, composable systems requires managing values and types at both runtime and compile time. The combinators module solves three distinct problems that arise in complex Scala applications:
+
+### The Tuple Nesting Problem
+
+When building up results step-by-step—aggregating function parameters, accumulating intermediate results, or constructing compound values—you often end up with deeply nested tuples:
+
+```scala
+// Manual nesting is tedious and error-prone
+val step1 = (1, "a")
+// step1: Tuple2[Int, String] = (1, "a")
+val step2 = (step1, true)
+// step2: Tuple2[Tuple2[Int, String], Boolean] = ((1, "a"), true)
+val step3 = (step2, 3.14)
+// step3: Tuple2[Tuple2[Tuple2[Int, String], Boolean], Double] = (
+//   ((1, "a"), true),
+//   3.14
+// )
+val step4 = (step3, 'x') 
+// step4: Tuple2[Tuple2[Tuple2[Tuple2[Int, String], Boolean], Double], Char] = (
+//   (((1, "a"), true), 3.14),
+//   'x'
+// )
+```
+
+This creates two problems:
+1. **Ergonomic burden**: Consumers of compound values must destructure deeply nested structures
+2. **Inconsistency**: Different code paths produce different tuple shapes, making composition fragile
+
+The `Tuples` combinator automatically flattens these structures, producing clean, predictable tuples at each step.
+
+### The Either Canonicalization Problem
+
+Error handling often involves composing multiple error types through Either chains. Without systematic canonicalization, Either types nest unpredictably:
+
+```scala
+// Inconsistent nesting across code paths
+val result1: Either[E1, V] = Left(e1)
+val result2: Either[E1, Either[E2, V]] = Right(Left(e2))
+val result3: Either[Either[E1, E2], V] = Right(Right(v))
+// Each path has a different structure!
+```
+
+This causes problems when:
+1. **Serializing error types** for schemas (each variant has a different shape)
+2. **Accumulating errors** (inconsistent nesting makes aggregation complex)
+3. **Pattern matching** (must handle multiple nesting patterns)
+
+The `Eithers` combinator canonicalizes all Either types to a uniform left-nested form, ensuring systematic error composition.
+
+### The Scala 3 Union Type Gap
+
+Scala 3 introduces native union types (`A | B`) that are more idiomatic than `Either[A, B]`. However, existing code, libraries, and serialization infrastructure are built around `Either`. When adopting Scala 3, you face a choice:
+
+1. Stick with `Either` for compatibility (missing idiomatic Scala 3 syntax)
+2. Switch to union types (breaking compatibility with Either-based code)
+3. Maintain two parallel type systems (duplication and cognitive overhead)
+
+The `Unions` combinator bridges this gap, enabling bidirectional conversion between `Either[L, R]` and `L | R` with zero runtime overhead. Use union types idiomatically in your APIs while maintaining Either compatibility at serialization boundaries.
+
+## Quick Example
+
+Here is how to combine multiple values and canonicalize error types:
+
+```scala
+import zio.blocks.combinators.{Tuples, Eithers}
+
+// Aggregate three values into a flattened tuple
+val username: String = "alice"
+// username: String = "alice"
+val userId: Int = 42
+// userId: Int = 42
+val email: String = "alice@example.com"
+// email: String = "alice@example.com"
+val userTuple: Tuple3[String, Int, String] = Tuples.combine(username, Tuples.combine(userId, email))
+// userTuple: Tuple3[String, Int, String] = ("alice", 42, "alice@example.com")
+
+// Canonicalize nested Either types to left-nested form
+val validationError: Either[String, Either[String, Boolean]] = Right(Left("invalid email"))
+// validationError: Either[String, Either[String, Boolean]] = Right(
+//   Left("invalid email")
+// )
+val canonical      : Either[Either[String, String], Boolean] = Eithers.combine(validationError)
+// canonical: Either[Either[String, String], Boolean] = Left(
+//   Right("invalid email")
+// )
+```
+
+## Concat (Scala 2 Only)
+
+`Concat` is the Scala-2-only witness used by APIs such as `Stream.++` / `Stream.concat` to preserve Scala 3-style union behavior without introducing a separate operator.
+
+Its rules are:
+
+- same type => keep that type
+- subtype + supertype => keep the supertype
+- siblings with a unique meaningful common supertype => keep that supertype (e.g. `Dog` and `Cat` under sealed `Animal` collapse to `Animal`)
+- otherwise (no shared meaningful supertype) => widen to `Either[L, R]` (the Scala 2 encoding of `L | R`)
+
+For example, Scala 2 infers witnesses equivalent to these shapes:
+
+```scala
+Concat.Concat.WithOut[Int, Int, Int]
+Concat.Concat.WithOut[Dog, Animal, Animal]
+Concat.Concat.WithOut[Dog, Cat, Animal]
+Concat.Concat.WithOut[String, Int, Either[String, Int]]
+```
+
+A common supertype is "meaningful" when it is something other than the noise types Scala 2's LUB inference produces by default (`Any`, `AnyRef`, `AnyVal`, `Object`, `Product`, `Serializable`, `java.io.Serializable`, `Comparable`). If filtering those parents leaves exactly one candidate, it becomes the result type — and the witness is identity-like, so callers such as `Stream.concat` reuse values bare without wrapping. Zero or multiple meaningful parents fall through to `Either`.
+
+Unlike `Choices`, `Concat` is not usually called directly at runtime. It exists mainly so shared Scala-2 APIs can infer the same public result types that Scala 3 expresses with native unions.
+
 ## Tuples
 
 The `Tuples` module combines values into flat tuples and separates them back.
 
 ### combine
 
-`Tuples.Tuples[L, R]` combines two values into a flattened tuple.
+To combine two values into a flattened tuple:
 
 ```scala
 import zio.blocks.combinators.Tuples
 
-// Basic combination
-val result1: (Int, String) = Tuples.combine(1, "hello")
-
-// Tuple flattening
-val result2: (Int, String, Boolean) = Tuples.combine((1, "hello"), true)
-
-// Deep flattening (Scala 3)
-val result3: (Int, String, Boolean, Double) = Tuples.combine((1, "hello"), (true, 3.14))
+val result1 = Tuples.combine(1, "hello")                 // (1, "hello")
+val result2 = Tuples.combine((1, "hello"), true)         // (1, "hello", true)
+val result3 = Tuples.combine((1, "hello"), (true, 3.14)) // (1, "hello", true, 3.14)j
 ```
 
 #### Identity Handling
@@ -65,14 +179,9 @@ Unit and EmptyTuple values are automatically eliminated:
 ```scala
 import zio.blocks.combinators.Tuples
 
-// Unit on left - returns right value
-val result1: Int = Tuples.combine((), 42)
-
-// Unit on right - returns left value
-val result2: String = Tuples.combine("hello", ())
-
-// EmptyTuple identity (Scala 3)
-val result3: String = Tuples.combine(EmptyTuple, "world")
+Tuples.combine((), 42)              // 42
+Tuples.combine("hello", ())          // "hello"
+Tuples.combine(EmptyTuple, "world")  // "world"
 ```
 
 #### Tuple Flattening
@@ -82,64 +191,47 @@ Nested tuples are automatically flattened:
 ```scala
 import zio.blocks.combinators.Tuples
 
-// Tuple + value flattens to larger tuple
-val result1: (Int, String, Boolean) = Tuples.combine((1, "a"), true)
-
-// Tuple + tuple concatenates (Scala 3 - recursive flattening)
-val result2: (Int, String, Boolean, Double) = Tuples.combine((1, "a"), (true, 3.14))
-
-// Scala 2 - flattens left tuple only
-val result3: (Int, String, (Boolean, Double)) = Tuples.combine((1, "a"), (true, 3.14))
+Tuples.combine((1, "a"), true)          // (1, "a", true)
+Tuples.combine((1, "a"), (true, 3.14))  // (1, "a", true, 3.14)
 ```
 
 ### separate
 
-`separate` is accessed via the unified typeclass instance and splits a tuple into its init (all but last) and last element.
+To split a tuple into its init (all but last) and last element, access `Tuples#separate` via the unified typeclass instance:
 
 ```scala
 import zio.blocks.combinators.Tuples
 
-// 2-tuple separation
-val t2 = summon[Tuples.Tuples[Int, String]]  // Scala 3
-// or: implicitly[Tuples.Tuples[Int, String]]  // Scala 2
-val (left1, right1): (Int, String) = t2.separate((1, "hello"))
-// left1 = 1, right1 = "hello"
+val t2 = summon[Tuples.Tuples[Int, String]]
+t2.separate((1, "hello")) // ((1), "hello")
 
-// 3-tuple separation
 val t3 = summon[Tuples.Tuples[(Int, String), Boolean]]
-val (left2, right2): ((Int, String), Boolean) = t3.separate((1, "hello", true))
-// left2 = (1, "hello"), right2 = true
+t3.separate((1, "hello", true)) // ((1, "hello"), true)
 
-// 4-tuple separation
 val t4 = summon[Tuples.Tuples[(Int, String, Boolean), Double]]
-val (left3, right3): ((Int, String, Boolean), Double) = t4.separate((1, "hello", true, 3.14))
-// left3 = (1, "hello", true), right3 = 3.14
-
-
+t4.separate((1, "hello", true, 3.14)) // ((1, "hello", true), 3.14)
 ```
-### Type-Level Operations
 
-The output type is computed at compile time via the `Out` type member:
+When building recursive data structures like path codecs, `separate` decomposes combined tuples to process each segment independently:
 
 ```scala
 import zio.blocks.combinators.Tuples
 
-// Access the combiner with explicit output type
-val combiner: Tuples.Tuples.WithOut[Int, String, (Int, String)] = 
-  summon[Tuples.Tuples[Int, String]]
+// Simulating recursive path encoding: a codec combines left and right path segments
+case class PathSegment(name: String, value: String)
 
-// Access with explicit types
-val instance: Tuples.Tuples.WithOut[Int, String, (Int, String)] = 
-  summon[Tuples.Tuples[Int, String]]
-```
-
-### Scala 2 vs Scala 3 Differences
+def encodePathSegment(combined: (String, String)): PathSegment = {
+  val tuples = summon[Tuples.Tuples[String, String]]
+  val (left, right) = tuples.separate(combined)
+  PathSegment(left, right)
+}
 
-| Feature | Scala 2.13 | Scala 3.x |
-|---------|------------|-----------|
-| Maximum tuple arity | 22 | Unlimited |
-| Tuple flattening | Left tuple only | Recursive both sides |
-| EmptyTuple identity | Not available | Supported |
+// Decompose a 3-element path into segments for recursive encoding
+val path: (String, String, String) = ("users", "123", "profile")
+val tuples3 = summon[Tuples.Tuples[(String, String), String]]
+val (prefix, suffix) = tuples3.separate(path)
+// prefix = ("users", "123"), suffix = "profile"
+```
 
 ## Eithers
 
@@ -147,22 +239,26 @@ The `Eithers` module canonicalizes Either types to left-nested form and separate
 
 ### combine
 
-`Eithers.Eithers[L, R]` transforms an `Either[L, R]` into its left-nested canonical form.
+To transform an `Either[L, R]` into its left-nested canonical form:
 
 ```scala
 import zio.blocks.combinators.Eithers
 
 // Atomic Either - unchanged
-val result1: Either[Int, String] = Eithers.combine(Left(42): Either[Int, String])
+Eithers.combine(Left(42): Either[Int, String])
+// res5: Either[Int, String] = Left(42)
 
 // Right-nested Either - reassociates to left-nested
-val input: Either[Int, Either[String, Boolean]] = Right(Right(true))
-val result2: Either[Either[Int, String], Boolean] = Eithers.combine(input)
-// Right(Right(true)) becomes Right(true)
+val input2 = Right(Right(true)): Either[Int, Either[String, Boolean]]
+// input2: Either[Int, Either[String, Boolean]] = Right(Right(true))
+Eithers.combine(input2)
+// res6: Either[Either[Int, String], Boolean] = Right(true)
 
 // Left(42) becomes Left(Left(42))
-val input2: Either[Int, Either[String, Boolean]] = Left(42)
-val result3: Either[Either[Int, String], Boolean] = Eithers.combine(input2)
+val input3 = Left(42): Either[Int, Either[String, Boolean]]
+// input3: Either[Int, Either[String, Boolean]] = Left(42)
+Eithers.combine(input3)
+// res7: Either[Either[Int, String], Boolean] = Left(Left(42))
 ```
 
 #### Canonical Form
@@ -182,22 +278,74 @@ This transformation preserves values while reassociating the structure:
 
 ### separate
 
-`separate` is accessed via the unified typeclass instance and peels the rightmost alternative from a canonical Either:
+`Eithers#separate` is accessed via the unified typeclass instance and reverses the canonicalization performed by `combine`. Together, they form a round-trip: canonicalizing to left-nested form and then separating back to the original structure:
 
 ```scala
 import zio.blocks.combinators.Eithers
 
 val e = summon[Eithers.Eithers[Int, String]]
-val input: Either[Int, String] = Left(42)
-val result: Either[Int, String] = e.separate(e.combine(input))
+// e: Eithers[Int, String] {
+  type Out >: Either[Int, String] <: Either[Int, String]
+} = zio.blocks.combinators.Eithers$Eithers$AtomicInstance@65d7b306
+val input = Left(42): Either[Int, String]
+// input: Either[Int, String] = Left(42)
+e.separate(e.combine(input))
+// res8: Either[Int, String] = Left(42)
 ```
 
-### Use Cases
+Use `separate` to decompose a canonical Either back to its original structure when you need to handle different error types differently:
+
+```scala
+import zio.blocks.combinators.Eithers
 
-Eithers canonicalization is useful for:
-- **Schema sum type encoding** - Uniform representation of sealed traits
-- **Error handling composition** - Combining error types systematically
-- **Cross-version compatibility** - Works identically on Scala 2 and 3
+sealed trait ValidationError
+case class FieldError(field: String) extends ValidationError
+case class FormatError(message: String) extends ValidationError
+
+// You have a right-nested Either from multiple validation steps
+val input: Either[FieldError, Either[FormatError, String]] = Right(Left(FormatError("invalid date")))
+
+val eithers = summon[Eithers.Eithers[FieldError, Either[FormatError, String]]]
+```
+
+Canonicalize to left-nested form for uniform processing, then reverse it to extract the original error types:
+
+```scala
+// Original form: Either[FieldError, Either[FormatError, String]]
+input
+// res9: Either[FieldError, Either[FormatError, String]] = Right(
+//   Left(FormatError("invalid date"))
+// )
+
+// Canonicalize to left-nested form for uniform processing
+val canonicalized = eithers.combine(input)
+// canonicalized: Either[Either[FieldError, FormatError], String] = Left(
+//   Right(FormatError("invalid date"))
+// )
+
+// Reverse canonicalization to extract the original error types
+val original = eithers.separate(canonicalized)
+// original: Either[FieldError, Either[FormatError, String]] = Right(
+//   Left(FormatError("invalid date"))
+// )
+
+// Back to original form
+original
+// res10: Either[FieldError, Either[FormatError, String]] = Right(
+//   Left(FormatError("invalid date"))
+// )
+```
+
+Handle each error type independently:
+
+```scala
+// Handle each error type independently
+original match {
+  case Left(fieldErr: FieldError) => println(s"Field validation failed: ${fieldErr.field}")
+  case Right(Left(formatErr: FormatError)) => println(s"Format error: ${formatErr.message}")
+  case Right(Right(value)) => println(s"Valid: $value")
+}
+```
 
 ## Unions (Scala 3 Only)
 
@@ -210,28 +358,32 @@ The `Unions` module converts between Either types and Scala 3 union types.
 ```scala
 import zio.blocks.combinators.Unions
 
-val either: Either[Int, String] = Left(42)
-val union: Int | String = Unions.combine(either)
-// Result: 42 (typed as Int | String)
+val either1 = Left(42): Either[Int, String]
+// either1: Either[Int, String] = Left(42)
+Unions.combine(either1)
+// res12: Int | String = 42
 
-val either2: Either[Int, String] = Right("hello")
-val union2: Int | String = Unions.combine(either2)
-// Result: "hello" (typed as Int | String)
+val either2 = Right("hello"): Either[Int, String]
+// either2: Either[Int, String] = Right("hello")
+Unions.combine(either2)
+// res13: Int | String = "hello"
 ```
 
 ### separate
 
-`separate` is accessed via the unified typeclass instance and discriminates a union type back to Either:
+`Unions#separate` is accessed via the unified typeclass instance and discriminates a union type back to Either:
 
 ```scala
 import zio.blocks.combinators.Unions
 
 val u = summon[Unions.Unions.WithOut[Int, String, Int | String]]
-val result: Either[Int, String] = u.separate(42: Int | String)
-// Result: Left(42)
-
-val result2: Either[Int, String] = u.separate("hello": Int | String)
-// Result: Right("hello")
+// u: Unions[Int, String] {
+  type Out >: Int | String <: Int | String
+} = zio.blocks.combinators.Unions$Unions$UnionInstance@64a090cd
+u.separate(42: Int | String)
+// res14: Either[Int, String] = Left(42)
+u.separate("hello": Int | String)
+// res15: Either[Int, String] = Right("hello")
 ```
 ### Same-Type Rejection
 
@@ -253,8 +405,10 @@ val either: Either[Int, Int] = Left(1)  // Distinguishable via Left/Right
 Union discrimination relies on runtime type tests, which are fragile for erased types:
 
 ```scala
+import scala.collection.immutable.List
+
 // Problematic: List[Int] and List[String] erase to List
-val value: List[Int] | List[String] = List(1, 2, 3)
+val problematicValue: List[Int] | List[String] = List(1, 2, 3)
 // Runtime cannot distinguish List[Int] from List[String]
 
 // Safe: Use distinct concrete types
@@ -263,7 +417,12 @@ val value: Int | String = 42  // Works reliably
 
 ## Generic Usage Patterns
 
-### With Implicit Parameters (Scala 2)
+The combinators module supports both Scala 2's implicit parameters and Scala 3's context parameters. Here are idiomatic usage patterns for each:
+
+<Tabs groupId="scala-version" defaultValue="scala2">
+  <TabItem value="scala2" label="Scala 2">
+
+To combine multiple values using implicit typeclass resolution:
 
 ```scala
 import zio.blocks.combinators.Tuples
@@ -280,7 +439,10 @@ val result = combineAll(1, "hello", true)
 // result: (Int, String, Boolean)
 ```
 
-### With Context Parameters (Scala 3)
+  </TabItem>
+  <TabItem value="scala3" label="Scala 3">
+
+To combine multiple values using context parameters:
 
 ```scala
 import zio.blocks.combinators.Tuples
@@ -296,6 +458,9 @@ val result = combineAll(1, "hello", true)
 // result: (Int, String, Boolean)
 ```
 
+  </TabItem>
+</Tabs>
+
 ### Path-Dependent Types
 
 The `Out`, `Left`, and `Right` type members are path-dependent:
@@ -309,37 +474,102 @@ def process[L, R](l: L, r: R)(using t: Tuples.Tuples[L, R]): (L, R) =
 val result: (Int, String) = process(1, "hello")
 ```
 
-### Type Aliases for Clarity
+## Integration Points
+
+The combinator types integrate with other ZIO Blocks modules through systematic composition:
+
+**Schema Evolution**: The `Eithers` canonicalization strategy directly supports schema sum type encoding. When deriving schemas for sealed trait hierarchies, the combinator ensures all Either encodings use the same left-nested form, enabling consistent serialization across schema variants.
+
+**Error Handling**: `Eithers` provides a foundation for systematic error composition. Libraries building polymorphic error types can leverage canonicalization to ensure uniform error nesting, preventing subtle bugs from inconsistent Either structure.
+
+**Scala 3 APIs**: The `Unions` type enables idiomatic Scala 3 DSLs and API designs that use native union syntax. Gateway types that convert between union-based and Either-based representations (e.g., for serialization compatibility) can use `Unions` for zero-cost interop.
+
+**Tuple-Based Builders**: The `Tuples` module supports builder patterns and accumulator-based APIs that need to combine heterogeneous values step-by-step. By flattening automatically, it eliminates the ergonomic burden of manual nesting, making fluent builder chains natural.
+
+## Scala 2 vs Scala 3: Compatibility and Differences
+
+The combinators module works across Scala 2.13 and Scala 3.x with **full source compatibility**. Write your code once; it compiles on both versions. However, certain features are version-specific due to language capabilities:
+
+### Tuples: Version Differences
+
+**Scala 2.13 Limitations:**
+- Maximum arity of 22 (the standard library tuple limit)
+- Tuple flattening only works when the left argument is a tuple (right argument cannot be recursively flattened)
+- No `EmptyTuple` type (use `Unit` as identity instead)
+
+**Scala 3.x Enhancements:**
+- Unlimited arity (tuples are truly variable-length)
+- Recursive flattening on both sides: `Tuples.combine((1, "a"), (true, 3.14))` flattens both tuples into a 4-tuple
+- `EmptyTuple` as a first-class type with proper identity semantics
+
+**Example: The difference in practice**
+
+<Tabs groupId="scala-version" defaultValue="scala2">
+  <TabItem value="scala2" label="Scala 2.13">
+
+In Scala 2.13, combining two tuples on the right side fails to compile:
 
 ```scala
 import zio.blocks.combinators.Tuples
 
-// Typeclass with known output type
-type IntStringTuples = Tuples.Tuples.WithOut[Int, String, (Int, String)]
+// ERROR: right side not flattened
+val result = Tuples.combine((1, 2), (3, 4))  // Type mismatch
+```
+
+  </TabItem>
+  <TabItem value="scala3" label="Scala 3.x">
 
-// Typeclass with known left/right types
-type TripleTuples = Tuples.Tuples.WithOut[(Int, String), Boolean, (Int, String, Boolean)]
+In Scala 3.x, recursive flattening on both sides works seamlessly:
+
+```scala
+import zio.blocks.combinators.Tuples
+
+// OK: both sides flattened
+val result = Tuples.combine((1, 2), (3, 4))  // (1, 2, 3, 4)
 ```
 
-## Performance Characteristics
+  </TabItem>
+</Tabs>
+
+### Eithers: Full Cross-Version Support
+
+`Eithers` canonicalization works identically on Scala 2.13 and 3.x. No version-specific behavior. Use with confidence across versions—canonicalization is deterministic.
+
+### Unions: Scala 3 Only
+
+`Unions` requires Scala 3 because:
+- Union types (`A | B`) are a Scala 3 language feature
+- Runtime type tests (via `TypeTest`) are only available in Scala 3
+- Scala 2 has no native union syntax
+
+For Scala 2.13 codebases, use `Either` directly or `Eithers` canonicalization instead.
+
+### Feature Matrix
+
+| Feature                        | Scala 2.13 | Scala 3.x | Notes                         |
+|--------------------------------|------------|-----------|-------------------------------|
+| **Tuples.combine**             | ✅          | ✅         | Left-only flattening in 2.13  |
+| **Tuples.separate**            | ✅          | ✅         | Works identically on both     |
+| **Eithers.combine**            | ✅          | ✅         | No differences                |
+| **Eithers.separate**           | ✅          | ✅         | No differences                |
+| **Choices.left/right/separate**| ✅          | ✅         | Scala 2 uses `Either` alias   |
+| **Unions.combine**             | ❌          | ✅         | Requires Scala 3              |
+| **Unions.separate**            | ❌          | ✅         | Requires Scala 3              |
+| **EmptyTuple as identity**     | ❌          | ✅         | Use `Unit` in Scala 2         |
+| **Unlimited tuple arity**      | ❌          | ✅         | Limited to 22 in Scala 2      |
+| **Recursive tuple flattening** | ❌          | ✅         | Right side not flattened in 2 |
+
+### Migration Path from Scala 2 to 3
 
-| Module | Time Complexity | Notes |
-|--------|-----------------|-------|
-| Tuples.combine | O(1) to O(n) | O(1) for small tuples; O(n) for flattening nested tuples |
-| Tuples.separate | O(n) | Splits tuple at size-1 position |
-| Eithers.combine | O(d) | d = nesting depth of right-nested Either |
-| Eithers.separate | O(d) | Same as combine (delegates to combiner) |
-| Unions.combine | O(1) | Direct Either fold |
-| Unions.separate | O(1) | Single type test |
+When adopting Scala 3, no changes are required for existing `Tuples` and `Eithers` code. Your code continues to work without modification. However, you can take advantage of new capabilities:
 
-All operations are pure and allocation-minimal.
+1. **Adopt `EmptyTuple` idiom**: Use `EmptyTuple` instead of `Unit` when combining with `Tuples` in Scala 3 for consistency with modern tuple syntax. Note that `Unit` remains fully supported and valid—`EmptyTuple` is a stylistic enhancement, not a replacement.
+2. **Simplify tuple builders**: Leverage recursive flattening on both sides to remove manual nesting. In Scala 3, `Tuples.combine((1, "a"), (true, 3.14))` automatically flattens to `(1, "a", true, 3.14)`.
+3. **Adopt `Choices` in shared code**: Use `Choices.left`, `Choices.right`, and `Choices.separate` when you want a single `|`-based API shape to compile on both Scala 2 and Scala 3.
+4. **Adopt `Unions` in Scala 3-only code**: Replace `Either` with union types in new Scala 3-only code for idiomatic syntax using the `Unions` combinator.
+5. **Gradual adoption**: Use `Choices` in cross-version modules and `Unions` in Scala-3-only modules. Convert between them at module boundaries using `Unions.combine` and `Unions.separate` as needed.
 
-## Cross-Version Summary
+## See Also
 
-| Feature | Scala 2.13 | Scala 3.x |
-|---------|------------|-----------|
-| Tuples.Tuples | Yes (max 22) | Yes (unlimited) |
-| Eithers.Eithers | Yes | Yes |
-| Unions.Unions | No | Yes |
-| Recursive tuple flattening | No | Yes |
-| EmptyTuple handling | No | Yes |
+- [Schema](./schema/schema.md) — The Schema module uses `Eithers` canonicalization for encoding sealed trait hierarchies and sum types with consistent Either nesting.
+- **HTTP Model Schema** — When extracting multiple typed query parameters or headers in the HTTP Model schema module, `Eithers` provides systematic composition of error types for uniform error handling.