@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.4

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swift-concurrency/references/approachable-concurrency.md

@@ -1,80 +1,80 @@
-# Approachable Concurrency Quick Reference
-
-Use this reference when the project has opted into the Swift 6.2 approachable
-concurrency settings (default MainActor isolation / main-actor-by-default).
-
-## Detecting the Mode
-
-**Xcode 26:** Check build settings under Swift Compiler > Concurrency:
-- Swift language version: 6.2+
-- Default Actor Isolation / Main Actor by Default: enabled
-- Strict Concurrency Checking: Complete / Targeted / Minimal
-
-**SwiftPM:** Inspect `Package.swift` `swiftSettings` for the corresponding flags.
-
-## Behavior Changes
-
-### Async functions stay on the caller's actor
-
-In Swift 6.2, nonisolated async functions no longer hop to the global
-concurrent executor. They stay on whichever actor called them. This eliminates
-many "sending X risks causing data races" errors.
-
-### Default MainActor isolation
-
-With SE-0466 enabled, all declarations in the module are implicitly `@MainActor`.
-This means:
-- Global and static variables are protected by default.
-- Protocol conformances are implicitly isolated.
-- Mutable state is safe without explicit annotation.
-
-### Isolated conformances
-
-Protocol conformances can be explicitly isolated:
-`extension Foo: @MainActor SomeProtocol`. The compiler prevents using the
-conformance outside the matching isolation context.
-
-## Applying Fixes in This Mode
-
-- **Prefer minimal annotations.** Let default MainActor isolation do the work
-  for UI-bound code.
-- **Use isolated conformances** instead of `nonisolated` workarounds for
-  protocol conformances.
-- **Keep global/shared mutable state on MainActor** unless there is a clear
-  performance need to offload.
-- **Remove redundant `@MainActor` annotations** that are now implied by the
-  default isolation mode.
-
-## Offloading Work
-
-- Use `@concurrent` on async functions that must run on the concurrent pool.
-- Make types or members `nonisolated` only when they are truly thread-safe and
-  used off the main actor.
-- Continue to respect `Sendable` boundaries when values cross actors or tasks.
-
-## Common Pitfalls
-
-| Pitfall | Why it happens | Fix |
-|---|---|---|
-| CPU-heavy work on MainActor | Default isolation hides the problem | Move to `@concurrent` async function |
-| `Task.detached` breaking isolation | Ignores inherited actor context | Use `Task { }` unless you truly need detachment |
-| Redundant `@MainActor` everywhere | Default isolation already provides it | Remove explicit annotations |
-| `nonisolated` on mutable state | Breaks the safety guarantee | Keep mutable state isolated |
-
-## Concurrency Keywords
-
-| Keyword | What it does |
-|---|---|
-| `async` | Function can suspend |
-| `await` | Suspend here until done |
-| `Task { }` | Start async work, inherits context |
-| `Task.detached { }` | Start async work, no inherited context |
-| `Task.immediate { }` | Start immediately on current actor |
-| `@MainActor` | Runs on main thread |
-| `actor` | Type with isolated mutable state |
-| `nonisolated` | Opts out of actor isolation |
-| `Sendable` | Safe to pass between isolation domains |
-| `@concurrent` | Always run on background thread pool (Swift 6.2+) |
-| `async let` | Start parallel work (fixed count) |
-| `TaskGroup` | Dynamic parallel work |
-| `sending` | Parameter-level isolation transfer (SE-0430) |
+# Approachable Concurrency Quick Reference
+
+Use this reference when the project has opted into the Swift 6.2 approachable
+concurrency settings (default MainActor isolation / main-actor-by-default).
+
+## Detecting the Mode
+
+**Xcode 26:** Check build settings under Swift Compiler > Concurrency:
+- Swift language version: 6.2+
+- Default Actor Isolation / Main Actor by Default: enabled
+- Strict Concurrency Checking: Complete / Targeted / Minimal
+
+**SwiftPM:** Inspect `Package.swift` `swiftSettings` for the corresponding flags.
+
+## Behavior Changes
+
+### Async functions stay on the caller's actor
+
+In Swift 6.2, nonisolated async functions no longer hop to the global
+concurrent executor. They stay on whichever actor called them. This eliminates
+many "sending X risks causing data races" errors.
+
+### Default MainActor isolation
+
+With SE-0466 enabled, all declarations in the module are implicitly `@MainActor`.
+This means:
+- Global and static variables are protected by default.
+- Protocol conformances are implicitly isolated.
+- Mutable state is safe without explicit annotation.
+
+### Isolated conformances
+
+Protocol conformances can be explicitly isolated:
+`extension Foo: @MainActor SomeProtocol`. The compiler prevents using the
+conformance outside the matching isolation context.
+
+## Applying Fixes in This Mode
+
+- **Prefer minimal annotations.** Let default MainActor isolation do the work
+  for UI-bound code.
+- **Use isolated conformances** instead of `nonisolated` workarounds for
+  protocol conformances.
+- **Keep global/shared mutable state on MainActor** unless there is a clear
+  performance need to offload.
+- **Remove redundant `@MainActor` annotations** that are now implied by the
+  default isolation mode.
+
+## Offloading Work
+
+- Use `@concurrent` on async functions that must run on the concurrent pool.
+- Make types or members `nonisolated` only when they are truly thread-safe and
+  used off the main actor.
+- Continue to respect `Sendable` boundaries when values cross actors or tasks.
+
+## Common Pitfalls
+
+| Pitfall | Why it happens | Fix |
+|---|---|---|
+| CPU-heavy work on MainActor | Default isolation hides the problem | Move to `@concurrent` async function |
+| `Task.detached` breaking isolation | Ignores inherited actor context | Use `Task { }` unless you truly need detachment |
+| Redundant `@MainActor` everywhere | Default isolation already provides it | Remove explicit annotations |
+| `nonisolated` on mutable state | Breaks the safety guarantee | Keep mutable state isolated |
+
+## Concurrency Keywords
+
+| Keyword | What it does |
+|---|---|
+| `async` | Function can suspend |
+| `await` | Suspend here until done |
+| `Task { }` | Start async work, inherits context |
+| `Task.detached { }` | Start async work, no inherited context |
+| `Task.immediate { }` | Start immediately on current actor |
+| `@MainActor` | Runs on main thread |
+| `actor` | Type with isolated mutable state |
+| `nonisolated` | Opts out of actor isolation |
+| `Sendable` | Safe to pass between isolation domains |
+| `@concurrent` | Always run on background thread pool (Swift 6.2+) |
+| `async let` | Start parallel work (fixed count) |
+| `TaskGroup` | Dynamic parallel work |
+| `sending` | Parameter-level isolation transfer (SE-0430) |

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swift-concurrency/references/swift-6-2-concurrency.md

