Overview

This PR implements a pure, algebraic Migration System for ZIO Schema 2. It represents structural transformations between schema versions as first-class, serializable data, enabling schema evolution and data versioning without requiring runtime representations of past data versions.

This implementation includes the Core Architecture, the Typed User API, and the platform-specific Macros (Scala 2 & Scala 3) required for a type-safe selector DSL.

Features

Core Architecture

• Pure Data
  Migrations are represented by the DynamicMigration ADT and MigrationActions, which are fully serializable and introspectable.

• Type Safety
  The user-facing Migration[A, B] API enforces source and target schemas.

• Reversibility
  All actions support structural inversion (e.g., dropField is reversible because it stores a default value for restoration).

• Error Types
  A comprehensive MigrationError hierarchy (TypeMismatch, MissingField, etc.) captures the exact DynamicOptic path where a failure occurred.

Selector-Based DSL

• Users can define migrations using type-safe selector functions
  (e.g. _.renameField(_.name, _.fullName)).

Macro Implementation

• Scala 3

  • Uses quoted macros (inline) to extract paths.
  • Utilizes StructuralSchemaDerivation to define structural types on the fly.

• Scala 2

  • Uses scala-reflect (whitebox macros) to parse selector trees (field, .when, .each) into DynamicOptic nodes at compile time.

Verification Laws

• Identity
  Migration.identity[A] is a no-op.

• Associativity
  Composition of migrations is associative.

• Structural Reverse
  Reversing a migration and reversing it again yields the original structure.

• Semantic Inverse
  Validated via the Best-Effort Semantic Inverse property.

Changes

Core

shared/src/main/scala/zio/blocks/schema/migration/

• Migration.scala
  Typed API generic over source and target.

• DynamicMigration.scala
  Untyped, serializable core.

• MigrationAction.scala
  Atomic operations (AddField, DropField, Rename, TransformValue, Join, Split, etc.).

• MigrationBuilder.scala
  DSL builder implementation.

• MigrationError.scala
  Error ADT with path support.

Scala 2 Integration

shared/src/main/scala-2/zio/blocks/schema/migration/

• MigrationBuilderMacros.scala
  Implements macro logic to split selector paths into DynamicOptic nodes.
  Supports fields, .when[Case], and .each.

• MigrationBuilderPlatform.scala
  Wiring for the builder to use macros.

Scala 3 Integration

shared/src/main/scala-3/...

• StructuralSchemaDerivation.scala
  Implements Schema.structural[T] for refinement types and union types (tagged enums).

• Validation
  Compile-time validation logic.

Integration

• SchemaExpr.scala
  Added DynamicLiteral and DefaultValue for migration action support.

Testing

shared/src/test/scala/zio/blocks/schema/migration/

• MigrationBuilderSpec
  Verifies selector syntax execution for Scala 2 & Scala 3.

• MigrationSpec
  Law checks and property-based tests.

Verification

• Test Suite
  Passed 664 tests
  (sbt ++2.13.12 schemaJVM/test), covering all implemented actions, laws, and selector syntax.

• Style
  Code matches project style (sbt scalafmtAll).

Notes

Structural Types

• Scala 3
  Fully supported via Schema.structural[T].

• Scala 2
  Users should use case classes for version snapshots, as structural type derivation is a Scala 3–only feature in this PR.

Collection Macros

• Scala 2 implementation focuses on record operations (rename, drop, add) via selectors.
• Complex nested collection transforms (transformValues) are supported via DynamicOptic paths or Scala 3 selectors.

AI Disclosure

• Used Claude Sonnet to understand the codebase, write comments, and ensure full test coverage.
• Used ChatGPT to rephrase the PR description.

/claim #519