@zio.dev/zio-blocks 0.0.1

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

@@ -0,0 +1,632 @@
+# 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.