Generated migrations: upgrade bound data when the schema changes

[matt-edmondson]

Split out of #120, item 4, now that items 1 and 2 (path resolution, and loading/validating bound data) have landed.

Problem

When a schema changes, the data files bound to it by a DataSource silently stop conforming. SchemaDataValidator will now report that they no longer conform (#120), but nothing helps a user fix the data.

Scope

Detect schema changes that affect bound data — a renamed, removed or retyped member, a changed enum value — and generate migration code or scripts that upgrade the data in place.

Dependencies

• A schema diff. Nothing today can compare two versions of a schema. This is the substantial part.
• The format version field (Document the .schema.json format and add a format version field #121, landed): formatVersion and the migration policy in docs/schema-format.md establish how the schema file itself migrates. Data migration should follow the same shape rather than inventing a parallel mechanism.
• Code generation: generator architecture and a first-party C# generator #119, if migrations are emitted as generated code rather than run directly.

Notes

Renames are the interesting case and are now tractable: as of #112 a rename cascades through the schema, so a diff sees a member renamed rather than one member removed and another added — but only if the rename is recorded. Consider whether the diff can infer renames, or whether the schema needs to retain rename history for data migration to be reliable.

Acceptance criteria

• Two versions of a schema can be diffed into a set of changes affecting bound data.
• A migration is generated for renamed, removed and retyped members, and for enum value changes.
• Data migrated by it validates clean against the new schema.

[matt-edmondson]

Triage

Priority: Medium Effort: Large

What needs to be done: When a schema changes in a way that affects bound data (renamed/removed/retyped member, changed enum value), generate migration code/scripts to upgrade the data in place. The substantial missing piece is a schema diff — nothing today compares two schema versions.

Suggested next steps / acceptance criteria:

• Build the schema-diff capability first; it's called out in the issue itself as "the substantial part" and everything else depends on it.
• Decide whether rename detection is inferred from the diff or whether the schema needs to retain explicit rename history (the issue raises this as open).
• Follow the versioning shape already established by formatVersion/Document the .schema.json format and add a format version field #121 rather than inventing a parallel mechanism.

Blockers / dependencies: Depends on a schema-diff capability that doesn't exist yet (no tracking issue found for it — may be worth splitting out as its own issue before starting this one). Loosely depends on #119/#126's generator architecture if migrations are emitted as generated code rather than run directly, per the issue's own notes.

---

Generated by Claude Code