codexkit 1.0.0

package/.codex/skills/core-data-expert/references/glossary.md

@@ -0,0 +1,233 @@
+# Core Data Glossary
+
+Quick reference for Core Data terminology.
+
+## Core Concepts
+
+**Core Data**
+Apple's framework for object graph management and persistence.
+
+**Persistent Store**
+The underlying storage (typically SQLite database) where data is saved.
+
+**Managed Object Model**
+Describes your data schema (entities, attributes, relationships).
+
+**Entity**
+A class definition in your data model (like a database table).
+
+**Attribute**
+A property of an entity (like a database column).
+
+**Relationship**
+A connection between entities (one-to-one, one-to-many, many-to-many).
+
+## Stack Components
+
+**NSPersistentContainer**
+Encapsulates the Core Data stack (model, coordinator, contexts).
+
+**NSPersistentCloudKitContainer**
+Extends NSPersistentContainer with CloudKit sync capabilities.
+
+**NSPersistentStoreCoordinator**
+Manages one or more persistent stores and coordinates access.
+
+**NSManagedObjectContext**
+Scratch pad for working with managed objects. Changes aren't persisted until saved.
+
+**NSManagedObject**
+Base class for Core Data objects. Represents a row in a database table.
+
+**NSManagedObjectID**
+Unique, immutable identifier for a managed object. Thread-safe.
+
+## Context Types
+
+**View Context**
+Main queue context for UI operations. Runs on main thread.
+
+**Background Context**
+Private queue context for heavy work. Runs on background thread.
+
+**Child Context**
+Context with a parent context. Saves push changes to parent, not to disk.
+
+## Fetching
+
+**NSFetchRequest**
+Describes a search for objects in the persistent store.
+
+**NSFetchedResultsController**
+Manages fetch results for table/collection views with automatic updates.
+
+**Predicate**
+Filter condition for fetch requests (like SQL WHERE clause).
+
+**Sort Descriptor**
+Defines ordering for fetch results (like SQL ORDER BY).
+
+**Faulting**
+Lazy loading mechanism. Object data loaded only when accessed.
+
+**Prefetching**
+Loading related objects eagerly to avoid faulting.
+
+## Operations
+
+**Save**
+Persists changes from context to persistent store.
+
+**Fetch**
+Retrieves objects from persistent store.
+
+**Insert**
+Creates new object in context.
+
+**Delete**
+Marks object for deletion. Removed on save.
+
+**Refresh**
+Reloads object from persistent store, discarding in-memory changes.
+
+**Reset**
+Clears all objects from context, freeing memory.
+
+**Rollback**
+Discards all unsaved changes in context.
+
+## Batch Operations
+
+**NSBatchInsertRequest**
+Inserts multiple objects at SQL level (iOS 14+).
+
+**NSBatchDeleteRequest**
+Deletes multiple objects at SQL level.
+
+**NSBatchUpdateRequest**
+Updates multiple objects at SQL level.
+
+## Advanced Features
+
+**Persistent History Tracking**
+Records all changes in a transaction log for cross-context synchronization.
+
+**Derived Attribute**
+Computed attribute stored in database (e.g., `articles.@count`).
+
+**Transformable**
+Custom type stored using value transformer.
+
+**Constraint**
+Ensures attribute uniqueness (requires merge policy).
+
+**Merge Policy**
+Determines how conflicts are resolved when saving.
+
+## Migration
+
+**Lightweight Migration**
+Automatic migration for simple model changes.
+
+**Staged Migration**
+Complex migration decomposed into steps (iOS 17+).
+
+**Deferred Migration**
+Delays cleanup work for better performance (iOS 14+).
+
+**Composite Attribute**
+Structured data within single attribute (iOS 17+).
+
+**Mapping Model**
+Describes how to migrate from one model version to another.
+
+**Version Hash**
+Checksum identifying a specific model version.
+
+## Threading
+
+**perform**
+Executes block asynchronously on context's queue.
+
+**performAndWait**
+Executes block synchronously on context's queue (blocks calling thread).
+
+**Thread Confinement**
+Each context must be accessed only from its queue.
+
+**automaticallyMergesChangesFromParent**
+Context automatically receives changes from parent context.
+
+## Validation
+
+**validateForInsert**
+Called before inserting object.
+
+**validateForUpdate**
+Called before updating object.
+
+**validateForDelete**
+Called before deleting object.
+
+## Lifecycle
+
+**awakeFromInsert**
+Called once when object first inserted.
+
+**awakeFromFetch**
+Called when object loaded from store.
+
+**willSave**
+Called before each save.
+
+**didSave**
+Called after save completes.
+
+**prepareForDeletion**
+Called when object marked for deletion.
+
+## CloudKit
+
+**Container Identifier**
+Unique ID for CloudKit container (e.g., `iCloud.com.example.app`).
+
+**Development Environment**
+CloudKit environment for testing (schema mutable).
+
+**Production Environment**
+CloudKit environment for released apps (schema immutable).
+
+**Schema Initialization**
+First run creates CloudKit schema from Core Data model.
+
+**Event Notification**
+Notification sent when CloudKit sync events occur.
+
+## Debugging
+
+**SQL Debug**
+Launch argument to log SQL queries: `-com.apple.CoreData.SQLDebug 1`
+
+**Concurrency Debug**
+Launch argument to catch threading violations: `-com.apple.CoreData.ConcurrencyDebug 1`
+
+**Migration Debug**
+Launch argument to log migration steps: `-com.apple.CoreData.MigrationDebug 1`
+
+## Common Acronyms
+
+**CD** - Core Data
+**MOC** - Managed Object Context (NSManagedObjectContext)
+**MO** - Managed Object (NSManagedObject)
+**FRC** - Fetched Results Controller (NSFetchedResultsController)
+**PSC** - Persistent Store Coordinator (NSPersistentStoreCoordinator)
+**MOD** - Managed Object Model (NSManagedObjectModel)
+
+## Quick Reference
+
+**Thread-safe:** NSManagedObjectID, NSPersistentStoreCoordinator
+**Not thread-safe:** NSManagedObject, NSManagedObjectContext
+**Main thread only:** View context operations
+**Background thread:** Background context operations
+**Automatic:** Lightweight migration (with NSPersistentContainer)
+**Manual:** Staged migration, custom mapping models

