@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/core-data/SKILL.md

@@ -1,498 +1,432 @@
 ---
 name: core-data
-description: "Build, review, or improve Core Data persistence in apps that have not adopted SwiftData. Use when working with NSManagedObject subclasses, NSFetchedResultsController for list-driven UI, NSBatchInsertRequest / NSBatchDeleteRequest / NSBatchUpdateRequest for bulk operations, NSPersistentHistoryChangeRequest for persistent history tracking and multi-target sync, NSStagedMigrationManager for staged schema migrations (iOS 17+), NSCompositeAttributeDescription for composite attributes (iOS 17+), or when integrating Core Data threading with Swift Concurrency. For Core Data + SwiftData coexistence or migration, see the swiftdata skill instead."
+description: "Create, audit or refine Core Data persistence for apps still on Core Data rather than SwiftData: stack setup, NSManagedObject subclasses, NSFetchedResultsController for list UIs, NSBatchInsertRequest, NSBatchDeleteRequest and NSBatchUpdateRequest bulk work, NSPersistentHistoryChangeRequest history tracking across app and extension targets, NSStagedMigrationManager staged migrations and NSCompositeAttributeDescription composite attributes (iOS 17+), and making Core Data contexts work with Swift Concurrency. Use when working on an existing Core Data store. Not for Core Data and SwiftData coexistence or migration; use the swiftdata skill."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Core Data
 
-Build and maintain data persistence using Core Data for apps that have not
-adopted SwiftData. Covers stack setup, concurrency, batch operations,
-NSFetchedResultsController, persistent history tracking, staged migration,
-and testing.
+For apps that still persist with Core Data rather than SwiftData. Covers the
+stack, queue rules and Swift Concurrency, fetched results controllers, batch
+requests, persistent history, staged migration, composite attributes and
+testing. Hand-offs: SwiftData coexistence and migration go to `swiftdata`;
+iCloud sync details (zones, sharing, `CKError`) go to `cloudkit-sync`; test
+style goes to `swift-testing`.
 
-## Contents
+## The stack
 
