halotukozak

Method too large

Bartłomiej Kozak — Thu, 30 Oct 2025 00:00:00 GMT

Scala 3 macro vs JVM method size limit

It's so big

While working on my BSc thesis, I encountered a cryptic Scala compilation error: "method too large". I use macros to generate code, and I mean, a lot of code! Think derivations, routing REST API generation or SQL queries.

What's going on?

To simplify the example, let’s reduce it to generating a long list. In a real case, though, the list creation can't be replaced with a simple loop, because the elements aren't predictable.

import scala.quoted.*

inline def someMacro[T](inline n: Int, elem: T): Seq[T] =
  ${ someMacroImpl[T]('{ n }, '{ elem }) }

def someMacroImpl[T: Type](n: Expr[Int], elem: Expr[T])(using Quotes): Expr[Seq[T]] = 
  val longList = Seq.fill(n.valueOrAbort)(elem)
  Expr.ofSeq(longList)

def usage = someMacro(100000, 42) // List(42, 42, 42, ..., 42)

I assume you have some familiarity with macros in Scala, otherwise this Software Mill article can be helpful. I use them to generate a long list of repeated elements at compile time and then inject it into the code.

Quick recap:

inline marks the method as an inline one that will be expanded at compile time
Splice syntax ${ ... } that invokes the macro implementation
Quote syntax '{ n } and '{ elem } that converts values into Expr[T] representations
Quotes parameter provides the context for macro expansion
Expr.ofSeq converts a sequence of expressions into an expression representing a sequence

When I try to compile this code, I get a not-too-verbose error:

Error while emitting Usage$package$
Method too large: Usage$package$.main ()Lscala/collection/immutable/Seq;
one error found

This error occurs when a single method exceeds the JVM's limit of 64KB of bytecode. But how can we bypass this limitation?

Local methods translation

JVM doesn't support local methods directly, so Scala finds a way to compile them. Let's see how. Consider the following Scala code:

def sth() = 
  def local() = ???

  local()

which is compiled to:

//decompiled from Usage$package.class

import scala.runtime.Nothing;

public final class Usage$package {
    public static Nothing sth() {
        return Usage$package$.MODULE$.sth();
    }
}

//decompiled from Usage$package$.class
import java.io.Serializable;
import scala.Predef .;
import scala.runtime.ModuleSerializationProxy;
import scala.runtime.Nothing;

public final class Usage$package$ implements Serializable {
    public static final Usage$package$ MODULE$ = new Usage$package$();

    private Usage$package$() {
    }

    private Object writeReplace() {
        return new ModuleSerializationProxy(Usage$package$.class);
    }

    public Nothing sth() {
        return this.local$1();
    }

    private final Nothing local$1() {
        return .MODULE$.$qmark$qmark$qmark();
    }
}

As you can see, the local method local is compiled to a private method local$1 of the enclosing object Usage$package$.

The chunking solution

The story goes that nine women can't have a baby in a month. In our case, we can't generate a large method, but we can split it into smaller methods.

inline def someMacro2[T](inline n: Int, elem: T): Seq[T] =
  ${ someMacroImpl2[T]('{ n }, '{ elem }) }

