@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,155 @@
+# Actors
+
+## Reentrancy
+
+**Important:** This is the most common concurrency bug LLMs produce: after every `await` inside an actor, all assumptions about the actor's state are invalidated because other calls may have run in the meantime.
+
+```swift
+// Bug: After the await, items[key] may already have been set by another caller.
+// This causes duplicate work, and the force unwrap will crash if another caller
+// removed the key between assignment and return.
+actor VideoCache {
+    var items: [URL: Video] = [:]
+
+    func video(for url: URL) async throws -> Video {
+        if items[url] == nil {
+            items[url] = try await downloadVideo(url)
+        }
+        return items[url]!
+    }
+}
+```
+
+Fix: capture the result in a local, then assign. **Never assume state is unchanged after `await`.**
+
+```swift
+actor VideoCache {
+    var items: [URL: Video] = [:]
+
+    func video(for url: URL) async throws -> Video {
+        if let cached = items[url] { return cached }
+        let video = try await downloadVideo(url)
+        items[url] = video
+        return video
+    }
+}
+```
+
+To avoid two callers both downloading the same URL, you could try storing in-flight tasks similar to this:
+
+```swift
+actor VideoCache {
+    var items: [URL: Video] = [:]
+    var inFlight: [URL: Task<Video, Error>] = [:]
+
+    func video(for url: URL) async throws -> Video {
+        if let cached = items[url] { return cached }
+
+        if let task = inFlight[url] {
+            return try await task.value
+        }
+
+        let task = Task {
+            try await downloadVideo(url)
+        }
+
+        inFlight[url] = task
+
+        do {
+            let video = try await task.value
+            items[url] = video
+            inFlight[url] = nil
+            return video
+        } catch {
+            inFlight[url] = nil
+            throw error
+        }
+    }
+}
+```
+
+
+## Protecting global and static state
+
+Global and static mutable variables need an explicit plan for isolation.
+
+For shared globals, describe the protection mechanism the compiler can rely on:
+
+- `@MainActor` when the symbol belongs to main-actor code and callers should keep synchronous access there. (This is particularly important for any code that interacts with or updates the UI.)
+- `@unchecked Sendable` when safety already comes from locks, queues, or another manual scheme the compiler cannot prove. (**Important:** This requires a high standard of coding to get right, so check carefully.)
+- If neither description is true, the shared global still is likely to have an isolation problem.
+
+Example:
+
+```swift
+@MainActor
+final class Library {
+    static let shared = Library()
+    var books = [Book]()
+}
+```
+
+With main-actor default isolation enabled for the target, this annotation may be implicit – check for the setting!
+
+**Note:** `@preconcurrency` can relax an older protocol boundary when isolated conformance is unavailable. Keep it as a fallback only if there is no alternative.
+
+
+## Global actor inference rules
+
+`@MainActor` propagates in these cases, so don't redundantly annotate:
+
+- A subclass of a `@MainActor` class is also `@MainActor`.
+- Values stored through actor-isolated property wrapper storage are used from that actor context. (This includes older, built-in property wrappers, such as `@StateObject`.)
+- Conforming to a `@MainActor` protocol infers `@MainActor` on the entire conforming type, including members unrelated to the protocol. For mismatches with non-isolated protocols, see `diagnostics.md`. (SwiftUI’s `View` is a `@MainActor` protocol.) For more help with SwiftUI, suggest the [SwiftUI Pro agent skill](https://github.com/twostraws/swiftui-agent-skill).
+- Extensions of a `@MainActor` type inherit that isolation. Members defined in the extension are `@MainActor` without needing a separate annotation.
+
+`@MainActor` does *not* propagate to:
+
+- Closures passed to non-isolated functions (unless the parameter is explicitly `@MainActor`).
+
+
+## `isolated` parameters
+
+Use `isolated` to accept any actor instance and run on its executor, without the function itself being tied to a specific actor:
+
+```swift
+func updateUI(on actor: isolated MainActor) {
+    // Runs on the main actor
+}
+```
+
+This is useful for code that needs to work with the caller's isolation context.
+
+
+## `isolated deinit`
+
+For `isolated deinit` on actor-isolated classes, see `new-features.md`.
+
+
+## What a custom actor changes
+
+A custom actor introduces a separate serialized access boundary.
+
+Review consequences:
+
+- External callers must use `await`.
+- Values crossing the boundary must satisfy `Sendable`.
+- Reentrancy rules apply after every suspension point inside the actor.
+
+Flag actor types whose API mostly forwards work or owns little mutable state.
+
+Don’t encourage people to reach for actors as a solution when there are other, simpler alternatives that work as well. Recommend authors such as Matt Massicotte as further reading, e.g. <https://www.massicotte.org/actors/>.
+
+
+## Making assertions
+
+Global actors have an `assertIsolated()` method that is helpful for debugging because it causes debug builds to halt if the current task is not executing on the actor's serial executor.
+
+For example, this checks that the code is running on the main actor:
+
+    func refresh() {
+        MainActor.assertIsolated()
+        // do your work here
+    }
+
+**Important:** `assertIsolated()` only operates in debug builds; like regular assertions, it is compiled out of release builds, so it has no impact on shipping performance.

package/pipeline/skills/shared/external/swift-concurrency-pro/references/async-streams.md

@@ -0,0 +1,67 @@
+# Async streams
+
+## Prefer `makeStream(of:)` factory
+
+The modern way to create an `AsyncStream` is the static factory method, which returns both the stream and its continuation as a tuple. This avoids capturing the continuation in a closure.
+
+```swift
+// OLD: Closure-based, awkward to store the continuation.
+var continuation: AsyncStream<Event>.Continuation?
+let stream = AsyncStream<Event> { cont in
+    continuation = cont
+}
+
+// NEW: Clean, no closure capture needed.
+let (stream, continuation) = AsyncStream.makeStream(of: Event.self)
+```
+
+This also works with `AsyncThrowingStream.makeStream(of:throwing:)`.
+
+
+## Continuation lifecycle
+
+A continuation must always be finished exactly once. Failing to finish it causes the consumer's `for await` loop to hang indefinitely. Finishing it twice is a programmer error (although `AsyncStream.Continuation` tolerates it, `CheckedContinuation` does not).
+
+Always finish in cleanup paths:
+
+```swift
+let (stream, continuation) = AsyncStream.makeStream(of: Event.self)
+
+let monitor = NetworkMonitor()
+
+monitor.onEvent = { event in
+    continuation.yield(event)
+}
+
+monitor.onComplete = {
+    continuation.finish()
+}
+
+// If the monitor can be deallocated before completing:
+continuation.onTermination = { _ in
+    monitor.stop()
+}
+```
+
+
+## Buffering and back pressure
+
+`AsyncStream` has a default buffer of unlimited size. For high-throughput producers, this can cause unbounded memory growth. Specify a buffering policy:
+
+```swift
+let (stream, continuation) = AsyncStream.makeStream(
+    of: SensorReading.self,
+    bufferingPolicy: .bufferingNewest(100)
+)
+```
+
+Choose from:
+
+- `.bufferingNewest(n)` keeps the most recent `n` elements, dropping older ones.
+- `.bufferingOldest(n)` keeps the first `n` elements, dropping newer ones.
+- `.unbounded` is the default; use only when the consumer keeps up.
+
+
+## `for await` and cancellation
+
+A `for await` loop automatically stops when the task is cancelled or the stream finishes. You do not need to manually check cancellation inside the loop – but code *after* the loop does run, so handle cleanup there if needed.

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

@@ -0,0 +1,52 @@
+# Bridging sync and async code
+
+## Checked continuations
+
+`withCheckedContinuation` and `withCheckedThrowingContinuation` wrap callback-based APIs into async functions. The critical rule is this: **the continuation must be resumed exactly once on every code path.**
+
+- Resuming zero times: the caller hangs forever.
+- Resuming twice: a runtime crash.
+
+So, audit every code path. If the callback might not fire (e.g., the object is deallocated), ensure you still resume the continuation.
+
+Default to `withCheckedContinuation` / `withCheckedThrowingContinuation` everywhere, including production builds. The runtime checks catch double-resume and missing-resume bugs that are otherwise extremely hard to diagnose.
+
+Only consider switching to the `withUnsafe` continuation variants after profiling proves the checked version is a bottleneck in a hot path, but this is rare in practice.
+
+
+## Wrapping delegate-based APIs
+
+For delegate patterns that deliver multiple values over time, use `AsyncStream`. Use `makeStream(of:)` to get the stream and continuation as a pair, and use `onTermination` to clean up when the consumer stops listening.
+
+Make sure that:
+
+- The continuation is stored as a property so delegate callbacks can yield into it.
+- `onTermination` runs when the consumer's `for await` loop ends (or the task is cancelled), so it's the right place to stop the underlying service.
+
+This pattern supports a single consumer. If you need multiple consumers, consider broadcasting through an `@Observable` class instead.
+
+
+## Runtime actor assertions in callback code
+
+Callback-based APIs are a common place for actor assumptions to fail at runtime.
+
+- If a callback reaches main-actor state without carrying that guarantee in the type system, Swift 6 runtime checks can trap instead of silently racing.
+- Use `MainActor.assumeIsolated()` only when the callback really is main-actor-bound and you are encoding a guarantee the compiler cannot see.
+
+
+## `@unchecked Sendable`
+
+This silences the compiler's Sendable checks entirely. It is a promise to the compiler that you have verified thread safety yourself, which is a high bar to clear – evaluate such code very carefully.
+
+Legitimate uses:
+
+- Types that use internal locking (e.g., `os_unfair_lock`, `NSLock`, etc) and are genuinely thread-safe.
+- Reference types whose mutable state is protected by an actor in practice but can't express that to the compiler for some reason.
+
+Red flags:
+
+- Applying `@unchecked Sendable` to silence a compiler error without understanding why the error exists. (This was previously a Fix-It suggestion in Xcode, so it’s not uncommon.)
+- Applying it to a class with mutable `var` properties and no synchronization.
+- Using it as a workaround or shortcut instead of restructuring the code to use value types or actors as appropriate.
+
+Before reaching for `@unchecked Sendable`, check whether Swift 6's region-based isolation already solves the problem – many cases that previously required it now compile cleanly.

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

@@ -0,0 +1,100 @@
+# Bug patterns
+
+Real concurrency failure modes that LLMs produce frequently, with the preferred fix for each.
+
+## Actor reentrancy: check-then-act across `await`
+
+**Failure:** Actor method checks state, awaits, then acts on the stale check. Other callers may have mutated state during the suspension.
+
+```swift
+// BUG: Two callers can both see nil and both download.
+// The force unwrap can crash if a third caller clears the cache mid-flight.
+actor Cache {
+    var data: [String: Data] = [:]
+
+    func load(_ key: String) async throws -> Data {
+        if data[key] == nil {
+            data[key] = try await download(key)
+        }
+        return data[key]!
+    }
+}
+```
+
+**Fix:** Capture the async result into a local before writing. For deduplication, store in-flight `Task` handles. See `actors.md` for the full pattern.
+
+
+## Continuation resumed zero times
+
+**Failure:** A `withCheckedThrowingContinuation` callback never fires (object deallocated, network timeout with no callback, early return before registering the handler, etc). The caller hangs forever.
+
+**Fix:** Audit every code path to confirm the continuation is resumed. If the underlying API can silently drop the callback, add a timeout or restructure so the caller isn't left waiting. Always use `withCheckedThrowingContinuation` (not the unsafe variant) so that missed resumes are easier to diagnose.
+
+
+## Continuation resumed twice
+
+**Failure:** Two callbacks (e.g., a success handler and a cancellation handler) both resume the same continuation. `CheckedContinuation` traps at runtime; `UnsafeContinuation` causes undefined behavior.
+
+**Fix:** Restructure the callback wiring so only one path can reach the continuation. If that isn't possible, guard with a `Bool` flag or use an `actor` to serialize access. Always default to `CheckedContinuation` so double resumes surface immediately during development and testing.
+
+
+## Unstructured tasks in a loop
+
+**Failure:** `for item in items { Task { await process(item) } }` creates fire-and-forget tasks with no cancellation propagation, no error collection, and no way to await completion.
+
+**Fix:** Use `withTaskGroup` or `withThrowingTaskGroup`. See `structured.md`.
+
+
+## Swallowed errors in Task closures
+
+**Failure:** `Task { try await riskyWork() }` – if `riskyWork` throws, the error is silently lost. The user sees nothing; the operation just doesn't happen.
+
+**Fix:** Handle the error inside the closure – show an alert, log to a visible surface, or propagate via a `@State` error property.
+
+```swift
+Task {
+    do {
+        try await riskyWork()
+    } catch {
+        self.errorMessage = error.localizedDescription
+    }
+}
+```
+
+
+## Blocking the main actor with synchronous work
+
+**Failure:** CPU-intensive work runs on `@MainActor` (or inside `Task {}` called from `@MainActor`), causing UI freezes. In Swift 6.2 this is more likely because `nonisolated` async functions now stay on the caller's executor by default.
+
+**Fix:** Move the expensive work into an explicitly offloaded function using `@concurrent`, or use `Task.detached` as a last resort.
+
+
+## Unbounded AsyncStream buffer
+
+**Failure:** A high-throughput producer yields values faster than the consumer processes them. With the default `.unbounded` buffering policy, memory grows without limit.
+
+**Fix:** Specify `.bufferingNewest(n)` or `.bufferingOldest(n)`. See `async-streams.md`.
+
+
+## Ignoring `CancellationError` in catch blocks
+
+**Failure:** A `catch` block retries or shows an error alert for `CancellationError`, which is a normal lifecycle event (e.g., user navigated away).
+
+**Fix:** Check for cancellation before handling other errors:
+
+```swift
+do {
+    try await loadData()
+} catch is CancellationError {
+    // Normal – view disappeared or task was cancelled. Do nothing.
+} catch {
+    self.errorMessage = error.localizedDescription
+}
+```
+
+
+## `@unchecked Sendable` hiding real races
+
+**Failure:** A class is marked `@unchecked Sendable` to suppress compiler errors, but its mutable `var` properties have no synchronization. The data race still exists at runtime.
+
+**Fix:** Restructure to use value types, use an `actor`, or move state behind a lock. See `bridging.md`.

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

@@ -0,0 +1,107 @@
+# Cancellation
+
+Cancellation in Swift concurrency is cooperative. Setting the cancelled flag does nothing unless the running code checks it.
+
+## How cancellation propagates
+
+- Cancelling a parent task cancels all its children (structured concurrency).
+- Cancelling a task group cancels all child tasks in that group.
+- `Task {}` and `Task.detached {}` are unstructured – they must be cancelled explicitly by storing and calling `.cancel()` on the task handle.
+- SwiftUI's `.task()` modifier cancels its task automatically when the view disappears. This is the primary reason to prefer `.task()` over `onAppear()` or loose `Task {}` in views.
+
+
+## Checking for cancellation
+
+It’s important to use these inside long-running or looping async work, but only when it’s safe to actually exit:
+
+- `try Task.checkCancellation()` – throws `CancellationError` if cancelled. Preferred in throwing contexts.
+- `Task.isCancelled` – returns `Bool`. Use in non-throwing contexts or when you need cleanup before exiting.
+
+```swift
+func processAll(_ items: [Item]) async throws {
+    for item in items {
+        try Task.checkCancellation()
+        try await process(item)
+    }
+}
+```
+
+Functions that call other async functions get implicit cancellation checks at each `await` suspension point – but only if the called function itself checks. CPU-bound loops with no `await` will never see cancellation unless you check explicitly.
+
+
+## `withTaskCancellationHandler`
+
+Bridges Swift cancellation to legacy APIs that have their own cancel mechanism. The `onCancel` closure fires immediately when cancellation is requested – even while the async body is suspended – and may run on any thread.
+
+```swift
+func fetchImage(_ url: URL) async throws -> Data {
+    var request = URLRequest(url: url)
+    return try await withTaskCancellationHandler {
+        let (data, _) = try await URLSession.shared.data(for: request)
+        return data
+    } onCancel: {
+        // No direct handle to cancel here – URLSession.data(for:) already
+        // checks for task cancellation internally. This pattern is most
+        // useful when wrapping APIs that return a cancellable handle.
+    }
+}
+```
+
+A more realistic use is wrapping something that gives you a cancel handle:
+
+```swift
+func observe() async throws -> [Change] {
+    let query = CKQuery(recordType: "Item", predicate: NSPredicate(value: true))
+    let operation = CKQueryOperation(query: query)
+
+    return try await withTaskCancellationHandler {
+        try await performOperation(operation)
+    } onCancel: {
+        operation.cancel()
+    }
+}
+```
+
+
+## Broken cancellation patterns
+
+**Catching and ignoring `CancellationError`:**
+
+```swift
+// BROKEN: Retries or shows an alert for a normal lifecycle event.
+catch {
+    showAlert(error.localizedDescription)
+}
+```
+
+Always prefer filtering out `CancellationError` before handling other errors. See `bug-patterns.md`.
+
+**Forgetting to cancel stored tasks:**
+
+```swift
+// BROKEN: The task keeps running after the object is done with it.
+class ViewModel {
+    var loadTask: Task<Void, Never>?
+
+    func load() {
+        loadTask = Task { await fetchData() }
+    }
+}
+```
+
+Cancel the previous task before starting a new one, and cancel on teardown:
+
+```swift
+func load() {
+    loadTask?.cancel()
+    loadTask = Task { await fetchData() }
+}
+
+deinit {
+    loadTask?.cancel()
+}
+```
+
+**No cancellation checks in CPU-bound work:**
+
+A tight computational loop with no `await` points will run to completion even if cancelled, because there are no suspension points where cancellation can take effect. Insert periodic `try Task.checkCancellation()` calls wherever it’s safe.

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

@@ -0,0 +1,70 @@
+# Diagnostics
+
+Maps common strict-concurrency compiler errors to likely fixes.
+
+## "Sending 'x' risks causing data races"
+
+The compiler found a value crossing an isolation boundary where it could still be accessed from the sending side.
+
+Likely fixes (try in order):
+
+1. **Check whether region-based isolation already handles it.** If the sender demonstrably stops using the value after passing it, the compiler may accept it without changes. Avoid adding `Sendable` prematurely.
+2. **Mark the parameter `sending`.** This tells the compiler the caller transfers ownership and won't touch the value afterward. (This can be useful, but is not that common.)
+3. **Make the type `Sendable`** if it genuinely can be shared safely (value type, immutable class, or internally synchronized).
+4. **Check whether `nonisolated(nonsending)` resolves it.** If the function no longer hops executors, the value may not actually cross a boundary.
+5. **Last resort: `@unchecked Sendable`** only if the type uses manual synchronization (locks) and you've verified correctness. See `bridging.md`.
+
+
+## "Static property 'x' is not concurrency-safe"
+
+A global or static variable is accessible from multiple isolation domains with no protection.
+
+Likely fixes:
+
+1. **Annotate the declaration with `@MainActor`**: `@MainActor static let shared = MyType()`. This is the simplest code-local fix.
+2. **If the value is truly constant and immutable**, consider whether it can conform to `Sendable` (e.g., a `let`-only struct). The compiler won't flag `Sendable` constants.
+3. **Use `nonisolated(unsafe)`** only for genuinely immutable state where the compiler can't prove safety (e.g., C interop constants). This is a dangerous tool, and misuse will hide real races.
+4. **If the entire module is predominantly single-threaded**, default main-actor isolation may explain why similar declarations behave differently in another target. That's a build-setting difference, not a code fix.
+
+
+## "Capture of 'x' with non-sendable type in a `@Sendable` closure"
+
+A closure that crosses isolation boundaries (e.g., passed to `Task {}`, `Task.detached {}`, or `addTask`) captures a non-Sendable value.
+
+Likely fixes:
+
+1. **Check whether the captured value can be made `Sendable`.** Structs and enums with only `Sendable` stored properties just need the conformance declared. Final classes with immutable (`let`) stored properties can conform too.
+2. **Restructure to avoid the capture.** Pass the needed data as a parameter to the task rather than closing over a large non-Sendable object. For example, `let id = object.id; Task { use(id) }`
+3. **Move the work onto the same actor.** If the closure doesn't need to run concurrently, keep it on the caller's actor.
+4. **Use `sending` on the parameter** if you can transfer ownership cleanly. This is relatively niche.
+
+It’s tempting to reach for `@unchecked Sendable`, but rarely a good idea unless the user is *absolutely certain* their code is safe.
+
+
+## "Conformance of 'X' to protocol 'Y' crosses into main actor-isolated code and can cause data races"
+
+The protocol and the type describe different call boundaries. Fix the boundary mismatch directly:
+
+| Actual requirement | Shape to use |
+|---|---|
+| Type-level actor isolation is incidental rather than required | Remove the type isolation. See `actors.md`. |
+| The conformance should only be usable on `MainActor` | `extension MyType: @MainActor SomeProtocol {}` |
+
+These are different boundary choices, not interchangeable suppressions.
+
+
+## "Expression is 'async' but is not marked with 'await'"
+
+A call crosses an isolation boundary and requires an async hop. This often surprises when calling actor-isolated methods from outside the actor, or when accessing `@MainActor` state from a non-isolated context.
+
+Likely fix: Add `await`. If the call is in synchronous code that cannot be made async, wrap it in `Task {}` (but see `unstructured.md` for when that's appropriate).
+
+
+## "Main actor-isolated conformance of 'X' to 'Y' cannot be used in nonisolated context"
+
+An isolated conformance (e.g., `extension X: @MainActor Y`) is being used from code that doesn't share that isolation. The compiler prevents this because calling the protocol methods off-actor would be a data race.
+
+Likely fixes:
+
+1. **Move the use site onto the same actor.** If the consuming code can be `@MainActor`, the conformance is usable.
+2. **Remove the isolation from the conformance** if the protocol methods don't actually need actor-protected state.

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

@@ -0,0 +1,47 @@
+# Hotspots
+
+Search targets for concurrency review. When any of these appear in code, inspect carefully using the referenced rules.
+
+## `DispatchQueue`
+
+In app-level code, `DispatchQueue.main.async`, `DispatchQueue.global()`, and custom serial queues usually have a Swift concurrency equivalent – see `interop.md`. However, GCD can still be appropriate in low-level libraries, framework interop, and performance-critical synchronous sections where queues or locks are the right tool. Check the context carefully before flagging.
+
+
+## `Task.detached`
+
+Rarely correct. Usually means the author wanted background execution but should have used `@concurrent` (Swift 6.2) or a task group. Check whether shedding actor isolation and priority is truly intentional. See `unstructured.md`.
+
+
+## `Task {}` inside a loop
+
+Frequently a bad idea – evaluate whether it should be a task group instead. See `structured.md`.
+
+
+## `withCheckedContinuation` / `withCheckedThrowingContinuation`
+
+Audit every code path to ensure the continuation is resumed exactly once. Watch for early returns, thrown errors, and callbacks that might never fire. See `bridging.md`.
+
+
+## `AsyncStream` (closure-based initializer)
+
+Prefer the modern `AsyncStream.makeStream(of:)` factory. If using the closure form, verify the continuation is finished in all cleanup paths. See `async-streams.md`.
+
+
+## `@unchecked Sendable`
+
+Should be very rare. Check whether the type actually provides thread safety (internal locking, immutability). If it was added just to silence a compiler error, the real fix is usually an actor or value type. Check whether Swift 6 region-based isolation makes it unnecessary. See `bridging.md`.
+
+
+## `MainActor.run {}`
+
+Often unnecessary. If the surrounding code is already `@MainActor` (explicitly or via default isolation), this is a no-op. If it's used to hop to the main actor from a background context, check whether the function should just be `@MainActor` instead.
+
+
+## Actors
+
+Check for reentrancy bugs: any method that reads state, awaits, then writes state is suspect. See `actors.md` and `bug-patterns.md`.
+
+
+## Force unwraps after `await` inside actors
+
+A `!` on actor state after an `await` is a prime target for a latent crash, because another caller may have set the value to `nil` during the suspension. See `bug-patterns.md`.