Implement opaque fn typeclass

Author: ignacio-hivemind

.gitignore

@@ -2,6 +2,8 @@
 .bloop
 .bsp
 .metals
+.idea
+.scala-build
 target
 project/project
 project/target

ai-docs/opaque-typeclass.spec.md

@@ -0,0 +1,268 @@
+# Opaque Type Encoder Specification
+
+## Problem Statement
+
+Currently, the `PromptEncoder` typeclass creates runtime wrapper objects for each encoder instance. This has several implications:
+
+1. **Runtime Overhead**: Each encoder is a wrapper around a function `A => Prompt`
+2. **Memory Allocation**: Creating encoder instances allocates objects
+3. **Indirection**: Method calls through trait interfaces add overhead
+4. **Compilation Time**: Complex typeclass resolution chains
+
+## Design Goal: Zero-Cost Abstraction
+
+The goal is to explore using **opaque types** to eliminate runtime overhead while maintaining:
+- **Type Safety**: Compile-time guarantees about encoder availability
+- **Ergonomics**: Good error messages when implicits are missing
+- **Composability**: Support for contravariant operations and combinators
+- **Developer Experience**: Clear, actionable compiler errors
+
+## Current Implementation Analysis
+
+### Current PromptEncoder:
+```scala
+trait PromptEncoder[A]:
+  def encode(a: A): Prompt
+
+object PromptEncoder:
+  given PromptEncoder[String] = x => Literal(x)
+  // Runtime: creates object with vtable lookup
+```
+
+**Issues:**
+- Each `given` creates a wrapper object
+- Method calls go through virtual dispatch
+- Memory allocation for each encoder instance
+
+## Proposed Solution: Opaque Function Types
+
+### Option 1: Direct Opaque Function
+```scala
+opaque type PromptEncoder[A] = A => Prompt
+
+object PromptEncoder:
+  // Zero-cost: just the function, no wrapper
+  given PromptEncoder[String] = x => Literal(x)
+  
+  extension [A](encoder: PromptEncoder[A])
+    def encode(a: A): Prompt = encoder(a)
+```
+
+### Option 2: Opaque Type with Phantom Type Parameter
+```scala
+opaque type PromptEncoder[A] <: (A => Prompt) = A => Prompt
+
+object PromptEncoder:
+  def apply[A](f: A => Prompt): PromptEncoder[A] = f
+  
+  given PromptEncoder[String] = apply(x => Literal(x))
+  
+  extension [A](encoder: PromptEncoder[A])
+    def encode(a: A): Prompt = encoder(a)
+```
+
+### Option 3: Opaque Type with Smart Constructor
+```scala
+opaque type PromptEncoder[A] = A => Prompt
+
+object PromptEncoder:
+  inline def from[A](f: A => Prompt): PromptEncoder[A] = f
+  
+  given string: PromptEncoder[String] = from(x => Literal(x))
+  given prompt: PromptEncoder[Prompt] = from(identity)
+```
+
+## Ergonomics Analysis
+
+### Error Messages Comparison
+
+**Current Trait-Based Approach:**
+```scala
+val x: String = "hello"
+val prompt = x.toPrompt(validator)  // Missing PromptEncoder[String]
+```
+Error: `No given instance of type PromptEncoder[String] was found`
+
+**Opaque Type Approach:**
+```scala
+val x: String = "hello" 
+val prompt = x.toPrompt(validator)  // Missing PromptEncoder[String]
+```
+Expected Error: `No given instance of type PromptEncoder[String] was found`
+
+### @implicitNotFound Annotation Support
+
+**Question**: Do `@implicitNotFound` annotations work with opaque types?
+
+**Test Cases to Explore:**
+
+#### Test 1: Basic @implicitNotFound on Opaque Type
+```scala
+import scala.annotation.implicitNotFound
+
+@implicitNotFound("No PromptEncoder available for type ${A}. Please provide an encoder or import PromptEncoder.unsafe._")
+opaque type PromptEncoder[A] = A => Prompt
+```
+
+#### Test 2: @implicitNotFound on Companion Object Methods
+```scala
+opaque type PromptEncoder[A] = A => Prompt
+
+object PromptEncoder:
+  @implicitNotFound("Custom encoder message for ${A}")
+  def summon[A](using encoder: PromptEncoder[A]): PromptEncoder[A] = encoder
+```
+
+#### Test 3: @implicitNotFound on Extension Methods
+```scala
+extension [A](a: A)
+  @implicitNotFound("Cannot convert ${A} to Prompt. Missing PromptEncoder[${A}]")
+  def toPrompt(validator: PromptValidator[A])(using encoder: PromptEncoder[A]): Prompt = 
+    Value(a, validator, encoder)
+```
+
+## Performance Analysis
+
+### Runtime Characteristics
+
+**Current Trait Implementation:**
+- ✅ Type safety at compile time
+- ❌ Virtual method dispatch overhead
+- ❌ Object allocation for each encoder
+- ❌ Memory overhead for trait objects
+
+**Opaque Function Implementation:**
+- ✅ Type safety at compile time  
+- ✅ Direct function call (no vtable)
+- ✅ Zero allocation overhead
+- ✅ Functions are values, not objects
+
+### Compilation Impact
+
+**Questions to Investigate:**
+1. **Specialization**: Do opaque function types specialize better?
+2. **Inlining**: Can the compiler inline through opaque boundaries?
+3. **Typeclass Resolution**: Is resolution faster with opaque types?
+4. **Binary Size**: Does the compiled output differ significantly?
+
+## Composability Analysis
+
+### Contravariant Semigroupal Support
+
+**Current Implementation:**
+```scala
+given contravariantSemigroupal: cats.ContravariantSemigroupal[PromptEncoder] with
+  def contramap[A, B](fa: PromptEncoder[A])(f: B => A): PromptEncoder[B] = ???
+  def product[A, B](fa: PromptEncoder[A], fb: PromptEncoder[B]): PromptEncoder[(A, B)] = ???
+```
+
+**Opaque Type Challenge:**
+```scala
+opaque type PromptEncoder[A] = A => Prompt
+
+// How to implement ContravariantSemigroupal for opaque types?
+given contravariantSemigroupal: cats.ContravariantSemigroupal[PromptEncoder] with
+  def contramap[A, B](fa: PromptEncoder[A])(f: B => A): PromptEncoder[B] = 
+    (b: B) => fa(f(b))  // This should work!
+    
+  def product[A, B](fa: PromptEncoder[A], fb: PromptEncoder[B]): PromptEncoder[(A, B)] =
+    (pair: (A, B)) => 
+      val (a, b) = pair
+      fa(a) |+| fb(b)  // Requires Semigroup[Prompt]
+```
+
+## Migration Strategy
+
+### Phase 1: Proof of Concept
+1. Create opaque type version alongside current implementation
+2. Test error message quality with @implicitNotFound
+3. Benchmark performance differences
+4. Verify cats typeclass instance compatibility
+
+### Phase 2: A/B Testing
+1. Implement same DSL functionality with both approaches
+2. Compare developer experience in real usage
+3. Measure compilation times and binary size
+4. Test IDE support and error highlighting
+
+### Phase 3: Decision & Migration
+1. Choose approach based on empirical evidence
+2. Create migration guide if opaque types are superior
+3. Deprecate old implementation gradually
+4. Update documentation and examples
+
+## Experimental Test Cases
+
+### Test 1: Basic Functionality
+```scala
+// Should work identically to current implementation
+opaque type TestEncoder[A] = A => Prompt
+
+given TestEncoder[String] = (s: String) => Literal(s)
+given TestEncoder[Int] = (i: Int) => Literal(i.toString)
+
+val stringPrompt: Prompt = summon[TestEncoder[String]]("hello")
+val intPrompt: Prompt = summon[TestEncoder[Int]](42)
+```
+
+### Test 2: Error Message Quality
+```scala
+// Should produce helpful error message
+def needsEncoder[A](a: A)(using TestEncoder[A]): Prompt = ???
+
+needsEncoder(List(1, 2, 3))  // No TestEncoder[List[Int]] - what error?
+```
+
+### Test 3: Composition
+```scala
+// Should compose like current encoders
+case class Person(name: String, age: Int)
+
+given TestEncoder[Person] = (p: Person) => 
+  summon[TestEncoder[String]](p.name) |+| summon[TestEncoder[Int]](p.age)
+```
+
+### Test 4: Performance Benchmark
+```scala
+// Compare allocation and timing
+def benchmarkCurrent(data: List[String]): List[Prompt] = 
+  data.map(summon[PromptEncoder[String]].encode)
+
+def benchmarkOpaque(data: List[String]): List[Prompt] = 
+  data.map(summon[TestEncoder[String]])
+```
+
+## Open Questions
+
+1. **@implicitNotFound Behavior**: Do annotations work on opaque types?
+2. **IDE Support**: How do IDEs display opaque type errors?
+3. **Debugging**: Can we debug through opaque type boundaries?
+4. **Specialization**: Does Scala 3 specialize opaque function types?
+5. **Variance**: How do opaque types interact with variance annotations?
+6. **Binary Compatibility**: Are opaque types binary compatible across versions?
+
+## Success Criteria
+
+**Must Have:**
+- ✅ Zero runtime overhead compared to current implementation
+- ✅ Equivalent type safety guarantees
+- ✅ Compatible with cats typeclass instances
+- ✅ Clear error messages for missing encoders
+
+**Nice to Have:**
+- ✅ Better error messages than current implementation
+- ✅ Faster compilation times
+- ✅ Smaller binary size
+- ✅ Better IDE integration
+
+**Deal Breakers:**
+- ❌ Worse error messages than current approach
+- ❌ Loss of composability features
+- ❌ Breaking changes to public API
+- ❌ Incompatibility with ecosystem libraries
+
+## Conclusion
+
+Opaque types offer a promising path to zero-cost abstractions for the encoder typeclass. The main unknowns are around error message quality and @implicitNotFound annotation support. 
+
+**Recommendation**: Implement a proof-of-concept to empirically test error messages, performance, and developer ergonomics before making any migration decisions.