@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftdata/references/core-data-coexistence.md

@@ -1,504 +1,308 @@
-# Core Data Coexistence
+# Core Data and SwiftData together
 
-Standalone Core Data patterns for projects not yet on SwiftData, strategies
-for running Core Data and SwiftData side by side against the same store, and
-migration guidance for transitioning from Core Data to SwiftData.
+For a question about running both frameworks or moving from one to the other,
+start at [Sharing one store](#sharing-one-store). The Core Data stack section
+is context for reading an existing app, not a Core Data tutorial.
 
 ## Contents
 
-- [Standalone Core Data Stack](#standalone-core-data-stack)
-- [Core Data + SwiftData Coexistence](#core-data--swiftdata-coexistence)
-- [Migration from Core Data to SwiftData](#migration-from-core-data-to-swiftdata)
+- [The Core Data side at a glance](#the-core-data-side-at-a-glance)
+- [Sharing one store](#sharing-one-store)
+- [Migrating an app to SwiftData](#migrating-an-app-to-swiftdata)
+- [Checklist](#checklist)
 
-## Standalone Core Data Stack
+## The Core Data side at a glance
 
-For teams that haven't adopted SwiftData, Core Data remains a fully supported
-persistence framework.
-
-Docs: [NSPersistentContainer](https://sosumi.ai/documentation/coredata/nspersistentcontainer),
-[Setting up a Core Data stack](https://sosumi.ai/documentation/coredata/setting-up-a-core-data-stack)
-
-### NSPersistentContainer Setup
-
-`NSPersistentContainer` encapsulates the Core Data stack: the managed object
-model, the persistent store coordinator, and the managed object context.
+Core Data remains fully supported, and many apps keep it. The pieces you will
+meet when reading such an app:
 
 ```swift
 import CoreData
 
-final class CoreDataStack: @unchecked Sendable {
-    static let shared = CoreDataStack()
-
+final class LibraryStack {
     let container: NSPersistentContainer
 
-    private init() {
-        // Name must match the .xcdatamodeld file name
-        container = NSPersistentContainer(name: "MyAppModel")
-
-        container.loadPersistentStores { description, error in
-            if let error {
-                fatalError("Core Data store failed to load: \(error)")
-            }
+    init() {
+        // "Library" is also the name of Library.xcdatamodeld.
+        container = NSPersistentContainer(name: "Library")
+        let main = container.viewContext
+        main.automaticallyMergesChangesFromParent = true
+        main.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
+        container.loadPersistentStores { description, loadError in
+            guard let loadError else { return }
+            fatalError("Could not open \(description.url?.lastPathComponent ?? "store"): \(loadError)")
         }
-
-        // Automatically merge changes from background contexts
-        container.viewContext.automaticallyMergesChangesFromParent = true
-        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
-    }
-
-    /// The main-thread context for UI reads
-    var viewContext: NSManagedObjectContext {
-        container.viewContext
-    }
-
-    /// A new background context for writes
-    func newBackgroundContext() -> NSManagedObjectContext {
-        container.newBackgroundContext()
     }
 }
 ```
 
-### NSManagedObjectContext Usage
+- `viewContext` runs on the main queue and serves reads and UI.
+- Writes and bulk work use `newBackgroundContext()` inside
+  `await context.perform { }`.
 
-The `viewContext` is bound to the main queue; use it for reads and UI. Use
-background contexts for writes and batch operations.
+Fetching:
 
 ```swift
-// Reading on the main context
-func fetchTrips() throws -> [CDTrip] {
-    let context = CoreDataStack.shared.viewContext
-    let request = CDTrip.fetchRequest()
-    request.sortDescriptors = [NSSortDescriptor(keyPath: \CDTrip.startDate, ascending: true)]
-    return try context.fetch(request)
-}
-
-// Writing on a background context
-func createTrip(name: String, destination: String) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        let trip = CDTrip(context: context)
-        trip.name = name
-        trip.destination = destination
-        trip.startDate = Date.now
-        trip.id = UUID()
-        try context.save()
-    }
-}
-```
-
-### NSFetchRequest with NSPredicate and NSSortDescriptor
-
-```swift
-import CoreData
-
-func fetchUpcomingTrips(destination: String) throws -> [CDTrip] {
-    let context = CoreDataStack.shared.viewContext
-    let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
-
-    // Predicate: filter by destination and future start date
-    request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: [
-        NSPredicate(format: "destination ==[cd] %@", destination),
-        NSPredicate(format: "startDate > %@", Date.now as NSDate)
-    ])
-
-    // Sort: newest first
-    request.sortDescriptors = [
-        NSSortDescriptor(keyPath: \CDTrip.startDate, ascending: false)
+func overdueLoans(for member: String, in context: NSManagedObjectContext) throws -> [CDLoan] {
+    let request = NSFetchRequest<CDLoan>(entityName: "Loan")
+    let conditions = [
+        NSPredicate(format: "memberName ==[cd] %@", member),
+        NSPredicate(format: "dueAt < %@", Date() as NSDate)
     ]
-
-    // Performance: limit results and prefetch relationships
-    request.fetchLimit = 20
-    request.relationshipKeyPathsForPrefetching = ["accommodation"]
-
+    request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: conditions)
+    request.sortDescriptors = [NSSortDescriptor(keyPath: \CDLoan.dueAt, ascending: true)]
+    request.fetchLimit = 50
+    request.relationshipKeyPathsForPrefetching = ["book"]
     return try context.fetch(request)
 }
 
-// Counting without loading objects
-func countFavoriteTrips() throws -> Int {
-    let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
-    request.predicate = NSPredicate(format: "isFavorite == YES")
-    return try CoreDataStack.shared.viewContext.count(for: request)
-}
+let openCount = try context.count(for: NSFetchRequest<CDLoan>(entityName: "Loan"))
 ```
 
-### Saving Context and Error Handling
+Saving, with failures turned into app errors:
 
 ```swift
-func saveContext(_ context: NSManagedObjectContext) throws {
-    guard context.hasChanges else { return }
+enum LibraryStoreError: Error { case duplicate, missingField, other(Error) }
 
+func commit(_ moc: NSManagedObjectContext) throws {
+    if !moc.hasChanges { return }
     do {
-        try context.save()
-    } catch {
-        // Roll back unsaved changes to prevent inconsistent state
-        context.rollback()
-
-        if let nsError = error as NSError? {
-            // Check for common Core Data errors
-            switch nsError.code {
-            case NSManagedObjectConstraintMergeError:
-                // Unique constraint violation -- handle merge conflict
-                throw PersistenceError.constraintViolation(nsError)
-            case NSValidationMissingMandatoryPropertyError:
-                // Required property is nil
-                throw PersistenceError.validationFailed(nsError)
-            default:
-                throw PersistenceError.saveFailed(nsError)
-            }
+        try moc.save()
+    } catch let error as NSError {
+        moc.rollback()
+        switch error.code {
+        case NSManagedObjectConstraintMergeError: throw LibraryStoreError.duplicate
+        case NSValidationMissingMandatoryPropertyError: throw LibraryStoreError.missingField
+        default: throw LibraryStoreError.other(error)
         }
-        throw error
     }
 }
-
-enum PersistenceError: Error {
-    case constraintViolation(NSError)
-    case validationFailed(NSError)
-    case saveFailed(NSError)
-}
 ```
 
-### Background Processing Pattern
+Bulk insert (iOS 13+) bypasses the context, so push the result into the view
+context afterwards:
 
 ```swift
-func importTrips(_ records: [TripRecord]) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        // Batch insert for performance (iOS 13+)
-        let batchInsert = NSBatchInsertRequest(
-            entity: CDTrip.entity(),
-            objects: records.map { record in
-                [
-                    "id": record.id,
-                    "name": record.name,
-                    "destination": record.destination,
-                    "startDate": record.startDate
-                ] as [String: Any]
-            }
-        )
-        batchInsert.resultType = .count
-        let result = try context.execute(batchInsert) as? NSBatchInsertResult
-        print("Inserted \(result?.result as? Int ?? 0) trips")
-
-        // Merge changes into viewContext
-        NSManagedObjectContext.mergeChanges(
-            fromRemoteContextSave: [NSInsertedObjectsKey: []],
-            into: [CoreDataStack.shared.viewContext]
-        )
+func importBooks(_ rows: [[String: any Sendable]], stack: LibraryStack) async throws {
+    let context = stack.container.newBackgroundContext()
+    let inserted: [NSManagedObjectID] = try await context.perform {
+        let insert = NSBatchInsertRequest(entity: CDBook.entity(), objects: rows)
+        insert.resultType = .objectIDs
+        let outcome = try context.execute(insert)
+        return (outcome as? NSBatchInsertResult)?.result as? [NSManagedObjectID] ?? []
     }
+    let changes = [NSInsertedObjectsKey: inserted]
+    NSManagedObjectContext.mergeChanges(fromRemoteContextSave: changes,
+                                        into: [stack.container.viewContext])
 }
 ```
 
-## Core Data + SwiftData Coexistence
+Use `resultType = .count` when you only need how many rows went in; request
+`.objectIDs`, as above, when you want to merge the inserted objects into other
+contexts.
 
-Core Data and SwiftData can share the same underlying SQLite store. This
-enables gradual migration: keep existing Core Data code running while
-introducing SwiftData for new features.
+Apple documentation: the `NSPersistentContainer` reference
+(https://developer.apple.com/documentation/coredata/nspersistentcontainer) and
+the Core Data stack setup article in the same section.
 
-Docs: [Adopting SwiftData for a Core Data app](https://sosumi.ai/documentation/coredata/adopting_swiftdata_for_a_core_data_app)
+## Sharing one store
 
-### Using the Same Underlying Store
+Both frameworks can open the same SQLite file, which lets an app move one
+screen at a time.
 
-Both stacks must point to the same SQLite file and agree on the schema. The
-Core Data `.xcdatamodeld` and SwiftData `@Model` classes must describe the
-same entities and properties.
+Point SwiftData at the file Core Data already uses:
 
 ```swift
-import SwiftData
-import CoreData
-
-// 1. Determine the store URL that Core Data already uses
 let storeURL = NSPersistentContainer.defaultDirectoryURL()
-    .appendingPathComponent("MyAppModel.sqlite")
-
-// 2. Point SwiftData at the same store
-let config = ModelConfiguration(
-    "MyAppModel",
-    url: storeURL
-)
-
-let container = try ModelContainer(
-    for: Trip.self,
-    configurations: config
-)
-```
-
-### ModelConfiguration Pointing to Existing Core Data Store
-
-Key rules for coexistence:
-
-1. The `@Model` class name must match the Core Data entity name.
-2. Property names and types must match exactly.
-3. Use `@Attribute(originalName:)` if you renamed properties.
-4. Both stacks should use the same store file.
-
-```swift
-// Core Data entity: CDTrip (entity name "Trip" in .xcdatamodeld)
-// Attributes: name (String), destination (String), startDate (Date),
-//             isFavorite (Boolean), imageData (Binary Data)
-
-// Matching SwiftData model
-@Model
-class Trip {
-    var name: String
-    var destination: String
-    var startDate: Date
-    var isFavorite: Bool = false
-    @Attribute(.externalStorage) var imageData: Data?
-
-    init(name: String, destination: String, startDate: Date) {
-        self.name = name
-        self.destination = destination
-        self.startDate = startDate
-    }
-}
+    .appendingPathComponent("Library.sqlite")
+let sharedStore = ModelConfiguration("Library", url: storeURL)
+let swiftDataSide = try ModelContainer(for: Book.self, Loan.self, configurations: sharedStore)
 ```
 
-### Gradual Coexistence Strategy
+Rules for the shared store:
 
-```swift
-// Phase 1: Core Data stack still handles writes;
-//          SwiftData reads the same store for new UI
-@main
-struct MyApp: App {
-    let coreDataStack = CoreDataStack.shared  // Existing Core Data
-
-    var body: some Scene {
-        WindowGroup {
-            ContentView()
-        }
-        // SwiftData reads from the same store
-        .modelContainer(for: Trip.self, configurations:
-            ModelConfiguration(url: coreDataStack.storeURL)
-        )
-    }
-}
+- Each `@Model` class name equals the Core Data entity name. Name the Core Data
+  classes differently (for example `CDBook`) so the Swift types do not collide.
+- Property names and types match exactly. Where the Swift name has to differ,
+  use `@Attribute(originalName:)`.
+- Both stacks use the same file.
+- Turn on persistent history (`NSPersistentHistoryTrackingKey`) in the Core
+  Data store description.
+- Only one framework writes a given entity at a time. Pick the writer per
+  entity and keep it there until that entity moves.
+- `automaticallyMergesChangesFromParent` and
+  `NSPersistentStoreRemoteChangeNotification` let each side notice the other's
+  writes.
+- A mismatch between the `.xcdatamodeld` and the `@Model` classes crashes at
+  load time. Test the pairing thoroughly.
 
-// Phase 2: New features use SwiftData for both reads and writes
-// Phase 3: Migrate remaining Core Data code to SwiftData
-// Phase 4: Remove Core Data stack and .xcdatamodeld
-```
+A phased move:
 
-### Important Coexistence Rules
+1. Core Data keeps writing; new screens read through SwiftData.
+2. New features read and write with SwiftData.
+3. Remaining code moves over entity by entity.
+4. Delete the Core Data stack and the `.xcdatamodeld`.
 
-- **Do not write to the same entity from both stacks simultaneously.** Pick
-  one stack per entity for writes to avoid conflicts.
-- Core Data's `automaticallyMergesChangesFromParent` and
-  `NSPersistentStoreRemoteChangeNotification` help detect changes from the
-  other stack.
-- Test thoroughly -- schema mismatches between the `.xcdatamodeld` and
-  `@Model` cause crashes.
+Apple documentation: the SwiftData adoption article for Core Data apps, in the
+Core Data section of the developer documentation.
 
-## Migration from Core Data to SwiftData
+## Migrating an app to SwiftData
 
-### Step 1: Map Core Data Entities to `@Model` Classes
+### Step 1: write one model per entity
 
-Create a `@Model` class for each Core Data entity. Property names and types
-must align with the `.xcdatamodeld` definition.
+To-one relationships become optional references; to-many become arrays. Give
+both ends an inverse.
 
 ```swift
-// Core Data entity "Article"
-// Attributes: id (UUID), title (String), body (String),
-//             createdAt (Date), isDraft (Boolean)
-// Relationships: author (to-one → Author), tags (to-many → Tag)
-
 @Model
-class Article {
-    @Attribute(.unique) var id: UUID
+final class Book {
     var title: String
-    var body: String
-    var createdAt: Date
-    var isDraft: Bool = true
-
-    @Relationship(deleteRule: .nullify, inverse: \Author.articles)
-    var author: Author?
+    var isbn: String
+    var publishedOn: Date?
+    @Relationship(deleteRule: .nullify, inverse: \Loan.book)
+    var loans: [Loan] = []
 
-    @Relationship(deleteRule: .nullify, inverse: \Tag.articles)
-    var tags: [Tag] = []
-
-    init(id: UUID = UUID(), title: String, body: String, createdAt: Date = .now) {
-        self.id = id
+    init(title: String, isbn: String) {
         self.title = title
-        self.body = body
-        self.createdAt = createdAt
+        self.isbn = isbn
     }
 }
 
 @Model
-class Author {
-    @Attribute(.unique) var id: UUID
-    var name: String
-    var articles: [Article] = []
-
-    init(id: UUID = UUID(), name: String) {
-        self.id = id
-        self.name = name
-    }
-}
-
-@Model
-class Tag {
-    @Attribute(.unique) var id: UUID
-    var name: String
-    var articles: [Article] = []
-
-    init(id: UUID = UUID(), name: String) {
-        self.id = id
-        self.name = name
+final class Loan {
+    var memberName: String
+    var dueAt: Date
+    @Relationship(deleteRule: .nullify)
+    var book: Book?
+
+    init(memberName: String, dueAt: Date) {
+        self.memberName = memberName
+        self.dueAt = dueAt
     }
 }
 ```
 
-### Type Mapping Reference
+Type mapping, SwiftData type first:
 
-| Core Data Type | SwiftData Type |
+| Swift type in the `@Model` | Core Data attribute it replaces |
 |---|---|
-| String | String |
-| Boolean | Bool |
-| Integer 16/32/64 | Int |
-| Float / Double | Float / Double |
-| Date | Date |
-| Binary Data | Data |
-| UUID | UUID |
-| URI | URL |
-| Decimal | Decimal |
-| Transformable | Codable struct (composite, iOS 18+) |
-| To-one relationship | Optional reference to `@Model` |
-| To-many relationship | Array of `@Model` |
-
-### Step 2: Schema Versioning Considerations
-
-If the Core Data store has existing data, SwiftData must be able to open it.
-Use `VersionedSchema` and `SchemaMigrationPlan` for non-trivial changes.
+| `String` | String |
+| `Bool` | Boolean |
+| `Int` | any of the Integer types (16, 32 or 64 bit) |
+| `Double` / `Float` | Double / Float |
+| `Decimal` | Decimal |
+| `Date` | Date |
+| `UUID` | UUID |
+| `URL` | URI |
+| `Data` | Binary Data |
+| A `Codable` struct or enum, stored as a composite attribute | Transformable |
+| Optional reference to another `@Model` | To-one relationship |
+| `[RelatedModel]` array | To-many relationship |
+
+Compatible `Codable` structs and enums are storable in any SwiftData release;
+there is no separate OS threshold for storing them.
+
+### Step 2: open the existing store
+
+If the SwiftData models match the Core Data model exactly, the store opens with
+no migration. If you also want to change the schema, describe the current shape
+as the first `VersionedSchema` and migrate from there:
 
 ```swift
-// If the SwiftData model exactly matches the Core Data schema,
-// no migration is needed -- SwiftData opens the store directly.
-
-// For schema differences, define versioned schemas:
-enum SchemaV1: VersionedSchema {
-    static var versionIdentifier = Schema.Version(1, 0, 0)
-    static var models: [any PersistentModel.Type] { [Article.self, Author.self] }
+enum LibraryV1: VersionedSchema {
+    static let versionIdentifier: Schema.Version = .init(1, 0, 0)
 
-    @Model class Article {
-        var id: UUID
+    static var models: [any PersistentModel.Type] { [Book.self, Loan.self] }
+    @Model final class Book {
         var title: String
-        var body: String
-        var createdAt: Date
-        init(id: UUID, title: String, body: String, createdAt: Date) {
-            self.id = id; self.title = title
-            self.body = body; self.createdAt = createdAt
-        }
+        var isbn: String
+        init(title: String, isbn: String) { self.title = title; self.isbn = isbn }
     }
-
-    @Model class Author {
-        var id: UUID
-        var name: String
-        init(id: UUID, name: String) { self.id = id; self.name = name }
+    @Model final class Loan {
+        var memberName: String
+        var dueAt: Date
+        init(memberName: String, dueAt: Date) { self.memberName = memberName; self.dueAt = dueAt }
     }
 }
 
-enum SchemaV2: VersionedSchema {
-    static var versionIdentifier = Schema.Version(2, 0, 0)
-    static var models: [any PersistentModel.Type] { [Article.self, Author.self, Tag.self] }
+enum LibraryV2: VersionedSchema {
+    static let versionIdentifier: Schema.Version = .init(2, 0, 0)
 
-    @Model class Article {
-        var id: UUID
+    static var models: [any PersistentModel.Type] { [Book.self, Loan.self, Shelf.self] }
+    @Model final class Book {
         var title: String
-        var body: String
-        var createdAt: Date
-        var isDraft: Bool = true  // New property
-        init(id: UUID, title: String, body: String, createdAt: Date) {
-            self.id = id; self.title = title
-            self.body = body; self.createdAt = createdAt
-        }
+        var isbn: String
+        var isArchived: Bool = false
+        init(title: String, isbn: String) { self.title = title; self.isbn = isbn }
     }
-
-    @Model class Author {
-        var id: UUID
-        var name: String
-        init(id: UUID, name: String) { self.id = id; self.name = name }
+    @Model final class Loan {
+        var memberName: String
+        var dueAt: Date
+        init(memberName: String, dueAt: Date) { self.memberName = memberName; self.dueAt = dueAt }
     }
-
-    @Model class Tag {
-        var id: UUID
-        var name: String
-        init(id: UUID, name: String) { self.id = id; self.name = name }
+    @Model final class Shelf {
+        var code: String
+        init(code: String) { self.code = code }
     }
 }
 
-enum ArticleMigrationPlan: SchemaMigrationPlan {
-    static var schemas: [any VersionedSchema.Type] { [SchemaV1.self, SchemaV2.self] }
+enum LibraryMigration: SchemaMigrationPlan {
+    static var schemas: [any VersionedSchema.Type] { [LibraryV1.self, LibraryV2.self] }
     static var stages: [MigrationStage] {
-        [MigrationStage.lightweight(fromVersion: SchemaV1.self, toVersion: SchemaV2.self)]
+        [.lightweight(fromVersion: LibraryV1.self, toVersion: LibraryV2.self)]
     }
 }
 ```
 
-### Step 3: Testing Migration Paths
+### Step 3: test against a real store
 
-Always test migration with real production data copies before shipping.
+Copy a fixture store taken from a real install, including its `-wal` and
+`-shm` files, open it through the migration plan, and check the data.
 
 ```swift
-import XCTest
+import Testing
 import SwiftData
-
-final class MigrationTests: XCTestCase {
-
-    func testCoreDataToSwiftDataMigration() throws {
-        // 1. Copy a known Core Data store into the test bundle
-        let sourceURL = Bundle(for: type(of: self))
-            .url(forResource: "TestStore", withExtension: "sqlite")!
-
-        let tempDir = FileManager.default.temporaryDirectory
-            .appendingPathComponent(UUID().uuidString)
-        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
-
-        let destURL = tempDir.appendingPathComponent("TestStore.sqlite")
-        try FileManager.default.copyItem(at: sourceURL, to: destURL)
-
-        // Copy WAL and SHM if they exist
-        for ext in ["-wal", "-shm"] {
-            let src = sourceURL.deletingLastPathComponent()
-                .appendingPathComponent("TestStore.sqlite\(ext)")
-            if FileManager.default.fileExists(atPath: src.path) {
-                try FileManager.default.copyItem(
-                    at: src,
-                    to: tempDir.appendingPathComponent("TestStore.sqlite\(ext)")
-                )
-            }
-        }
-
-        // 2. Open with SwiftData
-        let config = ModelConfiguration(url: destURL)
-        let container = try ModelContainer(
-            for: SchemaV2.Article.self,
-            migrationPlan: ArticleMigrationPlan.self,
-            configurations: config
-        )
-
-        // 3. Verify data survived migration
-        let context = ModelContext(container)
-        let articles = try context.fetch(FetchDescriptor<SchemaV2.Article>())
-        XCTAssertFalse(articles.isEmpty, "Migration should preserve existing articles")
-
-        // 4. Verify new properties have defaults
-        for article in articles {
-            XCTAssertTrue(article.isDraft, "New isDraft property should default to true")
-        }
-
-        // Cleanup
-        try FileManager.default.removeItem(at: tempDir)
+import Foundation
+
+@Test func legacyLibraryStoreMigrates() throws {
+    let fm = FileManager.default
+    let scratch = fm.temporaryDirectory.appending(path: "migration-\(UUID().uuidString)")
+    try fm.createDirectory(at: scratch, withIntermediateDirectories: true)
+    defer { try? fm.removeItem(at: scratch) }
+
+    for suffix in ["", "-wal", "-shm"] {
+        guard let source = Bundle.module.url(forResource: "Library.sqlite\(suffix)",
+                                             withExtension: nil) else { continue }
+        try fm.copyItem(
+            at: source,
+            to: scratch.appendingPathComponent("Library.sqlite\(suffix)"))
     }
+
+    let config = ModelConfiguration(url: scratch.appendingPathComponent("Library.sqlite"))
+    let container = try ModelContainer(
+        for: LibraryV2.Book.self, LibraryV2.Loan.self, LibraryV2.Shelf.self,
+        migrationPlan: LibraryMigration.self,
+        configurations: config
+    )
+    let context = ModelContext(container)
+    let books = try context.fetch(FetchDescriptor<LibraryV2.Book>())
+
+    #expect(!books.isEmpty)
+    #expect(books.allSatisfy { !$0.isArchived })
 }
 ```
 
-### Migration Checklist
+Run this against copies of production data before every release that touches
+the schema.
+
+## Checklist
 
-- [ ] Every Core Data entity has a matching `@Model` class with identical property names and types
-- [ ] Relationship inverse properties are specified in both directions
-- [ ] `VersionedSchema` and `SchemaMigrationPlan` defined for non-trivial schema changes
-- [ ] `ModelConfiguration` points to the existing Core Data SQLite file
-- [ ] Tested migration with a copy of production data
-- [ ] Only one stack writes to each entity during coexistence
-- [ ] `automaticallyMergesChangesFromParent` enabled on Core Data's `viewContext`
-- [ ] `.xcdatamodeld` removed only after full migration is verified
+- [ ] One `@Model` per entity, with identical names and types.
+- [ ] Relationships have inverses on both sides.
+- [ ] Non-trivial changes go through a `VersionedSchema` and a
+      `SchemaMigrationPlan`.
+- [ ] The SwiftData configuration points at the existing SQLite file.
+- [ ] The migration was tested on a copy of production data.
+- [ ] Each entity has exactly one writer at any time.
+- [ ] `automaticallyMergesChangesFromParent` is on in the Core Data stack.
+- [ ] The `.xcdatamodeld` is deleted only after everything is verified.