-- [Stack Setup](#stack-setup)
-- [Concurrency and Threading](#concurrency-and-threading)
-- [NSFetchedResultsController](#nsfetchedresultscontroller)
-- [Batch Operations](#batch-operations)
-- [Persistent History Tracking](#persistent-history-tracking)
-- [Staged Migration](#staged-migration)
-- [Composite Attributes](#composite-attributes)
-- [SwiftData Boundary](#swiftdata-boundary)
-- [Testing](#testing)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Stack Setup
-
-`NSPersistentContainer` encapsulates the Core Data stack.
-
-Docs: [NSPersistentContainer](https://sosumi.ai/documentation/coredata/nspersistentcontainer)
+`NSPersistentContainer` wraps the model, coordinator and contexts. Create it
+once and share it.
 
 ```swift
 import CoreData
 
-final class CoreDataStack: @unchecked Sendable {
-    static let shared = CoreDataStack()
-
+final class LibraryStore: Sendable {
+    static let shared = LibraryStore()
     let container: NSPersistentContainer
 
     private init() {
-        container = NSPersistentContainer(name: "MyAppModel")
+        container = NSPersistentContainer(name: "Library")
         container.loadPersistentStores { _, error in
-            if let error { fatalError("Core Data store failed: \(error)") }
+            if let error { fatalError("Store failed to load: \(error)") }
         }
-        container.viewContext.automaticallyMergesChangesFromParent = true
-        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
+        let ui = container.viewContext
+        ui.automaticallyMergesChangesFromParent = true
+        ui.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump   // NSMergeByPropertyObjectTrumpMergePolicy
     }
 
-    var viewContext: NSManagedObjectContext { container.viewContext }
-
-    func newBackgroundContext() -> NSManagedObjectContext {
+    func makeWorker() -> NSManagedObjectContext {
         container.newBackgroundContext()
     }
 }
 ```
 
-For CloudKit sync, use `NSPersistentCloudKitContainer` instead.
+`LibraryStore` is checked `Sendable` with no `@unchecked`: its only stored
+property is a `let` of `NSPersistentContainer`, which the SDK marks `Sendable`.
+Replace `fatalError` with real recovery in shipping code. When the store syncs
+through iCloud, create an `NSPersistentCloudKitContainer` instead.
 
-## Concurrency and Threading
+## Queues and threads
 
-Core Data contexts are bound to queues. The `viewContext` is on the main queue;
-background contexts operate on private queues.
+Every context belongs to a queue: `viewContext` to the main queue, background
+contexts to private queues.
 
-Docs: [NSManagedObjectContext](https://sosumi.ai/documentation/coredata/nsmanagedobjectcontext)
-
-**Rules:**
-- Always use `perform(_:)` or `performAndWait(_:)` when accessing a context
-  off its own queue.
-- Never pass `NSManagedObject` instances across context or thread boundaries.
-  Pass `NSManagedObjectID` instead and re-fetch.
-- Set `automaticallyMergesChangesFromParent = true` on the `viewContext`.
+- Touch a context from anywhere other than its own queue only inside
+  `perform(_:)` or `performAndWait(_:)`.
+- Never hand an `NSManagedObject` to another context or thread. Pass its
+  `NSManagedObjectID` and fetch it again on the other side.
+- Turn on `automaticallyMergesChangesFromParent` for `viewContext`.
 
 ```swift
-// Writing on a background context
-func updateTrip(id: NSManagedObjectID, newName: String) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        guard let trip = try context.existingObject(with: id) as? CDTrip else {
-            throw PersistenceError.notFound
-        }
-        trip.name = newName
-        try context.save()
+func markReturned(_ loanID: NSManagedObjectID) async throws {
+    let worker = LibraryStore.shared.makeWorker()
+    try await worker.perform {
+        guard let loan = try worker.existingObject(with: loanID) as? Loan else { return }
+        loan.returnedAt = .now
+        try worker.save()
     }
 }
 ```
 
-### Swift Concurrency Integration
+### Swift Concurrency
 
-`NSManagedObjectContext.perform(_:)` has an `async throws` overload
-(iOS 15+). Avoid marking `NSManagedObject` subclasses as `Sendable`.
+Since iOS 15 you can `try await context.perform { }`. Do not mark
+`NSManagedObject` subclasses `Sendable` or `@unchecked Sendable`; they are not
+thread-safe.
 
 ```swift
-func importItems(_ records: [ItemRecord]) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        for record in records {
-            let item = CDItem(context: context)
-            item.id = record.id
-            item.title = record.title
+func importBooks(_ rows: [BookRow]) async throws {
+    let worker = LibraryStore.shared.makeWorker()
+    try await worker.perform {
+        for row in rows {
+            let book = Book(context: worker)
+            book.isbn = row.isbn
+            book.title = row.title
         }
-        try context.save()
+        if worker.hasChanges { try worker.save() }
     }
-    // After save completes, viewContext auto-merges if configured
+    // viewContext picks this up through automatic merging
 }
-```
-
-**Do not use `@unchecked Sendable` on managed objects.** If you need
-cross-boundary communication, pass the `objectID` (which is `Sendable`)
-and re-fetch:
 
-```swift
-let objectID = trip.objectID  // Sendable
-Task.detached {
-    let bgContext = CoreDataStack.shared.newBackgroundContext()
-    try await bgContext.perform {
-        let trip = try bgContext.existingObject(with: objectID) as! CDTrip
-        trip.isFavorite = true
-        try bgContext.save()
+func archive(_ bookID: NSManagedObjectID) {
+    Task.detached {                       // NSManagedObjectID is Sendable
+        let worker = LibraryStore.shared.makeWorker()
+        try await worker.perform {
+            let book = try worker.existingObject(with: bookID) as? Book
+            book?.isArchived = true
+            try worker.save()
+        }
     }
 }
 ```
 
-## NSFetchedResultsController
+## `NSFetchedResultsController`
 
-Efficiently drives `UITableView` / `UICollectionView` from a Core Data fetch
-request, with built-in change tracking and optional caching.
-
-Docs: [NSFetchedResultsController](https://sosumi.ai/documentation/coredata/nsfetchedresultscontroller)
+An FRC feeds a table or collection view from a fetch request, tracks changes,
+and can cache section data.
 
 ```swift
-import CoreData
 import UIKit
 
-class TripsViewController: UITableViewController, NSFetchedResultsControllerDelegate {
-
-    private lazy var fetchedResultsController: NSFetchedResultsController<CDTrip> = {
-        let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
-        request.sortDescriptors = [
-            NSSortDescriptor(keyPath: \CDTrip.startDate, ascending: false)
-        ]
-        request.fetchBatchSize = 20
-
-        let controller = NSFetchedResultsController(
-            fetchRequest: request,
-            managedObjectContext: CoreDataStack.shared.viewContext,
-            sectionNameKeyPath: nil,
-            cacheName: "TripsCache"
-        )
-        controller.delegate = self
-        return controller
-    }()
+final class ShelfViewController: UICollectionViewController, @preconcurrency NSFetchedResultsControllerDelegate {
+    private var results: NSFetchedResultsController<Book>!
+    private var dataSource: UICollectionViewDiffableDataSource<String, NSManagedObjectID>!
 
     override func viewDidLoad() {
         super.viewDidLoad()
-        try? fetchedResultsController.performFetch()
-    }
-
-    // MARK: - UITableViewDataSource
-
-    override func numberOfSections(in tableView: UITableView) -> Int {
-        fetchedResultsController.sections?.count ?? 0
+        let request = Book.fetchRequest()
+        request.sortDescriptors = [NSSortDescriptor(keyPath: \Book.title, ascending: true)]
+        request.fetchBatchSize = 25
+        results = NSFetchedResultsController(fetchRequest: request,
+                                             managedObjectContext: LibraryStore.shared.container.viewContext,
+                                             sectionNameKeyPath: nil,
+                                             cacheName: nil)
+        results.delegate = self
+        try? results.performFetch()
     }
 
-    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
-        fetchedResultsController.sections?[section].numberOfObjects ?? 0
-    }
-
-    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
-        let cell = tableView.dequeueReusableCell(withIdentifier: "TripCell", for: indexPath)
-        let trip = fetchedResultsController.object(at: indexPath)
-        cell.textLabel?.text = trip.name
-        return cell
-    }
-
-    // MARK: - NSFetchedResultsControllerDelegate (diffable)
-
-    func controller(
-        _ controller: NSFetchedResultsController<any NSFetchRequestResult>,
-        didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference
-    ) {
-        let snapshot = snapshot as NSDiffableDataSourceSnapshot<String, NSManagedObjectID>
-        dataSource.apply(snapshot, animatingDifferences: true)
+    func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>,
+                    didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference) {
+        let typed = snapshot as NSDiffableDataSourceSnapshot<String, NSManagedObjectID>
+        dataSource.apply(typed, animatingDifferences: true)
     }
 }
 ```
 
-**Key points:**
-- The fetch request **must** have at least one sort descriptor.
-- Call `deleteCache(withName:)` before changing the fetch request predicate or
-  sort descriptors, or set `cacheName` to `nil`.
-- The diffable snapshot delegate method (`didChangeContentWith:`) is available
-  iOS 13+ and is preferred over the older per-change callbacks.
-- After a context `reset()`, call `performFetch()` again.
+Without a diffable data source, read `results.sections?.count`,
+`results.sections?[section].numberOfObjects` and `results.object(at:)`.
 
-## Batch Operations
+Rules:
 
-Batch operations execute at the SQL level, bypassing the managed object
-context. They are fast but don't trigger context notifications automatically.
+- The fetch request needs at least one sort descriptor.
+- Before changing the predicate or sort descriptors, call
+  `NSFetchedResultsController.deleteCache(withName:)` or use `cacheName: nil`.
+- The snapshot callback (iOS 13+) is preferred over the per-object change callbacks.
+- After `reset()` on the context, call `performFetch()` again.
 
-### NSBatchInsertRequest (iOS 13+)
+## Batch requests
 
-Docs: [NSBatchInsertRequest](https://sosumi.ai/documentation/coredata/nsbatchinsertrequest)
+Batch requests run directly against SQLite. They skip the context, which makes
+them fast, but they post no context notifications, so **merge their results
+yourself**.
 
 ```swift
-func batchImport(_ records: [[String: Any]]) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        let request = NSBatchInsertRequest(
-            entity: CDTrip.entity(),
-            objects: records
-        )
-        request.resultType = .objectIDs
-        let result = try context.execute(request) as? NSBatchInsertResult
-        if let ids = result?.result as? [NSManagedObjectID] {
-            NSManagedObjectContext.mergeChanges(
-                fromRemoteContextSave: [NSInsertedObjectsKey: ids],
-                into: [CoreDataStack.shared.viewContext]
-            )
-        }
-    }
+@Sendable func publish(_ result: Any?, as key: String) {
+    let ids = result as? [NSManagedObjectID] ?? []
+    let ui = LibraryStore.shared.container.viewContext
+    NSManagedObjectContext.mergeChanges(fromRemoteContextSave: [key: ids], into: [ui])
 }
-```
-
-### NSBatchDeleteRequest (iOS 9+)
 
-Docs: [NSBatchDeleteRequest](https://sosumi.ai/documentation/coredata/nsbatchdeleterequest)
+let worker = LibraryStore.shared.makeWorker()
 
-```swift
-func deleteOldTrips(before cutoff: Date) async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        let fetchRequest: NSFetchRequest<NSFetchRequestResult> = CDTrip.fetchRequest()
-        fetchRequest.predicate = NSPredicate(format: "endDate < %@", cutoff as NSDate)
-        let request = NSBatchDeleteRequest(fetchRequest: fetchRequest)
-        request.resultType = .resultTypeObjectIDs
-        let result = try context.execute(request) as? NSBatchDeleteResult
-        if let ids = result?.result as? [NSManagedObjectID] {
-            NSManagedObjectContext.mergeChanges(
-                fromRemoteContextSave: [NSDeletedObjectsKey: ids],
-                into: [CoreDataStack.shared.viewContext]
-            )
-        }
-    }
+// Insert (iOS 13+)
+try await worker.perform {
+    let insert = NSBatchInsertRequest(entity: Book.entity(), objects: rows.map { ["isbn": $0.isbn, "title": $0.title] })
+    insert.resultType = .objectIDs
+    let inserted = try worker.execute(insert) as? NSBatchInsertResult
+    publish(inserted?.result, as: NSInsertedObjectsKey)
 }
-```
 
-### NSBatchUpdateRequest (iOS 8+)
+// Delete (iOS 9+)
+try await worker.perform {
+    let stale: NSFetchRequest<NSFetchRequestResult> = Loan.fetchRequest()
+    stale.predicate = NSPredicate(format: "returnedAt < %@", cutoff as NSDate)
+    let delete = NSBatchDeleteRequest(fetchRequest: stale)
+    delete.resultType = .resultTypeObjectIDs
+    let removed = try worker.execute(delete) as? NSBatchDeleteResult
+    publish(removed?.result, as: NSDeletedObjectsKey)
+}
 
-```swift
-func markAllTripsAsNotFavorite() async throws {
-    let context = CoreDataStack.shared.newBackgroundContext()
-    try await context.perform {
-        let request = NSBatchUpdateRequest(entity: CDTrip.entity())
-        request.propertiesToUpdate = ["isFavorite": false]
-        request.resultType = .updatedObjectIDsResultType
-        let result = try context.execute(request) as? NSBatchUpdateResult
-        if let ids = result?.result as? [NSManagedObjectID] {
-            NSManagedObjectContext.mergeChanges(
-                fromRemoteContextSave: [NSUpdatedObjectsKey: ids],
-                into: [CoreDataStack.shared.viewContext]
-            )
-        }
-    }
+// Update (iOS 8+)
+try await worker.perform {
+    let update = NSBatchUpdateRequest(entity: Book.entity())
+    update.propertiesToUpdate = ["isArchived": true]
+    update.resultType = .updatedObjectIDsResultType
+    let changed = try worker.execute(update) as? NSBatchUpdateResult
+    publish(changed?.result, as: NSUpdatedObjectsKey)
 }
 ```
 
-**Always merge changes** back into relevant contexts after batch operations.
-Batch delete does not enforce the Deny delete rule.
-
-## Persistent History Tracking
+A batch delete does not honor the **Deny** delete rule and skips validation
+beyond the basic delete rules. Check those constraints yourself first.
 
-Track store-level changes across targets (app, extensions, widgets) and
-processes.
+## Persistent history
 
-Docs: [NSPersistentHistoryChangeRequest](https://sosumi.ai/documentation/coredata/nspersistenthistorychangerequest)
+History tracking records store-level changes so the app, its extensions and
+widgets (separate processes) can see each other's writes, including batch
+requests.
 
-### Enable History Tracking
+### Turn it on
 
 ```swift
-let description = NSPersistentStoreDescription()
-description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
-description.setOption(true as NSNumber,
-    forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
+guard let description = container.persistentStoreDescriptions.first else { return }
+for key in [NSPersistentHistoryTrackingKey, NSPersistentStoreRemoteChangeNotificationPostOptionKey] {
+    description.setOption(NSNumber(value: true), forKey: key)
+}
 container.persistentStoreDescriptions = [description]
 ```
 
-### Observe, Fetch, Merge, and Purge
+### Consume it
+
+1. Observe `.NSPersistentStoreRemoteChange`, with the container's persistent store coordinator as the object.
+2. On a background context, fetch transactions after your last token.
+3. Merge each transaction into `viewContext` and move the token forward.
+4. Purge history older than the token.
 
 ```swift
-// 1. Observe remote change notifications
-NotificationCenter.default.addObserver(
-    self, selector: #selector(storeRemoteChange(_:)),
-    name: .NSPersistentStoreRemoteChange, object: container.persistentStoreCoordinator
-)
-
-// 2. Fetch history since last token
-@objc func storeRemoteChange(_ notification: Notification) {
-    let context = container.newBackgroundContext()
-    context.perform {
-        let request = NSPersistentHistoryChangeRequest.fetchHistory(after: self.lastToken)
-        if let result = try? context.execute(request) as? NSPersistentHistoryResult,
-           let transactions = result.result as? [NSPersistentHistoryTransaction] {
-            // 3. Merge into viewContext
+final class HistoryReader: NSObject, @unchecked Sendable {
+    private let container: NSPersistentContainer
+    private let worker: NSManagedObjectContext
+    private let tokenKey: String            // one per target: "history.app", "history.widget"
+    private var lastToken: NSPersistentHistoryToken?
+
+    init(container: NSPersistentContainer, target: String) {
+        self.container = container
+        self.worker = container.newBackgroundContext()
+        self.tokenKey = "history.\(target)"
+        super.init()
+        lastToken = Self.loadToken(forKey: tokenKey)
+        let center = NotificationCenter.default
+        center.addObserver(self, selector: #selector(storeChanged),
+                           name: .NSPersistentStoreRemoteChange, object: container.persistentStoreCoordinator)
+    }
+
+    @objc private func storeChanged(_ note: Notification) {
+        worker.perform { [self] in
+            let fetch = NSPersistentHistoryChangeRequest.fetchHistory(after: lastToken)
+            let history = try? worker.execute(fetch) as? NSPersistentHistoryResult
+            guard let transactions = history?.result as? [NSPersistentHistoryTransaction] else { return }
+            let ui = container.viewContext
             for transaction in transactions {
-                self.container.viewContext.mergeChanges(fromContextDidSave: transaction.objectIDNotification())
-                self.lastToken = transaction.token
+                let changes = transaction.objectIDNotification().userInfo ?? [:]
+                NSManagedObjectContext.mergeChanges(fromRemoteContextSave: changes, into: [ui])
+                lastToken = transaction.token
+            }
+            Self.saveToken(lastToken, forKey: tokenKey)
+            if let lastToken {
+                _ = try? worker.execute(NSPersistentHistoryChangeRequest.deleteHistory(before: lastToken))
             }
         }
-        // 4. Purge old history
-        let purgeRequest = NSPersistentHistoryChangeRequest.deleteHistory(before: self.lastToken)
-        try? context.execute(purgeRequest)
+    }
+
+    private static var defaults: UserDefaults { UserDefaults(suiteName: "group.app.library") ?? .standard }
+
+    private static func loadToken(forKey key: String) -> NSPersistentHistoryToken? {
+        defaults.data(forKey: key).flatMap {
+            try? NSKeyedUnarchiver.unarchivedObject(ofClass: NSPersistentHistoryToken.self, from: $0)
+        }
+    }
+
+    private static func saveToken(_ token: NSPersistentHistoryToken?, forKey key: String) {
+        guard let token else { return }
+        let encoded = try? NSKeyedArchiver.archivedData(withRootObject: token, requiringSecureCoding: true)
+        defaults.set(encoded, forKey: key)
     }
 }
 ```
 
-Store `lastToken` in `UserDefaults` (per target) so history is processed
-correctly across launches.
+`@unchecked Sendable` rests on one guarantee: after `init` (which sets
+`lastToken` before the observer is registered), `lastToken` is read and written
+only inside `worker.perform`, and one context runs its `perform` blocks one at a
+time on its private queue. Creating a new background context per notification
+would break that, because two notifications could then run on two queues at
+once.
 
-## Staged Migration
+The static merge call is safe from the worker queue; calling
+`viewContext.mergeChanges(fromContextDidSave: transaction.objectIDNotification())`
+inside `viewContext.perform` is the equivalent instance form.
 
-`NSStagedMigrationManager` (iOS 17+) sequences schema migrations through
-ordered stages, each lightweight or custom.
+Keep one token per target (for example in the shared `UserDefaults` suite) so
+each process resumes where it stopped after relaunch. Purge only up to the
+point every reader has consumed.
 
-Docs: [NSStagedMigrationManager](https://sosumi.ai/documentation/coredata/nsstagedmigrationmanager)
+## Staged migration (iOS 17+)
 
-```swift
-import CoreData
+`NSStagedMigrationManager` applies an ordered list of stages, each either
+lightweight or custom.
+
+- `NSLightweightMigrationStage` takes the **version checksums** (`[String]`) of
+  compiled model versions, not their names, and has a `label`.
+- `NSManagedObjectModelReference(name:in:versionChecksum:)` points to one model version.
+- `NSCustomMigrationStage(migratingFrom:to:)` takes a source and a destination
+  reference and offers `label` and `willMigrateHandler` (called with the manager and stage).
 
-// Define migration stages
-// Use version checksums from the compiled model versions, not model names.
-let checksumV1 = "<ModelV1 version checksum>"
-let checksumV2 = "<ModelV2 version checksum>"
-let checksumV3 = "<ModelV3 version checksum>"
-let stage1to2 = NSLightweightMigrationStage([checksumV1, checksumV2])
-stage1to2.label = "Add isFavorite property"
-
-let modelV2 = NSManagedObjectModelReference(
-    name: "ModelV2",
-    in: Bundle.main,
-    versionChecksum: checksumV2
-)
-let modelV3 = NSManagedObjectModelReference(
-    name: "ModelV3",
-    in: Bundle.main,
-    versionChecksum: checksumV3
-)
-let stage2to3 = NSCustomMigrationStage(
-    migratingFrom: modelV2,
-    to: modelV3
-)
-stage2to3.label = "Split name into firstName/lastName"
-stage2to3.willMigrateHandler = { migrationManager, currentStage in
-    guard let container = migrationManager.container else { return }
-    let context = container.newBackgroundContext()
+```swift
+let v1 = NSManagedObjectModelReference(name: "Library_v1", in: .main, versionChecksum: "k3Qp...v1")
+let v2 = NSManagedObjectModelReference(name: "Library_v2", in: .main, versionChecksum: "R8bz...v2")
+let v3Checksum = "Yt5m...v3"
+
+let splitAuthor = NSCustomMigrationStage(migratingFrom: v1, to: v2)
+splitAuthor.label = "Split author into first and last name"
+splitAuthor.willMigrateHandler = { manager, _ in
+    guard let store = manager.container else { return }
+    let context = store.newBackgroundContext()
     try context.performAndWait {
-        // Transform data between schema versions
-        let request = NSFetchRequest<NSManagedObject>(entityName: "Person")
-        let people = try context.fetch(request)
-        for person in people {
-            let fullName = person.value(forKey: "name") as? String ?? ""
-            let parts = fullName.split(separator: " ", maxSplits: 1)
-            person.setValue(String(parts.first ?? ""), forKey: "firstName")
-            person.setValue(parts.count > 1 ? String(parts.last!) : "", forKey: "lastName")
+        let request = NSFetchRequest<NSManagedObject>(entityName: "Book")
+        for book in try context.fetch(request) {
+            let full = book.value(forKey: "author") as? String ?? ""
+            let parts = full.split(separator: " ", maxSplits: 1).map(String.init)
+            book.setValue(parts.first, forKey: "authorFirst")
+            book.setValue(parts.count > 1 ? parts[1] : nil, forKey: "authorLast")
         }
         try context.save()
     }
 }
 
-// Apply to the persistent store
-let manager = NSStagedMigrationManager([stage1to2, stage2to3])
-let description = NSPersistentStoreDescription()
-description.setOption(manager,
-    forKey: NSPersistentStoreStagedMigrationManagerOptionKey)
+let addIndexes = NSLightweightMigrationStage([v3Checksum])
+addIndexes.label = "v2 to v3: add indexes"
+
+let manager = NSStagedMigrationManager([splitAuthor, addIndexes])
+let description = container.persistentStoreDescriptions.first ?? NSPersistentStoreDescription()
+description.setOption(manager, forKey: NSPersistentStoreStagedMigrationManagerOptionKey)
 container.persistentStoreDescriptions = [description]
 container.loadPersistentStores { _, error in
-    if let error { fatalError("Migration failed: \(error)") }
+    if let error { MigrationLog.failed(error) }
 }
 ```
 
-For apps targeting below iOS 17, use lightweight migration
-(`NSInferMappingModelAutomaticallyOption`) or mapping models.
-
-`NSLightweightMigrationStage` takes **version checksums** (`[String]`), not
-human-readable model names.
-
-## Composite Attributes
-
-iOS 17+ supports composite attributes: groups of sub-attributes on an entity
-that act as a single logical unit. Define them in the model editor by adding a
-Composite type attribute and nesting sub-attributes beneath it.
+The option must be on the store description **before** `loadPersistentStores`.
+Read the checksums from the compiled `.momd` (for example
+`NSManagedObjectModel.versionChecksum`), never type a model name in their place.
 
-Docs: [NSCompositeAttributeDescription](https://sosumi.ai/documentation/coredata/nscompositeattributedescription)
+Older deployment targets fall back to inferred mapping
+(`NSInferMappingModelAutomaticallyOption`) or hand-written mapping models.
 
-Composite attributes map to `Codable` structs in SwiftData coexistence
-scenarios.
+## Composite attributes (iOS 17+)
 
-## SwiftData Boundary
+`NSCompositeAttributeDescription` groups several sub-attributes into one
+logical attribute, for example an address made of street, city and postcode.
+Create it in the model editor by choosing the **Composite** type and adding
+nested attributes. When the same store is read by SwiftData, a composite maps
+to a `Codable` struct.
 
-Use the `swiftdata` skill for Core Data + SwiftData coexistence or migration
-implementation. Before handing off, preserve these Core Data boundaries:
+## Where SwiftData starts
 
-- SwiftData must point at the existing persistent store URL when it is meant to
-  share or migrate Core Data data.
-- Shared persisted data must keep entity names, property names, types, and
-  schema compatible across the Core Data model and SwiftData `@Model` classes.
-- Map renamed persisted properties with SwiftData `@Attribute(originalName:)`.
+Coexistence and migration work belongs to `swiftdata`. The rules that matter
+from this side:
 
-## Testing
+- Point SwiftData at the **existing** store URL when it shares or takes over Core Data data.
+- The `@Model` classes must line up with the Core Data model: same entity and
+  property names, matching types, a compatible schema.
+- Map renamed persisted properties with `@Attribute(originalName:)`.
 
-### In-Memory Store for Tests
+## Testing with an in-memory store
 
 ```swift
-import CoreData
 import Testing
+import CoreData
 
-struct CoreDataTests {
-    func makeTestContainer() throws -> NSPersistentContainer {
-        let container = NSPersistentContainer(name: "MyAppModel")
-        let description = NSPersistentStoreDescription()
-        description.type = NSInMemoryStoreType
-        container.persistentStoreDescriptions = [description]
-
-        var loadError: Error?
-        container.loadPersistentStores { _, error in loadError = error }
-        if let loadError { throw loadError }
-        return container
-    }
-
-    @Test func createAndFetchTrip() throws {
-        let container = try makeTestContainer()
-        let context = container.viewContext
-
-        let trip = CDTrip(context: context)
-        trip.name = "Test Trip"
-        trip.startDate = .now
-        try context.save()
+enum TestModel {
+    nonisolated(unsafe) static let shared: NSManagedObjectModel = {   // loaded once, never mutated
+        let compiled = Bundle(for: LibraryStore.self).url(forResource: "Library", withExtension: "momd")
+        return compiled.flatMap(NSManagedObjectModel.init(contentsOf:)) ?? NSManagedObjectModel()
+    }()
+}
 
-        let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()
-        let trips = try context.fetch(request)
-        #expect(trips.count == 1)
-        #expect(trips.first?.name == "Test Trip")
-    }
+func makeMemoryContainer() throws -> NSPersistentContainer {
+    let container = NSPersistentContainer(name: "Library", managedObjectModel: TestModel.shared)
+    let memory = NSPersistentStoreDescription()
+    memory.type = NSInMemoryStoreType
+    container.persistentStoreDescriptions = [memory]
+    var failure: Error?
+    container.loadPersistentStores { _, problem in failure = problem }
+    if let failure { throw failure }
+    return container
 }
-```
 
-**Tips:**
-- Share the `NSManagedObjectModel` instance across tests to avoid "duplicate
-  entity" warnings.
-- Use a single shared model loaded once:
+@Test func savingABookPersistsIt() throws {
+    let context = try makeMemoryContainer().viewContext
+    let book = Book(context: context)
+    book.title = "Dune"
+    try context.save()
 
-```swift
-private let sharedModel: NSManagedObjectModel = {
-    let url = Bundle.main.url(forResource: "MyAppModel", withExtension: "momd")!
-    return NSManagedObjectModel(contentsOf: url)!
-}()
-
-func makeTestContainer() throws -> NSPersistentContainer {
-    let container = NSPersistentContainer(name: "MyAppModel",
-                                          managedObjectModel: sharedModel)
-    // ... configure in-memory store
+    let fetched = try context.fetch(Book.fetchRequest())
+    #expect(fetched.count == 1)
+    #expect(fetched.first?.title == "Dune")
 }
 ```
 
-## Common Mistakes
+Load the model once and pass the same `NSManagedObjectModel` to every test
+container; loading it per test produces "multiple entity descriptions claim"
+duplicate-entity warnings.
+
+## Common mistakes
 
 | Mistake | Fix |
-|---------|-----|
-| Passing `NSManagedObject` across threads | Pass `objectID` and re-fetch in the target context |
-| Forgetting to merge batch operation results | Call `mergeChanges(fromRemoteContextSave:into:)` |
-| Calling `save()` without checking `hasChanges` | Guard with `context.hasChanges` first |
-| Using deprecated `init(concurrencyType:)` confinement type | Use `.privateQueueConcurrencyType` or `.mainQueueConcurrencyType` |
-| Not setting `mergePolicy` on `viewContext` | Set `NSMergeByPropertyObjectTrumpMergePolicy` to avoid conflict crashes |
-| Modifying fetch request on live `NSFetchedResultsController` without deleting cache | Call `deleteCache(withName:)` first or use `cacheName: nil` |
-| Batch delete ignoring Deny delete rule | Batch delete bypasses delete rules; validate manually |
-| Marking `NSManagedObject` as `@unchecked Sendable` | Do not. Pass `objectID` instead |
-| Pointing SwiftData at a fresh store during coexistence | Use the existing store URL and compatible schema when SwiftData should share or migrate Core Data data |
-
-## Review Checklist
-
-- [ ] `NSPersistentContainer` is initialized once and shared
-- [ ] `viewContext` used only on main queue; background contexts for writes
-- [ ] `perform(_:)` or `performAndWait(_:)` wraps all off-queue context access
-- [ ] `automaticallyMergesChangesFromParent` set on `viewContext`
-- [ ] `mergePolicy` set on `viewContext` to prevent conflict crashes
-- [ ] Batch operation results merged into relevant contexts
-- [ ] `NSFetchedResultsController` fetch requests have sort descriptors
-- [ ] Persistent history tracking enabled for multi-target apps
-- [ ] Core Data + SwiftData handoff preserves store URL, schema compatibility, entity/property names, and rename mappings
-- [ ] Tests use in-memory stores with shared `NSManagedObjectModel`
-- [ ] No `NSManagedObject` instances cross thread boundaries
+|---|---|
+| Handing an `NSManagedObject` to another thread | Send `objectID` and fetch again |
+| Batch results never merged | `NSManagedObjectContext.mergeChanges(fromRemoteContextSave:into:)` |
+| `save()` with nothing to save | Check `context.hasChanges` first |
+| The deprecated confinement type passed to `init(concurrencyType:)` | Pick `.privateQueueConcurrencyType` or `.mainQueueConcurrencyType` |
+| No `mergePolicy` on `viewContext` | `NSMergeByPropertyObjectTrumpMergePolicy`, avoiding merge-conflict failures |
+| Editing a live FRC request without clearing its cache | `deleteCache(withName:)` or `cacheName: nil` |
+| Relying on the Deny rule with batch delete | Batch delete ignores it; validate manually |
+| `@unchecked Sendable` on managed objects | Remove it; pass `objectID` |
+| SwiftData opening a fresh, empty file while sharing data with Core Data | Reuse the current store URL and keep the schema compatible |
+
+## Review checklist
+
+- [ ] One `NSPersistentContainer`, created once and shared
+- [ ] `viewContext` used only on the main queue; writes on background contexts
+- [ ] Every off-queue access wrapped in `perform` or `performAndWait`
+- [ ] `automaticallyMergesChangesFromParent` on `viewContext`
+- [ ] `mergePolicy` on `viewContext`
+- [ ] Batch request results merged
+- [ ] FRC fetch requests sorted
+- [ ] Persistent history enabled when several targets share the store
+- [ ] SwiftData hand-off keeps the store URL, schema, entity and property names, and rename mappings
+- [ ] Test containers are in-memory and share a single loaded model
+- [ ] No `NSManagedObject` crosses a thread boundary
 
 ## References
 
-- Apple docs: [Core Data](https://sosumi.ai/documentation/coredata) | [NSPersistentContainer](https://sosumi.ai/documentation/coredata/nspersistentcontainer) | [NSFetchedResultsController](https://sosumi.ai/documentation/coredata/nsfetchedresultscontroller) | [NSStagedMigrationManager](https://sosumi.ai/documentation/coredata/nsstagedmigrationmanager)
+- [Core Data](https://developer.apple.com/documentation/coredata)
+- [NSPersistentContainer](https://developer.apple.com/documentation/coredata/nspersistentcontainer)
+- [NSManagedObjectContext](https://developer.apple.com/documentation/coredata/nsmanagedobjectcontext)
+- [NSFetchedResultsController](https://developer.apple.com/documentation/coredata/nsfetchedresultscontroller)
+- [NSBatchInsertRequest](https://developer.apple.com/documentation/coredata/nsbatchinsertrequest)
+- [NSBatchDeleteRequest](https://developer.apple.com/documentation/coredata/nsbatchdeleterequest)
+- [NSPersistentHistoryChangeRequest](https://developer.apple.com/documentation/coredata/nspersistenthistorychangerequest)
+- [NSStagedMigrationManager](https://developer.apple.com/documentation/coredata/nsstagedmigrationmanager)
+- [NSCompositeAttributeDescription](https://developer.apple.com/documentation/coredata/nscompositeattributedescription)