kindlings

Wiring the per-library derivation policy (issue #85) into a derivation module: the shared DerivationPolicy trait, the AllowDerivation marker + policy package object, gating the structural case-class/enum rules, the ;/| list-encoding gotcha, and the integration test module.

Bootstrapping a new Kindlings derivation module. Build configuration, 3-layer file structure, entry points (type class + inlined body), implementation requirements REQ-1 through REQ-12, test coverage checklist, error hierarchy, syncing from Hearth.

Profile JMH benchmarks with JFR: statistical execution sampling (any JDK) and deterministic method timing/tracing (JDK 25+, JEP 520) to measure exact invocation counts and timing of macro-generated codec/encoder/decoder methods. Covers exact sbt/JMH commands, targeting generated methods, reading results, and the JDK gating.

Quick-reference table of commonly used Hearth API signatures: Expr, Type, MIO, ValDefsCache, CaseClass, Enum, LambdaBuilder, Environment. Always verify with MCP.

Cross-compilation pitfalls for Scala 2.13 + 3 macros with Hearth. Path-dependent types, splice isolation, type constructor matching, reification failures, Array ClassTag, upcast constraints, phantom types, asInstanceOf semantics, IsMap ordering.

Parsing selector/path lambdas (`_.a.b.each.when[T]`) and building optics-like marker DSLs with Hearth. DestructuredExpr step-chain walking, per-platform markers + invariant evidence, CaseClass copy-with-modification, non-exhaustive MatchCase, runtime-typeclass delegation. Reference: the `optics` module (quicklens reimplemented).

Deriving type classes for case classes: CaseClass.parse, primaryConstructor, field access, Expr_?? existential types, decoder construction, nest vs nestInCache, dual-path derivation.

Creating IsCollection and IsMap providers for external collection types (e.g. cats NonEmptyList, NonEmptyMap). Helper method pattern, runtime helper pattern, fromUntyped matching, SBT reload.

Canonical recipe for generating type-class instances with cached defs via ValDefsCache. forwardDeclare, buildCachedWith, toValDefs.use, parTuple for parallel derivation. Use when implementing multi-method type class instances or solving Scala 3 sibling-splice isolation.

Finding and using Hearth documentation. ReadTheDocs URLs by version, verifying APIs via MCP, Hearth source as reference (key files), cross-referencing with kindlings.

Deriving type classes for sealed traits and Scala 3 enums: Enum.parse, Enum.matchOn dispatch, singleton handling, discriminator decoding, recursive enum self-reference (var-self trick).

Polymorphic (kind * -> *) type class derivation with Hearth. Erased approach with AnyF, two-probe field classification (Int/String probes), bridge methods for type constructor summoning, runtime helpers for erased HKT calls, ConsK algorithm.

When to use LambdaBuilder and when not to. Strict rule: only for collection/Optional iteration lambdas passed to runtime helpers. Migration guide for inappropriate usages.

Core Hearth macro architecture: rule-based derivation, context passing, MIO effects, ValDefsCache caching, recursive derivation with implicit ignoring. Foundation for all type class derivation modules.

Loading Hearth standard extensions exactly once per macro bundle. ensureStandardExtensionsLoaded() pattern, LoadStandardExtensionsOnce trait, what extensions provide (IsCollection, IsMap, IsValueType, IsOption).

Creating IsValueType providers for external value types (refined, iron, opaque types). Provider registration, wrap/unwrap methods, Type.Ctor2.fromUntyped for cross-compilation.

Debugging Kindlings macro derivation. LogDerivation imports, MIO diagnostic logging, flame graph generation, error trait hierarchy per module, compile-time annotation collection, recursive type tracking with MLocal.

Writing and testing executable code snippets in the Kindlings user guide. Expected output verification syntax, running snippet tests (just test-snippets), template variables.

Factory instance pattern for generating final type class instances. Lambda factories for monomorphic (kind *), erasure-based factories with Witness types for polymorphic (kind * -> *). Benchmark data showing lambda vs anonymous class performance.

Runtime performance optimization for macro-generated type class instances. semiEval for compile-time config, ValDefs.createVar for typed locals, sentinel loops, inline built-in encoding/decoding, inline collection loops, position-based record access.