feat(schema): implement Schema Migration System (#519)

[yuvrajangadsingh]

Implements the schema migration system from #519.

The main design choice here was creating a dedicated MigrationExpr type rather than modifying the existing SchemaExpr. The reason: SchemaExpr contains function-based types (IsNumeric, Optic[_, _, _]) that aren't serializable, and I didn't want to break or complicate existing code to make them work. A separate MigrationExpr keeps everything self-contained — all changes are in the migration package, nothing else is touched.

How it works

Two-layer architecture following the existing Patch/DynamicPatch pattern:

• DynamicMigration — the untyped, serializable core. A vector of MigrationAction values (pure ADT, no closures) that operates on DynamicValue. Supports composition (++), structural reverse, and path-based navigation via DynamicOptic.

• Migration[A, B] — typed wrapper that pairs a DynamicMigration with source/target schemas. Handles the conversion between typed values and DynamicValue.

• MigrationBuilder — fluent API using macros to convert _.field selector syntax into DynamicOptic at compile time (both Scala 2.13 and 3). In Scala 3, there's also a MigrationComplete type class that gives you a compile error if your migration doesn't cover all fields.

• MigrationExpr — pure expression type for computed values: arithmetic, string concat, comparisons, type conversions. All serializable, no closures.

Actions

20 action types covering records (AddField, DropField, Rename, TransformValue, Mandate, Optionalize, Nest, Unnest), joins/splits (Join, Split, JoinExpr, SplitExpr), type conversions (ChangeType, ChangeTypeExpr), enums (RenameCase, TransformCase), and collections (TransformElements, TransformKeys, TransformValues). Plus expression-based variants (TransformValueExpr).

Nested migrations work naturally — TransformCase, TransformElements, etc. contain their own Vector[MigrationAction], so you can express hierarchical transformations.

Quick example

// Compile-time validated (Scala 3)
val migration = Migration.builder[UserV1, UserV2]
  .renameField(_.name, _.fullName)
  .addField(_.age, 0)
  .build  // won't compile if fields are missing

// Nest fields into a sub-record
val nest = MigrationAction.Nest(root, "address", Vector("street", "city", "zip"))

// Expression-based transforms
val fullName = field(_.firstName) ++ Literal(" ") ++ field(_.lastName)

Tests

335 tests across 4 spec files, organized the same way the repo does it for Patch (separate PatchSpec, DynamicPatchSpec, etc.):

• DynamicMigrationSpec — core ops, path navigation, Nest/Unnest, multi-step, laws
• MigrationActionSpec — action laws, error handling, enum scenarios, reverse round-trips
• MigrationBuilderSpec — typed Migration[A, B], builder API, composition
• MigrationExprSpec — expression evaluation, arithmetic, string ops, type conversions

Also added DynamicMigrationBenchmark with 8 JMH benchmarks (addField, rename, composed, nested, sequence transform, reverse, nest, unnest) plus a spec that validates benchmark output.

Why 23 files

12 of the 23 files are platform-specific macro code for Scala 2/3 cross-compilation. The metaprogramming APIs are completely different between scala.reflect and scala.quoted, so each platform needs its own implementations. This is the same pattern used throughout the repo — Patch, Schema, Optic all have separate platform-specific files per concern.

The remaining 11 are: 5 shared source files (core logic), 4 test files, 2 benchmark files.

Closes #519

[yuvrajangadsingh]

/claim #519

Ready for review! This implementation addresses all success criteria from issue #519 with:

• 226 tests (most comprehensive test suite)
• Zero changes to existing code - dedicated MigrationExpr instead of modifying SchemaExpr
• Full compile-time validation via MigrationComplete type class (Scala 3)
• Selector functions via macros (not strings) - addresses feedback from closed PRs
• Hierarchical nested migrations (lists of lists) - addresses feedback from Schema Migration System for zio-blocks #891

cc @jdegoes

[yuvrajangadsingh]

@copilot review

[yuvrajangadsingh]

Hey @jdegoes — noticed this got closed. Is there specific feedback or something you'd like changed? Happy to rework if needed.