def someMacroImpl2[T: Type](n: Expr[Int], elem: Expr[T])(using quotes: Quotes): Expr[Seq[T]] = 
  import quotes.reflect.*
  import scala.collection.mutable

  val longList = Seq.fill(n.valueOrAbort)(elem)

  val symbol = Symbol.newVal(
    Symbol.spliceOwner,
    Symbol.freshName("builder"),
    TypeRepr.of[mutable.Builder[T, Seq[T]]],
    Flags.Synthetic,
    Symbol.noSymbol,
  )

  val valDef = ValDef(symbol, Some('{ Seq.newBuilder[T] }.asTerm))

  val builder = Ref(symbol).asExprOf[mutable.Builder[T, Seq[T]]]

  val additions = longList
    .map(element =>
      '{
        def avoidTooLargerMethod(): Unit = $builder += $element
          avoidTooLargerMethod()
      }.asTerm,
    )
    .toList

  val result = '{ $builder.result() }.asTerm

  Block(valDef :: additions, result).asExprOf[Seq[T]]

The entry point is much the same, but in the implementation, we usequotes.reflect.* to build the AST manually.

We create a new Symbol for a mutable builder, then we create a ValDef to define this builder variable. Fresh name generation is crucial here to avoid name clashes in the generated code.

We create a reference to this builder with Ref(symbol).

additions is a list of terms, each representing a local method that adds an element to the builder. We don't have to worry about the method names since they are local and will be compiled to unique private methods.

We then create a Block that contains the variable definition, all the addition methods, and the final result retrieval.

Finally, we convert this block to an expression of type Seq[T].

The generated code looks like this:

def usage = {
  val builder$macro$1: scala.collection.mutable.Builder[scala.Int, scala.collection.immutable.Seq[scala.Int]] = scala.Seq.newBuilder[scala.Int]

  def avoidTooLargerMethod(): scala.Unit = {
    builder$macro$1.+=(42)
    ()
  }

  avoidTooLargerMethod()

  def `avoidTooLargerMethod₂`(): scala.Unit = {
    builder$macro$1.+=(42)
    ()
  }

  `avoidTooLargerMethod₂`()

  def `avoidTooLargerMethod₃`(): scala.Unit = {
    builder$macro$1.+=(42)
    ()
  }

  `avoidTooLargerMethod₃`()
  builder$macro$1.result()
}

And decompiled to Java:

//
// Source code recreated by IntelliJ IDEA
// (powered by FernFlower decompiler)
//

//decompiled from Usage$package.class

import scala.collection.immutable.Seq;

public final class Usage$package {
    public static Seq<Object> usage() {
        return Usage$package$.MODULE$.usage();
    }
}

//decompiled from Usage$package$.class
import java.io.Serializable;
import scala.collection.immutable.Seq;
import scala.collection.mutable.Builder;
import scala.package.;
import scala.runtime.BoxesRunTime;
import scala.runtime.ModuleSerializationProxy;

public final class Usage$package$ implements Serializable {
    public static final Usage$package$ MODULE$ = new Usage$package$();

    private Usage$package$() {
    }

    private Object writeReplace() {
        return new ModuleSerializationProxy(Usage$package$.class);
    }

    public Seq<Object> usage() {
        Builder var1 = .MODULE$.Seq().newBuilder();
        this.avoidTooLargerMethod$1(var1);
        this.avoidTooLargerMethod$2(var1);
        this.avoidTooLargerMethod$3(var1);
        return (Seq) var1.result();
    }

    private final void avoidTooLargerMethod$1(final Builder builder$macro$1$1) {
        builder$macro$1$1.$plus$eq(BoxesRunTime.boxToInteger(42));
    }

    private final void avoidTooLargerMethod$2(final Builder builder$macro$1$2) {
        builder$macro$1$2.$plus$eq(BoxesRunTime.boxToInteger(42));
    }

    private final void avoidTooLargerMethod$3(final Builder builder$macro$1$3) {
        builder$macro$1$3.$plus$eq(BoxesRunTime.boxToInteger(42));
    }
}

Case closed

Back to working on my thesis now. We'll see if I find time to write something here again.

Written by me[^*], no AI.

[^*]: The English text and grammar were kindly reviewed and corrected by my friend Mateusz.

Type-Safe Access to Method Parameter Defaults in Scala

Bartłomiej Kozak — Sat, 10 Jan 2026 00:00:00 GMT

The Problem: Hidden Defaults

Someone asked on the Scala contributors forum how to access method parameter defaults.

Default parameters are convenient syntax sugar, but sometimes you need to access them programmatically. Imagine you're building a configuration builder and want to include the default values in help text:

case class Database(host: String = "localhost", port: Int = 5432, name: String = "mydb")

// You want to generate documentation:
// "host" (default: localhost)
// "port" (default: 5432)
// "name" (default: mydb)

We'd like to pass a method reference and get back a Map[String, Any] containing all parameter defaults.

@main
def main(): Unit =
  assert(defaults(method) == Map("x" -> 10, "y" -> "two"))

def method(x: Int = 10, y: String = "two") = ???

Prerequisites

With this goal in mind, let's ensure you have the right background knowledge before diving into the implementation. I assume you're comfortable with Scala and have some familiarity with Scala 3 macros. If you need a refresher on Scala 3 macros, I recommend this Software Mill article first.

I use Scala 3.8.0-RC4 for this example.

How Scala Encodes Defaults

Since the JVM doesn't natively support default parameters, Scala gets creative. When you define a method with defaults, the compiler generates companion methods in the class for each defaulted parameter. These methods are named with a special encoding: $default$N, where N is the parameter position (1-indexed).

So def method(x: Int = 10, y: String = "two") = ??? actually creates:

//
// Source code recreated by IntelliJ IDEA
// (powered by FernFlower decompiler)
//
// decompiled from main$package$.class
import java.io.Serializable;
import scala.runtime.Nothing;
import scala.runtime.Scala3RunTime.;

public final class main$package$ implements Serializable {
    // ... other generated code ...

    public Nothing method(final int x, final String y) {
        return scala.Predef..MODULE$.$qmark$qmark$qmark();
    }

    public int method$default$1() {
        return 10;
    }

    public String method$default$2() {
        return "two";
    }
}

Scala compiler on call site generates calls to these $default$N methods when parameters are omitted. Understanding this encoding is crucial because our macro will hunt for these hidden $default$N methods. With that foundation, let's build the first version.

Step 1: Simple Version (Map-Based)

Let's move to the code. We will use the quotes.reflect to look under the hood of the method definition at compile time. Our macro does three things:

extracts the symbol of method we're analyzing,
finds all generated $default$N methods,
builds a map connecting parameter names to their default values.

Here's the code with detailed comments:

inline def defaults[T](inline fun: T): Map[String, Any] = ${ defaultsImpl('{ fun }) }

def defaultsImpl[T: Type](expr: Expr[T])(using quotes: Quotes): Expr[Map[String, Any]] =
  import quotes.reflect.*
  
  // Extract the method reference from the inline parameter
  // Lambda(...) = the anonymous function wrapper, Apply(...) = the function call
  val Lambda(_, Apply(method, _)) = expr
    .asTerm                                     // convert Expr[?] to the Reflection Term
    .underlying                                 // get the real method behind the inline wrapper
    .runtimeChecked                             // disable the exhaustiveness check (we assume happy path here)
  
  // Get the method's symbol (compile-time metadata about the method)
  val methodSymbol = method.symbol
  
  
  // Collect all parameter names in order
  val paramNames = methodSymbol.paramSymss // "parameter symbol sequences" (handles grouped parameters)
    .flatten                               // combine all groups into one list
    .map(_.name)                           // extract just the names
    .toVector                              // convert to Vector for indexed access (we need positions later)
  
  // Build the prefix for hidden default methods
  val prefix = methodSymbol.name + "$default$"
  
  // Find all hidden default methods and map them to parameter names
  val defaults = methodSymbol.owner.methodMembers
    .collect:
      case m if m.name.startsWith(prefix) =>            // Only collect methods starting with our prefix (e.g., "greet$default$1")
        val position = m.name.stripPrefix(prefix).toInt // Extract the position number
        paramNames(position - 1) -> Ref(m)              // Ref(m) creates an expression that can call this method at runtime
    
    // Convert each (paramName, methodRef) pair to an expression tuple
    // This prepares them for splicing into the macro result
    .map: (k, v) =>
      Expr.ofTuple((Expr(k), v.asExpr)) //Expr lifts String into Expr[String], asExpr converts Term to Expr[?]

  // Varargs(...) converts List[Expr[T]] to Expr[List[T]]
  '{ ${ Varargs(defaults) }.toMap }

This macro successfully extracts defaults into a Map. Let's see it in action:

Testing the First Version

def greet(name: String = "samsepi0l", number: Int = 43) = s"$greeting $number"

@main
def main(): Unit =
  val d = defaults(greet)
  println(d) // Map("name" -> "samsepi0l", "number" -> "43")

  // Access via string key (but no type safety)
  val name = d("name")
  val number: Int = d("number").asInstanceOf[Int] // type is Any, must cast

Why We Need Better: Type-Safety

Our first solution works, but it has drawbacks: we can get a runtime error when key does not exist and the type of value is always Any.

Step 2: Type-Safe Version with Computed Field Names

To solve these issues, we'll use two powerful Scala 3 features: Selectable and Computed Field Names.

What is Selectable?

Selectable is a trait that enables dynamic access to the refined fields. The selectDynamic method takes a field name and returns the value associated with that name.

class DynamicConfig extends Selectable:
  val x = 10
  val y = "hello"

  def selectDynamic(name: String): Any = name match
    case "x" => x
    case "y" => y
    case _ => throw new NoSuchFieldException(s"No such field: $name")

import scala.reflect.Selectable.reflectiveSelectable

val d: Selectable { val x: Int; val y: String; def selectDynamic(name: String): Any } = new DynamicConfig
val x: Int = d.x    // works
val y: String = d.y // works
val z = d.z         // compile error: no z field

This solution is type-safe because the compiler knows the types of x and y at compile time, but it requires us to import implicit conversion that turns a value into a Selectable such that structural selections are performed on that value.

What are Computed Field Names?

This basic Selectable gives us dynamic access, but lacks type safety. That's where computed field names come in. They let us encode field types at compile-time. The Selectable trait now can have a Fields type member that can be instantiated to a named tuple.

trait Selectable:
  type Fields <: NamedTuple.AnyNamedTuple

If Fields is instantiated in a subclass of Selectable to some named tuple type, then the available fields and their types will be defined by that type. For example, if Fields is defined as (x: Int, y: String), then the Selectable instance will have fields x of type Int and y of type String.

class DynamicConfig extends Selectable:
  type Fields = (x: Int, y: String)
  
  private val data = Map("x" -> 10, "y" -> "hello")
  
  def selectDynamic(name: String): Any = data(name)

val d = new DynamicConfig
val x: Int = d.x      // works
val y: String = d.y   // works
// val z = d.z        // compile error: no z field

With Selectable and Computed Field Names understood, let's enhance our macro to automatically generate the Fields type for any method's defaults.

The Type-Safe Implementation

We're gonna enhance our macro to build a Fields type member that is a named tuple of parameter names and types.

Example: for method(x: Int = 10, y: String = "hi") names should become: ("x", "y"), types should become: (Int, String).

The result should be (x: Int, y: String) (which is a syntax sugar for NamedTuple[("x", "y"), (Int, String)]).

import scala.NamedTuple.{AnyNamedTuple, NamedTuple}
import scala.quoted.*

// 'transparent' is key: type information flows through to the caller
// Without it, type refinements would be hidden inside the return type
transparent inline def defaults[T](inline fun: T): DefaultsExtractor = 
  ${ defaultsImpl('{ fun }) }

def defaultsImpl[T: Type](expr: Expr[T])(using quotes: Quotes): Expr[DefaultsExtractor] =
  import quotes.reflect.*
  
  // Extract method symbol (same as before)
  val Lambda(_, Apply(method, _)) = expr.asTerm.underlying.runtimeChecked
  val methodSymbol = method.symbol
  val prefix = methodSymbol.name + "$default$"
  val paramNames = methodSymbol.paramSymss.flatten.map(_.name).toVector

  // Build runtime map (same as before)
  val defaults = methodSymbol.owner.methodMembers
    .collect:
      case m if m.name.startsWith(prefix) =>
        paramNames(m.name.stripPrefix(prefix).toInt - 1) -> Ref(m)

  // Convert to expression that builds a Map at runtime
  val defaultsExpr =
    val list = Expr.ofSeq:
      defaults.map: (name, term) =>
        Expr.ofTuple((Expr(name), term.asExpr))
        
    '{ $list.toMap }

  val fieldsType = TypeRepr
    .of[NamedTuple]
    .appliedTo:
      defaults
        // Start with empty tuples: () and ()
        .foldLeft((TypeRepr.of[EmptyTuple], TypeRepr.of[EmptyTuple])):
          case ((accNames, accTypes), (paramName, term)) =>
            // For each (paramName, defaultMethod) pair, build up both tuples
            
            // Build the names tuple by cons-ing the parameter name. *: is Scala's tuple cons operator (like :: for lists at type level)
            val newNames = TypeRepr.of[*:].appliedTo(List(
              ConstantType(StringConstant(paramName)), // convert a string to a type
              accNames                                 // previously accumulated names
            ))
            
            //Similarly for types
            val newTypes = TypeRepr.of[*:].appliedTo(List(
              term.tpe,                               // the type of the default value's expression
              accTypes                                // previously accumulated types
            ))
            
            (newNames, newTypes)
        // After the fold, convert the (names, types) pair to a List
        // for passing to .appliedTo
        .toList

  // Pattern match to "escape" the type into the macro's context
  // asType match converts TypeRepr to a compile-time Type
  fieldsType.asType match
      // Pattern introduces a type variable 'fields' capturing what we built (with bounds to AnyNamedTuple)
    case '[ type fields <: AnyNamedTuple; fields ] =>
      '{
        new DefaultsExtractor($defaultsExpr):
          type Fields = fields  // Refine the abstract type to our computed one
      }

// The extractor class that makes everything work
sealed class DefaultsExtractor(defaults: Map[String, Any]) extends Selectable:
  // This type member will be refined by each macro invocation
  // to the exact NamedTuple of defaults for that specific method
  type Fields <: AnyNamedTuple

  // The magic method: enables d.x, d.y syntax
  // When you write d.x, the compiler expands it to:
  // selectDynamic("x").asInstanceOf[T]
  // where T is the type of "x" from the Fields type member
  final def selectDynamic(name: String): Any = defaults(name)

This code works because of a crucial detail: the transparent keyword.

Why transparent inline def?

The transparent keyword means the inline function doesn't create a type boundary. Type refinements (the type Fields = ... part) flow through to the caller's context. Without it, the detailed field information would be hidden inside the DefaultsExtractor's type, and callers couldn't see which fields are available.

Edge Cases & Production Considerations

This implementation handles the happy path. It may crash on varargs, implicits, nested functions or in combination with access modifiers.

Case closed

You can get the code on GitHub. Back to sleep now. Would you like me to write something here again?

References

Scala Type Class Derivation with (almost) no macros

Bartłomiej Kozak — Sun, 01 Feb 2026 00:00:00 GMT

Boilerplate in Type Class Instances

Back in the Scala 2 days, type class derivation was a "dark art". Automating serialization — take AVSystem’s GenCodecs, for instance — required wrestling with the Reflection API or Shapeless. You’d easily end up with 1,200 lines of low-level macro code just to handle the boilerplate of peering into class structures.

With Scala 3, the approach has changed significantly. We can achieve the same (and more) using the native Mirror API and scala.compiletime utilities. Most of the process is now "just Scala code" that runs at compile-time. We still need a tiny bit of macro magic for advanced features like annotation extraction, but we can get 95% of the way there with standard, readable code.

The Foundation: GenCodec

We assume a robust serialization API already exists. Our goal isn't to write the serializer itself, but to automate instance creation for complex types. The GenCodec trait defines how to read and write a type T.

trait GenCodec[T]:
  def read(input: Input): T
  def write(output: Output, value: T): Unit

object GenCodec:
  // Basic primitives are already defined
  given GenCodec[Boolean] = ???
  given GenCodec[Char] = ???
  given GenCodec[Byte] = ???
  // ... other basic types

  given [C[X] <: Seq[X], T: GenCodec] => GenCodec[C[T]] = ???
  // ... other collections

  // Internal "low-level" derivation methods that handle the 
  // actual serialization logic for different class shapes:
  private def deriveSingleton[T <: Singleton](typeName: String, value: T): GenCodec[T] = ???

  private def deriveSum[T](
    typeName: String,
    instances: Array[GenCodec[?]],
    fieldNames: Array[String],
    classes: Array[Class[?]],
  ): GenCodec[T] = ???

  private def deriveProduct[T <: Product](
    typeName: String,
    instances: Array[GenCodec[?]],
    fieldNames: Array[String],
  ): GenCodec[T] = ???

The Power of Mirrors

Scala 3 introduces Mirror, a type class synthesized by the compiler that provides a compile-time representation of a class's structure. It lets us decompose types into their components without runtime reflection.

Mirror.ProductOf[T]: For case classes (product types).
Mirror.SumOf[T]: For enums and sealed traits (sum types).

Our first attempt at a derived method uses these mirrors to extract type information:

inline private def derived[T]: GenCodec[T] = compiletime.summonFrom:
  case m: Mirror.Of[T] =>
    val typeName = compiletime.constValue[m.MirroredLabel]
    val instances =
      compiletime.constValueTuple[Tuple.Map[m.MirroredElemTypes, GenCodec]].toArray.map(_.asInstanceOf[GenCodec[?]])
    val fieldNames = compiletime.constValueTuple[m.MirroredElemLabels].toArray.map(_.asInstanceOf[String])

    m match
      case m: Mirror.ProductOf[T] =>
        deriveProduct(typeName, instances, fieldNames)
      case m: Mirror.SumOf[T] =>
        val classes = compiletime
          .summonAll[Tuple.Map[m.MirroredElemTypes, ClassTag]]
          .toArray
          .map(_.asInstanceOf[ClassTag[?]].runtimeClass)

        deriveSum(typeName, instances, fieldNames, classes)
  case _ => compiletime.error("Cannot derive GenCodec")

compiletime.summonFrom is a compile-time conditional that pattern matches on available givens (implicits) in the current scope. It tries each case in order and uses the first one that successfully resolves. This is the heart of flexible derivation.

compiletime.constValue extracts a literal value (like a String "MR. ROBOT") from the type level to the value level. At compile-time, m.MirroredLabel is a singleton type containing the class name: constValue materializes it as a runtime String.

compiletime.constValueTuple converts a tuple of types into a tuple of values. For example, field labels in a Mirror exist as a tuple of singleton string types like ("id", "name").

Tuple.Map is a type-level operation that transforms each element of a tuple. If you have a tuple of types (Int, String) and apply Tuple.Map[..., GenCodec], the compiler computes the type (GenCodec[Int], GenCodec[String]).

Note that we use .toArray.map(_.asInstanceOf[GenCodec[?]]) instead of a direct cast to .asInstanceOf[Array[GenCodec[?]]]. In the JVM, arrays are reified, so we cannot cast Array[Any] directly to Array[GenCodec[?]]. Instead, we convert to an array of Any and then map each element to the desired type.

Recursive Derivation

The simple version works when all fields and subclasses already have GenCodec instances, but we want to derive GenCodecs for subclasses recursively.

inline private def summonInstances[Elems <: Tuple](
  summonAllowed: Boolean,
  deriveAllowed: Boolean,
): Tuple =
  inline compiletime.erasedValue[Elems] match
    case _: (elem *: elems) =>
      val elemCodec = compiletime.summonFrom:
        case codec: GenCodec[`elem`] if summonAllowed => codec
        case _ if deriveAllowed => derived[elem]

      elemCodec *: summonInstances[elems](summonAllowed, deriveAllowed)
    case _: EmptyTuple => EmptyTuple

compiletime.erasedValue lets us pattern match on a type without having a runtime value of that type. It's a no-op at runtime that tells the compiler: "I want to inspect the structure of this type as if I had a value of it."

inline match is a powerful Scala 3 feature that ensures the pattern matching is fully expanded at compile-time. Unlike a regular match, inline match is resolved by the compiler; the cases that don't match are literally discarded from the generated bytecode, leaving only the branch that corresponds to the actual type.

Now we update derived to use recursive summoning:

inline private def derived[T]: GenCodec[T] = compiletime.summonFrom:
    case m: Mirror.Of[T] =>
      val typeName = compiletime.constValue[m.MirroredLabel]
      val fieldNames = compiletime.constValueTuple[m.MirroredElemLabels].toArray.map(_.asInstanceOf[String])

      m match
        case m: Mirror.ProductOf[T] => 
          val instances = summonInstances[m.MirroredElemTypes](summonAllowed = true, deriveAllowed = false).toArray.map(_.asInstanceOf[GenCodec[?]])
          deriveProduct(typeName, instances, fieldNames)
        case m: Mirror.SumOf[T] =>
          val instances = summonInstances[m.MirroredElemTypes](summonAllowed = true, deriveAllowed = true).toArray.map(_.asInstanceOf[GenCodec[?]])
          val classes = compiletime
            .summonAll[Tuple.Map[m.MirroredElemTypes, ClassTag]]
            .toArray
            .map(_.asInstanceOf[ClassTag[?]].runtimeClass)

          deriveSum(typeName, instances, fieldNames, classes)
    case _ => compiletime.error("Cannot derive GenCodec")

For product types, we only summon existing instances (no deriving); for sum types, we allow deriving subclasses recursively.

Handling Cycles

Recursive data structures (like a Node pointing to another Node) cause infinite recursion at compile-time because the compiler tries to generate a GenCodec[Node] while it's still in the middle of generating a GenCodec[Node].

To break this cycle, we introduce a Deferred wrapper. We place it in the implicit scope before we start the derivation process:

final class Deferred[T] extends GenCodec[T]:
  var underlying: GenCodec[T] = null.asInstanceOf[GenCodec[T]]

  def read(input: Input): T = underlying.read(input)
  def write(output: Output, value: T): Unit = underlying.write(output, value)

inline def derived[T]: GenCodec[T] =
  given deferred: Deferred[T] = new Deferred[T]

  val underlying = unsafeDerived[T] // our renamed old 'derived'
  deferred.underlying = underlying
  underlying

The given deferred: Deferred[T] makes the instance available during the derivation of T itself. When the compiler encounters a field of type T (the recursive step), it will find this given instead of trying to call derived[T] again. Later, we fill in the underlying field with the fully constructed codec. This works because we use a var - the instance is "lazily" completed after the skeleton is created.

The "Almost" Part

Sometimes we need to derive codecs for singleton types (like object instances). For individual values, we can use the ValueOf type class. The ValueOf[T] gives us the runtime value of a singleton type. But how do we get its name? For that, we need our first "real" macro.

Type Names via Opaque Types

When Mirror isn't available (e.g., for primitives or singletons), we still need the type's name for serialization.

We use an opaque type to carry the type name without runtime overhead:

opaque type TypeName[T] <: String = String

object TypeName:
  inline given [T] => TypeName[T] = ${ deriveImpl[T] }

  private def deriveImpl[T: Type](using quotes: Quotes): Expr[TypeName[T]] =
    import quotes.reflect.*
    Expr(TypeRepr.of[T].show)

This macro extracts the fully-qualified type name at compile-time and encodes it as a string literal. The opaque type ensures it's treated distinctly from String for type safety, but at runtime it's just a string.

Finally, we integrate this into our unsafeDerived method:

inline private def unsafeDerived[T]: GenCodec[T] = compiletime.summonFrom:
    case m: Mirror.Of[T] => // as before
    case v: ValueOf[T] =>
      deriveSingleton(compiletime.summonInline[TypeName[T]], v.value)
    case _ => compiletime.error("Cannot derive GenCodec")

Handling Annotations

Scala 2 scala-commons supported custom names via an @name annotation. We use Scala 3's RefiningAnnotation which are more "sticky" than normal ones. They are conceptually kept around when normal refinements would also not be stripped away. A small macro helps us check for the presence of an annotation at compile-time:

class name(val value: String) extends RefiningAnnotation

@implicitNotFound("${T} is not annotated with ${A}")
opaque type HasAnnotation[T, A <: RefiningAnnotation] = A

object HasAnnotation:
  extension [T, A <: RefiningAnnotation](has: HasAnnotation[T, A]) def value: A = has

  inline given [T, A <: RefiningAnnotation] => HasAnnotation[T, A] = ${ materializeImpl[T, A] }

  private def materializeImpl[T: Type, A <: RefiningAnnotation: Type](using quotes: Quotes): Expr[HasAnnotation[T, A]] =
    import quotes.reflect.*
    TypeRepr.of[T].typeSymbol.getAnnotation(TypeRepr.of[A].typeSymbol) match
      case Some(annot) => annot.asExprOf[A]
      case _ => report.errorAndAbort(s"${Type.show[T]} is not annotated with ${Type.show[A]}")

If a type has the annotation, HasAnnotation[T, A] gives us the annotation object itself. If not, the macro aborts at compile-time with a clear error.

By combining HasAnnotation with summonFrom, we can check for annotations and fall back to defaults:

class name(val value: String) extends scala.annotation.RefiningAnnotation

inline private def constName[T](inline fallback: String) = compiletime.summonFrom:
  case h: HasAnnotation[T, `name`] => h.value
  case _ => fallback

The backticks around name are crucial - they tell the compiler to treat name as a type name, not a type binding. Without them, the compiler would think name is a variable in scope, leading to errors.

For field names, we need to check each field's type separately:

inline private def constNames[Tup <: Tuple]: Tuple = inline compiletime.erasedValue[Tup] match
    case _: ((label, tpe) *: tail) =>
      val head = constName[tpe](compiletime.constValue[label].asInstanceOf[String])
      head *: constNames[tail]
    case _: EmptyTuple => EmptyTuple

We zip labels with types, then for each field, check if its type has a @name annotation. If yes, use that; otherwise use the label.

Now integrate this into unsafeDerived:

inline private def unsafeDerived[T]: GenCodec[T] = compiletime.summonFrom:
  case m: Mirror.Of[T] =>
    val typeName = constName[T](compiletime.constValue[m.MirroredLabel])
    val fieldNames = constNames[Tuple.Zip[m.MirroredElemLabels, m.MirroredElemTypes]].toArray.map(_.asInstanceOf[String])

    // ... as before, using typeName and fieldNames
  case v: ValueOf[T] =>
    val typeName = constName[T](compiletime.summonInline[TypeName[T]])
    deriveSingleton(typeName, v.value)
  case _ => compiletime.error("Cannot derive GenCodec")

Summary

We've moved from 1,200 lines of complex reflection to a few dozen lines of type-safe, compile-time Scala 3 code. While we still use macros for annotation processing, the "heavy lifting" is now handled by the compiler's native understanding of types.

I'm defending my bachelor's thesis the day after tomorrow. I hope I won't stop blogging after that. If you enjoyed this post, consider following me on LinkedIn for updates on future content!

scala-cli E2E Repo Setup

Bartłomiej Kozak — Mon, 02 Mar 2026 00:00:00 GMT

Why scala-cli?

Every time I start a new Scala project, I find myself googling the same setup steps — formatting, testing, coverage, publishing, documentation. The traditional tools don't help: sbt has a steep learning curve, Mill is fast but struggles with IntelliJ support. scala-cli bridges this gap — as simple as a script but as capable as a build tool, with first-class IDE support that actually works.

This post is the reference I wish I had: a complete copy-paste workflow for a small library, using only scala-cli. Maybe it'll save you the same googling.

The Basics

A minimal scala-cli library project may look like this:

my-library/
├── project.scala
├── .scalafmt.conf
├── src/
│   └── MyLib.scala
├── test/
│   └── MyLibTest.scala
└── .scoverage/
    └── report.sc

Your configuration lives inside your source files using "directives". However, as your project grows, you can consolidate these into a single file named project.scala. Directives cover the Scala version, dependencies (both main and test-only), and compiler options — all in one place:

//> using scala 3.8.2
//> using test.dep org.scalameta::munit::1.2.3

//> using options -deprecation -feature -new-syntax -unchecked
//> using options -language:noAutoTupling
//> using options -Yexplicit-nulls
//> using options -Wsafe-init -Werror -Wunused:all

scala-cli will automatically download the Scala compiler and dependencies, compile all files in the directory, and execute the entry point.

IDE Support

If you're using VS Code (with Metals) or IntelliJ, scala-cli works out of the box. If you ever feel the IDE is out of sync, run:

scala-cli --power setup-ide .

Formatting with Scalafmt

Consistent code style is non-negotiable. scala-cli has built-in support for scalafmt.

To format your code:

scala-cli fmt .

If you want to customize the style, create a .scalafmt.conf file in your root directory. scala-cli will pick it up automatically. You can also enforce formatting in CI:

scala-cli fmt . --check

Testing

Testing doesn't require a separate build module. Just create a *.test.scala file or put your tests in a tests/ directory.

For example, create MyTests.test.scala:

class MyTests extends munit.FunSuite {
  test("math works") {
    assertEquals(1 + 1, 2)
  }
}

Run all tests in the current directory:

scala-cli test .

scala-cli is smart enough to include test-only dependencies only when running the test command.

Code Coverage

scala-cli doesn't have a native coverage command. My approach here uses the Scala 3 compiler's built-in coverage instrumentation directly, with a custom report script that gives you full control. This is exactly how it's done in the made project.

How Scala 3 coverage instrumentation works

The Scala 3 compiler has a built-in coverage phase. When you pass -coverage-out:<dir>, the compiler does two things during compilation:

Writes scoverage.coverage — a serialized file describing every instrumentable statement in your source code: its location, source file, line number, and a unique ID. This is the coverage map.
Injects measurement calls into the compiled bytecode. Every instrumented statement gets a Invoker.invoked(id, dataDir) call that writes a tiny file (scoverage.measurements.{id}) to <dir> at runtime. Each file's existence proves that statement was executed.

After scala-cli test . finishes, the output directory contains the coverage map and a measurement file for every statement that was hit during the test run. The report step is just: deserialize the map, scan which measurement files exist, compute the ratio.

Report Generation

Add coverage directives to project.scala:
```
//> using options -coverage-out:./.scoverage
```
-coverage-out:./.scoverage tells the compiler where to write both the coverage map and the runtime measurement files. Everything lands in .scoverage/.
Run tests:
```
scala-cli test .
```
After this, .scoverage/ contains scoverage.coverage (the map) and scoverage.measurements.* files (one per executed statement).

Generate the report:

I depend on the scoverage library directly and have written a simple Scala script:

//> using scala 3.8.2
//> using dep org.scoverage::scalac-scoverage-reporter:2.5.2
//> using dep org.scoverage::scalac-scoverage-domain:2.5.2
//> using dep org.scoverage::scalac-scoverage-serializer:2.5.2

import scoverage.reporter.{ScoverageHtmlWriter, CoberturaXmlWriter, IOUtils}
import scoverage.serialize.Serializer
import java.io.File

val coverageFile = new File(".scoverage/scoverage.coverage")
val sourceDir = new File(".")
val measurementDir = new File(".scoverage")
val outDir = new File(".scoverage/report")

if !coverageFile.exists() then
  println(s"Error: Coverage file not found at ${coverageFile.getAbsolutePath}")
  sys.exit(1)

val coverage = Serializer.deserialize(coverageFile, sourceDir)
val measurementFiles = IOUtils.findMeasurementFiles(measurementDir)
coverage.apply(IOUtils.invoked(measurementFiles.toIndexedSeq))

outDir.mkdirs()

ScoverageHtmlWriter(Seq(sourceDir), outDir, None).write(coverage)
CoberturaXmlWriter(Seq(sourceDir), outDir, None).write(coverage)

println(s"Statement coverage: ${coverage.statementCoverageFormatted}%")

Run it with scala-cli .scoverage/report.sc.

This is the "deserialize, scan, compute" step from above — Serializer.deserialize loads the coverage map, IOUtils.findMeasurementFiles collects which statements were hit, and the two writers produce the output:

ScoverageHtmlWriter — browsable HTML where you can click into each source file and see covered (green) vs uncovered (red) lines.
CoberturaXmlWriter — cobertura.xml, the standard format that CI tools understand.

CI integration

In GitHub Actions, the coverage step chains naturally after scala-cli test:

- run: scala-cli --power test .
- run: scala-cli .scoverage/report.sc
- name: Code Coverage Report
  uses: 5monkeys/cobertura-action@master
  continue-on-error: true
  with:
    path: .scoverage/report/cobertura.xml
    minimum_coverage: 80

scala-cli test . runs with instrumentation (because -coverage-out is in project.scala), the report script generates cobertura.xml, and cobertura-action posts the coverage summary directly on the PR — no external service or token needed.

Publishing to Maven Central

Yes, you can publish libraries to Maven Central (or any repo) using scala-cli. This requires the --power flags.

First, add publishing metadata to your project.scala:

//> using publish.organization com.example
//> using publish.name my-library
//> using publish.computeVersion git:tag
//> using publish.description "My awesome Scala library"
//> using publish.url https://github.com/yourname/my-library
//> using publish.license Apache-2.0
//> using publish.vcs github:yourname/my-library
//> using publish.repository central
//> using publish.developer "yourname|Your Name|https://github.com/yourname"

computeVersion git:tag derives the version from the latest git tag — push v0.1.0 and the published artifact is 0.1.0. No version string to update manually.

PGP Key Setup

Maven Central requires all artifacts to be PGP-signed. scala-cli can generate a key pair for you:

scala-cli --power config --create-pgp-key --email your@email.com

This creates a PGP key and stores it in your local scala-cli config. For CI, you need to export the private key and passphrase as repository secrets. If you prefer using GPG directly:

gpg --gen-key
gpg --armor --export-secret-keys YOUR_KEY_ID  # → store as PGP_PRIVATE_KEY secret
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID

You'll need four secrets in your CI environment: SONATYPE_USERNAME, SONATYPE_PASSWORD, PGP_PRIVATE_KEY, and PGP_PASSPHRASE. The Sonatype credentials come from creating an account on Central Portal — after verifying your namespace (e.g. io.github.yourname via GitHub), generate a user token.

Running the publish command

# To a local repository (for testing)
scala-cli --power publish local .

# To Sonatype/Maven Central
scala-cli --power publish . --verbose \
  --user "env:SONATYPE_USERNAME" \
  --password "env:SONATYPE_PASSWORD" \
  --secret-key "env:PGP_PRIVATE_KEY" \
  --secret-key-password "env:PGP_PASSPHRASE"

The "env:..." syntax tells scala-cli to read from environment variables rather than passing secrets as arguments.

GitHub Actions Integration

scala-cli is perfect for CI because it's lightweight. Here's the full CI workflow from made — two parallel jobs for formatting and tests (including the coverage pipeline from Section 4):

name: Run CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint:
    name: Scalafmt
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: coursier/cache-action@v8.0
      - uses: VirtusLab/scala-cli-setup@v1
      - run: scala-cli --power fmt --check .

  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: coursier/cache-action@v8.0
      - uses: VirtusLab/scala-cli-setup@v1
      - run: scala-cli --power test .
      - run: scala-cli .scoverage/report.sc
      - name: Code Coverage Report
        uses: 5monkeys/cobertura-action@master
        continue-on-error: true
        with:
          path: .scoverage/report/cobertura.xml
          minimum_coverage: 80
      - run: scala-cli --power doc .

fetch-depth: 0 is needed because publish.computeVersion git:tag requires the full git history to derive the version. coursier/cache-action caches downloaded JVMs and dependencies between runs. The doc step at the end validates that Scaladoc generates without errors — a cheap smoke test for documentation quality.

The publish workflow triggers on version tags:

name: Publish
on:
  push:
    tags: [ 'v*' ]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: coursier/cache-action@v8.0
      - uses: VirtusLab/scala-cli-setup@v1
      - run: |
          scala-cli --power publish . --verbose \
            --user "env:SONATYPE_USERNAME" \
            --password "env:SONATYPE_PASSWORD" \
            --secret-key "env:PGP_PRIVATE_KEY" \
            --secret-key-password "env:PGP_PASSPHRASE"
        env:
          SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
          SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
          PGP_PRIVATE_KEY: ${{ secrets.PGP_PRIVATE_KEY }}
          PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }}

Push a tag, artifact lands on Maven Central. That's it.

Documentation Generation

scala-cli can generate Scaladoc with a single command:

scala-cli --power doc .

This produces a scala-doc/ directory with browsable HTML documentation. For a library, you'll want to pass additional flags to the Scaladoc tool after --:

scala-cli --power doc . -- \
  -project "My Library" \
  -project-version v0.1.0 \
  -snippet-compiler:compile \
  -source-links:"src=github://yourname/my-library?tag=v0.1.0"

-snippet-compiler:compile compiles code snippets in @example blocks during generation — broken examples fail the build, not the reader. -source-links adds clickable "Source" links from the docs back to your GitHub repository at the right tag.

In CI, running scala-cli --power doc . without extra flags is a cheap smoke test — if any Scaladoc comment has a syntax error or a broken @example snippet, the build fails.

One caveat: if your project uses Scala 3 macros, scala-cli doc . may fail because the Scaladoc compiler tries to expand them in a context where they can't run. There's no clean workaround yet — for now, you may need to exclude macro-heavy files from documentation generation.

Deploying to GitHub Pages

In case you would like to deploy Scaladoc to GitHub Pages on every version tag, here's the workflow.

name: Deploy documentation to Pages

on:
  push:
    tags: [ 'v*' ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: coursier/cache-action@v8.0
      - uses: VirtusLab/scala-cli-setup@v1
      - name: Generate documentation
        run: |
          scala-cli --power doc . -- \
          -project "M&DE" \
          -project-version ${{ github.ref_name }} \
          -project-footer "made with ❤️ and coffee" \
          -social-links:github::https://github.com/halotukozak/made \
          -snippet-compiler:compile \
          -source-links:"src=github://halotukozak/made?tag=${{ github.ref_name }}" \
          -revision:${{ github.ref_name }}
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v4
        with:
          path: 'scala-doc'
      - uses: actions/deploy-pages@v4

${{ github.ref_name }} injects the git tag (e.g. v0.1.0) into the project version and source links, so every tagged release gets documentation with correct versioned links back to the source. -social-links:github:: adds a GitHub icon linking to the repository. -revision anchors source links to the exact commit.

Push a tag — docs land on GitHub Pages automatically, right alongside the Maven Central publish.

Extra: Testing Across JVM Versions

One of the most powerful features of scala-cli is its ability to manage JVM installations automatically. Testing your code against multiple Java versions is a one-liner:

# Run tests on Java 11
scala-cli test . --jvm 11

You don't need sdkman or manually managed $JAVA_HOME. scala-cli uses coursier to download the requested JVM under the hood, ensuring your tests are reproducible across different environments. You can also pin the version in your project.scala:

//> using jvm 21

Wrapping Up

scala-cli is no longer just a "scripting tool". It's a robust, fast, and modern way to build Scala applications. Whether you're writing a simple automation script or a published library, scala-cli provides a seamless E2E experience without the overhead of traditional build tools.

References

Official scala-cli Documentation
M&DE Repository — the project used as the example throughout this post
Scala 3 Compiler Options
VirtusLab's GitHub Actions Setup
Scoverage
Scala 3 Scaladoc

Homogeneous Tuples in Scala 3

Bartłomiej Kozak — Mon, 06 Apr 2026 00:00:00 GMT

The Problem: Tuples That Lie

Scala 3 tuples are heterogeneous by design. (1, "hello", true) is a (Int, String, Boolean) — each element has its own type. But sometimes you know all elements share a single type. Maybe you're collecting database column IDs, or accumulating configuration values, or — as in my case — building typed pipelines where a tuple of transformations all operate on the same domain.

"Why not just use a List[Int]?" — because tuples carry their arity and per-element types at compile time. In a larger structure you might have (Column[Int], Column[Int], Column[String]) where only some positions share a type. You want to operate on the homogeneous prefix without losing track of what's where. And you don't want runtime checks — the whole point is to catch mismatches before the code runs.

The compiler doesn't help you here. A (Int, Int, Int) is still three separate types glued together, and Scala offers no built-in way to say "this tuple contains only Ints."

Let's see what happens when you try.

What Doesn't Work

Tuple.map

Tuples in Scala 3 have a map method. But it takes a polymorphic function [t] => t => F[t] — inside that lambda, t is abstract. You don't know it's Int, so you can't call Int-specific operations:

val tup = (1, 2, 3)

// Won't compile — t is not known to be Int:
//tup.map([t] => (x: t) => x + 1)

// You'd have to cast, losing all safety:
tup.map[[X] =>> Int]([t] => (x: t) => x.asInstanceOf[Int] + 1)
// Returns (2, 3, 4), but nothing stops you from calling this on ("a", "b", "c")

We have to explicitly pass [[X] =>> Int] as the result type because the compiler can't infer what F should be when the return type doesn't match t. And of course, the compiler won't stop you from writing the same code for ("a", "b", "c") — you'd get a ClassCastException instead of a compile error.

Converting to Array or List

OK, so map doesn't work without casts. What about converting the whole tuple to an Array or List first?

val tup: Tuple = (1, 2, 3)

// Array: JVM arrays are reified — Array[Object] cannot be cast to Array[Int]
tup.toArray.asInstanceOf[Array[Int]] // ClassCastException!

// You can map element-by-element, but that's a runtime cast with zero compile-time safety:
tup.toArray.map(_.asInstanceOf[Int]).sum // works, but (1, "oops", 3) blows up at runtime

// List: erasure means the cast silently succeeds...
tup.toList.asInstanceOf[List[Int]].sum // returns 6
// ...but on a mixed tuple the bug just hides until you actually use the values:
val mixed: Tuple = (1, "oops", 3)
mixed.toList.asInstanceOf[List[Int]].sum // ClassCastException — far from the real mistake

Every approach so far either crashes at runtime or silently hides the bug. We need a way to prove, at compile time, that a tuple contains only elements of a given type.

The containsOnly Proof

A Match Type

Scala 3's match types let us compute types based on pattern matching at the type level. Here's the idea: walk the tuple recursively and check that every element matches the target type.

type ContainsOnly[Tup <: Tuple, T] <: Boolean = Tup match
  case EmptyTuple => true
  case T *: tail => ContainsOnly[tail, T]
  case _ => false

This reads naturally: an empty tuple trivially contains only T, a tuple whose head is T recurses on the tail, anything else is false.

Let's test it with summon, which materializes a given at compile time or fails:

// These compile:
summon[ContainsOnly[(Int, Int, Int), Int] =:= true]
summon[ContainsOnly[EmptyTuple, String] =:= true]

// This doesn't compile:
// summon[ContainsOnly[(Int, String, Int), Int] =:= true]
// Error: Cannot prove that false =:= true

It works! You could even use the match type directly as a constraint with =:=:

def processInts[Tup <: Tuple](tup: Tup)(using ContainsOnly[Tup, Int] =:= true): String =
  "all ints!"

processInts((1, 2, 3)) // compiles!
// processInts((1, "x", 3)) // doesn't compile — Cannot prove that false =:= true

This works, but has two problems. The error message is cryptic — "Cannot prove that false =:= true" says nothing about which type broke it. And =:= has no public constructor, so you can't create an instance yourself — meaning there's no escape hatch for cases where you know the constraint holds but the compiler can't prove it (e.g. after a runtime check). A dedicated type class solves both.

The Type Class

The standard approach: wrap the match type in a type class whose given instance can only be synthesized when the match type reduces to true.

A first attempt with a regular class:

@implicitNotFound("${Tup} does not contain only ${T}")
class containsOnly[Tup <: Tuple, T]

object containsOnly:

  type Loop[Tup <: Tuple, T] <: Boolean = Tup match
    case EmptyTuple => true
    case T *: tail => Loop[tail, T]
    case _ => false

  inline given [Tup <: Tuple, T] => (Loop[Tup, T] =:= true) => containsOnly[Tup, T] = containsOnly()

Here we use the new given syntax introduced in Scala 3.6. Instead of given [Tup, T](using ...): Result, we write given [Tup, T] => (...) => Result — each => introduces a new clause. The type parameters come first, then the context parameter (Loop[Tup, T] =:= true — our proof that the match type reduced to true), and finally the result type. It reads left-to-right: "for any Tup and T, given that Loop[Tup, T] equals true, produce a containsOnly[Tup, T]."

One subtlety: we'd like Loop to be private, but it can't be — the compiler needs to see it at the call site to reduce Loop[Tup, T] and resolve the =:= evidence.

This works — containsOnly instances are only synthesized when Loop reduces to true. But every summon allocates a new containsOnly() object at runtime, even though the instance carries no data. It's a pure compile-time proof that wastes heap space.

We could create a single reusable instance to avoid repeated allocations, but we can do even better — eliminate the object entirely with an opaque type:

@implicitNotFound("${Tup} does not contain only ${T}")
opaque infix type containsOnly[Tup <: Tuple, T] = Boolean

object containsOnly:

  type Loop[Tup <: Tuple, T] <: Boolean = Tup match
    case EmptyTuple => true
    case T *: tail => Loop[tail, T]
    case _ => false

  inline given [Tup <: Tuple, T] => (Loop[Tup, T] =:= true) => containsOnly[Tup, T] = true

Now containsOnly[Tup, T] is just a Boolean at runtime — literally the value true. No object, no allocation, no overhead. The =:= evidence ensures the compiler only synthesizes this given when Loop reduces to true. If you try to summon containsOnly[(Int, String), Int], the evidence can't be constructed and compilation fails.

The infix modifier lets us write Tup containsOnly T instead of containsOnly[Tup, T] — a small readability win.

Let's test that the type class works as a constraint:

def processInts[Tup <: Tuple](tup: Tup)(using Tup containsOnly Int): Int =
  tup.toList.asInstanceOf[List[Int]].sum // safe now — the proof guarantees all elements are Int

processInts((1, 2, 3)) // compiles: 6
processInts(EmptyTuple) // compiles: 0
// processInts((1, "nope", 3))  // doesn't compile!
// error: (Int, String, Int) does not contain only Int

The @implicitNotFound annotation gives us a human-readable error instead of the generic "No given instance" message.

Now we have a reusable, zero-cost proof that a tuple is homogeneous. Time to do something useful with it.

Putting containsOnly to Work

mapAs

Now let's put containsOnly to work. I want a mapAs extension on Tuple that requires a containsOnly proof, applies a polymorphic function to each element, and preserves the full type information in the result.

We use extension (tup: Tuple) and refer to tup.type in the return type. Why not extension [Tup <: Tuple](tup: Tup)? Because Tuple.Map[Tup, F] is a match type — the compiler needs to see a concrete tuple to reduce it. An abstract type parameter Tup leaves the match stuck. tup.type, however, is the singleton type of the actual value, so at the call site the compiler knows the exact shape and Tuple.Map reduces correctly.

Note the asInstanceOf[t & T] inside the implementation — this cast is safe because the containsOnly proof guarantees every element is already a T. The cast just narrows the abstract t to t & T so the bounded polymorphic function f accepts it. Without the proof, this would be exactly the kind of unsafe cast we're trying to eliminate.

A first attempt — one method with all type parameters:

extension (tup: Tuple)
  inline def mapAs[T, F[_ <: T]](inline f: [t <: T] => t => F[t])(using tup.type containsOnly T): Tuple.Map[tup.type, [X] =>> F[X & T]] =
    tup.map[[X] =>> F[X & T]]([t] => (t: t) => f(t.asInstanceOf[t & T]))

This compiles, but using it is painful — Scala can't partially infer type parameters, so you must specify both T and F explicitly:

// You'd have to write:
(1, 2, 3).mapAs[Int, Option]([t <: Int] => (x: t) => Some(x))

// But you can't write this (F can't be inferred from T alone):
// (1, 2, 3).mapAs[Int]([t <: Int] => (x: t) => Some(x))

We want to fix T first (via mapAs[Int]) and let the compiler infer F from the function we pass.

Currying Type Parameters with a Wrapper

The classic trick: return an intermediate object that captures the first type parameter, then let the caller supply the second.

extension (tup: Tuple)
  inline def mapAs[T](using tup.type containsOnly T): MapAs[T, tup.type] = MapAs(tup)

class MapAs[T, Tup <: Tuple](private val underlying: Tup):
  inline def apply[F[_ <: T]](inline f: [t <: T] => t => F[t]): Tuple.Map[Tup, [X] =>> F[X & T]] =
    underlying.map[[X] =>> F[X & T]]([t] => (t: t) => f(t.asInstanceOf[t & T]))

Let me unpack what's going on:

mapAs[T] fixes the element type and returns a MapAs wrapper, but only if the containsOnly proof exists.
MapAs.apply[F] takes the higher-kinded type F and a polymorphic function f.
Tuple.Map[Tup, ...] computes the result type: if Tup = (Int, Int, Int) and F = Option, the result is (Option[Int], Option[Int], Option[Int]).
The X & T intersection ensures the compiler knows each element is a subtype of T.

Testing:

val ints = (1, 2, 3)
val opts: (Option[Int], Option[Int], Option[Int]) = ints.mapAs[Int]([t <: Int] => (x: t) => Some(x))
// opts = (Some(1), Some(2), Some(3))

val strs = ("a", "b")
val lengths: (List[String], List[String]) = strs.mapAs[String]([t <: String] => (x: t) => List(x))
// lengths = (List(a), List(b))

// This won't compile:
// (1, "mixed", 3).mapAs[Int]([t <: Int] => (x: t) => Some(x))

It works, but there's a problem. MapAs is a class — every call allocates a wrapper object on the heap. For a type-level operation that exists purely to curry type parameters, that's wasteful.

Eliminating the Wrapper Allocation

We could try extending AnyVal, but the optimization isn't guaranteed. The JVM still allocates when the value class is used as a generic type parameter, assigned to a supertype, or passed to a method expecting Any. The proper Scala 3 approach is an opaque type — a compile-time-only abstraction erased to its underlying type with guaranteed zero overhead:

opaque type MapAs[T, Tup <: Tuple] = Tup

object MapAs:
  extension [T, Tup <: Tuple](mapAs: MapAs[T, Tup])
    inline def apply[F[_ <: T]](inline f: [t <: T] => t => F[t]): Tuple.Map[Tup, [X] =>> F[X & T]] =
      (mapAs: Tup).map[[X] =>> F[X & T]]([t] => (t: t) => f(t.asInstanceOf[t & T]))

extension (tup: Tuple)
  inline def mapAs[T](using tup.type containsOnly T): MapAs[T, tup.type] = tup

Inside the MapAs companion, we know that MapAs[T, Tup] is Tup. Outside, the type system enforces the abstraction boundary. No allocation, no erasure surprises, no caveats. The API is identical:

val result: (Option[Int], Option[Int], Option[Int]) = (1, 2, 3).mapAs[Int]([t <: Int] => (x: t) => Some(x))
// result = (Some(1), Some(2), Some(3))

Can We Skip the Wrapper Entirely?

After all that work on the wrapper, let's check if Scala 3 actually needs it. Since SIP-47 (clause interleaving, stable since Scala 3.4), you can mix type and value parameter clauses freely:

extension (tup: Tuple)
  inline def mapAs[T](using tup.type containsOnly T)[F[_ <: T]](inline f: [t <: T] => t => F[t]): Tuple.Map[tup.type, [X] =>> F[X & T]] =
    tup.map[[X] =>> F[X & T]]([t] => (t: t) => f(t.asInstanceOf[t & T]))

That's it. One method. The using clause sits between the two type parameter lists, so T is fixed first, the containsOnly proof is resolved, and then F is provided — all in a single call.

val result = (1, 2, 3).mapAs[Int]([t <: Int] => (x: t) => Some(x))
// result = (Some(1), Some(2), Some(3))

// Compile error:
// (1, "nope").mapAs[Int]([t <: Int] => (x: t) => Some(x))
// error: (Int, String) does not contain only Int

No wrapper, no opaque type, no AnyVal. Clause interleaving makes the entire intermediate-object pattern unnecessary.

Let's peek at what the compiler actually generates (decompiled from bytecode):

Tuple3 tup$proxy1 = .MODULE$.apply(BoxesRunTime.boxToInteger(1), BoxesRunTime.boxToInteger(2), BoxesRunTime.boxToInteger(3));
containsOnly$package$ var4 = containsOnly.package..MODULE$;
scala..eq.colon.eq x$1$proxy1 = scala..less.colon.less..MODULE$.refl();
boolean x$2$proxy1 = true;
Function1 f$proxy2 = (t) -> {
    int var1 = BoxesRunTime.unboxToInt(t);
    return scala.Some..MODULE$.apply(BoxesRunTime.boxToInteger(var1));
};
scala.runtime.Tuples..MODULE$.map(tup$proxy1, f$proxy2);

All the type-level machinery has been erased. The =:= evidence becomes a call to refl() (a no-op singleton), the containsOnly proof is just true, and mapAs inlines down to a single Tuples.map call with a plain Java lambda. No wrappers, no intermediate objects — just a tuple, a function, and a runtime map.

Beyond Type Constructors

Plain Return Types

So far every example used a type constructor like Option or List as the result — F was always something the compiler could figure out from the function's return type. But what if your function returns a plain type?

val tup = (1, 2, 3)
tup.mapAs[Int]([x <: Int] => x => x.toString)

This fails:

Found:    String
Required: (F?[_$1 <: Int])[x]

The problem is that mapAs expects F[_ <: T] — a type constructor that wraps T. Option[Int] fits because Option is [X] =>> Option[X]. But String isn't F[Int] for any F — it has no relationship to the input type, so the compiler can't infer what F should be.

The fix is to tell the compiler explicitly what F is — a constant function that ignores its argument and returns String:

tup.mapAs[Int][[X <: Int] =>> String]([x <: Int] => (x: x) => x.toString)

Or equivalently, with a named type alias:

type KString[_] = String
tup.mapAs[Int][KString]([x <: Int] => (x: x) => x.toString)

This pattern comes up more often than you'd expect — any time the result type doesn't depend on the element type, you'll need to spell out F.

Limitation: Abstract Type Members

The same explicit-F technique suggests another interesting use case. Suppose your elements share a common trait with an abstract type member:

trait C:
  type T
  def t: T

val tup = (new C { type T = String; val t = "" }, new C { type T = Int; val t = 1 })

Each element is a C, but its T is different. Unfortunatelly, we cannot extract T with a match type that peels open the refinement:

type C_Of[t] = C { type T = t }
type Extract_T[X <: C] = X match
  case C_Of[t] => t

tup.mapAs[C][Extract_T]([x <: C] => (x: x) => x.t)

Fails with:

Found:    x.t
Required: Extract_T[x]

A type projection doesn't help either:

tup.mapAs[C][[X <: C] =>> X#T]([x <: C] => (x: x) => x.t)

Fails with:

x is not a legal path
since it is not a concrete type

The root issue is that match types cannot reduce when the scrutinee is an abstract type parameter — the compiler doesn't "open" the refinement at the call site. Type projections (X#T) require a concrete path, which a polymorphic lambda's type parameter is not. As of now, abstract type members remain out of reach for mapAs. If you know a workaround, I'd love to hear it.

Case Closed

We went from runtime ClassCastException through match types, type classes, wrapper classes, opaque types, and finally arrived at a one-liner using clause interleaving. Each step taught us something about Scala 3's type system — and the last step reminded us to check if the language already has a simpler way.

I'd like to use containsOnly and mapAs patterns in M&DE, where typed pipelines need to transform homogeneous tuples of domain objects while preserving full type information. If you're building something similar, grab the code and adjust.

PS. Thesis defended. What do normal people do with their free time?

References

Yes, You Can Debug a Scala 3 Macro

Bartłomiej Kozak — Tue, 28 Apr 2026 00:00:00 GMT

The State of Scala 3 Macro Docs

There is no good Scala 3 macro book. Most of what I know I picked up from forum threads, release notes or papers. This post is my attempt to collect everything I've figured out so far, plus the tips that aren't written down anywhere else.

This post wouldn't exist without my best friend Bartek, who has a knack for doing impossible things — mostly because nobody told him they were impossible.

Where to Learn From

Tutorials

I'd recommend starting with these four. They overlap in places, but each one introduces something the others skip:

SoftwareMill — Scala 3 Macros: Tips and Tricks — the best starting point if you've never touched a macro before.
Rock the JVM — A Comprehensive Guide to Scala 3 Macros — longest of the four, with worked examples.
eed3si9n — Intro to Scala 3 Macros — concise, focused on the quote/splice mental model.
Official Scala 3 Macros Guide and the Metaprogramming Reference — the official source.

Papers

Once the tutorials stop helping, the papers explain why the API looks the way it does. They're less scary than they sound — skim the abstracts and intros first, and dip into the ones that match the question you're currently stuck on:

Scala 3 Macros: A Technical Report — the design rationale.
Stojanov, Biboudis et al. — Inlining in Scala 3 — how inline actually works.
Stucki et al. — Multi-Stage Programming with Generative and Analytical Macros — the theoretical foundation for quotes and splices.

Quotes.scala Is Your Best Friend

You'll spend more time in Quotes.scala than in any tutorial. Every tree type and every available method is defined there.

Each tree kind follows the same four-part shape: the type, the module object, a TypeTest for pattern matching, and an extension methods trait. For example:

/** Tree representing an if/then/else `if (...) ... else ...` in the source code. */
type If <: Term
/** Module object of `type If`. */
val If: IfModule

/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is an `If`. */
given IfTypeTest: TypeTest[Tree, If]

/** Makes extension methods on `If` available without any imports. */
given IfMethods: IfMethods

/** Methods of the module object `val If`. */
trait IfModule {
  this: If.type =>
  def apply(cond: Term, thenp: Term, elsep: Term): If
  def copy(original: Tree)(cond: Term, thenp: Term, elsep: Term): If
  def unapply(tree: If): (Term, Term, Term)
}

/** Extension methods of `If`. */
trait IfMethods:
  extension (self: If)
    def cond: Term
    def thenp: Term
    def elsep: Term
    def isInline: Boolean

Once you spot the pattern, the rest of the reflection API stops being a guessing game. The Scaladoc itself is packed with hints about invariants, tree shapes and idiomatic usage — far more than the guides on the website.

When Quotes.scala runs out, the compiler source is the next stop. For example, I've learned how to synthesise an anonymous class by reading tpd.scala.

A Note on IDEs

For macro-heavy code, VS Code with Metals has been less painful than IntelliJ. Sometimes (really sometimes) navigation is better, error messages are clearer, and there are files that compile fine in Metals but IntelliJ refuses to recognise. Syntax highlighting breaks on nested quotes; the formatter mangles code around splices. I still use IntelliJ for everything else.

Measuring Where the Compiler Spends Time

Slow compiles and outright compiler hangs aren't things you can diagnose with println. The built-in profiler shows you exactly which phase and which expansion is eating the clock.

Enable it via compiler options:

-Yprofile-enabled
-Yprofile-trace:<path to output file>

This emits a trace in the Chrome/Perfetto format. Load it in ui.perfetto.dev and you get a flamegraph of phases, macro expansions, and type-check calls:

The option is documented exactly once, in a 3.6.3 release note — which is how you find most Scala tooling features, and yes, it's as infuriating as it sounds.

Print Debugging, but Better

Everyone says println is the only way to debug a macro, so I built myself a pile of utilities on top of it. This one dumps everything the compiler knows about a type into a single error message:

def dbg(using quotes: Quotes, printer: quotes.reflect.Printer[quotes.reflect.TypeRepr])(tpe: quotes.reflect.TypeRepr): Nothing =
  quotes.reflect.errorAndAbort(
    s"""
       |type: ${tpe.show}
       |widen: ${tpe.widen.show}
       |widenTermRefByName: ${tpe.widenTermRefByName.show}
       |widenByName: ${tpe.widenByName.show}
       |dealias: ${tpe.dealias.show}
       |dealiasKeepOpaques: ${tpe.dealiasKeepOpaques.show}
       |simplified: ${tpe.simplified.show}
       |classSymbol: ${tpe.classSymbol}
       |typeSymbol: ${tpe.typeSymbol}
       |termSymbol: ${tpe.termSymbol}
       |isSingleton: ${tpe.isSingleton}
       |baseClasses: ${tpe.baseClasses}
       |isFunctionType: ${tpe.isFunctionType}
       |isContextFunctionType: ${tpe.isContextFunctionType}
       |isErasedFunctionType: ${tpe.isErasedFunctionType}
       |isDependentFunctionType: ${tpe.isDependentFunctionType}
       |isTupleN: ${tpe.isTupleN}
       |typeArgs: ${tpe.typeArgs}
       |""".stripMargin,
    )

Or this one, for when you're guessing at an AST shape:

inline def showRawAst(inline body: Any) = ${ showRawAstImpl('{ body }) }

def showRawAstImpl(body: Expr[Any])(using quotes: Quotes) =
  import quotes.reflect.*
  report.errorAndAbort(Printer.TreeStructure.show(body.asTerm.underlyingArgument))

showRawAst(someExpression) aborts compilation with the raw Apply(Select(Ident(...), ...), ...) shape of the expression. When you don't know which quotes.reflect case to match on, it tells you.

Attaching a Real Debugger

My best friend, Bartek, didn't get the memo that println was the only way to debug a macro.

He (and his LLM) treated the compiler as just another JVM process — attached a debugger, set breakpoints inside our macro implementations, and watched them fire on the next compile.

Written down like that it sounds obvious. Macros run during compilation, so the program to debug is the Scala compiler. The compile-side recipe is always the same: start the compiler's JVM with -agentlib:jdwp=..., whether you run Mill, sbt or scala-cli. What changes is how you configure the IDE side.

Starting the Compile with JDWP

The flag:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005

suspend=y pauses the JVM until a debugger connects, so you can attach before anything expands. How to inject the flag depends on the build tool:

mill

JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" mill -i YourModule.compile

sbt

sbt -jvm-debug 5005

scala-cli

# stop any running Bloop daemon (otherwise it'll reuse the old JVM without the agent)
scala-cli --power bloop exit

# compile, passing JDWP args to the new Bloop JVM
scala-cli compile . --bloop-java-opt "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"

All three end up the same way: a Scala compiler sitting on port 5005, waiting.

VS Code — launch.json

Add an attach configuration pointing at port 5005:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "scala",
      "request": "attach",
      "name": "Debug Macro (Compile-time)",
      "hostName": "localhost",
      "port": 5005,
      "buildTarget": "YourModuleName"
    }
  ]
}

buildTarget is the BSP target for the module whose sources contain your breakpoints. Metals lists them in the status bar; it's usually the module name from your build file.

Set breakpoints, start to compile, then Run -> Start Debugging.

IntelliJ IDEA — Remote JVM Debug

IntelliJ has no BSP-aware attach config for macros, so use the generic remote debugger:

Run -> Edit Configurations -> + -> Remote JVM Debug.
Host localhost, port 5005, "Attach to remote JVM", command line args for remote JVM auto-filled.
Start to compile.
Run -> Debug -> your new configuration.

Case Closed

There is no official "how to debug a Scala 3 macro" page. Until there is, I hope this one saves someone time. See ya next time.

References

Magical Kotlin: Building a Type-Safe Validation DSL

Bartłomiej Kozak — Fri, 12 Jun 2026 00:00:00 GMT

Kotlin Is Getting Tricky

Scala has the reputation for complexity on the JVM. Kotlin is usually seen as the pragmatic, safe, slightly boring alternative. I think that is changing. With a handful of recent features — context parameters, definitely-non-null types, contracts — Kotlin can be just as clever, and just as fun to abuse.

To show how these compose, I built a small validation library called sure. It is Kotlin Multiplatform, and the public API reads like this:

@Validatable
data class Address(val city: String, val zip: String) {
    companion object {
        val validator = Validator<Address> {
            field(::city) { notBlank() }
            field(::zip) { lengthIn(5..5) }
        }
    }
}

@Validatable
data class User(val name: String, val age: Int, val address: Address) {
    companion object {
        val validator = Validator<User> {
            field(::name) { notBlank(); lengthIn(1..50) }
            field(::age) { inRange(0..150) }
            validated(::address)   // reuses Address's own validator, resolved by type
        }
    }
}

User("alice", 30, Address("Kraków", "30001")).validate() // ValidationResult.Valid

No reflection on user types, no string field names — and that validate() isn't hand-written. A KSP processor generates it at compile time; everything between here and there is how the pieces it relies on get built.

A Note on Valiktor

What I built looks a lot like Valiktor. I found it after I'd written most of this. Valiktor predates context parameters and definitely-non-null types, so its API carries more boilerplate.

Setup

Everything below uses Kotlin 2.4.0.

I'll build the library from scratch — one feature at a time, starting from the simplest function that works and pulling in a new mechanism only when the previous step's pain forces it, until we reach the final API. The same example types ride through every step:

data class Address(val city: String, val zip: String)
data class User(val name: String, val age: Int, val address: Address)

Step 1: The hand-rolled version

The simplest thing that could work — one function:

fun validateUser(user: User): List<String> {
    val errors = mutableListOf<String>()

    when {
        user.name.isBlank() -> errors += "name: must not be blank"
        user.name.length !in 1..50 -> errors += "name: must be 1..50 characters"
    }
    if (user.age !in 0..150) errors += "age: must be in 0..150"

    if (user.address.city.isBlank()) errors += "address.city: must not be blank"
    if (user.address.zip.length != 5) errors += "address.zip: must be 5 digits"

    return errors
}

It works, but it hurts. The error list is hand-threaded through every branch. Field names are strings. Each rule re-states the field it talks about. And the nested Address doesn't compose — every check on it re-states the address. prefix by hand, and a second level of nesting would mean another prefix on top, with nothing to stop a typo in either.

Step 2: A scope to hold the errors

The first pain is the most basic: the error list is a local variable I pass around by hand. I'll move it into an object that travels with the validation — a scope. The scope holds the value being checked and owns the error list, so rules just call raise:

class ValidationScope<T>(val value: T) {
    val errors: List<String>
        field = mutableListOf()
    fun raise(message: String) {
        errors += message
    }
}

That field = mutableListOf() under the property is not a typo — it's an explicit backing field, stable as of Kotlin 2.4 (experimental behind -Xexplicit-backing-fields in 2.3). It lets a val declare two types: a public one and the one the field actually holds. Here the public type is List<String>, but inside the class the name errors resolves to the MutableList behind it — so callers get a read-only view while raise still appends, with no "private _errors plus public getter erorrs" template.

To run rules against a scope, I take a lambda with the scope as its receiver — that lambda is the validator:

class Validator<T>(private val rules: ValidationScope<T>.() -> Unit) {
    fun validate(value: T): List<String> {
        val scope = ValidationScope(value)
        scope.rules()
        return scope.errors
    }
}

The call site already reads better — no list to declare, no list to return:

val userValidator = Validator<User> {
    if (value.name.isBlank()) raise("name: must not be blank")
    if (value.age !in 0..150) raise("age: must be in 0..150")
    if (value.address.city.isBlank()) raise("address.city: must not be blank")
    if (value.address.zip.length != 5) raise("address.zip: must be 5 digits")
}

userValidator.validate(User("", 200, Address("Kraków", "30")))
// [name: must not be blank, age: must be in 0..150, address.zip: must be 5 digits]

rules: ValidationScope<T>.() -> Unit is a function with receiver: inside the braces, this is the scope, so value and raise resolve unqualified. Still, the messages are strings and I'm reaching into value.name while re-typing "name:" by hand. That duplication is the next pain.

Step 3: KProperty0 — name the field once

"name" (the label) and value.name (the read) are the same field spelled twice. I want to name it once. Kotlin has bound property references for exactly this: user::name is a KProperty0<String> that carries both the property's name and a zero-argument get().

To use them, the rules block hands its value back to me, and the scope grows a parent link and a path so a field can descend into a child scope that still reports into the same error list:

class Validator<T>(private val rules: ValidationScope<T>.(T) -> Unit) {
    fun validate(value: T): List<String> {
        val scope = ValidationScope(value)
        scope.rules(value)
        return scope.errors
    }
}

class ValidationScope<T>(
    val value: T,
    private val parent: ValidationScope<*>? = null,
    val path: String = "",
) {
    val errors: MutableList<String> = parent?.errors ?: mutableListOf()
    fun raise(message: String) {
        errors += if (path.isEmpty()) message else "$path: $message"
    }
}

field takes the property reference, reads it once, and runs the block against a child scope:

fun <F> ValidationScope<*>.field(property: KProperty0<F>, block: ValidationScope<F>.(F) -> Unit) {
    val childPath = if (path.isEmpty()) property.name else "$path.${property.name}"
    val child = ValidationScope(property.get(), this, childPath)
    child.block(property.get())
}

The leaf checks are extensions on the scope they apply to, so notBlank() exists only on a ValidationScope<String>:

fun ValidationScope<String>.notBlank() {
    if (value.isBlank()) raise("must not be blank")
}

fun <T : Comparable<T>> ValidationScope<T>.inRange(range: ClosedRange<T>) {
    if (value !in range) raise("must be in $range")
}

The field name is written once now, as a bound reference:

val userValidator = Validator<User> { user ->
    field(user::name) { notBlank() }
    field(user::age) { inRange(0..150) }
    field(user::address) { address ->
        field(address::city) { notBlank() }
        field(address::zip) { notBlank() }
    }
}

Better — but two things still grate. The block has to name its value (user ->) and every reference repeats it (user::name, user::age). And each check is welded to one receiver: field, notBlank, inRange are all extensions on ValidationScope, so a function can require exactly one scope and nothing more.

Step 4: Context parameters — drop the receiver juggling

I'd rather write field(::name) than field(user::name), and lose the user ->. For ::name to resolve, this inside the block has to be the User — but the block still has to reach the scope, to raise. That's two receivers at once, and an ordinary T.() -> Unit only gives you one.

Carrying an implicit dependency like this is one of the things context parameters are good for. A context parameter is a dependency a function declares without making it the receiver. The rules block becomes an extension on the value, with a scope available in context:

class Validator<T>(private val rules: context(ValidationScope<T>) T.() -> Unit) {
    fun validate(value: T): List<String> {
        val scope = ValidationScope(value)
        rules(scope, value)
        return scope.errors
    }
}

Now this is the User, so ::name resolves, while the ValidationScope<User> rides along in context — no user ->. field declares the scope it needs as a context parameter instead of an extension receiver:

context(scope: ValidationScope<*>)
fun <F> field(property: KProperty0<F>, block: ValidationScope<F>.(F) -> Unit) {
    val childPath = if (scope.path.isEmpty()) property.name else "${scope.path}.${property.name}"
    val child = ValidationScope(property.get(), scope, childPath)
    child.block(property.get())
}

The checks move from receiver to context too, sharing one check helper. Note the predicate flags the failure: when it returns true, the value is bad and check raises — so each leaf describes what's wrong, not what's allowed.

context(scope: ValidationScope<T>)
fun <T> check(predicate: (T) -> Boolean, onError: (T) -> String) {
    if (predicate(scope.value)) scope.raise(onError(scope.value))   // predicate true → raise
}

context(_: ValidationScope<String>)
fun notBlank() = check<String>({ it.isBlank() }) { "must not be blank" }

context(_: ValidationScope<String>)
fun lengthIn(range: IntRange) = check<String>({ it.length !in range }) { "must be $range characters" }

context(_: ValidationScope<T>)
fun <T : Comparable<T>> inRange(range: ClosedRange<T>) = check({ it !in range }) { "must be in $range" }

The top-level call site loses both the user -> and the repeated receiver — only a nested field still names its value (address ->), because a field block hands the value in as its lambda argument rather than as this:

val userValidator = Validator<User> {
    field(::name) { notBlank() }
    field(::age) { inRange(0..150) }
    field(::address) { address ->
        field(address::city) { notBlank() }
        field(address::zip) { lengthIn(5..5) }
    }
}

The one trap worth calling out: a context parameter is not a second this. If you remember the old context receivers, those did add a second receiver — context parameters don't. Inside Validator<User> { … } there's a single this (the User), so ::name resolves against it, while the scope just rides along:

Inside…	the single `this` is…	the scope is…
`Validator<User> { … }`	the `User`	an ambient `context(ValidationScope<User>)` parameter — not a `this`
`field(::name) { … }`	the `ValidationScope<String>`	the receiver itself (`field`'s block is `ValidationScope<F>.(F)`)

You can't call the scope's members directly — raise("…") won't resolve in the outer block, and there's no this@ValidationScope label. Its only job is to satisfy other functions that ask for one: when notBlank() declares context(_: ValidationScope<String>), the compiler finds the nearest matching value and wires it in. It's resolution, not dispatch, and at the JVM level it lowers to an ordinary leading argument. A function can also ask for several context parameters at once — which is what lets a field block stay a plain extension on the scope while the value arrives as the lambda argument.

Step 5: Nesting — the sealed scope family and the value contract

Stacking field already nests one object in another — address.city works because each call extends the parent's path with .name. The real test is collections, where errors must still report a sensible path — tags[2], headers[Accept] — but each kind of descent builds that path differently. A single ValidationScope class can't express "append .name" vs "append [index]" vs "append [key]" cleanly, so I split it into a small two-tier family. The base declares the contract; one intermediate owns the error list, the other forwards errors to its parent; and a leaf per nesting kind only has to say how it builds its path.

@ValidationDsl
sealed class ValidationScope<out T> {
    internal abstract val path: String
    internal abstract fun addError(error: ValidationError)

    fun raise(message: String) = addError(ValidationError(path, message))
}

// owns the error list — RootScope, and the throwaway EphemeralScope from Step 8
sealed class ParentScope<out T> : ValidationScope<T>() {
    val errors: List<ValidationError>
        field = mutableListOf()
    final override fun addError(error: ValidationError) {
        errors += error
    }
}

// no list of its own — forwards every error up to its parent
sealed class ChildrenScope<out T> : ValidationScope<T>() {
    abstract val parent: ValidationScope<*>
    final override fun addError(error: ValidationError) = parent.addError(error)
}

internal class RootScope<out T>(val value: T) : ParentScope<T>() {
    override val path = ""
}

internal class FieldScope<out T>(
    val value: T,
    name: String,
    override val parent: ValidationScope<*>,
) : ChildrenScope<T>() {
    override val path = if (parent.path.isEmpty()) name else "${parent.path}.$name"
}

internal class ItemScope<out T>(
    val value: T,
    index: Int,
    override val parent: ValidationScope<*>,
) : ChildrenScope<T>() {
    override val path = "${parent.path}[$index]"
}

internal class EntryScope<out T>(
    val value: T,
    key: Any?,
    override val parent: ValidationScope<*>,
) : ChildrenScope<T>() {
    override val path = "${parent.path}[$key]"
}

Two intermediate classes carry all the plumbing. ParentScope owns the list — behind the explicit backing field from Step 2, so addError appends internally while callers only read — and ChildrenScope forwards addError to its parent, so every nested error bubbles up to the one RootScope at the top. A leaf then declares only its path and holds its value; raise lives once, on the base. Both intermediates and the base are sealed, which matters for the accessor next.

Errors are now a small type instead of a bare string, so the path rides along (this becomes a sealed type with Field/ Element/Root cases in Step 11):

data class ValidationError(val path: String, val message: String)

The value contract

Start with the payoff, because the syntax below only makes sense once you know what it buys. Picture a user validating a nullable field — optional(::nickname) { … } where nickname: String?. Inside that block I want to call notBlank(), but notBlank() only exists on ValidationScope<String>, not ValidationScope<String?>. Without help I'd be writing value!! or value?.let { … } at every single check — exactly the null-noise this library exists to delete. What I want instead: one null check at the top of the block, and the compiler treats the value as a plain String for the rest — no !!, no ?, no cast.

A contract delivers that. It's a promise the getter makes to the compiler, stated in the contract { } block: when this getter returns a non-null value, treat the receiver as a scope of the non-null type — written returnsNotNull() implies (this@value is ValidationScope<T & Any>). That T & Any is a definitely-non-null type: "the non-null version of an unbounded generic T" — for nullable T = X? it's X, for already-non-null T it collapses to T.

@OptIn(ExperimentalContracts::class)
val <T> ValidationScope<T>.value: T
    get() {
        contract {
            returnsNotNull() implies (this@value is ValidationScope<T & Any>)
        }

        return when (this) {
            is RootScope -> value
            is FieldScope -> value
            is ItemScope -> value
            is EntryScope -> value
            is EphemeralScope -> value
        }
    }

Why an extension and not a member? The base scope owns no value — each leaf declares its own — so as a member, value would have to be abstract on ValidationScope. And Kotlin forbids contracts on abstract (or open) declarations: a contract { } describes one concrete body, but an abstract member has none, and an open one could be overridden out from under its promise. An extension is neither — it's a single final function with a real body, the exhaustive when that reconstructs value from whichever leaf this happens to be. That's the form a contract { } is allowed on, and its receiver parameter is what returnsNotNull() implies (this@value is ValidationScope<T & Any>) smart-casts.

In Step 7 this same contract lets one helper handle nullable and non-nullable fields with no cast.

The collection combinators each spin up the matching scope, so a deep failure still reports the right path:

context(scope: ValidationScope<List<T>>)
inline fun <T : Any> eachItem(rule: ValidationScope<T>.(T) -> Unit) {
    scope.value.forEachIndexed { index, item ->
        ItemScope(item, index, scope).rule(item)
    }
}

context(scope: ValidationScope<Map<K, V>>)
inline fun <K, V : Any> eachValue(rule: ValidationScope<V>.(V) -> Unit) {
    for ((k, v) in scope.value) EntryScope(v, k, scope).rule(v)
}

A failure inside eachItem now reports tags[2]: must not be blank, because ItemScope built that path from its parent's.

Step 6: @DslMarker — closing the leak

Now that scopes nest, the DSL has a quiet bug. Inside a nested block, this is the inner scope — but the enclosing scope is still in lexical reach, and both expose raise, addError, and friends. A member meant for the outer scope can silently resolve there from an inner block, attaching an error at the wrong path, with no error from the compiler.

@DslMarker is the fence against this. Annotate the scope type and the compiler forbids an implicit call that would skip past the nearest receiver to an outer one of the same marker:

@DslMarker
annotation class ValidationDsl

That's the annotation already sitting on ValidationScope back in Step 5. After it, reaching an outer scope from a nested block is a compile error unless you qualify it explicitly ( this@Validator.raise(...)). You only ever see the innermost scope by default — which is what you wanted.

Step 7: Nullable fields — field vs optional

So far field assumed a non-null property. Real DTOs have nullable fields, with two sensible behaviors: skip if null (optional), or fail if null (a required field that happens to be nullable). The definitely-non-null type from Step 5 carries the whole signature:

context(scope: ValidationScope<*>)
inline fun <F : Any> field(
    property: KProperty0<F>,
    block: ValidationScope<F>.(F) -> Unit = {},
) {
    val value = property.get()
    FieldScope(value, property.name, scope).block(value)
}

context(scope: ValidationScope<*>)
inline fun <F : Any> optional(
    property: KProperty0<F?>,
    block: ValidationScope<F>.(F) -> Unit,
) {
    val value = property.get()
    if (value != null) {
        FieldScope(value, property.name, scope).block(value)
    }
}

optional takes a KProperty0<F?> and, inside the null check, the value narrows to F. field constrains its block to F : Any, so even on a nullable property the rules see a non-null value. No casts anywhere — F & Any does the narrowing in the type, the Step 5 contract does it on the value.

Step 8: Combinators that need a private scope — anyOf / not

Some combinators don't want their inner errors recorded — they only care whether the inner rules passed. anyOf succeeds if any branch is clean; not succeeds if its rule fails. Both run rules against a throwaway scope whose errors never reach the parent. This is the fifth scope, and it falls straight out of the Step 5 split: it owns its errors rather than forwarding them, so it's a ParentScope, and that's the entire definition — the list, the backing field, and addError are all inherited.

internal class EphemeralScope<out T>(
    val value: T,
    parent: ValidationScope<*>,
) : ParentScope<T>() {
    override val path = parent.path
}

context(scope: ValidationScope<T>)
fun <T> anyOf(vararg rules: ValidationScope<T>.() -> Unit, message: () -> String) {
    val anyValid = rules.any { rule ->
        val isolated = EphemeralScope(scope.value, scope)
        isolated.rule()
        isolated.errors.isEmpty()
    }
    if (!anyValid) scope.raise(message())
}

context(scope: ValidationScope<T>)
fun <T> not(rule: ValidationScope<T>.() -> Unit, message: () -> String) {
    val isolated = EphemeralScope(scope.value, scope)
    isolated.rule()
    if (isolated.errors.isEmpty()) scope.raise(message())   // rule passed → negation fails
}

EphemeralScope keeps its own list instead of delegating up, so the parent never sees the trial-run errors.

The rule language is done: nesting with correct paths, @DslMarker safety, optional/field for nullables, and anyOf/not. Every pain from the hand-rolled Step 1 function is now gone.

The remaining steps change register. Steps 1–8 fixed pains; from here on the rules are settled and the work is dressing them in a public API — make Validator findable by type, translate messages, and finally generate validate(). Same library, outer layer.

Step 9: The Validator class — inline, reified, noinline

Validator has been a thin wrapper. I want three things from it: construct it as Validator<User> { … }, look it up later by type, and validate an arbitrary value. Looking up by type means storing T::class, which means the type must survive to runtime — reified — and that forces the constructing function inline:

open class Validator<T>(
    protected val kClass: KClass<T & Any>,
    internal val applyRules: ValidationScope<T>.() -> Unit,
) {
    companion object {
        inline operator fun <reified T : Any> invoke(
            noinline rules: context(ValidationScope<T>) T.() -> Unit,
        ): Validator<T> = Validator(T::class) { rules(value) }
    }
}

Three deliberate keywords:

reified T keeps the type at runtime, so T::class is a real KClass for the registry — and that's what forces inline.
noinline rules is the counterweight: the lambda is stored in the Validator, so it must exist as a real object in bytecode, and inlined lambdas don't — their bodies are copied into the call site with nothing left to store.
The rules type context(ValidationScope<T>) T.() -> Unit is the same context-plus-receiver shape from Step 4, now at the top level — this is the value, the scope is in context.

Three smaller choices in the signature are worth a line each:

KClass<T & Any>, not KClass<T>. The class leaves T unbounded so it can wrap a nullable target, but KClass's own parameter is Any-bounded — there's no KClass of a nullable type. T::class already produces a KClass<T & Any>, so the definitely-non-null projection is the only thing that fits the field.
operator fun invoke on the companion, instead of a plain constructor. Building a Validator needs T::class, which needs reified, which needs inline — and a constructor can be none of those. So the real entry point has to be an inline reified factory function. Naming it invoke on the companion keeps the constructor-like call site: Validator<User> { … } resolves to Validator.Companion.invoke<User>(…), so nothing at the call site has to change.
open class with an open fun validate. @Validatable(with = …) (Step 12) lets a caller register a custom Validator subclass in place of the default, and that's only possible if the class can be extended and validate overridden — a final class would slam the door.

Step 10: Validating an Any — the isInstanceOf contract

The point of the registry is to validate a value you only know as Any?. After a runtime type check I want to use it as T without an unchecked cast — and a contract buys that:

@OptIn(ExperimentalContracts::class)
private fun <T : Any> Any.isInstanceOf(kClass: KClass<T>): Boolean {
    contract { returns(true) implies (this@isInstanceOf is T) }
    return kClass.isInstance(this)
}

open fun validate(value: Any?): ValidationResult = when {
    value == null -> ValidationResult.Invalid(listOf(ValidationError("", "must not be null")))
    !value.isInstanceOf(kClass) ->
        ValidationResult.Invalid(listOf(ValidationError("", "expected ${kClass.simpleName}")))
    else -> {
        val scope = RootScope(value)   // value smart-cast to T here
        applyRules(scope)
        if (scope.errors.isEmpty()) ValidationResult.Valid else ValidationResult.Invalid(scope.errors)
    }
}

returns(true) implies (this is T) reads alarming — it's an unverified assertion, meaning the compiler can't prove it and takes the claim on faith, then smart-casts value to T with no as T and no warning. What makes it safe rather than reckless is the function body: KClass.isInstance performs the real runtime type check, so by the time the assertion is "trusted" it has already been verified at runtime. The contract just teaches the compiler what that Boolean result means. ValidationResult is just Valid or Invalid(errors) — a sealed result type that replaces the raw List once there's a type mismatch to report.

Step 11: Structured, translatable messages — fun interface

The messages have been bare strings this whole time. Errors shouldn't hard-code English, so I replace the string with a Message carrying a stable key, pre-stringified args, and a default text:

data class Message(val key: String, val args: List<String> = emptyList(), val text: String = key) {
    fun render(translator: Translator? = null): String = translator?.translate(key, args) ?: text

    companion object {
        val NotBlank = Message("validation.notBlank", text = "must not be blank")
        fun LengthIn(range: IntRange) =
            Message("validation.lengthIn", listOf(range.toString()), "must be $range characters")
        // …
    }
}

The translator is a single-method interface, so I declare it fun interface and any caller can hand it a lambda:

fun interface Translator {
    fun translate(key: String, args: List<String>): String?
}

val pl = Translator { key, args -> catalogue[key]?.format(args) }
error.message.render(pl)   // a lambda where an interface is expected

render falls back to text when no translator resolves the key — useful out of the box, localizable when you need it. The ValidationError from Step 5 grows into a sealed type whose cases carry a Message and a path:

sealed interface ValidationError {
    val message: Message

    data class Field(val path: String, override val message: Message) : ValidationError
    data class Element(val path: String, val index: Int, override val message: Message) : ValidationError
    data class Root(override val message: Message) : ValidationError
}

This is the one place the Step 5 split shows a seam. With a single ValidationError(path, message), raise could live once on the base. Now the case depends on the scope — Root for root and ephemeral scopes, Field for a field or map entry, Element (with its index) for a list item — so raise(message: Message) goes back to abstract on the base, and each leaf builds its own:

abstract fun raise(message: Message)   // on ValidationScope, replacing the String version

// RootScope, EphemeralScope
override fun raise(message: Message) = raise(ValidationError.Root(message))

// FieldScope, EntryScope
override fun raise(message: Message) = raise(ValidationError.Field(path, message))

// ItemScope
override fun raise(message: Message) = raise(ValidationError.Element(parent.path, index, message))

Every check now returns a Message instead of a String; the rest of the structure is untouched.

Step 12: @Validatable + KSP — generating validate()

One pain is left: calling someValidator.validate(req) by hand and wiring up a registry. The shape I'm after is the one from the very top of this post — tag a class @Validatable, point it at its validator, and get a validate() extension for free:

@Validatable
data class Address(val city: String, val zip: String) {
    companion object {
        val validator = Validator<Address> {
            field(::city) { notBlank() }
            field(::zip) { lengthIn(5..5) }
        }
    }
}

@Validatable
data class User(val name: String, val age: Int, val address: Address) {
    companion object {
        val validator = Validator<User> {
            field(::name) { notBlank(); lengthIn(1..50) }
            field(::age) { inRange(0..150) }
            validated(::address)   // Address's validator, looked up by type
        }
    }
}

User("alice", 30, Address("Kraków", "30001")).validate()   // ValidationResult — nothing hand-wired

The annotation itself is tiny. It marks the class and, optionally, names an external validator object instead of the companion validator:

@Target(AnnotationTarget.CLASS)
annotation class Validatable(val with: KClass<out Validator<*>> = Validator::class)

The shape is deliberately the same as @Serializable from kotlinx.serialization: tag a class, and a compile-time processor emits the boilerplate you'd otherwise hand-write — there encodeToString/decodeFromString wiring, here a validate() extension. Same ergonomics, same "no reflection, no runtime cost" promise; the only difference is that kotlinx.serialization ships a full compiler plugin while this is a few hundred lines of KSP.

Turning that @Validatable into a real validate() is a compile-time job, and KSP — Kotlin Symbol Processing — is the tool for it. It's the lightweight successor to kapt: instead of generating Java stubs and running a javac annotation processor, KSP hands you a resolved view of the program's Kotlin symbols (classes, functions, properties, annotations) and lets you emit new source files, which the compiler then picks up in the same build. No reflection, no runtime cost, no stub round-trip — the generated validate() is as if you'd typed it.

The processor isn't annotated or imported anywhere — KSP discovers it through a META-INF/services entry, a plain service-loader file naming the provider class:

# src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
sure.ksp.ValidationExtensionProcessorProvider

The provider's only job is to hand KSP a SymbolProcessor, wired with the two services every processor leans on: a CodeGenerator to emit files and a KSPLogger to report problems back through the compiler.

class ValidationExtensionProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
        ValidationExtensionProcessor(environment.codeGenerator, environment.logger)
}

One detail sets the tone for the whole processor: it works on strings KSP resolves for it, never on the sure types directly — the KSP module doesn't even depend on the runtime one. So the fully-qualified names it cares about are just constants:

private const val ANNOTATION_FQN = "sure.Validatable"
private const val VALIDATOR_FQN = "sure.Validator"
private const val VALIDATION_SCOPE_FQN = "sure.ValidationScope"
private const val VALIDATION_RESULT_FQN = "sure.ValidationResult"
private const val GENERATED_PACKAGE = "sure"
private const val GENERATED_FILE = "GeneratedValidationExtensions"
private const val VALIDATOR_FIELD = "validator"
private const val WITH_ARG = "with"

process is the workhorse. KSP runs in rounds — it calls process again whenever a round generated new symbols that themselves need processing — so a one-shot generator latches a generated flag and bails on re-entry. It asks the Resolver for every class carrying @Validatable, turns each into a small ValidatorRef, and writes one file:

private class ValidationExtensionProcessor(
    private val codeGenerator: CodeGenerator,
    private val logger: KSPLogger,
) : SymbolProcessor {
    private var generated = false

    override fun process(resolver: Resolver): List<KSAnnotated> {
        if (generated) return emptyList()

        val classes = resolver.getSymbolsWithAnnotation(ANNOTATION_FQN, false)
            .filterIsInstance<KSClassDeclaration>()
            .toList()
        if (classes.isEmpty()) return emptyList()

        val refs = classes.mapNotNull { it.toValidatorRef() }
        if (refs.isEmpty()) return emptyList()

        val originatingFiles = classes.mapNotNull { it.containingFile }.distinct()
        codeGenerator.createNewFile(
            Dependencies(false, *originatingFiles.toTypedArray()),
            GENERATED_PACKAGE,
            GENERATED_FILE,
        ).use { stream -> OutputStreamWriter(stream).use { it.write(render(refs)) } }

        generated = true
        return emptyList()
    }

Three things in there carry weight. getSymbolsWithAnnotation(ANNOTATION_FQN, false) returns a flat sequence of annotated symbols — the false (inDepth) keeps it shallow, since @Validatable only ever lands on a top-level class, never nested inside another annotated one. The List<KSAnnotated> that process returns is KSP's deferral channel: symbols that couldn't be resolved this round and should be retried next one; a finished one-shot returns nothing. And Dependencies(aggregating = false, *originatingFiles) is the incremental-build wiring — it ties the generated file to the exact @Validatable sources it was built from, so editing one of them regenerates only what's affected instead of the whole module.

toValidatorRef is where the annotation is read. A @Validatable type names its validator one of two ways, and the processor tries them in order — an explicit with = first, then the companion validator — walking the KSP symbol tree rather than reflecting. These are all extension functions on KSClassDeclaration, nested in the processor:

    private fun KSClassDeclaration.toValidatorRef(): ValidatorRef? {
    val receiverFqn = qualifiedName?.asString() ?: run {
        logger.warn("@Validatable type ${simpleName.asString()} has no qualified name", this)
        return null
    }
    val validatorExpression = customValidatorFqn() ?: companionValidatorExpression(receiverFqn) ?: return null
    return ValidatorRef(receiverFqn, validatorExpression)
}

The with = path has a wrinkle. KSP doesn't hand you a KClass — it hands you a KSType, a symbol in its model of the program, so you resolve the annotation, find the with argument, and read its declaration's qualified name. The catch is the default: @Validatable declares with = Validator::class as its "unset" sentinel, so a value equal to sure.Validator means no custom validator was given and the code returns null to fall through to the companion:

    private fun KSClassDeclaration.customValidatorFqn(): String? {
    val annotation = annotations.firstOrNull {
        it.annotationType.resolve().declaration.qualifiedName?.asString() == ANNOTATION_FQN
    } ?: return null

    val withType = annotation.arguments
        .firstOrNull { it.name?.asString() == WITH_ARG }
        ?.value as? KSType ?: return null

    val withFqn = withType.declaration.qualifiedName?.asString()
    return withFqn?.takeUnless { it == VALIDATOR_FQN }   // default sentinel → not a custom validator
}

The companion path scans the class's nested declarations for the companion object, then for a property named validator. A missing one isn't a reason to emit code that won't compile — it's a user mistake, so the processor logger.errors against the offending class and fails the build with a message that says exactly how to fix it:

    private fun KSClassDeclaration.companionValidatorExpression(receiverFqn: String): String? {
    val companion = declarations.filterIsInstance<KSClassDeclaration>().firstOrNull { it.isCompanionObject }
    val hasValidator = companion?.getAllProperties()?.any { it.simpleName.asString() == VALIDATOR_FIELD } == true
    return if (!hasValidator) {
        logger.error(
            "@Validatable class ${simpleName.asString()} must declare a `$VALIDATOR_FIELD` property in its " +
                    "companion object, or specify @Validatable($WITH_ARG = SomeObject::class)",
            this,
        )
        null
    } else {
        "$receiverFqn.$VALIDATOR_FIELD"
    }
}

The logger.warn vs logger.error split is deliberate: a class with no qualified name (anonymous or local) is just skipped with a warning, but a @Validatable whose validator can't be resolved is a hard error that stops the build.

There's no clever code generator behind render. It's a buildString that prints Kotlin source as text from the (receiver, validator) pairs — no templating engine, no AST builder, just appendLine. For each @Validatable type it emits a validate() extension, then one shared validatorsByClass map, a reified validatorFor<T>() lookup over it, and a validated(::field) overload that uses that lookup to resolve a nested validator by type:

    private fun render(refs: List<ValidatorRef>): String = buildString {
    appendLine("package $GENERATED_PACKAGE")
    appendLine()
    for (ref in refs) {
        appendLine(
            "fun ${ref.receiverFqn}.validate(): $VALIDATION_RESULT_FQN = " +
                    "${ref.validatorExpression}.validate(this)",
        )
        appendLine()
    }
    appendLine("@PublishedApi")
    appendLine("internal val validatorsByClass: Map<kotlin.reflect.KClass<*>, $VALIDATOR_FQN<*>> = mapOf(")
    for (ref in refs) {
        appendLine("    ${ref.receiverFqn}::class to ${ref.validatorExpression},")
    }
    appendLine(")")
    appendLine()
    appendLine("@Suppress(\"UNCHECKED_CAST\")")
    appendLine("inline fun <reified T : Any> validatorFor(): $VALIDATOR_FQN<T> =")
    appendLine("    validatorsByClass[T::class] as? $VALIDATOR_FQN<T>")
    appendLine("        ?: error(\"No validator registered for \${T::class.qualifiedName}\")")
    appendLine()
    // a validated(::field) overload that finds the sub-validator in the registry by type
    appendLine("context(_: $VALIDATION_SCOPE_FQN<*>)")
    appendLine("inline fun <reified F : Any> validated(property: kotlin.reflect.KProperty0<F>) =")
    appendLine("    validated(property, validatorFor<F>())")
}
}

private data class ValidatorRef(val receiverFqn: String, val validatorExpression: String)

Everything is a fully-qualified name because generated source has no imports to lean on — $VALIDATION_RESULT_FQN, kotlin.reflect.KClass, and the collected receiverFqns all print in full so the file compiles wherever it lands. For the two @Validatable types above, that produces a single sure/GeneratedValidationExtensions.kt the compiler picks up in the same build — one validate() per type, all of them in the shared registry:

package sure

fun com.example.Address.validate(): sure.ValidationResult =
    com.example.Address.validator.validate(this)

fun com.example.User.validate(): sure.ValidationResult =
    com.example.User.validator.validate(this)

@PublishedApi
internal val validatorsByClass: Map<kotlin.reflect.KClass<*>, sure.Validator<*>> = mapOf(
    com.example.Address::class to com.example.Address.validator,
    com.example.User::class to com.example.User.validator,
)

@Suppress("UNCHECKED_CAST")
inline fun <reified T : Any> validatorFor(): sure.Validator<T> =
    validatorsByClass[T::class] as? sure.Validator<T>
        ?: error("No validator registered for ${T::class.qualifiedName}")

context(_: sure.ValidationScope<*>)
inline fun <reified F : Any> validated(property: kotlin.reflect.KProperty0<F>) =
    validated(property, validatorFor<F>())

The validate() extension is what the call site at the very top of this post resolves to; validatorFor<T>() backs the type-keyed registry that Validator was made reified for back in Step 9. The generated validated(::address) overload closes a small loop with it — because every @Validatable type is in the registry, a nested field can pull its sub-validator by type with no explicit reference, exactly the call the two snippets above use.

That convenience comes with a caveat worth stating plainly: validatorFor<F>() is a runtime map lookup, not a compile-time guarantee. validated(::address) type-checks whether or not an Address validator was ever registered; if the field's type isn't @Validatable (or its module wasn't on the path when the registry was generated), the lookup misses and error(...) throws at validation time. The explicit validated(::address, Address.validator) form keeps that honest — passing the validator directly is checked by the compiler. So this is the usual derivation trade-off: the zero-argument overload is convenient, the explicit one is statically safe.

This is the Kotlin equivalent of Scala's automatic type-class derivation — except instead of inductive givens resolved by the compiler, it's a code generator emitting plain source. The same trade-off shows up there too: Scala's implicit resolution fails the compile, whereas this registry lookup can only fail at runtime.

That closes the loop: the public API from the very top of this post is now fully assembled.

Through the Decompiler

The library is done — the section below is a bonus for the curious. Most of the "magic" above exists only in source; decompiling the JVM target shows it flattening into ordinary bytecode patterns. If you don't care what it lowers to, jump to Case Closed.

Context parameters are the clearest case. A check like notBlank() has no receiver in Kotlin, but its context(_: ValidationScope<String>) lowers to a plain leading parameter:

public static final void notBlank(ValidationScope $context) {
    check($context, NotBlankPredicate.INSTANCE, NotBlankMessage.INSTANCE);
}

field(::name) inlines into the caller. The property reference becomes a fresh synthetic class with a get(); there is no reflective dispatch, just a specialized getter call:

KProperty0 property$iv = (KProperty0) new PropertyReference0Impl($receiver) {
    public Object get() {
        return ((User) this.receiver).getName();
    }
};
Object value$iv = property$iv.get();
FieldScope fs = new FieldScope(value$iv, property$iv.getName(), scope$iv);
// … inlined block body …

reified T in Validator<User> { … } lowers to a literal User.class at the call site — Reflection.getOrCreateKotlinClass(User.class) — captured into the Validator constructor. The noinline rules lambda forced a real Function object, so it shows up as a synthetic class rather than copied-in code; that's the whole point of noinline.

Contracts leave no trace at all in bytecode. returns(true) implies (this is T) and returnsNotNull() implies … are compile-time-only — they change what the Kotlin compiler will let you write, then evaporate. The decompiled isInstanceOf is a one-liner returning kClass.isInstance(this); the smart cast it enabled became an ordinary, checked-at-source assignment with no runtime cast inserted.

Explicit backing fields collapse to exactly what you'd hand-write. The val errors: List / field = mutableListOf() pair becomes one private field and a read-only getter — no second property, and crucially no setter:

private final List errors = new ArrayList();        // the single backing field
public final List getErrors() { return this.errors; }  // read-only — no setErrors emitted

Inside the class, where errors means the MutableList, errors += message is just a method call on that same field:

((Collection) this.errors).add(message);   // from `errors += message`

So the encapsulation is real, not a wrapper: callers see List, the class mutates the one underlying instance, and nothing is allocated to bridge the two.

fun interface doesn't allocate a class per lambda. Translator { key, args -> … } lowers to an invokedynamic call site backed by LambdaMetafactory — the same machinery as a plain Kotlin/Java lambda, the runtime spins up the implementation on first use:

// the `Translator { … }` becomes:
0: invokedynamic #40,  0   // InvokeDynamic #0:translate:()Lsure/Translator;

Definitely-non-null types mostly vanish. F & Any erases to its ordinary bound — there's no special JVM type — so the guarantee is carried by @Metadata plus the occasional Intrinsics.checkNotNullParameter guard the compiler drops in at a public boundary. At runtime it's a plain non-null reference like any other.

Case Closed

The library is, structurally, a type class: type-indexed dispatch (validatorFor<T>()), behavior parameterized by type, and — via KSP — derivation. Where the Scala version of this story leans on Mirrors and inductive givens, Kotlin gets there with context parameters and a KSP code generator for the derivation.

As it turns out, Kotlin can be scary too.

The full source — multiplatform targets, every built-in check, the KSP processor, tests — is at github.com/halotukozak/sure.