@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/core-data-expert/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: core-data-expert
+description: "Use when writing, debugging, or optimizing Core Data code on iOS/macOS — fetch requests, migrations, merge conflicts, threading, CloudKit sync. MUST load before any Core Data schema changes or performance work."
+version: 1.0.0
+tags: [apple, integration]
+dependencies: []
+---
+
+# Core Data Expert
+
+## When to Use
+
+- When working with Core Data stack setup, threading/concurrency, migrations, or performance issues.
+
+## When NOT to Use
+
+- When the app does not use Core Data (e.g., alternative persistence layers).
+
+
+## Agent behavior contract (follow these rules)
+
+1. Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
+2. Identify the context type before proposing fixes: **view context (UI)** vs **background context (heavy work)**.
+3. Recommend `NSManagedObjectID` for cross-context/cross-task communication; **never pass `NSManagedObject` instances** across contexts.
+4. Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
+5. When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
+6. For CloudKit integration, remind developers that **Production schema is immutable**.
+7. Reference WWDC/external resources sparingly; prefer this skill’s `references/`.
+
+## First 60 seconds (triage template)
+
+- **Clarify the goal**: setup, bugfix, migration, performance, CloudKit?
+- **Collect minimal facts**:
+  - platform + deployment target
+  - store type (SQLite / in-memory) and whether CloudKit is enabled
+  - context involved (view vs background) and whether Swift Concurrency is in use
+  - exact error message + stack trace/logs
+- **Branch immediately**:
+  - threading/crash → focus on context confinement + `NSManagedObjectID` handoff
+  - migration error → identify model versions + migration strategy
+  - batch ops not updating UI → persistent history tracking + merge pipeline
+
+## Routing map (pick the right reference fast)
+
+- **Stack setup / merge policies / contexts** → `references/stack-setup.md`
+- **Saving patterns** → `references/saving.md`
+- **Fetch requests / list updates / aggregates** → `references/fetch-requests.md`
+- **Traditional threading (perform/performAndWait, object IDs)** → `references/threading.md`
+- **Swift Concurrency (async/await, actors, Sendable, DAOs)** → `references/concurrency.md`
+- **Batch insert/delete/update** → `references/batch-operations.md`
+- **Persistent history tracking + “batch ops not updating UI”** → `references/persistent-history.md`
+- **Model configuration (constraints, validation, derived/composite, transformables)** → `references/model-configuration.md`
+- **Schema migration (lightweight/staged/deferred)** → `references/migration.md`
+- **CloudKit integration & debugging** → `references/cloudkit-integration.md`
+- **Performance profiling & memory** → `references/performance.md`
+- **Testing patterns** → `references/testing.md`
+- **Terminology** → `references/glossary.md`
+
+## Common errors → next best move
+
+- **“Failed to find a unique match for an NSEntityDescription”** → `references/testing.md` (shared `NSManagedObjectModel`)
+- **`NSPersistentStoreIncompatibleVersionHashError`** → `references/migration.md` (versioning + migration)
+- **Cross-context/threading exceptions** (e.g. delete/update from wrong context) → `references/threading.md` and/or `references/concurrency.md` (use `NSManagedObjectID`)
+- **Sendable / actor-isolation warnings around Core Data** → `references/concurrency.md` (don’t “paper over” with `@unchecked Sendable`)
+- **`NSMergeConflict` / constraint violations** → `references/model-configuration.md` + `references/stack-setup.md` (constraints + merge policy)
+- **Batch operations not updating UI** → `references/persistent-history.md` + `references/batch-operations.md`
+- **CloudKit schema/sync issues** → `references/cloudkit-integration.md`
+- **Memory grows during fetch** → `references/performance.md` + `references/fetch-requests.md`
+
+## Verification checklist (when changing Core Data code)
+
+- Confirm the context matches the work (UI vs background).
+- Ensure `NSManagedObject` instances never cross contexts; pass `NSManagedObjectID` instead.
+- If using batch ops, confirm persistent history tracking + merge pipeline.
+- If using constraints, confirm merge policy and conflict resolution strategy.
+- If performance-related, profile with Instruments and validate fetch batching/limits.
+
+## Reference files
+
+- `references/_index.md` (navigation)
+- `references/stack-setup.md`
+- `references/saving.md`
+- `references/fetch-requests.md`
+- `references/threading.md`
+- `references/concurrency.md`
+- `references/batch-operations.md`
+- `references/persistent-history.md`
+- `references/model-configuration.md`
+- `references/migration.md`
+- `references/cloudkit-integration.md`
+- `references/performance.md`
+- `references/testing.md`
+- `references/glossary.md`

