axiom-swiftdata-migration-diag

# SwiftData Migration Diagnostics

## Overview

SwiftData migration failures manifest as production crashes, data loss, corrupted relationships, or simulator-only success. **Core principle** 90% of migration failures stem from missing models in VersionedSchema, relationship inverse issues, or untested migration paths—not SwiftData bugs.

## Red Flags — Suspect SwiftData Migration Issue

If you see ANY of these, suspect a migration configuration problem:

- App crashes on launch after schema change
- "Expected only Arrays for Relationships" error
- "The model used to open the store is incompatible with the one used to create the store"
- "Failed to fulfill faulting for [relationship]"
- Migration works in simulator but crashes on real device
- Data exists before migration, gone after
- Relationships broken after migration (nil where they shouldn't be)
- ❌ **FORBIDDEN** "SwiftData migrations are broken, we should use Core Data"
  - SwiftData handles millions of migrations in production apps
  - Schema mismatches and relationship errors are always configuration, not framework
  - Do not rationalize away the issue—diagnose it

**Critical distinction** Simulator deletes the database on each rebuild, hiding schema mismatch issues. Real devices keep persistent databases and crash immediately on schema mismatch. **MANDATORY: Test migrations on real device with real data before shipping.**

## Mandatory First Steps

**ALWAYS run these FIRST** (before changing code):

```swift
// 1. Identify the crash/issue type
// Screenshot the crash message and note:
//   - "Expected only Arrays" = relationship inverse missing
//   - "incompatible model" = schema version mismatch
//   - "Failed to fulfill faulting" = relationship integrity broken
//   - Simulator works, device crashes = untested migration path
// Record: "Error type: [exact message]"

// 2. Check schema version configuration
// In your migration plan:
enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any V