@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-concurrency/references/concurrency-patterns.md

@@ -1,244 +1,222 @@
-# Concurrency Patterns
+# Approachable Concurrency Patterns
 
-Approachable concurrency patterns introduced in Swift 6.2+  -  a philosophy shift where
-code stays single-threaded by default until you choose to introduce concurrency.
+Swift 6.2 lets a target start out effectively single-threaded: with both
+Default Actor Isolation set to `MainActor` and Approachable Concurrency turned
+on, code runs on the main actor until you introduce parallelism deliberately.
+Either setting alone gives only part of that picture.
 
-## Contents
+## What problem 6.2 fixed
 
-- [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](#se-0481-weak-let)
-- [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 6.0 and 6.1 already enforced data-race safety at compile time, but
+straightforward code tripped it. An async method on a type with mutable state
+left the caller's actor and ran on the global concurrent executor, so passing
+state into it counted as sending across isolation even though nobody wanted
+parallel execution.
 
 ```swift
-// Swift 6.0/6.1: This produces a data-race error
-class PhotoProcessor {
-    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
+final class WaveformRenderer {
+    var sampleRate = 44_100.0
+    func render(_ audio: Data) async -> Waveform { Waveform(samples: []) }
 }
 
 @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)
+final class EpisodeDetailModel {
+    let renderer = WaveformRenderer()
+    var waveform: Waveform?
+
+    func refresh(with audio: Data) async {
+        waveform = await renderer.render(audio)
+        // Swift 6.0 / 6.1: error: sending 'self.renderer' risks causing data races
+        // Swift 6.2 with NonisolatedNonsendingByDefault: compiles, render runs on the main actor
     }
 }
 ```
 
-```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)
-    }
-}
-```
+## Default MainActor isolation (SE-0466)
 
-## SE-0466: Default MainActor Isolation
+Enable it with one of:
 
-Enable with the `-default-isolation MainActor` compiler flag, SwiftPM
-`.defaultIsolation(MainActor.self)`, or Xcode's separate `Default Actor
-Isolation` build setting set to `MainActor`.
+- `-default-isolation MainActor` passed to the compiler,
+- `.defaultIsolation(MainActor.self)` in a SwiftPM target's `swiftSettings`,
+- Xcode build setting `Default Actor Isolation` = `MainActor`.
 
-Do not confuse this with Xcode's `Approachable Concurrency` build setting, which
-enables a bundle of upcoming-feature flags such as nonisolated-nonsending by
-default, isolated-conformance inference, inferred Sendable captures, and related
-global-actor usability changes.
+This is a different switch from Xcode's `Approachable Concurrency` setting. That
+one enables a bundle of upcoming features: `NonisolatedNonsendingByDefault`,
+inference of isolated conformances, `Sendable` inference for captures, and
+smaller global-actor usability changes. In Swift 6 language mode some of those
+are already on, so the setting mainly adds the first two.
 
-**What it does:**
-- Unannotated declarations in the module are inferred as `@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.
+With default isolation on:
 
-**Recommended for:** Apps, scripts, and executable targets. Not recommended for
-library targets that should remain actor-agnostic.
+- global and `static` variables are protected by the main actor,
+- protocol conformances are isolated to the main actor,
+- UI code that never runs in parallel needs almost no annotations.
 
 ```swift
-// With default MainActor isolation -- no @MainActor annotations needed:
-final class StickerLibrary {
-    static let shared = StickerLibrary()
+final class DownloadSettings {
+    static let shared = DownloadSettings()
+    var wifiOnly = true
 }
 
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-    var selection: [PhotosPickerItem] = []
+final class LibraryModel {
+    let renderer = WaveformRenderer()
+    var selection: [Episode.ID] = []
 }
 
-extension StickerModel: Exportable {
-    func export() { photoProcessor.exportAsPNG() }
+extension LibraryModel: Archivable {
+    func archive() -> Data { Data() }
 }
 ```
 
-## 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.
+None of these declarations says `@MainActor`, yet all of them are main-actor
+isolated. Choose this mode for apps, command-line tools and other executables
+dominated by UI or sequential logic. Keep it off for libraries that callers
+should be able to use from any isolation.
 
-**Key implication:** Values passed into an async function are never sent outside
-the actor, eliminating data races without annotation.
+## Async functions run on the caller (SE-0461)
 
-To explicitly opt into background execution, use `@concurrent`.
+When `NonisolatedNonsendingByDefault` is enabled, a `nonisolated` async function
+inherits its caller's actor; the explicit spelling is `nonisolated(nonsending)`.
+Arguments never leave the caller's isolation, so the "risks causing data races"
+errors above disappear with no annotation. To run on the thread pool instead,
+mark the function `@concurrent`.
 
-## `@concurrent` Attribute
+## Leaving the caller with `@concurrent`
 
-Ensures a function always runs on the concurrent thread pool, freeing the
-calling actor for other work.
+A pattern that keeps the cache on the caller's actor and sends only the heavy
+work to the pool:
 
 ```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
+@MainActor
+final class ThumbnailStore {
+    private var cache: [URL: Thumbnail] = [:]
+
+    func thumbnail(for url: URL) async throws -> Thumbnail {
+        if let cached = cache[url] { return cached }
+        let made = try await Self.decode(url)
+        cache[url] = made
+        return made
     }
 
     @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? { /* ... */ }
+    nonisolated private static func decode(_ url: URL) async throws -> Thumbnail {
+        let bytes = try Data(contentsOf: url)
+        return Thumbnail(byteCount: bytes.count)
+    }
 }
 
-processedPhotos[item.id] = await PhotoProcessor().process(data: data)
+struct Thumbnail: Sendable { let byteCount: Int }
 ```
 
-## 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.
+The four steps are always the same: make the type or function `nonisolated`,
+add `@concurrent`, make it `async` if needed, and `await` it at each call site.
 
-```swift
-Task.immediate { await handleUserInput() }
-```
+## Starting without a queue hop (SE-0472)
 
-Use for latency-sensitive work where enqueue delay is unacceptable.
+`Task.immediate { }` begins executing synchronously on the current actor and
+only suspends at its first `await`, where a plain `Task { }` would be enqueued
+and start later. Reach for it when that enqueue delay is visible, such as
+reacting to a keystroke. `Task.immediateDetached { }` does the same without
+inheriting context. Both need the OS 26 runtime.
 
-## 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.
+## Isolated conformances
 
 ```swift
-protocol Exportable {
-    func export()
+protocol Archivable {
+    func archive() -> Data
 }
 
-extension StickerModel: @MainActor Exportable {
-    func export() { photoProcessor.exportAsPNG() }
+@MainActor
+final class PlaylistModel {
+    var titles: [String] = []
 }
 
-@MainActor
-struct ImageExporter {
-    var items: [any Exportable]
+extension PlaylistModel: @MainActor Archivable {
+    func archive() -> Data { Data(titles.joined(separator: "\n").utf8) }
+}
 
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // OK -- on MainActor
+@MainActor
+struct BackupBatch {
+    var items: [any Archivable] = []
+    mutating func include(_ playlist: PlaylistModel) {
+        items.append(playlist)            // allowed: same isolation
     }
 }
 
-// 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)
+nonisolated struct OffMainBackupBatch {
+    var items: [any Archivable] = []
+    mutating func include(_ playlist: PlaylistModel) {
+        items.append(playlist)
+        // error: main actor-isolated conformance of 'PlaylistModel' to 'Archivable'
+        // cannot be used in nonisolated context
     }
 }
 ```
 
-## SE-0481: weak let
+## Immutable weak references (SE-0481)
 
-Immutable weak references (`weak let`) enable `Sendable` conformance for types
-that hold weak references, since immutability guarantees thread safety.
-SE-0481 is implemented in Swift 6.3.
+`weak let` declares a weak reference that is never reassigned. Because the
+binding cannot change, a type storing only `weak let` references to `Sendable`
+objects can itself be `Sendable`. Swift 6.3 only.
 
-## SE-0475: Transactional Observation (Observations)
+```swift
+final class SessionObserver: Sendable {
+    weak let session: PlaybackSession?
+    init(session: PlaybackSession) { self.session = session }
+}
+```
 
-`Observations { }` provides transactional observation of `@Observable` types
-via `AsyncSequence`.
+## Transactional observation (SE-0475)
 
 ```swift
-for await _ in Observations { model.count } {
-    print("Count changed to \(model.count)")
+for await pending in Observations({ uploads.pendingCount }) {
+    badge.update(pending)
 }
 ```
 
-## Global and Static State
+Each iteration sees a consistent snapshot of the properties the closure read.
+
+## Global and static state
 
-Global and static variables are prone to data races. The most common protection
-is `@MainActor`:
+Globals and statics are shared by definition, so they race unless isolated. The
+usual answer is the main actor:
 
 ```swift
 @MainActor
-final class StickerLibrary {
-    static let shared = StickerLibrary()  // protected by MainActor
+final class FeatureFlags {
+    static let shared = FeatureFlags()
+    var experiments: Set<String> = []
 }
 ```
 
-With default MainActor isolation (SE-0466), this annotation is implicit.
+Under SE-0466 the `@MainActor` is inferred and can be deleted.
 
-## Migration and Build Settings
+## Build settings and migration
 
-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.
+- Every approachable-concurrency feature is opt-in.
+- Xcode 26: Build Settings, section Swift Compiler - Concurrency.
+- SwiftPM: `swiftSettings` on each target, through the `SwiftSetting` API.
 
-For Swift 6 language mode, strict concurrency checking is complete and
-data-race diagnostics are errors. Use Targeted or Minimal only as Swift 5
-migration settings while preparing code for Swift 6.
+```swift
+.target(
+    name: "PlayerApp",
+    swiftSettings: [
+        .defaultIsolation(MainActor.self),
+        .enableUpcomingFeature("NonisolatedNonsendingByDefault"),
+        .enableUpcomingFeature("InferIsolatedConformances")
+    ]
+)
+```
 
-Swift 6.2 includes migration tooling to help make necessary code changes
-automatically. See swift.org/migration for details.
+- Swift 6 language mode means complete checking with data-race errors.
+  Targeted and Minimal exist only for Swift 5 targets preparing to switch.
+- Swift 6.2 ships migration tooling that can apply many of the required edits
+  automatically; see swift.org/migration.
 
-## Summary
+## The progression
 
-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`.
+1. Start with main-actor-by-default code: nothing runs in parallel, so nothing
+   races.
+2. Let async functions run where they are called: still no parallelism.
+3. When profiling shows a need, move specific functions to the pool with
+   `@concurrent`.

package/pipeline/skills/shared/external/swift-concurrency/references/diagnostics.md

@@ -1,52 +1,64 @@
 # Concurrency Diagnostics
 
-Common Swift concurrency compiler warnings and errors with their fixes.
-
-## Diagnostic → Fix Reference
-
-| Diagnostic | Cause | Fix |
-| --- | --- | --- |
-| `Sending 'x' risks causing data races` | Passing a non-Sendable value across isolation boundaries | Make the type `Sendable`, use `sending` parameter, or restructure to avoid the crossing |
-| `Capture of 'x' with non-sendable type in a @Sendable closure` | Closure captures non-Sendable value | Make type Sendable, copy the value, or use an actor |
-| `Non-sendable type 'X' returned by implicitly asynchronous call` | Returning non-Sendable from cross-isolation call | Make return type Sendable or keep work on same isolation |
-| `Main actor-isolated property 'x' can not be mutated from a nonisolated context` | Accessing @MainActor state from non-main context | Add `@MainActor` to caller, use `await MainActor.run { }`, or restructure |
-| `Call to main actor-isolated function in a synchronous nonisolated context` | Calling @MainActor function without await | Add `await`, annotate caller `@MainActor`, or use `.task { }` in SwiftUI |
-| `Actor-isolated property 'x' can not be referenced from a nonisolated context` | Accessing actor state without await | Add `await` or move code into the actor |
-| `Type 'X' does not conform to protocol 'Sendable'` | Stored properties aren't all Sendable | Prefer an immutable value type or immutable snapshot; otherwise use actor isolation or synchronization. Use `@unchecked Sendable` only with documented internal locking |
-| `Passing closure as a 'sending' parameter risks causing data races` | Closure captures values that could race | Ensure captures are Sendable or don't escape the isolation domain |
-| `Task-isolated value of type 'X' passed as a strongly transferred parameter` | Moving a value out of a task unsafely | Copy the value or use `sending` return |
-| `Global variable 'x' is not concurrency-safe` | Mutable global without isolation | Add `@MainActor`, make it `nonisolated(unsafe)` (with justification), or use actor |
-
-## Swift 6.2 Approachable Concurrency Changes
-
-With `UpcomingFeature.InferSendableFromCaptures` (Swift 6.2):
-- Closures infer Sendable from their captures (fewer explicit annotations needed)
-- `nonisolated(nonsending)` is the new default for async functions (SE-0461)
-- `@concurrent` marks functions that intentionally run off-actor
-
-## Strict Concurrency Adoption Strategy
-
-1. **Know the language mode.** In Swift 6 / 6.3 language mode, strict
-   concurrency checking is complete and data-race diagnostics are errors.
-2. **Use migration levels only before Swift 6.** In Swift 5 language mode,
-   `Targeted` or `Minimal` can stage adoption before moving to `Complete`.
-3. **Fix diagnostics bottom-up.** Start with leaf types (models, DTOs), then
-   services, then UI.
-4. **Use `@preconcurrency import`** temporarily for third-party modules that
-   haven't adopted Sendable  -  document removal plan.
-
-For Sendable diagnostics, check this order before adding annotations:
-immutable `struct` / `enum`, immutable `let` properties on a `final` class,
-actor or global-actor isolation, a small synchronized wrapper, then
-`@unchecked Sendable` only when the compiler cannot see a proven lock invariant.
-
-## Runtime Diagnostics
-
-Enable the Thread Sanitizer (`-sanitize=thread`) to catch data races at runtime that the compiler can't statically prove.
-
-Xcode: Edit Scheme → Run → Diagnostics → Thread Sanitizer.
-
-Common TSan findings in concurrent code:
-- Simultaneous reads and writes to `Dictionary` or `Array` without actor protection
-- Delegate callbacks arriving on unexpected queues
-- Completion handlers racing with synchronous property access
+## Compiler messages and their fixes
+
+| Message | What happened | Fix, in order of preference |
+|---|---|---|
+| `Sending 'x' risks causing data races` | A non-`Sendable` value crosses an isolation boundary | Make the type `Sendable`; take it as a `sending` parameter; restructure so it does not cross |
+| `Capture of 'x' with non-sendable type 'T' in a '@Sendable' closure` | A `@Sendable` closure captures a non-`Sendable` value | Make the type `Sendable`; capture a copy of the data you need; move the state into an actor |
+| `Non-sendable type 'T' returned by implicitly asynchronous call` | A non-`Sendable` result crosses isolation on the way back | Return a `Sendable` type, or do the work in the caller's isolation |
+| `Main actor-isolated property 'x' can not be mutated from a nonisolated context` | Main-actor state written from nonisolated code | Mark the caller `@MainActor`; restructure; as a last step, `await MainActor.run { }` inside an async caller that must stay nonisolated |
+| `Call to main actor-isolated instance method 'f()' in a synchronous nonisolated context` | Sync nonisolated code calls main-actor code | Mark the caller `@MainActor`; make it async and `await`; in SwiftUI start the call from `.task { }` |
+| `Actor-isolated property 'x' can not be referenced from a nonisolated context` | Code outside the actor touches its state | `await` the access, or move the code into the actor |
+| `Type 'T' does not conform to the 'Sendable' protocol` | Some stored properties are not `Sendable` | Use an immutable value or a snapshot; then actor isolation or a lock; `@unchecked Sendable` only when an internal lock exists and is written down |
+| `Passing closure as a 'sending' parameter risks causing data races` | The closure captures values that may race | Capture only `Sendable` values, or keep the captured state inside one isolation domain |
+| `Task-isolated value of type 'T' passed as a strongly transferred parameter` | A value is moved out of a task that still uses it | Pass a copy, or return it as `sending` |
+| `Var 'x' is not concurrency-safe because it is nonisolated global shared mutable state` | A mutable global has no isolation | `@MainActor`; move it into an actor; make it a `let` of a `Sendable` type; `nonisolated(unsafe)` only with a written justification |
+
+Exact wording varies between compiler releases; match on the key phrase.
+
+## Effects of the 6.2 approachable settings
+
+- `NonisolatedNonsendingByDefault` (SE-0461): async functions without explicit
+  isolation run as `nonisolated(nonsending)`, on the caller's actor.
+- `@concurrent` marks the functions that should leave the caller on purpose.
+- `InferSendableFromCaptures` (SE-0418): closures and key paths become
+  `Sendable` when everything they capture is. It is already on in Swift 6
+  language mode; in Swift 5 mode it is one of the upcoming features the
+  Approachable Concurrency setting enables. Either way it removes explicit
+  `@Sendable` annotations.
+
+## Adopting strict checking
+
+- Swift 6 language mode, including 6.3, always runs complete checking and
+  reports data-race problems as errors.
+- The staged levels exist only before the switch: a Swift 5 target can go
+  through `Minimal` or `Targeted` on the way to `Complete`, then move to the
+  Swift 6 language mode.
+- Fix from the leaves upward: models and DTOs first, then services, then the
+  UI layer. Leaf fixes often make the upper errors vanish.
+- A third-party module without `Sendable` annotations can be imported with
+  `@preconcurrency import` for now. Write down when and how it will be removed.
+
+### Order of fixes for a Sendable error
+
+1. An immutable `struct` or `enum`.
+2. A `final class` whose stored properties are all `let`.
+3. Isolation to an actor or a global actor.
+4. A small wrapper that synchronizes access with a lock.
+5. `@unchecked Sendable`, only when a lock invariant exists that the compiler
+   cannot see, and with that invariant written next to the declaration.
+
+## Races the compiler cannot see: Thread Sanitizer
+
+Thread Sanitizer (`-sanitize=thread`) detects data races at run time, including
+ones inside code that static checking cannot reason about. In Xcode, open the
+scheme editor, select the Run action, and tick Thread Sanitizer on the
+Diagnostics tab.
+
+It typically reports:
+
+- a `Dictionary` or `Array` read and written from several threads with no
+  actor or lock around it;
+- delegate methods called on a queue the code did not expect;
+- completion handlers writing a property while synchronous code reads it.