buildanything 1.7.1 → 2.0.0

package/skills/ios/swift-concurrency/references/core-data.md

@@ -0,0 +1,560 @@
+# Core Data and Swift Concurrency
+
+Use this when:
+
+- You need to use Core Data with async/await or actors.
+- `NSManagedObject` instances are crossing context or actor boundaries.
+- You are resolving default `@MainActor` isolation conflicts with generated NSManagedObject subclasses.
+
+Skip this file if:
+
+- The issue is general actor isolation, not Core Data specific. Use `actors.md`.
+- You need general Sendable guidance. Use `sendable.md`.
+
+Jump to:
+
+- Core Principles
+- Data Access Objects (DAO) Pattern
+- Working Without DAOs (NSManagedObjectID)
+- Bridging Closures to Async
+- Custom Actor Executor (Advanced)
+- Default MainActor Isolation
+- SwiftUI Integration
+- Common Mistakes
+
+## Core Principles
+
+### Thread safety still matters
+
+Core Data's thread safety rules don't change with Swift Concurrency:
+- Can't pass `NSManagedObject` between threads
+- Must access objects on their context's thread
+- `NSManagedObjectID` is thread-safe (can pass around)
+
+### NSManagedObject cannot be Sendable
+
+```swift
+@objc(Article)
+public class Article: NSManagedObject {
+    @NSManaged public var title: String // ❌ Mutable, can't be Sendable
+}
+```
+
+**Don't use `@unchecked Sendable`** - hides warnings without fixing safety.
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.1: An introduction to Swift Concurrency and Core Data](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+## Available Async APIs
+
+### Context perform
+
+```swift
+extension NSManagedObjectContext {
+    func perform<T>(
+        schedule: ScheduledTaskType = .immediate,
+        _ block: @escaping () throws -> T
+    ) async rethrows -> T
+}
+```
+
+### What's missing
+
+No async alternative for:
+```swift
+func loadPersistentStores(
+    completionHandler: @escaping (NSPersistentStoreDescription, Error?) -> Void
+)
+```
+
+Must bridge manually (see below).
+
+## Data Access Objects (DAO)
+
+Thread-safe value types representing managed objects.
+
+### Pattern
+
+```swift
+// Managed object (not Sendable)
+@objc(Article)
+public class Article: NSManagedObject {
+    @NSManaged public var title: String?
+    @NSManaged public var timestamp: Date?
+}
+
+// DAO (Sendable)
+struct ArticleDAO: Sendable, Identifiable {
+    let id: NSManagedObjectID
+    let title: String
+    let timestamp: Date
+    
+    init?(managedObject: Article) {
+        guard let title = managedObject.title,
+              let timestamp = managedObject.timestamp else {
+            return nil
+        }
+        self.id = managedObject.objectID
+        self.title = title
+        self.timestamp = timestamp
+    }
+}
+```
+
+### Benefits
+
+- **Sendable**: Safe to pass across isolation domains
+- **Immutable**: No accidental mutations
+- **Clear API**: Explicit data transfer
+
+### Drawbacks
+
+- **Requires rewrite**: All fetch/mutation logic
+- **Boilerplate**: DAO for each entity
+- **Complexity**: Additional layer of abstraction
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.2: Sendable and NSManageObjects](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+## Working Without DAOs
+
+Pass only `NSManagedObjectID` between contexts.
+
+### Basic pattern
+
+```swift
+@MainActor
+func fetchArticle(id: NSManagedObjectID) -> Article? {
+    viewContext.object(with: id) as? Article
+}
+
+func processInBackground(articleID: NSManagedObjectID) async throws {
+    let backgroundContext = container.newBackgroundContext()
+    try await backgroundContext.perform {
+        guard let article = backgroundContext.object(with: articleID) as? Article else {
+            return
+        }
+        // Process article
+        try backgroundContext.save()
+    }
+}
+```
+
+### NSManagedObjectID is Sendable
+
+```swift
+// Safe to pass between tasks
+let articleID = article.objectID
+
+Task {
+    await processInBackground(articleID: articleID)
+}
+```
+
+## Bridging Closures to Async
+
+### Load persistent stores
+
+```swift
+extension NSPersistentContainer {
+    func loadPersistentStores() async throws {
+        try await withCheckedThrowingContinuation { continuation in
+            self.loadPersistentStores { description, error in
+                if let error {
+                    continuation.resume(throwing: error)
+                } else {
+                    continuation.resume(returning: ())
+                }
+            }
+        }
+    }
+}
+
+// Usage
+try await container.loadPersistentStores()
+```
+
+## Simple CoreDataStore Pattern
+
+Enforce isolation at API level:
+
+```swift
+nonisolated struct CoreDataStore {
+    static let shared = CoreDataStore()
+    
+    let persistentContainer: NSPersistentContainer
+    private var viewContext: NSManagedObjectContext {
+        persistentContainer.viewContext
+    }
+    
+    private init() {
+        persistentContainer = NSPersistentContainer(name: "MyApp")
+        persistentContainer.viewContext.automaticallyMergesChangesFromParent = true
+        
+        Task { [persistentContainer] in
+            try? await persistentContainer.loadPersistentStores()
+        }
+    }
+    
+    // View context operations (main thread)
+    @MainActor
+    func perform(_ block: (NSManagedObjectContext) throws -> Void) rethrows {
+        try block(viewContext)
+    }
+    
+    // Background operations
+    @concurrent
+    func performInBackground<T>(
+        _ block: @escaping (NSManagedObjectContext) throws -> T
+    ) async rethrows -> T {
+        let context = persistentContainer.newBackgroundContext()
+        return try await context.perform {
+            try block(context)
+        }
+    }
+}
+```
+
+### Usage
+
+```swift
+// Main thread operations
+@MainActor
+func loadArticles() throws -> [Article] {
+    try CoreDataStore.shared.perform { context in
+        let request = Article.fetchRequest()
+        return try context.fetch(request)
+    }
+}
+
+// Background operations
+func deleteAll() async throws {
+    try await CoreDataStore.shared.performInBackground { context in
+        let request = Article.fetchRequest()
+        let articles = try context.fetch(request)
+        articles.forEach { context.delete($0) }
+        try context.save()
+    }
+}
+```
+
+### Why this pattern works
+
+- **@MainActor**: Enforces view context on main thread
+- **@concurrent**: Forces background execution
+- **Compile-time safety**: Wrong isolation = error
+- **Simple**: No custom executors needed
+
+## Custom Actor Executor (Advanced)
+
+**Note**: Usually not needed. Consider simple pattern first.
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.3: Using a custom Actor executor for Core Data (advanced)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+### Implementation
+
+```swift
+final class NSManagedObjectContextExecutor: @unchecked Sendable, SerialExecutor {
+    private let context: NSManagedObjectContext
+    
+    init(context: NSManagedObjectContext) {
+        self.context = context
+    }
+    
+    func enqueue(_ job: consuming ExecutorJob) {
+        let unownedJob = UnownedJob(job)
+        let executor = asUnownedSerialExecutor()
+        
+        context.perform {
+            unownedJob.runSynchronously(on: executor)
+        }
+    }
+    
+    func asUnownedSerialExecutor() -> UnownedSerialExecutor {
+        UnownedSerialExecutor(ordinary: self)
+    }
+}
+```
+
+### Actor usage
+
+```swift
+actor CoreDataStore {
+    let persistentContainer: NSPersistentContainer
+    nonisolated let modelExecutor: NSManagedObjectContextExecutor
+    
+    nonisolated var unownedExecutor: UnownedSerialExecutor {
+        modelExecutor.asUnownedSerialExecutor()
+    }
+    
+    private init() {
+        persistentContainer = NSPersistentContainer(name: "MyApp")
+        let context = persistentContainer.newBackgroundContext()
+        modelExecutor = NSManagedObjectContextExecutor(context: context)
+    }
+    
+    func deleteAll<T: NSManagedObject>(
+        using request: NSFetchRequest<T>
+    ) throws {
+        let objects = try context.fetch(request)
+        objects.forEach { context.delete($0) }
+        try context.save()
+    }
+}
+```
+
+### Drawbacks
+
+- **Hidden complexity**: Executor details obscure Core Data
+- **Forces concurrency**: Even for main thread operations
+- **Not simpler**: More code than `perform { }`
+- **Error prone**: Easy to use wrong context
+
+**Recommendation**: Use simple pattern instead.
+
+## Default MainActor Isolation
+
+### Problem with auto-generated code
+
+When default isolation set to `@MainActor`, auto-generated managed objects conflict:
+
+```swift
+// Auto-generated (can't modify)
+class Article: NSManagedObject {
+    // Inherits @MainActor, conflicts with NSManagedObject
+}
+```
+
+**Error**: `Main actor-isolated initializer has different actor isolation from nonisolated overridden declaration`
+
+### Solution: Manual code generation
+
+1. Set entity to "Manual/None" code generation
+2. Generate class definitions
+3. Mark as `nonisolated`:
+
+```swift
+nonisolated class Article: NSManagedObject {
+    @NSManaged public var title: String?
+    @NSManaged public var timestamp: Date?
+}
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.4: Autogenerated Core Data Objects and Default MainActor Isolation Conflicts](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+```
+
+**Benefit**: Full control over isolation.
+
+## Common Patterns
+
+### Fetch on main thread
+
+```swift
+@MainActor
+func fetchArticles() throws -> [Article] {
+    let request = Article.fetchRequest()
+    return try viewContext.fetch(request)
+}
+```
+
+### Background save
+
+```swift
+func saveInBackground() async throws {
+    let context = container.newBackgroundContext()
+    try await context.perform {
+        let article = Article(context: context)
+        article.title = "New Article"
+        try context.save()
+    }
+}
+```
+
+### Pass ID, fetch in context
+
+```swift
+@MainActor
+func displayArticle(id: NSManagedObjectID) {
+    guard let article = viewContext.object(with: id) as? Article else {
+        return
+    }
+    // Use article
+}
+
+func processArticle(id: NSManagedObjectID) async throws {
+    try await CoreDataStore.shared.performInBackground { context in
+        guard let article = context.object(with: id) as? Article else {
+            return
+        }
+        // Process article
+        try context.save()
+    }
+}
+```
+
+### Batch operations
+
+```swift
+@concurrent
+func deleteAllArticles() async throws {
+    try await CoreDataStore.shared.performInBackground { context in
+        let request = NSFetchRequest<NSFetchRequestResult>(entityName: "Article")
+        let deleteRequest = NSBatchDeleteRequest(fetchRequest: request)
+        try context.execute(deleteRequest)
+    }
+}
+```
+
+## SwiftUI Integration
+
+### Environment injection
+
+```swift
+@main
+struct MyApp: App {
+    let persistentContainer = NSPersistentContainer(name: "MyApp")
+    
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environment(\.managedObjectContext, persistentContainer.viewContext)
+        }
+    }
+}
+```
+
+### View usage
+
+```swift
+struct ContentView: View {
+    @Environment(\.managedObjectContext) private var viewContext
+    @FetchRequest(
+        sortDescriptors: [NSSortDescriptor(keyPath: \Article.timestamp, ascending: true)]
+    ) private var articles: FetchedResults<Article>
+    
+    var body: some View {
+        List(articles) { article in
+            Text(article.title ?? "")
+        }
+    }
+}
+```
+
+## Best Practices
+
+1. **Pass NSManagedObjectID only** - never managed objects
+2. **Use perform { }** - don't access context directly
+3. **@MainActor for view context** - enforce main thread
+4. **@concurrent for background** - force background execution
+5. **Manual code generation** - control isolation
+6. **Keep it simple** - avoid custom executors unless needed
+7. **Enable Core Data debugging** - catch thread violations
+8. **Merge changes automatically** - `automaticallyMergesChangesFromParent = true`
+9. **Use background contexts** - for heavy operations
+10. **Test with Thread Sanitizer** - catch violations early
+
+## Debugging
+
+### Enable Core Data concurrency debugging
+
+```swift
+// Launch argument
+-com.apple.CoreData.ConcurrencyDebug 1
+```
+
+Crashes immediately on thread violations.
+
+### Thread Sanitizer
+
+Enable in scheme settings to catch data races.
+
+### Assertions
+
+```swift
+@MainActor
+func fetchArticles() -> [Article] {
+    assert(Thread.isMainThread)
+    // Fetch from viewContext
+}
+```
+
+## Decision Tree
+
+```
+Need to access Core Data?
+├─ UI/View context?
+│  └─ Use @MainActor + viewContext
+│
+├─ Background operation?
+│  ├─ Quick operation? → perform { } on background context
+│  └─ Batch operation? → NSBatchDeleteRequest/NSBatchUpdateRequest
+│
+├─ Pass between contexts?
+│  └─ Use NSManagedObjectID only
+│
+└─ Need Sendable type?
+   ├─ Can refactor? → Use DAO pattern
+   └─ Can't refactor? → Pass NSManagedObjectID
+```
+
+## Migration Strategy
+
+### For existing projects
+
+1. **Enable manual code generation** for all entities
+2. **Mark entities as nonisolated** if using default @MainActor
+3. **Wrap Core Data access** in CoreDataStore
+4. **Use @MainActor** for view context operations
+5. **Use @concurrent** for background operations
+6. **Pass NSManagedObjectID** between contexts
+7. **Test with debugging enabled**
+
+### For new projects
+
+1. **Start with simple pattern** (CoreDataStore)
+2. **Manual code generation** from the start
+3. **Consider DAOs** if heavy cross-context usage
+4. **Enable strict concurrency** early
+
+## Common Mistakes
+
+### ❌ Passing managed objects
+
+```swift
+func process(article: Article) async {
+    // ❌ Article not Sendable
+}
+```
+
+### ❌ Accessing context from wrong thread
+
+```swift
+func background() async {
+    let articles = viewContext.fetch(request) // ❌ Not on main thread
+}
+```
+
+### ❌ Using @unchecked Sendable
+
+```swift
+extension Article: @unchecked Sendable {} // ❌ Doesn't make it safe
+```
+
+### ❌ Not using perform
+
+```swift
+func save() async {
+    backgroundContext.save() // ❌ Not on context's thread
+}
+```
+
+## Common Mistakes Agents Make
+
+- **Passing `NSManagedObject` instances across actors**: Always transfer `NSManagedObjectID` or a Sendable value snapshot instead.
+- **Using `@unchecked Sendable` on `NSManagedObject`**: This does not make it thread-safe. The object is still bound to its context's queue.
+- **Skipping `perform { }`**: All background context access must go through `perform` or `performAndWait`.
+- **Accessing `viewContext` from a background task**: The view context belongs to the main actor; access it only from `@MainActor`-isolated code.
+
+## Further Learning
+
+For Core Data best practices, migration strategies, and advanced patterns:
+- [Core Data Best Practices](https://github.com/avanderlee/CoreDataBestPractices)
+- [Swift Concurrency Course](https://www.swiftconcurrencycourse.com)
+

package/skills/ios/swift-concurrency/references/glossary.md

@@ -0,0 +1,135 @@
+# Glossary
+
+Use this when:
+
+- You need a quick definition of a Swift Concurrency term.
+- You encounter unfamiliar terminology in other reference files.
+
+Skip this file if:
+
+- You need implementation patterns, not definitions. Use the relevant reference file instead.
+
+## Actor isolation
+
+A rule enforced by the compiler: actor-isolated state can only be accessed from the actor's executor. Cross-actor access requires `await`.
+
+## Global actor
+
+A shared isolation domain applied via attributes like `@MainActor` or a custom `@globalActor`. Types/functions isolated to the same global actor can interact without crossing isolation.
+
+## Default actor isolation
+
+A module/target-level setting that changes the default isolation of declarations. App targets often choose `@MainActor` as the default to reduce migration noise, but it changes behavior and diagnostics.
+
+## Strict concurrency checking
+
+Compiler enforcement levels for Sendable and isolation diagnostics (minimal/targeted/complete). Raising the level typically reveals more issues and can trigger the “concurrency rabbit hole” unless migrated incrementally.
+
+## Sendable
+
+A marker protocol that indicates a type is safe to transfer across isolation boundaries. The compiler verifies stored properties and captured values for thread-safety.
+
+## @Sendable
+
+An annotation for function types/closures that can be executed concurrently. It tightens capture rules (captured values must be Sendable or safely transferred).
+
+## Suspension point
+
+An `await` site where a task may suspend and later resume. After a suspension point, you must assume other work may have run and (for actors) state may have changed (reentrancy).
+
+## Reentrancy (actors)
+
+While an actor is suspended at an `await`, other tasks can enter the actor and mutate state. Code after `await` must not assume actor state is unchanged.
+
+## nonisolated
+
+Marks a declaration as not isolated to the surrounding actor/global actor. Use only when it truly does not touch isolated mutable state (typically immutable Sendable data).
+
+## nonisolated(nonsending) (Swift 6.2+ behavior)
+
+An opt-out to prevent “sending” non-Sendable values across isolation while still allowing an async function to run in the caller’s isolation. Used to reduce Sendable friction when you do not need to hop executors.
+
+## @concurrent (Swift 6.2+ behavior)
+
+An attribute used to explicitly opt a nonisolated async function into concurrent execution (i.e., not inheriting the caller’s actor). It is used during migration when enabling `NonisolatedNonsendingByDefault`.
+
+## @preconcurrency
+
+An annotation used to suppress Sendable-related diagnostics from a module that predates concurrency annotations. It reduces noise but shifts safety responsibility to you.
+
+## Region-based isolation / sending
+
+Mechanisms that model ownership transfer so certain non-Sendable values can be moved between regions safely. The `sending` keyword enforces that a value is no longer used after transfer.
+
+## AsyncSequence
+
+A protocol for types that provide asynchronous, sequential iteration over elements. Conforms to the `for await` loop pattern. Use for streaming data where elements arrive over time.
+
+## AsyncStream
+
+A concrete implementation of `AsyncSequence` that bridges callback-based or delegate-based APIs to async/await. Provides `yield()` to emit values and `finish()` to complete the stream.
+
+## Continuation
+
+A mechanism to bridge callback-based APIs to async/await. `withCheckedContinuation` and `withCheckedThrowingContinuation` provide safe bridging with runtime checks. `withUnsafeContinuation` variants skip checks for performance-critical code.
+
+## Task Local
+
+Task-scoped storage that propagates values through the task hierarchy automatically. Declared with `@TaskLocal` and accessed via the wrapper's static property. Child tasks inherit parent task locals.
+
+## Cooperative thread pool
+
+Swift's threading model where tasks run on a limited pool of threads managed by the runtime. Tasks yield cooperatively at suspension points, allowing other tasks to run. Avoid blocking operations that would starve the pool.
+
+## Executor
+
+The scheduling mechanism that determines where and when actor code runs. `MainActor` uses the main thread executor. Custom actors use the default executor unless a custom executor is specified.
+
+## Structured concurrency
+
+A pattern where child tasks have a well-defined relationship to parent tasks. Child tasks must complete before the parent scope exits. Provides automatic cancellation propagation and prevents orphaned tasks. Implemented via `async let` and `TaskGroup`.
+
+## Isolation domain
+
+A boundary that protects mutable state from concurrent access. Each actor instance defines its own isolation domain. The `@MainActor` global actor defines a shared isolation domain for UI work. Code must cross isolation boundaries explicitly via `await`.
+
+## Task priority
+
+A hint to the runtime about the relative importance of a task. Priorities include `.high`, `.medium`, `.low`, `.userInitiated`, `.utility`, and `.background`. Higher priority tasks are scheduled before lower priority ones. Priority can escalate when a high-priority task awaits a low-priority one.
+
+## Cancellation
+
+A cooperative mechanism to signal that a task should stop. Check `Task.isCancelled` or call `Task.checkCancellation()` (throws) in long-running work. Cancellation propagates to child tasks in structured concurrency.
+
+## Debounce
+
+Wait for a period of inactivity before emitting a value. Used to reduce API calls for rapid inputs like search fields. Implemented as `debounce(for:tolerance:clock:)` in AsyncAlgorithms.
+
+## Throttle
+
+Emit at most one value per time interval, discarding intermediate values. Used to prevent excessive calls from repeated actions like button taps. Implemented as `throttle(for:clock:reducing:)` in AsyncAlgorithms.
+
+## Merge (AsyncAlgorithms)
+
+Combine multiple asynchronous sequences into one, emitting values as they arrive from any source. Order is interleaved based on emission timing. Stable operator.
+
+## CombineLatest (AsyncAlgorithms)
+
+Combine multiple asynchronous sequences, emitting a tuple whenever any source emits a new value. Always uses the latest value from each sequence. Stable operator.
+
+## Zip (AsyncAlgorithms)
+
+Combine multiple asynchronous sequences by pairing elements in order. Waits for all sequences to emit before producing a tuple. Stable operator.
+
+## AsyncChannel
+
+An AsyncSequence with backpressure sending semantics. Allows multiple producers to send values safely to multiple consumers with flow control. Stable operator.
+
+## AsyncThrowingChannel
+
+Like AsyncChannel but can emit errors through the stream. Stable operator.
+
+## AsyncTimerSequence
+
+An AsyncSequence that emits a value at regular intervals. Replaces timer-based publishers and manual sleep loops. Stable operator.
+