@@ -1,233 +1,233 @@
-# Swift 6.2 Concurrency Changes
-
-Swift 6.2 introduces "approachable concurrency" -- a philosophy shift where
-code stays single-threaded by default until you choose to introduce concurrency.
-
-## Contents
-
-- [Core Problem Solved](#core-problem-solved)
-- [SE-0466: Default MainActor Isolation](#se-0466-default-mainactor-isolation)
-- [SE-0461: nonisolated(nonsending)](#se-0461-nonisolatednonsending)
-- [@concurrent Attribute](#concurrent-attribute)
-- [SE-0472: Task.immediate](#se-0472-taskimmediate)
-- [Isolated Conformances](#isolated-conformances)
-- [SE-0481: weak let (Proposed)](#se-0481-weak-let-proposed--swift-62)
-- [SE-0475: Transactional Observation (Observations)](#se-0475-transactional-observation-observations)
-- [Global and Static State](#global-and-static-state)
-- [Migration and Build Settings](#migration-and-build-settings)
-- [Summary](#summary)
-
-## Core Problem Solved
-
-In Swift 6.0/6.1, data-race safety was enforced at compile time, but the most
-natural code to write often produced data-race errors. Async functions on types
-with mutable state would implicitly hop to the global concurrent executor,
-causing send-safety violations even when no actual parallelism was intended.
-
-```swift
-// Swift 6.0/6.1: This produces a data-race error
-class PhotoProcessor {
-    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
-}
-
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-        // Error: Sending 'self.photoProcessor' risks causing data races
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-```swift
-// Swift 6.2: The same code compiles without error
-// because extractSticker stays on the caller's actor
-class PhotoProcessor {
-    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
-}
-
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-## SE-0466: Default MainActor Isolation
-
-Enable with the `-default-isolation MainActor` compiler flag or the Xcode 26
-"Approachable Concurrency" build setting.
-
-**What it does:**
-- All declarations in the module are implicitly `@MainActor` unless opted out.
-- Global and static variables are protected by the main actor by default.
-- Protocol conformances are implicitly isolated to `@MainActor`.
-- Eliminates most annotation burden for single-threaded UI code.
-
-**Recommended for:** Apps, scripts, and executable targets. Not recommended for
-library targets that should remain actor-agnostic.
-
-```swift
-// With default MainActor isolation -- no @MainActor annotations needed:
-final class StickerLibrary {
-    static let shared = StickerLibrary()
-}
-
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-    var selection: [PhotosPickerItem] = []
-}
-
-extension StickerModel: Exportable {
-    func export() { photoProcessor.exportAsPNG() }
-}
-```
-
-## SE-0461: nonisolated(nonsending)
-
-Nonisolated async functions stay on the caller's actor by default instead of
-hopping to the global concurrent executor. This is the `nonisolated(nonsending)`
-default behavior.
-
-**Key implication:** Values passed into an async function are never sent outside
-the actor, eliminating data races without annotation.
-
-To explicitly opt into background execution, use `@concurrent`.
-
-## @concurrent Attribute
-
-Ensures a function always runs on the concurrent thread pool, freeing the
-calling actor for other work.
-
-```swift
-class PhotoProcessor {
-    var cachedStickers: [String: Sticker] = [:]
-
-    func extractSticker(data: Data, with id: String) async -> Sticker {
-        if let sticker = cachedStickers[id] { return sticker }
-        let sticker = await Self.extractSubject(from: data)
-        cachedStickers[id] = sticker
-        return sticker
-    }
-
-    @concurrent
-    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
-}
-```
-
-**Steps to offload a function to background:**
-1. Ensure the containing type is `nonisolated` (or the function itself).
-2. Add `@concurrent` to the function.
-3. Add `async` if not already asynchronous.
-4. Add `await` at call sites.
-
-```swift
-nonisolated struct PhotoProcessor {
-    @concurrent
-    func process(data: Data) async -> ProcessedPhoto? { /* ... */ }
-}
-
-processedPhotos[item.id] = await PhotoProcessor().process(data: data)
-```
-
-## SE-0472: Task.immediate
-
-`Task.immediate` starts executing synchronously on the current actor before any
-suspension point, rather than being enqueued. There is also
-`Task.immediateDetached` which combines immediate start with detached semantics.
-
-```swift
-Task.immediate { await handleUserInput() }
-```
-
-Use for latency-sensitive work where enqueue delay is unacceptable.
-
-## Isolated Conformances
-
-A conformance that needs MainActor state is called an *isolated conformance*.
-The compiler ensures the conformance is only used in a matching isolation
-context.
-
-```swift
-protocol Exportable {
-    func export()
-}
-
-extension StickerModel: @MainActor Exportable {
-    func export() { photoProcessor.exportAsPNG() }
-}
-
-@MainActor
-struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // OK -- on MainActor
-    }
-}
-
-// But in a nonisolated context:
-nonisolated struct GenericExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        // Error: Main actor-isolated conformance of 'StickerModel' to
-        // 'Exportable' cannot be used in nonisolated context
-        items.append(item)
-    }
-}
-```
-
-## SE-0481: weak let (Proposed — Swift 6.2+)
-
-Immutable weak references (`weak let`) enable `Sendable` conformance for types
-that hold weak references, since immutability guarantees thread safety. Proposed
-in SE-0481; may not yet be available in shipping toolchains.
-
-## SE-0475: Transactional Observation (Observations)
-
-`Observations { }` provides transactional observation of `@Observable` types
-via `AsyncSequence`.
-
-```swift
-for await _ in Observations { model.count } {
-    print("Count changed to \(model.count)")
-}
-```
-
-## Global and Static State
-
-Global and static variables are prone to data races. The most common protection
-is `@MainActor`:
-
-```swift
-@MainActor
-final class StickerLibrary {
-    static let shared = StickerLibrary()  // protected by MainActor
-}
-```
-
-With default MainActor isolation (SE-0466), this annotation is implicit.
-
-## Migration and Build Settings
-
-All approachable concurrency features are opt-in via:
-- **Xcode 26:** Swift Compiler > Concurrency section in build settings.
-- **SwiftPM:** `swiftSettings` in Package.swift using the `SwiftSetting` API.
-
-Swift 6.2 includes migration tooling to help make necessary code changes
-automatically. See swift.org/migration for details.
-
-## Summary
-
-The Swift 6.2 concurrency progression:
-1. Start with code that runs on the main actor by default (no data race risk).
-2. Async functions run wherever they are called from (still no data race risk).
-3. When you need performance, offload specific code with `@concurrent`.
+# Swift 6.2 Concurrency Changes
+
+Swift 6.2 introduces "approachable concurrency" -- a philosophy shift where
+code stays single-threaded by default until you choose to introduce concurrency.
+
+## Contents
+
+- [Core Problem Solved](#core-problem-solved)
+- [SE-0466: Default MainActor Isolation](#se-0466-default-mainactor-isolation)
+- [SE-0461: nonisolated(nonsending)](#se-0461-nonisolatednonsending)
+- [@concurrent Attribute](#concurrent-attribute)
+- [SE-0472: Task.immediate](#se-0472-taskimmediate)
+- [Isolated Conformances](#isolated-conformances)
+- [SE-0481: weak let (Proposed)](#se-0481-weak-let-proposed--swift-62)
+- [SE-0475: Transactional Observation (Observations)](#se-0475-transactional-observation-observations)
+- [Global and Static State](#global-and-static-state)
+- [Migration and Build Settings](#migration-and-build-settings)
+- [Summary](#summary)
+
+## Core Problem Solved
+
+In Swift 6.0/6.1, data-race safety was enforced at compile time, but the most
+natural code to write often produced data-race errors. Async functions on types
+with mutable state would implicitly hop to the global concurrent executor,
+causing send-safety violations even when no actual parallelism was intended.
+
+```swift
+// Swift 6.0/6.1: This produces a data-race error
+class PhotoProcessor {
+    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
+}
+
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+        // Error: Sending 'self.photoProcessor' risks causing data races
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+```swift
+// Swift 6.2: The same code compiles without error
+// because extractSticker stays on the caller's actor
+class PhotoProcessor {
+    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
+}
+
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+## SE-0466: Default MainActor Isolation
+
+Enable with the `-default-isolation MainActor` compiler flag or the Xcode 26
+"Approachable Concurrency" build setting.
+
+**What it does:**
+- All declarations in the module are implicitly `@MainActor` unless opted out.
+- Global and static variables are protected by the main actor by default.
+- Protocol conformances are implicitly isolated to `@MainActor`.
+- Eliminates most annotation burden for single-threaded UI code.
+
+**Recommended for:** Apps, scripts, and executable targets. Not recommended for
+library targets that should remain actor-agnostic.
+
+```swift
+// With default MainActor isolation -- no @MainActor annotations needed:
+final class StickerLibrary {
+    static let shared = StickerLibrary()
+}
+
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+    var selection: [PhotosPickerItem] = []
+}
+
+extension StickerModel: Exportable {
+    func export() { photoProcessor.exportAsPNG() }
+}
+```
+
+## SE-0461: nonisolated(nonsending)
+
+Nonisolated async functions stay on the caller's actor by default instead of
+hopping to the global concurrent executor. This is the `nonisolated(nonsending)`
+default behavior.
+
+**Key implication:** Values passed into an async function are never sent outside
+the actor, eliminating data races without annotation.
+
+To explicitly opt into background execution, use `@concurrent`.
+
+## @concurrent Attribute
+
+Ensures a function always runs on the concurrent thread pool, freeing the
+calling actor for other work.
+
+```swift
+class PhotoProcessor {
+    var cachedStickers: [String: Sticker] = [:]
+
+    func extractSticker(data: Data, with id: String) async -> Sticker {
+        if let sticker = cachedStickers[id] { return sticker }
+        let sticker = await Self.extractSubject(from: data)
+        cachedStickers[id] = sticker
+        return sticker
+    }
+
+    @concurrent
+    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
+}
+```
+
+**Steps to offload a function to background:**
+1. Ensure the containing type is `nonisolated` (or the function itself).
+2. Add `@concurrent` to the function.
+3. Add `async` if not already asynchronous.
+4. Add `await` at call sites.
+
+```swift
+nonisolated struct PhotoProcessor {
+    @concurrent
+    func process(data: Data) async -> ProcessedPhoto? { /* ... */ }
+}
+
+processedPhotos[item.id] = await PhotoProcessor().process(data: data)
+```
+
+## SE-0472: Task.immediate
+
+`Task.immediate` starts executing synchronously on the current actor before any
+suspension point, rather than being enqueued. There is also
+`Task.immediateDetached` which combines immediate start with detached semantics.
+
+```swift
+Task.immediate { await handleUserInput() }
+```
+
+Use for latency-sensitive work where enqueue delay is unacceptable.
+
+## Isolated Conformances
+
+A conformance that needs MainActor state is called an *isolated conformance*.
+The compiler ensures the conformance is only used in a matching isolation
+context.
+
+```swift
+protocol Exportable {
+    func export()
+}
+
+extension StickerModel: @MainActor Exportable {
+    func export() { photoProcessor.exportAsPNG() }
+}
+
+@MainActor
+struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // OK -- on MainActor
+    }
+}
+
+// But in a nonisolated context:
+nonisolated struct GenericExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        // Error: Main actor-isolated conformance of 'StickerModel' to
+        // 'Exportable' cannot be used in nonisolated context
+        items.append(item)
+    }
+}
+```
+
+## SE-0481: weak let (Proposed — Swift 6.2+)
+
+Immutable weak references (`weak let`) enable `Sendable` conformance for types
+that hold weak references, since immutability guarantees thread safety. Proposed
+in SE-0481; may not yet be available in shipping toolchains.
+
+## SE-0475: Transactional Observation (Observations)
+
+`Observations { }` provides transactional observation of `@Observable` types
+via `AsyncSequence`.
+
+```swift
+for await _ in Observations { model.count } {
+    print("Count changed to \(model.count)")
+}
+```
+
+## Global and Static State
+
+Global and static variables are prone to data races. The most common protection
+is `@MainActor`:
+
+```swift
+@MainActor
+final class StickerLibrary {
+    static let shared = StickerLibrary()  // protected by MainActor
+}
+```
+
+With default MainActor isolation (SE-0466), this annotation is implicit.
+
+## Migration and Build Settings
+
+All approachable concurrency features are opt-in via:
+- **Xcode 26:** Swift Compiler > Concurrency section in build settings.
+- **SwiftPM:** `swiftSettings` in Package.swift using the `SwiftSetting` API.
+
+Swift 6.2 includes migration tooling to help make necessary code changes
+automatically. See swift.org/migration for details.
+
+## Summary
+
+The Swift 6.2 concurrency progression:
+1. Start with code that runs on the main actor by default (no data race risk).
+2. Async functions run wherever they are called from (still no data race risk).
+3. When you need performance, offload specific code with `@concurrent`.