Core Data Expert

1---2name: core-data-expert3description: 'Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.'4---5# Core Data Expert6 7Fast, production-oriented guidance for building **correct**, **performant** Core Data stacks and fixing common crashes.8 9## Agent behavior contract (follow these rules)10 111. Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).122. Identify the context type before proposing fixes: **view context (UI)** vs **background context (heavy work)**.133. Recommend `NSManagedObjectID` for cross-context/cross-task communication; **never pass `NSManagedObject` instances** across contexts.144. Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.155. When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).166. For CloudKit integration, remind developers that **Production schema is immutable**.177. Reference WWDC/external resources sparingly; prefer this skill’s `references/`.18 19## First 60 seconds (triage template)20 21- **Clarify the goal**: setup, bugfix, migration, performance, CloudKit?22- **Collect minimal facts**:23  - platform + deployment target24  - store type (SQLite / in-memory) and whether CloudKit is enabled25  - context involved (view vs background) and whether Swift Concurrency is in use26  - exact error message + stack trace/logs27- **Branch immediately**:28  - threading/crash → focus on context confinement + `NSManagedObjectID` handoff29  - migration error → identify model versions + migration strategy30  - batch ops not updating UI → persistent history tracking + merge pipeline31 32## Routing map (pick the right reference fast)33 34- **Stack setup / merge policies / contexts** → `references/stack-setup.md`35- **Saving patterns** → `references/saving.md`36- **Fetch requests / list updates / aggregates** → `references/fetch-requests.md`37- **Traditional threading (perform/performAndWait, object IDs)** → `references/threading.md`38- **Swift Concurrency (async/await, actors, Sendable, DAOs)** → `references/concurrency.md`39- **Batch insert/delete/update** → `references/batch-operations.md`40- **Persistent history tracking + “batch ops not updating UI”** → `references/persistent-history.md`41- **Model configuration (constraints, validation, derived/composite, transformables)** → `references/model-configuration.md`42- **Schema migration (lightweight/staged/deferred)** → `references/migration.md`43- **CloudKit integration & debugging** → `references/cloudkit-integration.md`44- **Performance profiling & memory** → `references/performance.md`45- **Testing patterns** → `references/testing.md`46- **Terminology** → `references/glossary.md`47 48## Common errors → next best move49 50- **“Failed to find a unique match for an NSEntityDescription”** → `references/testing.md` (shared `NSManagedObjectModel`)51- **`NSPersistentStoreIncompatibleVersionHashError`** → `references/migration.md` (versioning + migration)52- **Cross-context/threading exceptions** (e.g. delete/update from wrong context) → `references/threading.md` and/or `references/concurrency.md` (use `NSManagedObjectID`)53- **Sendable / actor-isolation warnings around Core Data** → `references/concurrency.md` (don’t “paper over” with `@unchecked Sendable`)54- **`NSMergeConflict` / constraint violations** → `references/model-configuration.md` + `references/stack-setup.md` (constraints + merge policy)55- **Batch operations not updating UI** → `references/persistent-history.md` + `references/batch-operations.md`56- **CloudKit schema/sync issues** → `references/cloudkit-integration.md`57- **Memory grows during fetch** → `references/performance.md` + `references/fetch-requests.md`58 59## Verification checklist (when changing Core Data code)60 61- Confirm the context matches the work (UI vs background).62- Ensure `NSManagedObject` instances never cross contexts; pass `NSManagedObjectID` instead.63- If using batch ops, confirm persistent history tracking + merge pipeline.64- If using constraints, confirm merge policy and conflict resolution strategy.65- If performance-related, profile with Instruments and validate fetch batching/limits.66 67## Reference files68 69- `references/_index.md` (navigation)70- `references/stack-setup.md`71- `references/saving.md`72- `references/fetch-requests.md`73- `references/threading.md`74- `references/concurrency.md`75- `references/batch-operations.md`76- `references/persistent-history.md`77- `references/model-configuration.md`78- `references/migration.md`79- `references/cloudkit-integration.md`80- `references/performance.md`81- `references/testing.md`82- `references/glossary.md`