package/dist/template/.opencode/skill/core-data-expert/references/batch-operations.md

@@ -0,0 +1,543 @@
+# Batch Operations
+
+Batch operations provide significant performance improvements for large-scale data modifications. They operate directly at the SQL level, bypassing the object graph.
+
+## Overview
+
+Core Data provides three batch operation types:
+- **NSBatchInsertRequest** - Bulk inserts (iOS 14+)
+- **NSBatchDeleteRequest** - Bulk deletes
+- **NSBatchUpdateRequest** - Bulk updates
+
+**Key Characteristics:**
+- Operate at SQL level (very fast)
+- Don't load objects into memory
+- Don't trigger validation
+- Don't send change notifications (requires persistent history tracking)
+- Can't set relationships during batch insert
+
+## NSBatchInsertRequest (iOS 14+)
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { (object: NSManagedObject) -> Bool in
+        guard let article = object as? Article else { return true }
+        
+        article.name = "Sample Article"
+        article.content = "Content here"
+        article.creationDate = Date()
+        
+        return false // Continue inserting
+    }
+    
+    do {
+        try context.execute(batchInsert)
+    } catch {
+        print("Batch insert failed: \(error)")
+    }
+}
+```
+
+### Inserting Multiple Objects
+
+```swift
+func batchInsertArticles(_ data: [ArticleData]) {
+    let context = container.newBackgroundContext()
+    
+    context.perform {
+        var index = 0
+        let batchInsert = NSBatchInsertRequest(
+            entity: Article.entity()
+        ) { (object: NSManagedObject) -> Bool in
+            guard index < data.count else { return true } // Stop
+            guard let article = object as? Article else { return true }
+            
+            let articleData = data[index]
+            article.name = articleData.name
+            article.content = articleData.content
+            article.creationDate = Date()
+            
+            index += 1
+            return false // Continue
+        }
+        
+        do {
+            try context.execute(batchInsert)
+        } catch {
+            print("Batch insert failed: \(error)")
+        }
+    }
+}
+```
+
+### Using Dictionary Representation (Alternative)
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let objects: [[String: Any]] = [
+        ["name": "Article 1", "content": "Content 1", "creationDate": Date()],
+        ["name": "Article 2", "content": "Content 2", "creationDate": Date()],
+        ["name": "Article 3", "content": "Content 3", "creationDate": Date()]
+    ]
+    
+    let batchInsert = NSBatchInsertRequest(
+        entity: Article.entity(),
+        objects: objects
+    )
+    
+    do {
+        try context.execute(batchInsert)
+    } catch {
+        print("Batch insert failed: \(error)")
+    }
+}
+```
+
+### Limitations
+
+**Cannot set relationships:**
+```swift
+// ❌ This won't work
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.category = someCategory // Can't set relationships!
+    return false
+}
+```
+
+**Workaround:** Set relationships after batch insert:
+```swift
+// 1. Batch insert articles
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.name = "Article"
+    return false
+}
+try context.execute(batchInsert)
+
+// 2. Fetch and set relationships
+let fetchRequest = Article.fetchRequest()
+let articles = try context.fetch(fetchRequest)
+for article in articles {
+    article.category = defaultCategory
+}
+try context.save()
+```
+
+## NSBatchDeleteRequest
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+    let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+    
+    do {
+        try context.execute(batchDelete)
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+### With Predicate
+
+```swift
+let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+fetchRequest.predicate = NSPredicate(format: "views < %d", 10)
+
+let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+
+context.perform {
+    do {
+        try context.execute(batchDelete)
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+### Getting Deleted Object IDs
+
+```swift
+let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+batchDelete.resultType = .resultTypeObjectIDs
+
+context.perform {
+    do {
+        let result = try context.execute(batchDelete) as? NSBatchDeleteResult
+        if let objectIDs = result?.result as? [NSManagedObjectID] {
+            print("Deleted \(objectIDs.count) objects")
+        }
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+## NSBatchUpdateRequest
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+    batchUpdate.predicate = NSPredicate(format: "isRead == NO")
+    batchUpdate.propertiesToUpdate = ["isRead": true]
+    
+    do {
+        try context.execute(batchUpdate)
+    } catch {
+        print("Batch update failed: \(error)")
+    }
+}
+```
+
+### Updating Multiple Properties
+
+```swift
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.predicate = NSPredicate(format: "views < %d", 100)
+batchUpdate.propertiesToUpdate = [
+    "views": 100,
+    "lastModified": Date(),
+    "isPopular": true
+]
+
+context.perform {
+    try? context.execute(batchUpdate)
+}
+```
+
+### Using Expressions
+
+```swift
+// Increment views by 1
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.propertiesToUpdate = [
+    "views": NSExpression(format: "views + 1")
+]
+
+context.perform {
+    try? context.execute(batchUpdate)
+}
+```
+
+### Getting Updated Object IDs
+
+```swift
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.propertiesToUpdate = ["isRead": true]
+batchUpdate.resultType = .updatedObjectIDsResultType
+
+context.perform {
+    do {
+        let result = try context.execute(batchUpdate) as? NSBatchUpdateResult
+        if let objectIDs = result?.result as? [NSManagedObjectID] {
+            print("Updated \(objectIDs.count) objects")
+        }
+    } catch {
+        print("Batch update failed: \(error)")
+    }
+}
+```
+
+## Persistent History Tracking Integration
+
+**Critical:** Batch operations don't send change notifications. You **must** enable persistent history tracking for UI updates.
+
+### Enable Persistent History Tracking
+
+```swift
+guard let description = container.persistentStoreDescriptions.first else { return }
+
+description.setOption(true as NSNumber, 
+                     forKey: NSPersistentHistoryTrackingKey)
+description.setOption(true as NSNumber,
+                     forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
+```
+
+### Observe Remote Changes
+
+```swift
+NotificationCenter.default.addObserver(
+    self,
+    selector: #selector(storeRemoteChange),
+    name: .NSPersistentStoreRemoteChange,
+    object: container.persistentStoreCoordinator
+)
+
+@objc func storeRemoteChange(_ notification: Notification) {
+    // Merge changes into view context
+    // See persistent-history.md for full implementation
+}
+```
+
+## Performance Comparison
+
+### Traditional Insert (Slow)
+
+```swift
+// Inserting 1000 objects: ~10 seconds
+for i in 0..<1000 {
+    let article = Article(context: context)
+    article.name = "Article \(i)"
+}
+try context.save()
+```
+
+### Batch Insert (Fast)
+
+```swift
+// Inserting 1000 objects: ~0.5 seconds
+var index = 0
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard index < 1000 else { return true }
+    guard let article = object as? Article else { return true }
+    article.name = "Article \(index)"
+    index += 1
+    return false
+}
+try context.execute(batchInsert)
+```
+
+**Performance gain: ~20x faster**
+
+## When to Use Batch Operations
+
+### Use Batch Insert When:
+- Importing large datasets (>100 objects)
+- Initial data seeding
+- Syncing data from server
+- Performance is critical
+
+### Use Batch Delete When:
+- Deleting many objects at once
+- Clearing old data
+- Implementing data retention policies
+- Performance is critical
+
+### Use Batch Update When:
+- Updating many objects with same values
+- Bulk status changes
+- Incrementing counters
+- Performance is critical
+
+### Don't Use Batch Operations When:
+- Need to set relationships
+- Need validation
+- Need to trigger lifecycle events (willSave, etc.)
+- Working with small datasets (<50 objects)
+- Need immediate UI updates without persistent history tracking
+
+## Complete Example: Import with Batch Insert
+
+```swift
+class DataImporter {
+    let container: NSPersistentContainer
+    
+    init(container: NSPersistentContainer) {
+        self.container = container
+    }
+    
+    func importArticles(_ data: [ArticleData]) {
+        let context = container.newBackgroundContext()
+        
+        context.perform {
+            var index = 0
+            let batchInsert = NSBatchInsertRequest(
+                entity: Article.entity()
+            ) { (object: NSManagedObject) -> Bool in
+                guard index < data.count else { return true }
+                guard let article = object as? Article else { return true }
+                
+                let articleData = data[index]
+                article.name = articleData.name
+                article.content = articleData.content
+                article.views = 0
+                article.creationDate = Date()
+                
+                index += 1
+                return false
+            }
+            
+            do {
+                let result = try context.execute(batchInsert) as? NSBatchInsertResult
+                print("Inserted \(data.count) articles")
+                
+                // If you need the object IDs
+                if let objectIDs = result?.result as? [NSManagedObjectID] {
+                    print("Object IDs: \(objectIDs)")
+                }
+            } catch {
+                print("Batch insert failed: \(error)")
+            }
+        }
+    }
+}
+```
+
+## Complete Example: Cleanup with Batch Delete
+
+```swift
+class DataCleaner {
+    let container: NSPersistentContainer
+    
+    init(container: NSPersistentContainer) {
+        self.container = container
+    }
+    
+    func deleteOldArticles(olderThan days: Int) {
+        let context = container.newBackgroundContext()
+        
+        context.perform {
+            let cutoffDate = Calendar.current.date(
+                byAdding: .day,
+                value: -days,
+                to: Date()
+            )!
+            
+            let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+            fetchRequest.predicate = NSPredicate(
+                format: "creationDate < %@",
+                cutoffDate as NSDate
+            )
+            
+            let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+            batchDelete.resultType = .resultTypeCount
+            
+            do {
+                let result = try context.execute(batchDelete) as? NSBatchDeleteResult
+                if let count = result?.result as? Int {
+                    print("Deleted \(count) old articles")
+                }
+            } catch {
+                print("Batch delete failed: \(error)")
+            }
+        }
+    }
+}
+```
+
+## Common Pitfalls
+
+### ❌ Not Enabling Persistent History Tracking
+
+```swift
+// Batch insert happens
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { ... }
+try context.execute(batchInsert)
+
+// UI doesn't update! No notifications sent
+```
+
+### ❌ Trying to Set Relationships
+
+```swift
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.category = category // Won't work!
+    return false
+}
+```
+
+### ❌ Expecting Validation
+
+```swift
+// No validation happens!
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.name = "" // Empty name - no validation error
+    return false
+}
+```
+
+### ❌ Using on View Context
+
+```swift
+// Don't use batch operations on view context
+viewContext.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { ... }
+    try? viewContext.execute(batchInsert) // Blocks UI!
+}
+```
+
+### ✅ Correct Approach
+
+```swift
+// 1. Enable persistent history tracking
+description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
+
+// 2. Use background context
+let context = container.newBackgroundContext()
+
+// 3. Execute batch operation
+context.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+        guard let article = object as? Article else { return true }
+        article.name = "Valid Name"
+        return false
+    }
+    try? context.execute(batchInsert)
+}
+
+// 4. UI updates via persistent history tracking
+```
+
+## Testing Batch Operations
+
+```swift
+func testBatchInsert() throws {
+    let context = container.newBackgroundContext()
+    
+    let expectation = XCTestExpectation(description: "Batch insert")
+    
+    context.perform {
+        var count = 0
+        let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+            guard count < 10 else { return true }
+            guard let article = object as? Article else { return true }
+            article.name = "Article \(count)"
+            count += 1
+            return false
+        }
+        
+        do {
+            try context.execute(batchInsert)
+            expectation.fulfill()
+        } catch {
+            XCTFail("Batch insert failed: \(error)")
+        }
+    }
+    
+    wait(for: [expectation], timeout: 5.0)
+    
+    // Verify
+    let fetchRequest = Article.fetchRequest()
+    let articles = try context.fetch(fetchRequest)
+    XCTAssertEqual(articles.count, 10)
+}
+```
+
+## Summary
+
+1. **Use batch operations for large datasets** - 10-20x performance improvement
+2. **Enable persistent history tracking** - Required for UI updates
+3. **Use background contexts** - Don't block UI
+4. **Can't set relationships in batch insert** - Set them separately if needed
+5. **No validation or lifecycle events** - Batch operations bypass object graph
+6. **Get result types** - Use resultType to get object IDs or counts
+7. **Test thoroughly** - Verify data integrity after batch operations
+8. **Consider trade-offs** - Speed vs validation/relationships/lifecycle events