@zio.dev/zio-blocks 0.0.1 → 0.0.21

package/reference/type-class-derivation-internals.md

@@ -1,632 +0,0 @@
-# Type-Class Derivation Internals: A Step-by-Step Deep Dive
-
-This document explains the internal mechanics of how ZIO Blocks derives type-class instances (like `Show`, `Eq`, `Encoder`, etc.) from a schema. We use the `Show` type-class derivation for a simple `Person` record as our running example.
-
-> **Related Documentation**: For a high-level overview of the `Deriver` API and how to implement custom derivers, see [Type Class Derivation](type-class-derivation.md).
-
-> **Example Code**: The traces in this document are generated from `DeriveShowApproachOne.scala` in the `zio-blocks-examples` module. Run it with `sbt "examples/runMain typeclassderivation.DeriveShowApproachOne"` to see the full execution trace.
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [The Key Components](#the-key-components)
-3. [The Complete Flow](#the-complete-flow)
-4. [Step-by-Step Walkthrough](#step-by-step-walkthrough)
-5. [Why Lazy Evaluation?](#why-lazy-evaluation)
-6. [Execution Trace Analysis](#execution-trace-analysis)
-
----
-
-## Overview
-
-When you write:
-
-```scala
-case class Person(name: String, age: Int)
-
-object Person {
-  implicit val schema: Schema[Person] = Schema.derived[Person]
-  implicit val show: Show[Person] = schema.derive(DeriveShow)
-}
-```
-
-The framework performs a sophisticated transformation that:
-
-1. **Traverses** the schema tree (which describes the structure of `Person`)
-2. **Transforms** each node, wrapping the runtime `Binding` with a `Lazy[TC[A]]` instance
-3. **Returns** the derived type-class instance at the root
-
-The key insight is that derivation is a **tree transformation** where each node gets augmented with its corresponding type-class instance.
-
----
-
-## The Key Components
-
-### 1. Schema and Reflect
-
-A `Schema[A]` is a wrapper around `Reflect[Binding, A]`, which is a tree structure describing your data type:
-
-```
-Schema[Person]
-  └── Reflect.Record[Binding, Person]
-        ├── Term("name", Reflect.Primitive[Binding, String])
-        └── Term("age", Reflect.Primitive[Binding, Int])
-```
-
-Each node carries:
-- **Type information** (TypeId, PrimitiveType for primitives)
-- **Binding** - runtime machinery for constructing/deconstructing values
-
-
-### 4. ReflectTransformer[F, G]
-
-The transformation is performed by a `ReflectTransformer` that visits each node:
-
-```scala
-trait ReflectTransformer[F[_, _], G[_, _]] {
-  def transformPrimitive[A](...): Lazy[Reflect.Primitive[G, A]]
-  def transformRecord[A](...): Lazy[Reflect.Record[G, A]]
-  // ... etc
-}
-```
-
-## The Complete Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                          Type-Class Derivation Flow                          │
-└─────────────────────────────────────────────────────────────────────────────┘
-
-INPUT:
-  Schema[Person] containing Reflect[Binding, Person]
-
-PHASE 1: Tree Transformation (Bottom-Up)
-  ┌──────────────────────────────────────────────────────────────────────────┐
-  │  For each node in the schema tree (leaves first, then parents):          │
-  │                                                                          │
-  │  1. Transform child nodes first (if any)                                 │
-  │  2. Call the appropriate Deriver method to get Lazy[TC[A]]               │
-  │  3. Wrap the Binding with the Lazy[TC[A]] into a BindingInstance         │
-  │  4. Return the transformed Reflect node                                  │
-  └──────────────────────────────────────────────────────────────────────────┘
-
-  Transformation sequence for Person:
-
-    Step 1: Transform Primitive "name" (String)
-            → deriver.derivePrimitive(String) → Lazy[Show[String]]
-            → BindingInstance(Binding.Primitive, Lazy[Show[String]])
-
-    Step 2: Transform Primitive "age" (Int)
-            → deriver.derivePrimitive(Int) → Lazy[Show[Int]]
-            → BindingInstance(Binding.Primitive, Lazy[Show[Int]])
-
-    Step 3: Transform Record "Person"
-            → deriver.deriveRecord(fields with transformed metadata)
-            → Lazy[Show[Person]]
-            → BindingInstance(Binding.Record, Lazy[Show[Person]])
-
-PHASE 2: Extract Root Instance
-  ┌──────────────────────────────────────────────────────────────────────────┐
-  │  transformedTree.metadata.instance.force                                 │
-  │                                                                          │
-  │  This forces the Lazy[Show[Person]] at the root, which:                  │
-  │  - Creates the Show[Person] instance                                     │
-  │  - Captures references to Lazy[Show[String]] and Lazy[Show[Int]]         │
-  │  - Does NOT force the child instances yet (they remain lazy)             │
-  └──────────────────────────────────────────────────────────────────────────┘
-
-OUTPUT:
-  Show[Person] instance that can show any Person value
-
-PHASE 3: Runtime Usage
-  ┌──────────────────────────────────────────────────────────────────────────┐
-  │  When show.show(Person("Alice", 30)) is called:                          │
-  │                                                                          │
-  │  1. Deconstruct Person into registers (name="Alice", age=30)             │
-  │  2. For each field, force its Lazy[Show] and call .show()                │
-  │     - Force Lazy[Show[String]], call show("Alice") → "\"Alice\""         │
-  │     - Force Lazy[Show[Int]], call show(30) → "30"                        │
-  │  3. Combine results → Person(name = "Alice", age = 30)                   │
-  └──────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Step-by-Step Walkthrough
-
-Let's trace through exactly what happens when we derive `Show[Person]`.
-
-### Phase 1: Schema Definition
-
-```scala
-case class Person(name: String, age: Int)
-implicit val schema: Schema[Person] = Schema.derived[Person]
-```
-
-At compile time, macros generate a `Reflect.Record` structure:
-
-```scala
-Reflect.Record[Binding, Person](
-  fields = Vector(
-    Term("name", Reflect.Primitive[Binding, String](PrimitiveType.String, ...)),
-    Term("age", Reflect.Primitive[Binding, Int](PrimitiveType.Int, ...))
-  ),
-  typeId = TypeId[Person],
-  recordBinding = Binding.Record[Person](constructor, deconstructor)
-)
-```
-
-### Phase 2: Derivation Starts
-
-```scala
-implicit val show: Show[Person] = schema.derive(DeriveShow)
-```
-
-This calls `DerivationBuilder.derive`, which:
-
-1. **Prepares override maps** (for custom instances/modifiers)
-2. **Calls `schema.reflect.transform(...)`** with a `ReflectTransformer`
-
-### Phase 3: Tree Transformation
-
-The transformation proceeds **bottom-up** (children before parents):
-
-#### Step 3.1: Transform Field "name" (String primitive)
-
-```
-[Reflect.Primitive.transform] Transforming primitive 'String' at path: .name
-  [transformPrimitive] Calling deriver.derivePrimitive for 'String'
-    [derivePrimitive] Creating Lazy[Show[String]] (not yet evaluated)
-  [transformPrimitive] Created BindingInstance for 'String' with Lazy[TC] instance
-```
-
-The transformer:
-1. Calls `deriver.derivePrimitive(PrimitiveType.String, ...)`
-2. Gets back `Lazy[Show[String]]` (unevaluated)
-3. Creates `BindingInstance(Binding.Primitive, Lazy[Show[String]])`
-4. Returns `Reflect.Primitive[BindingInstance, String]`
-
-#### Step 3.2: Transform Field "age" (Int primitive)
-
-```
-[Reflect.Primitive.transform] Transforming primitive 'Int' at path: .age
-  [transformPrimitive] Calling deriver.derivePrimitive for 'Int'
-    [derivePrimitive] Creating Lazy[Show[Int]] (not yet evaluated)
-  [transformPrimitive] Created BindingInstance for 'Int' with Lazy[TC] instance
-```
-
-Same process for Int.
-
-#### Step 3.3: Transform Record "Person"
-
-```
-[Reflect.Record.transform] All fields transformed, now transforming record 'Person'
-  [transformRecord] Calling deriver.deriveRecord for 'Person'
-    [deriveRecord] Creating Lazy[Show[Person]] (not yet evaluated)
-  [transformRecord] Created BindingInstance for 'Person' with Lazy[TC] instance
-```
-
-The transformer:
-1. Receives the transformed fields (with `BindingInstance` metadata)
-2. Calls `deriver.deriveRecord(transformedFields, ...)`
-3. Gets back `Lazy[Show[Person]]` (unevaluated)
-4. Creates `BindingInstance(Binding.Record, Lazy[Show[Person]])`
-5. Returns `Reflect.Record[BindingInstance, Person]`
-
-### Phase 4: Extract the Instance
-
-```
-[DerivationBuilder] STEP 3: Extracting the top-level instance
-  Calling .force on the Lazy[TC[A]] at the root...
-
-  [Lazy.force] Forcing unevaluated Lazy computation...
-  [deriveRecord] NOW EVALUATING: Creating Show instance for record type: Person
-    Step 1: Collecting Lazy[Show] instances for each field...
-      - Getting Lazy[Show] for field 'name' from transformed metadata
-      - Getting Lazy[Show] for field 'age' from transformed metadata
-    Step 2: Building Reflect.Record to compute register layout...
-    Step 3: Register layout computed.
-  [deriveRecord] Show instance for 'Person' created (field Show instances still lazy)
-```
-
-When `.force` is called on the root `Lazy[Show[Person]]`:
-
-1. The deferred computation in `deriveRecord` finally executes
-2. It retrieves the `Lazy[Show]` for each field (but doesn't force them!)
-3. It builds the register layout for field access
-4. It returns a `Show[Person]` instance
-
-**Critical Point**: The field `Show` instances (`Lazy[Show[String]]`, `Lazy[Show[Int]]`) are **not forced yet**. They are captured by closure in the `Show[Person]` implementation.
-
-### Phase 5: Using the Derived Instance
-
-```scala
-val result = Person.show.show(Person("Alice", 30))
-```
-
-```
-[Show.show] Called for Person value
-  Step A: Created registers for deconstruction
-  Step B: Deconstructed record into registers
-  Step C: Building field strings (will force Lazy[Show] for each field)...
-    - Field 'name': forcing Lazy[Show] and calling show(Alice)
-      [Lazy.force] Forcing unevaluated Lazy computation...
-      [derivePrimitive] NOW EVALUATING: Creating Show instance for primitive type: String
-    - Field 'name' result: name = "Alice"
-    - Field 'age': forcing Lazy[Show] and calling show(30)
-      [Lazy.force] Forcing unevaluated Lazy computation...
-      [derivePrimitive] NOW EVALUATING: Creating Show instance for primitive type: Int
-    - Field 'age' result: age = 30
-
-Final result: Person(name = "Alice", age = 30)
-```
-
-Only when we actually **use** the `Show[Person]` do the field instances get created:
-
-1. Deconstruct `Person("Alice", 30)` into registers
-2. For field "name":
-   - Force `Lazy[Show[String]]` → creates `Show[String]` instance
-   - Call `show("Alice")` → `"\"Alice\""`
-3. For field "age":
-   - Force `Lazy[Show[Int]]` → creates `Show[Int]` instance
-   - Call `show(30)` → `"30"`
-4. Combine: `Person(name = "Alice", age = 30)`
-
----
-
-## Why Lazy Evaluation?
-
-The `Lazy` wrapper is essential for handling **recursive types**:
-
-```scala
-case class Tree(value: Int, children: List[Tree])
-```
-
-The schema for `Tree` contains a reference back to itself:
-
-```
-Reflect.Record[Tree]
-  ├── Term("value", Reflect.Primitive[Int])
-  └── Term("children", Reflect.Sequence[Tree]  ← contains Tree!
-                         └── Reflect.Deferred[Tree] ← lazy reference)
-```
-
-Without lazy evaluation:
-- Deriving `Show[Tree]` would need `Show[List[Tree]]`
-- Which needs `Show[Tree]`
-- Which needs `Show[List[Tree]]`
-- **Infinite loop!**
-
-With lazy evaluation:
-- Deriving `Show[Tree]` creates `Lazy[Show[Tree]]`
-- `Lazy[Show[List[Tree]]]` captures a reference to the `Lazy[Show[Tree]]`
-- No infinite loop because nothing is evaluated until `.force`
-- The `Reflect.Deferred` uses caching to return the same instance
-
----
-
-## Execution Trace Analysis
-
-Here's the actual execution trace from running `DeriveShowApproachOne`. Each section is annotated to explain what's happening:
-
-### Actual Output
-
-```
-================================================================================
-Example 1: Simple Person Record with two primitive fields
-================================================================================
-
-------------------------------------------------------------
-PHASE 1: Schema Definition
-------------------------------------------------------------
-Creating Schema[Person] via Schema.derived[Person]
-This uses compile-time macros to generate a Reflect.Record structure
-
-Schema created: Schema {
-  record Person {
-    name: String
-    age: Int
-  }
-}
-```
-
-**What's happening**: At compile time, Scala macros inspect the `Person` case class and generate a `Reflect.Record` structure that describes its fields and types.
-
-```
-------------------------------------------------------------
-PHASE 2: Type-Class Derivation (schema.derive(DeriveShow))
-------------------------------------------------------------
-This is where the magic happens!
-The framework will:
-  1. Transform the schema tree, wrapping each node's Binding with BindingInstance
-  2. Create Lazy[Show[T]] instances for each schema node
-  3. Return the top-level Show[Person] instance
-
-
-================================================================================
-[DerivationBuilder.derive] Starting type-class derivation
-================================================================================
-  Schema structure: Schema {
-  record Person {
-    name: String
-    age: Int
-  }
-}
-
-[DerivationBuilder] STEP 1: Starting schema tree transformation
-  Purpose: Transform each node from Reflect[Binding, A] to Reflect[BindingInstance, A]
-  This wraps each Binding with a Lazy[TC[A]] instance for that node
-```
-
-**What's happening**: The `DerivationBuilder` begins the transformation process. The goal is to convert the schema tree from `Reflect[Binding, A]` (just runtime bindings) to `Reflect[BindingInstance, A]` (bindings + derived instances).
-
-```
-  [Lazy.force] Forcing unevaluated Lazy computation...
-```
-
-**What's happening**: The transformation itself is lazy! This first `.force` kicks off the tree traversal.
-
-```
-[Reflect.Record.transform] Starting transformation for 'Person' at path: .
-  - This record has 2 fields: name, age
-  - Will first transform all child fields (bottom-up), then transform the record itself
-```
-
-**What's happening**: We start at the root (Person), but we must transform children first. This is the **bottom-up** traversal pattern.
-
-```
-[Reflect.Primitive.transform] Transforming primitive 'Int' at path: .age
-  [transformPrimitive] Calling deriver.derivePrimitive for 'Int' at path: .age
-  [derivePrimitive] Creating Lazy[Show[Int]] (not yet evaluated)
-    - PrimitiveType: Int
-    - This Lazy will be forced later when the Show instance is actually needed
-  [transformPrimitive] Created BindingInstance for 'Int' with Lazy[TC] instance
-[Reflect.Primitive.transform] Completed transformation for 'Int'
-```
-
-**What's happening**: The `age` field (Int primitive) is transformed first:
-1. `deriver.derivePrimitive` is called, which returns a `Lazy[Show[Int]]`
-2. A `BindingInstance` is created wrapping the original `Binding.Primitive` with this `Lazy[Show[Int]]`
-3. The `Lazy` is **not forced yet** - the actual `Show[Int]` instance hasn't been created!
-
-```
-[Reflect.Primitive.transform] Transforming primitive 'String' at path: .name
-  [transformPrimitive] Calling deriver.derivePrimitive for 'String' at path: .name
-  [derivePrimitive] Creating Lazy[Show[String]] (not yet evaluated)
-    - PrimitiveType: String
-    - This Lazy will be forced later when the Show instance is actually needed
-  [transformPrimitive] Created BindingInstance for 'String' with Lazy[TC] instance
-[Reflect.Primitive.transform] Completed transformation for 'String'
-```
-
-**What's happening**: Same process for the `name` field (String primitive). Now both children are transformed.
-
-```
-[Reflect.Record.transform] All fields transformed, now transforming record 'Person'
-  [transformRecord] Calling deriver.deriveRecord for 'Person' at path: .
-  [deriveRecord] Creating Lazy[Show[Person]] (not yet evaluated)
-    - Number of fields: 2
-    - Field names: name, age
-    - This Lazy will be forced later when the Show instance is actually needed
-  [transformRecord] Created BindingInstance for 'Person' with Lazy[TC] instance
-[Reflect.Record.transform] Completed transformation for 'Person'
-```
-
-**What's happening**: Now the parent (Person record) can be transformed:
-1. It receives the transformed fields (with `BindingInstance` metadata)
-2. `deriver.deriveRecord` is called, returning `Lazy[Show[Person]]`
-3. A `BindingInstance` wraps `Binding.Record` with `Lazy[Show[Person]]`
-
-```
-[DerivationBuilder] STEP 2: Schema transformation complete
-  The entire schema tree has been transformed.
-  Each node now has a BindingInstance containing:
-    - The original Binding (for runtime operations)
-    - A Lazy[TC[A]] (the derived type-class instance)
-
-[DerivationBuilder] STEP 3: Extracting the top-level instance
-  Calling .force on the Lazy[TC[A]] at the root of the transformed tree...
-```
-
-**What's happening**: The tree transformation is complete. Now we need to extract the actual `Show[Person]` instance from the root node.
-
-```
-  [deriveRecord] NOW EVALUATING: Creating Show instance for record type: Person
-    Step 1: Collecting Lazy[Show] instances for each field...
-      - Getting Lazy[Show] for field 'name' from transformed metadata
-        (This retrieves the Lazy[Show] that was created during transformation)
-  [HasInstance.instance] Retrieving Lazy[TC] from BindingInstance
-    - Binding type: Primitive
-    - Instance evaluated: false
-        Got Lazy[Show] for 'name' (not yet forced)
-      - Getting Lazy[Show] for field 'age' from transformed metadata
-        (This retrieves the Lazy[Show] that was created during transformation)
-  [HasInstance.instance] Retrieving Lazy[TC] from BindingInstance
-    - Binding type: Primitive
-    - Instance evaluated: false
-        Got Lazy[Show] for 'age' (not yet forced)
-    Step 2: Building Reflect.Record to compute register layout...
-    Step 3: Register layout computed. UsedRegisters: 17179869185
-  [deriveRecord] Show instance for 'Person' created (field Show instances still lazy)
-```
-
-**What's happening**: This is crucial! When we force `Lazy[Show[Person]]`:
-1. The `deriveRecord` deferred code finally runs
-2. It retrieves the `Lazy[Show]` for each field from the transformed metadata
-3. **It does NOT force those lazy instances** - they remain unevaluated
-4. The `Show[Person]` is created, capturing references to the lazy field instances
-
-```
-------------------------------------------------------------
-PHASE 3: Using the Derived Show Instance
-------------------------------------------------------------
-Now calling personShow.show(Person("Alice", 30))
-This will force the Lazy[Show] instances as needed...
-
-    [Show.show] Called for Person value
-      Step A: Created registers for deconstruction
-      Step B: Deconstructed record into registers
-      Step C: Building field strings (will force Lazy[Show] for each field)...
-```
-
-**What's happening**: Now we actually use the `Show[Person]` instance:
-1. Registers are allocated for holding field values
-2. The `Person("Alice", 30)` value is deconstructed into registers (name="Alice", age=30)
-
-```
-        - Field 'name': forcing Lazy[Show] and calling show(Alice)
-  [Lazy.force] Forcing unevaluated Lazy computation...
-  [derivePrimitive] NOW EVALUATING: Creating Show instance for primitive type: String
-        - Field 'name' result: name = "Alice"
-```
-
-**What's happening**: For the first field:
-1. The `Lazy[Show[String]]` is finally forced
-2. The `derivePrimitive` deferred code runs, creating the actual `Show[String]`
-3. `show("Alice")` is called, returning `"\"Alice\""`
-
-```
-        - Field 'age': forcing Lazy[Show] and calling show(30)
-  [Lazy.force] Forcing unevaluated Lazy computation...
-  [derivePrimitive] NOW EVALUATING: Creating Show instance for primitive type: Int
-        - Field 'age' result: age = 30
-```
-
-**What's happening**: Same for the second field:
-1. `Lazy[Show[Int]]` is forced
-2. `Show[Int]` is created
-3. `show(30)` returns `"30"`
-
-```
-============================================================
-FINAL RESULT: Person(name = "Alice", age = 30)
-============================================================
-```
-
-**What's happening**: The field strings are combined into the final result.
-
----
-
-## Visual Representation of the Transformation
-
-### Before Transformation
-
-```
-Schema[Person]
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  Reflect.Record[Binding, Person]                                    │
-│  ┌─────────────────────────────────────────────────────────────┐   │
-│  │ metadata: Binding.Record[Person]                             │   │
-│  │   - constructor: (String, Int) => Person                     │   │
-│  │   - deconstructor: Person => (String, Int)                   │   │
-│  └─────────────────────────────────────────────────────────────┘   │
-│                                                                     │
-│  fields:                                                            │
-│  ├── Term("name", ─────────────────────────────────────────────┐   │
-│  │   │  Reflect.Primitive[Binding, String]                     │   │
-│  │   │  ┌─────────────────────────────────────────────────┐   │   │
-│  │   │  │ metadata: Binding.Primitive                     │   │   │
-│  │   │  │ primitiveType: PrimitiveType.String             │   │   │
-│  │   │  └─────────────────────────────────────────────────┘   │   │
-│  │   └─────────────────────────────────────────────────────────┘   │
-│  │                                                                  │
-│  └── Term("age", ──────────────────────────────────────────────┐   │
-│      │  Reflect.Primitive[Binding, Int]                        │   │
-│      │  ┌─────────────────────────────────────────────────┐   │   │
-│      │  │ metadata: Binding.Primitive                     │   │   │
-│      │  │ primitiveType: PrimitiveType.Int                │   │   │
-│      │  └─────────────────────────────────────────────────┘   │   │
-│      └─────────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### After Transformation
-
-```
-Reflect.Record[BindingInstance[Show], Person]
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  Reflect.Record[BindingInstance[Show], Person]                      │
-│  ┌─────────────────────────────────────────────────────────────┐   │
-│  │ metadata: BindingInstance[Show, Record, Person]              │   │
-│  │   ├── binding: Binding.Record[Person]                        │   │
-│  │   └── instance: Lazy[Show[Person]] ◄─── FORCED (evaluated)   │   │
-│  └─────────────────────────────────────────────────────────────┘   │
-│                                                                     │
-│  fields:                                                            │
-│  ├── Term("name", ─────────────────────────────────────────────┐   │
-│  │   │  Reflect.Primitive[BindingInstance[Show], String]       │   │
-│  │   │  ┌─────────────────────────────────────────────────┐   │   │
-│  │   │  │ metadata: BindingInstance[Show, Primitive, Str] │   │   │
-│  │   │  │   ├── binding: Binding.Primitive                │   │   │
-│  │   │  │   └── instance: Lazy[Show[String]] ◄── NOT YET! │   │   │
-│  │   │  └─────────────────────────────────────────────────┘   │   │
-│  │   └─────────────────────────────────────────────────────────┘   │
-│  │                                                                  │
-│  └── Term("age", ──────────────────────────────────────────────┐   │
-│      │  Reflect.Primitive[BindingInstance[Show], Int]          │   │
-│      │  ┌─────────────────────────────────────────────────┐   │   │
-│      │  │ metadata: BindingInstance[Show, Primitive, Int] │   │   │
-│      │  │   ├── binding: Binding.Primitive                │   │   │
-│      │  │   └── instance: Lazy[Show[Int]] ◄─── NOT YET!   │   │   │
-│      │  └─────────────────────────────────────────────────┘   │   │
-│      └─────────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### Key Observation
-
-Notice that after transformation:
-- The root `Lazy[Show[Person]]` is **FORCED** (evaluated)
-- The child `Lazy[Show[String]]` and `Lazy[Show[Int]]` are **NOT YET** evaluated
-- They will only be evaluated when `Show[Person].show(...)` is actually called
-
-This lazy evaluation strategy is what enables:
-1. **Efficient derivation**: Only create instances that are actually used
-2. **Recursive type support**: Self-referential types don't cause infinite loops
-3. **Memory efficiency**: Instances are created on-demand
-
----
-
-## Summary
-
-The type-class derivation process in ZIO Blocks:
-
-1. **Transforms the schema tree bottom-up**, visiting primitives/leaves before records/variants
-2. **Wraps each node's Binding** with a `BindingInstance` containing a `Lazy[TC[A]]`
-3. **Uses lazy evaluation** to defer actual instance creation until needed
-4. **Forces only what's necessary** - the root instance is forced, but children remain lazy until used
-5. **Handles recursion** through `Lazy` and `Reflect.Deferred` with caching
-
-This design provides:
-- **Efficiency**: Only creates instances that are actually used
-- **Safety**: Handles recursive types without stack overflow
-- **Composability**: Each node's derivation is independent and can be overridden
-
----
-
-## Key Files in the Codebase
-
-| File | Purpose |
-|------|---------|
-| `schema/shared/src/main/scala/zio/blocks/schema/derive/DerivationBuilder.scala` | Orchestrates the derivation process |
-| `schema/shared/src/main/scala/zio/blocks/schema/derive/Deriver.scala` | The trait you implement to create a new deriver |
-| `schema/shared/src/main/scala/zio/blocks/schema/derive/BindingInstance.scala` | Container for Binding + Lazy instance |
-| `schema/shared/src/main/scala/zio/blocks/schema/Reflect.scala` | Schema tree nodes with transform methods |
-| `schema/shared/src/main/scala/zio/blocks/schema/Lazy.scala` | Trampolined lazy evaluation monad |
-| `zio-blocks-examples/src/main/scala/typeclassderivation/DeriveShowApproachOne.scala` | Example with detailed logging |
-
----
-
-## Running the Example
-
-To see the full execution trace yourself:
-
-```bash
-sbt "examples/runMain typeclassderivation.DeriveShowApproachOne"
-```
-
-This will print the detailed step-by-step trace shown in this document, helping you understand exactly what happens during type-class derivation.