/claim #519

What this does

Implements the schema migration system specified in #519. Two-layer design: a serializable DynamicMigration core that operates on DynamicValue, and a typed Migration[A, B] wrapper with macro-validated selectors for the user-facing API.

Architecture

• DynamicMigration holds a Vector[MigrationAction] and applies them sequentially to DynamicValue trees
• Migration[A, B] wraps source/target schemas and delegates to DynamicMigration under the hood
• MigrationBuilder[A, B] provides the fluent API with selector macros that extract DynamicOptic paths at compile time
• DynamicSchemaExpr is the expression ADT for value transforms (no closures, fully serializable)
• MigrationValidation checks at build time that all source fields are accounted for in the target schema

MigrationAction ADT (16 cases)

Record: AddField, DropField, Rename, TransformValue, Mandate, Optionalize, Join, Split, ChangeType Enum: RenameCase, TransformCase Collection: TransformElements, TransformKeys, TransformValues Meta: ApplyMigration, Irreversible

Every action carries a DynamicOptic path and implements reverse.

Selector macros

Scala 3 uses inline + scala.quoted to parse selector lambdas into DynamicOptic paths. Scala 2 uses whitebox.Context macros with quasiquotes. Both support field access, .when[T] case selection, .each collection traversal, .atKey(k) map access, and .wrapped[T].

Literal API

literal[A](value)(implicit Schema[A]) converts typed values to DynamicSchemaExpr eagerly. No raw DynamicValue.Primitive(...) construction in user code.

What changed

20 new files, 3,722 lines. No existing files modified.

Shared (6 files): DynamicMigration, DynamicSchemaExpr, Migration, MigrationAction, MigrationValidation, package object Scala 3 (4 files): MigrationBuilder, SelectorMacros, MigrationSelectorSyntax, MigrationCompanionVersionSpecific Scala 2 (4 files): Same as Scala 3 with equivalent macro implementations Tests (6 files): DynamicMigrationSpec, DynamicSchemaExprSpec, MigrationActionSpec, MigrationSpec, MigrationValidationSpec, MigrationIntegrationSpec

Tests

191 migration tests across 6 test suites. All pass on both Scala 2.13.18 and 3.7.4. Zero regressions across the full test suite (15,909 total tests).

Success criteria from #519

• DynamicMigration fully serializable (no closures, no functions)
• Migration[A, B] wraps schemas and actions
• All actions path-based via DynamicOptic
• User API uses selector functions (S => A) via macros
• Macro validation in .build
• .buildPartial supported
• Structural reverse implemented
• Identity and associativity laws hold (tested)
• Enum rename/transform supported
• Errors include path information
• Comprehensive tests (191 tests, 6 suites)
• Scala 2.13 and Scala 3.5+ supported