package/.codex/skills/core-data-expert/references/migration.md

@@ -0,0 +1,393 @@
+# Schema Migration
+
+Schema migration is the process of updating your Core Data model as your app evolves. Core Data provides three migration strategies: lightweight, staged (iOS 17+), and deferred (iOS 14+).
+
+## When Migration is Required
+
+Core Data refuses to open a store when the model doesn't match:
+
+```
+Error: NSPersistentStoreIncompatibleVersionHashError
+```
+
+**This means:** Your data model changed, and you need to migrate.
+
+## Lightweight Migration (Recommended)
+
+Lightweight migration is automatic and handles most common changes.
+
+### Enabling Lightweight Migration
+
+With `NSPersistentContainer` (automatic):
+```swift
+let container = NSPersistentContainer(name: "Model")
+// Lightweight migration enabled by default
+```
+
+With `NSPersistentStoreDescription` (automatic):
+```swift
+let description = NSPersistentStoreDescription(url: storeURL)
+// Lightweight migration enabled by default
+```
+
+Manual setup (if needed):
+```swift
+let options = [
+    NSMigratePersistentStoresAutomaticallyOption: true,
+    NSInferMappingModelAutomaticallyOption: true
+]
+try coordinator.addPersistentStore(
+    ofType: NSSQLiteStoreType,
+    configurationName: nil,
+    at: storeURL,
+    options: options
+)
+```
+
+### Supported Operations
+
+**Attributes:**
+- Add attribute
+- Remove attribute
+- Make optional attribute non-optional (with default value)
+- Make non-optional attribute optional
+- Rename attribute (using renaming identifier)
+
+**Relationships:**
+- Add relationship
+- Remove relationship
+- Rename relationship (using renaming identifier)
+- Change cardinality (to-one ↔ to-many)
+- Change ordering (ordered ↔ non-ordered)
+
+**Entities:**
+- Add entity
+- Remove entity
+- Rename entity (using renaming identifier)
+- Create parent/child entity
+- Move attributes up/down hierarchy
+- Move entities in/out of hierarchy
+
+**Cannot do:**
+- Merge entity hierarchies (entities without common parent can't share parent)
+
+### Renaming Attributes/Entities
+
+Set the renaming identifier to the **old name**:
+
+```swift
+// In Data Model Editor:
+// 1. Rename attribute from "color" to "paintColor"
+// 2. Set Renaming Identifier to "color"
+```
+
+This allows chaining renames across versions:
+- V1: `color`
+- V2: `paintColor` (renaming ID: `color`)
+- V3: `primaryColor` (renaming ID: `paintColor`)
+
+Migration works: V1→V2, V2→V3, and V1→V3.
+
+### Testing Lightweight Migration
+
+```swift
+// Check if migration is possible
+let sourceModel = // ... load V1 model
+let destinationModel = // ... load V2 model
+
+if let mappingModel = try? NSMappingModel.inferredMappingModel(
+    forSourceModel: sourceModel,
+    destinationModel: destinationModel
+) {
+    print("Lightweight migration possible")
+} else {
+    print("Lightweight migration not possible")
+}
+```
+
+## Composite Attributes (iOS 17+)
+
+New in iOS 17: Structured data within a single attribute.
+
+### Creating Composite Attributes
+
+In Data Model Editor:
+1. Add Composite Attribute
+2. Add elements (String, Int, Date, etc.)
+3. Can nest composite attributes
+
+```swift
+// Example: ColorScheme composite
+// - primary: String
+// - secondary: String
+// - tertiary: String
+
+class Aircraft: NSManagedObject {
+    @NSManaged var colorScheme: [String: Any]
+}
+
+// Usage
+aircraft.colorScheme = [
+    "primary": "Red",
+    "secondary": "White",
+    "tertiary": "Blue"
+]
+
+// Querying
+fetchRequest.predicate = NSPredicate(format: "colorScheme.primary == %@", "Red")
+```
+
+### Benefits
+
+- No transformable code needed
+- Supports predicates with keypaths
+- Better than flattened attributes
+- Can prevent faulting across relationships
+
+## Staged Migration (iOS 17+)
+
+For complex migrations that exceed lightweight capabilities.
+
+### When to Use
+
+- Changes don't fit lightweight patterns
+- Need to run custom code during migration
+- Need to decompose complex changes into steps
+
+### Key Classes
+
+- `NSStagedMigrationManager` - Manages migration event loop
+- `NSCustomMigrationStage` - Custom code execution
+- `NSLightweightMigrationStage` - Lightweight-eligible changes
+- `NSManagedObjectModelReference` - Model references with checksums
+
+### Example: Denormalizing Data
+
+**Problem:** Move `flightData` attribute to separate entity.
+
+**Solution:** Decompose into stages:
+
+**Stage 1 (Lightweight):** Add new entity and relationship
+```swift
+// ModelV1 → ModelV2
+// Add FlightData entity
+// Add flightParameters relationship to Aircraft
+```
+
+**Stage 2 (Custom):** Copy data
+- Fetch rows using generic `NSManagedObject` / `NSFetchRequestResult` types.
+- Create new entities and copy data inside the migration stage handler.
+- Ensure the custom logic is restartable if the process is interrupted.
+
+**Stage 3 (Lightweight):** Remove old attribute
+```swift
+// ModelV3 → ModelV4
+// Remove flightData attribute from Aircraft
+```
+
+### Getting Version Checksum
+
+From Xcode build log:
+```
+Compile data model Model.xcdatamodeld
+version checksum: ABC123...
+```
+
+## Deferred Migration (iOS 14+)
+
+Defer cleanup work to keep app responsive.
+
+### When to Use
+
+- Removing attributes/relationships
+- Changing relationship hierarchy
+- Changing relationship ordering
+- Any migration with expensive cleanup
+
+### How It Works
+
+1. Migration runs synchronously (fast)
+2. Cleanup (indices, column drops) is deferred
+3. App uses latest schema immediately
+4. Finish cleanup when resources available
+
+### Enabling Deferred Migration
+
+```swift
+let description = NSPersistentStoreDescription(url: storeURL)
+description.setOption(
+    true as NSNumber,
+    forKey: NSPersistentStoreDeferredLightweightMigrationOptionKey
+)
+```
+
+### Checking for Pending Work
+
+```swift
+let metadata = try NSPersistentStoreCoordinator.metadataForPersistentStore(
+    ofType: NSSQLiteStoreType,
+    at: storeURL
+)
+
+if let hasDeferredWork = metadata[NSPersistentStoreDeferredLightweightMigrationOptionKey] as? Bool,
+   hasDeferredWork {
+    print("Deferred migration work pending")
+}
+```
+
+### Finishing Deferred Migration
+
+```swift
+func finishDeferredMigration() {
+    let coordinator = container.persistentStoreCoordinator
+    
+    do {
+        try coordinator.finishDeferredLightweightMigration()
+        print("Deferred migration completed")
+    } catch {
+        print("Failed to finish deferred migration: \(error)")
+    }
+}
+```
+
+### Scheduling with Background Tasks
+
+```swift
+import BackgroundTasks
+
+// Register task
+BGTaskScheduler.shared.register(
+    forTaskWithIdentifier: "com.example.app.migration",
+    using: nil
+) { task in
+    self.handleMigrationTask(task as! BGProcessingTask)
+}
+
+// Schedule task
+func scheduleMigration() {
+    let request = BGProcessingTaskRequest(identifier: "com.example.app.migration")
+    request.requiresNetworkConnectivity = false
+    request.requiresExternalPower = false
+    
+    try? BGTaskScheduler.shared.submit(request)
+}
+
+// Handle task
+func handleMigrationTask(_ task: BGProcessingTask) {
+    task.expirationHandler = {
+        task.setTaskCompleted(success: false)
+    }
+    
+    finishDeferredMigration()
+    task.setTaskCompleted(success: true)
+}
+```
+
+## Migration Debugging
+
+### Enable Migration Debug
+
+```
+-com.apple.CoreData.MigrationDebug 1
+```
+
+**Output:**
+```
+CoreData: annotation: Migration: Migrating from version 1 to version 2
+CoreData: annotation: Migration: Inferred mapping model
+CoreData: annotation: Migration: Completed successfully
+```
+
+### Common Errors
+
+**NSPersistentStoreIncompatibleVersionHashError**
+- Model changed, migration required
+- Enable lightweight migration or create mapping model
+
+**NSMigrationMissingSourceModelError**
+- Can't find source model
+- Ensure all model versions are in bundle
+
+**NSMigrationError**
+- Migration failed
+- Check if changes are lightweight-compatible
+- Use staged migration for complex changes
+
+## Best Practices
+
+1. **Test migrations thoroughly** - Test upgrade paths from all previous versions
+2. **Keep model versions** - Don't delete old .xcdatamodel files
+3. **Use lightweight when possible** - Simplest and most reliable
+4. **Decompose complex changes** - Use staged migration for non-lightweight changes
+5. **Defer expensive cleanup** - Use deferred migration for large datasets
+6. **Version your models** - Create new model version for each release
+7. **Test on real data** - Migration behavior differs with large datasets
+8. **Document changes** - Keep migration notes for future reference
+
+## Testing Migrations
+
+```swift
+func testMigration() throws {
+    // 1. Create store with old model
+    let oldModelURL = Bundle.main.url(forResource: "ModelV1", withExtension: "momd")!
+    let oldModel = NSManagedObjectModel(contentsOf: oldModelURL)!
+    
+    let coordinator = NSPersistentStoreCoordinator(managedObjectModel: oldModel)
+    try coordinator.addPersistentStore(
+        ofType: NSSQLiteStoreType,
+        configurationName: nil,
+        at: storeURL,
+        options: nil
+    )
+    
+    // 2. Add test data
+    let context = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
+    context.persistentStoreCoordinator = coordinator
+    
+    let entity = NSEntityDescription.insertNewObject(forEntityName: "Article", into: context)
+    entity.setValue("Test", forKey: "name")
+    try context.save()
+    
+    // 3. Close store
+    try coordinator.remove(coordinator.persistentStores.first!)
+    
+    // 4. Migrate with new model
+    let newModelURL = Bundle.main.url(forResource: "ModelV2", withExtension: "momd")!
+    let newModel = NSManagedObjectModel(contentsOf: newModelURL)!
+    
+    let newCoordinator = NSPersistentStoreCoordinator(managedObjectModel: newModel)
+    let options = [
+        NSMigratePersistentStoresAutomaticallyOption: true,
+        NSInferMappingModelAutomaticallyOption: true
+    ]
+    try newCoordinator.addPersistentStore(
+        ofType: NSSQLiteStoreType,
+        configurationName: nil,
+        at: storeURL,
+        options: options
+    )
+    
+    // 5. Verify data
+    let newContext = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
+    newContext.persistentStoreCoordinator = newCoordinator
+    
+    let fetchRequest = NSFetchRequest<NSManagedObject>(entityName: "Article")
+    let results = try newContext.fetch(fetchRequest)
+    
+    XCTAssertEqual(results.count, 1)
+    XCTAssertEqual(results.first?.value(forKey: "name") as? String, "Test")
+}
+```
+
+## Summary
+
+1. **Use lightweight migration** - Handles most common changes automatically
+2. **Enable by default** - NSPersistentContainer enables it automatically
+3. **Use renaming identifiers** - For renaming attributes/entities/relationships
+4. **Use composite attributes (iOS 17+)** - For structured data
+5. **Use staged migration (iOS 17+)** - For complex, non-lightweight changes
+6. **Use deferred migration (iOS 14+)** - For expensive cleanup operations
+7. **Test thoroughly** - Verify all upgrade paths
+8. **Keep all model versions** - Required for migration
+9. **Enable migration debug** - Helps diagnose issues
+10. **Document changes** - Track what changed in each version