@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-concurrency/SKILL.md

@@ -1,430 +1,382 @@
 ---
 name: swift-concurrency
-description: "Swift concurrency language reference and migration: Sendable and actor-isolation diagnostics, approachable concurrency (SE-0466 default MainActor, @concurrent, nonisolated(nonsending), Task.immediate), actors, TaskGroup and the Swift 6 strict-mode migration. Use when fixing strict-concurrency errors or migrating; for the smallest fix to one diagnostic use swift-concurrency-expert, for a file-by-file review swift-concurrency-pro."
+description: "Swift 6.2+ concurrency: actor isolation, Sendable, sending, approachable concurrency (SE-0466 default MainActor, @concurrent, nonisolated(nonsending), Task.immediate), TaskGroup, cancellation, AsyncStream, bridging callbacks and GCD, Swift 6 migration. Use when answering concurrency questions, reading Sendable or isolation diagnostics, or repairing strict-concurrency errors. Not for single-diagnostic fixes or per-file reviews."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Swift Concurrency
 
-Review, fix, and write concurrent Swift code targeting Swift 6.3+. Apply actor
-isolation, Sendable safety, and modern concurrency patterns with minimal
-behavior changes.
+Baseline: Swift 6.3 compilers and later. The aim of every change made with this
+skill is data-race safety through isolation and `Sendable`, reached with the
+smallest possible change in behavior. Features newer than Swift 6.0 name the
+release or proposal that introduced them.
+
+Not for the smallest fix to a single diagnostic (use `swift-concurrency-expert`)
+or a file-by-file review pass (use `swift-concurrency-pro`).
 
 ## Contents
 
-- [Triage Workflow](#triage-workflow)
-- [Swift 6.2 Language Changes](#swift-62-language-changes)
-- [Actor Isolation Rules](#actor-isolation-rules)
-- [Sendable Rules](#sendable-rules)
-- [Structured Concurrency Patterns](#structured-concurrency-patterns)
-- [Task Cancellation](#task-cancellation)
-- [Actor Reentrancy](#actor-reentrancy)
-- [AsyncSequence and AsyncStream](#asyncsequence-and-asyncstream)
-- [`@Observable and Concurrency`](#observable-and-concurrency)
-- [Synchronization Primitives](#synchronization-primitives)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
+- [Triage workflow](#triage-workflow)
+- [Approachable concurrency in Swift 6.2](#approachable-concurrency-in-swift-62)
+- [Isolation rules](#isolation-rules)
+- [Sendable rules](#sendable-rules)
+- [Tasks and structured concurrency](#tasks-and-structured-concurrency)
+- [Cancellation](#cancellation)
+- [Actor reentrancy](#actor-reentrancy)
+- [Streams and continuations](#streams-and-continuations)
+- [Observable models](#observable-models)
+- [Locks and atomics](#locks-and-atomics)
+- [Choosing how code moves between contexts](#choosing-how-code-moves-between-contexts)
+- [Mistakes to catch](#mistakes-to-catch)
+- [Review checklist](#review-checklist)
 - [References](#references)
 
-## Triage Workflow
-
-When diagnosing a concurrency issue, follow this sequence:
-
-### Step 1: Capture context
+## Triage workflow
 
-- Copy the exact compiler diagnostic(s) and the offending symbol(s).
-- Identify the project's concurrency settings:
-  - Swift language version (must be 6.2+).
-  - Whether Approachable Concurrency is enabled.
-  - Whether Default Actor Isolation is set to `MainActor`.
-  - Swift 6 strict concurrency status: complete/errors in Swift 6 language mode;
-    Complete / Targeted / Minimal only when auditing Swift 5 migration settings.
-- Determine the current actor context of the code (`@MainActor`, custom `actor`,
-  `nonisolated`) and whether a default isolation mode is active.
-- Confirm whether the code is UI-bound or intended to run off the main actor.
+**1. Collect the facts before editing.**
 
-### Step 2: Apply the smallest safe fix
+- Copy the compiler message word for word and note every symbol it names.
+- Find the Swift language version. This workflow assumes 6.2 or newer.
+- Check two build settings separately: is Approachable Concurrency on, and is
+  Default Actor Isolation set to `MainActor`?
+- In Swift 6 language mode strict checking is always complete and every
+  data-race diagnostic is an error. The Minimal, Targeted and Complete levels
+  only matter when you audit a target still in Swift 5 mode.
+- Work out where the failing code is isolated today: `@MainActor`, a custom
+  `actor`, or `nonisolated`, and whether a module-wide default applies.
+- Decide whether the code belongs to the UI or is meant to run away from the
+  main actor.
 
-Prefer edits that preserve existing behavior while satisfying data-race safety.
+**2. Make the smallest change that is still safe.** Keep behavior as it is.
 
-| Situation | Recommended fix |
+| Situation | Change |
 |---|---|
-| UI-bound type | Annotate the type or relevant members with `@MainActor`. |
-| Protocol conformance on MainActor type | Use an isolated conformance: `extension Foo: @MainActor Proto`. |
-| Global / static state | Protect with `@MainActor` or move into an actor. |
-| Background work needed | Use a `@concurrent` async function on a `nonisolated` type. |
-| Sendable error | Prefer immutable value types. Add `Sendable` only when correct. |
-| Cross-isolation callback | Use `sending` parameters (SE-0430) for finer control. |
-
-### Step 3: Verify
-
-- Rebuild and confirm the diagnostic is resolved.
-- Check for new warnings introduced by the fix.
-- Ensure no unnecessary `@unchecked Sendable` or `nonisolated(unsafe)` was added.
-
-## Swift 6.2 Language Changes
-
-Swift 6.2 introduces "approachable concurrency" -- a set of language changes
-that make concurrent code safer by default while reducing annotation burden.
-In Xcode, Approachable Concurrency and Default Actor Isolation are separate
-build settings: use Approachable Concurrency for the bundled upcoming-feature
-flags, and set Default Actor Isolation to `MainActor` when you want unannotated
-code inferred as `@MainActor`.
-
-### SE-0466: Default MainActor Isolation
-
-With the `-default-isolation MainActor` compiler flag, SwiftPM
-`.defaultIsolation(MainActor.self)`, or Xcode's `Default Actor Isolation`
-setting set to `MainActor`, unannotated declarations in the module are inferred
-as `@MainActor` unless explicitly opted out.
-
-**Effect:** Eliminates most data-race safety errors for UI-bound code and
-global/static state without writing `@MainActor` everywhere.
+| Type drives UI | `@MainActor` on the type or on the members that need it |
+| Main-actor type must satisfy a protocol | Isolated conformance: `extension Foo: @MainActor Proto` |
+| Global or `static` mutable state | Put it on `@MainActor` or inside an actor |
+| Work must leave the caller's actor | `@concurrent` async function on a `nonisolated` type |
+| Type fails a `Sendable` check | Prefer an immutable value type; declare `Sendable` only when it is true |
+| Value handed to another isolation once | A `sending` parameter or result (SE-0430) |
+
+**3. Confirm.** Rebuild and check the diagnostic is gone, no new warnings
+appeared, and no `@unchecked Sendable` or `nonisolated(unsafe)` slipped in
+without a proven reason.
+
+## Approachable concurrency in Swift 6.2
+
+Swift 6.2 changed defaults so that ordinary code needs fewer annotations and is
+safe without them. Xcode exposes two independent settings, and mixing them up
+is the most common planning error:
+
+- **Approachable Concurrency** switches on a group of upcoming features,
+  including `NonisolatedNonsendingByDefault` and isolated-conformance
+  inference. It does not make the module main-actor isolated.
+- **Default Actor Isolation = `MainActor`** (SE-0466) is the setting that makes
+  unannotated declarations infer `@MainActor`.
+
+Default isolation can be turned on three ways: the compiler flag
+`-default-isolation MainActor`, `.defaultIsolation(MainActor.self)` in a
+SwiftPM `swiftSettings` array, or the Xcode build setting. Use it for app
+targets, scripts and other executables where most code serves the UI. Leave
+library targets without it so they stay usable from any isolation.
 
 ```swift
-// With default MainActor isolation enabled, these are implicitly @MainActor:
-final class StickerLibrary {
-    static let shared = StickerLibrary()  // safe -- on MainActor
-    var stickers: [Sticker] = []
+// Target built with Default Actor Isolation = MainActor: no annotations needed.
+final class PlaybackQueue {
+    static let current = PlaybackQueue()   // main-actor protected
+    var upcoming: [Episode] = []            // main-actor protected
 }
 
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-    var selection: [PhotosPickerItem] = []
+final class EpisodeLibrary {
+    let renderer = WaveformRenderer()
+    var pinned: [Episode.ID] = []
 }
 
-// Conformances are also implicitly isolated:
-extension StickerModel: Exportable {
-    func export() {
-        photoProcessor.exportAsPNG()
-    }
+extension EpisodeLibrary: Archivable {      // conformance is main-actor isolated too
+    func archive() -> Data { Data() }
 }
 ```
 
-**When to use:** Recommended for apps, scripts, and other executable targets
-where most code is UI-bound. Not recommended for library targets that should
-remain actor-agnostic.
-
-### SE-0461: nonisolated(nonsending)
-
-Nonisolated async functions now stay on the caller's actor by default instead
-of hopping to the global concurrent executor. This is the
-`nonisolated(nonsending)` behavior.
+**Async functions stay where they are called (SE-0461).** With
+`NonisolatedNonsendingByDefault` on, a `nonisolated` async function runs on the
+caller's actor instead of jumping to the global concurrent executor. That
+behavior is spelled `nonisolated(nonsending)`. Without the feature, Swift 6.0
+and 6.1 semantics still apply and the function leaves the caller's actor.
 
 ```swift
-class PhotoProcessor {
-    func extractSticker(data: Data, with id: String?) async -> Sticker? {
-        // In Swift 6.2+, this runs on the caller's actor (e.g., MainActor)
-        // instead of hopping to a background thread.
-        // ...
-    }
+final class WaveformRenderer {
+    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
-        }
-        // No data race -- photoProcessor stays on MainActor
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-Use `@concurrent` to explicitly request background execution when needed.
+final class EpisodeDetailModel {
+    let renderer = WaveformRenderer()
+    var waveform: Waveform?
 
-### `@concurrent` Attribute
-
-`@concurrent` ensures a function always runs on the concurrent thread pool,
-freeing the calling actor to run other tasks.
-
-```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 {
-        // Expensive image processing -- runs on background thread pool
-        // ...
+    func open(_ url: URL) async throws {
+        let (audio, _) = try await URLSession.shared.data(from: url)
+        waveform = await renderer.render(audio)   // stays on the main actor: no race reported
     }
 }
 ```
 
-To move a function to a background thread:
-1. Ensure the containing type is `nonisolated` (or the function itself is).
-2. Add `@concurrent` to the function.
-3. Add `async` if not already asynchronous.
-4. Add `await` at call sites.
+**`@concurrent` asks for the thread pool on purpose.** A `@concurrent` function
+always runs on the concurrent pool, which frees the calling actor. To move a
+piece of work off the caller:
+
+1. Make the type, or just the function, `nonisolated`.
+2. Add `@concurrent`.
+3. Make the function `async` if it is not already.
+4. Put `await` at each call site.
 
 ```swift
-nonisolated struct PhotoProcessor {
+nonisolated struct TranscriptBuilder {
     @concurrent
-    func process(data: Data) async -> ProcessedPhoto? { /* ... */ }
+    func build(from audio: Data) async -> Transcript? { Transcript(lines: []) }
 }
 
-// Caller:
-processedPhotos[item.id] = await PhotoProcessor().process(data: data)
+// On the main actor:
+transcripts[episode.id] = await builder.build(from: audio)
 ```
 
-### SE-0472: Task.immediate
-
-`Task.immediate` starts executing synchronously on the current actor before
-any suspension point, rather than being enqueued.
+**Other 6.2 additions**, each covered in
+[concurrency-patterns.md](references/concurrency-patterns.md):
+
+- `Task.immediate` (SE-0472) runs synchronously on the current actor until its
+  first suspension instead of being enqueued; `Task.immediateDetached` adds
+  detached semantics. Use it where the enqueue delay is visible to the user,
+  for example `Task.immediate { await search.apply(query) }`.
+- `Observations { }` (SE-0475) turns reads of `@Observable` properties into an
+  `AsyncSequence` with transactional updates:
+  `for await elapsed in Observations({ player.elapsed }) { scrubber.move(to: elapsed) }`.
+- Isolated conformances let a main-actor type conform to a protocol whose
+  requirements it can only meet on the main actor. The compiler allows the
+  conformance only where that isolation holds.
+- SE-0473 adds `.epoch` to `ContinuousClock` and `SuspendingClock`, but the
+  iOS 26.4 SDK does not ship it yet ("value of type 'ContinuousClock' has no
+  member 'epoch'"); check your SDK before relying on it.
+
+## Isolation rules
+
+- Shared mutable state needs one owner: an actor, a global actor, or a
+  `Sendable` synchronization primitive such as `Mutex` or `Atomic`. Unowned
+  shared state is a race.
+- Code that reads or writes UI state is `@MainActor`. SwiftUI closures that the
+  framework documents as running off the main thread are the exception, and
+  they receive copies, not UI state (see
+  [swiftui-concurrency.md](references/swiftui-concurrency.md)).
+- `nonisolated` suits members that only read immutable `let` storage or do pure
+  computation.
+- `@concurrent` is the explicit way to leave the caller's actor.
+- `nonisolated(unsafe)` is for state whose synchronization you have proven by
+  other means, after every checked option has been ruled out.
+- An actor already serializes access. Adding `NSLock` or `DispatchSemaphore`
+  inside it buys nothing and can deadlock.
+
+## Sendable rules
+
+- A struct or enum is implicitly `Sendable` when all its stored properties are.
+- Actors are `Sendable`. So are classes isolated to a global actor, such as a
+  `@MainActor` class; writing `Sendable` on them again is noise.
+- Any other class qualifies only if it is `final` and every stored property is
+  a `let` of a `Sendable` type (a `let` holding a `Mutex` counts).
+- `@unchecked Sendable` is the final option, and the declaration must carry a
+  note saying which lock or invariant the compiler cannot see.
+- `sending` parameters and results (SE-0430) move a non-`Sendable` value into
+  another isolation region once, without making the type `Sendable`.
+- `@preconcurrency import` is for third-party modules you cannot change. Record
+  a plan to remove it.
+
+## Tasks and structured concurrency
+
+| Tool | What it inherits | Use for |
+|---|---|---|
+| `async let` | Everything; child task | A fixed number of concurrent calls |
+| `withTaskGroup` / `withThrowingTaskGroup` | Everything; child tasks | A number of calls known only at run time |
+| `Task { }` | Actor, priority, task-locals | Starting async work from synchronous code |
+| `Task.immediate { }` | Same as `Task`, starts at once | Latency-sensitive starts (OS 26 runtime) |
+| `Task.detached { }` | Nothing | Deliberately breaking inheritance; see the rule below |
 
 ```swift
-Task.immediate { await handleUserInput() }
-```
-
-Use for latency-sensitive work that should begin without delay. There is also
-`Task.immediateDetached` which combines immediate start with detached semantics.
-
-### SE-0475: Transactional Observation (Observations)
-
-`Observations { }` provides async observation of `@Observable` types via
-`AsyncSequence`, enabling transactional change tracking.
+async let profile = api.profile(for: userID)
+async let badges = api.badges(for: userID)
+let (loadedProfile, loadedBadges) = try await (profile, badges)
 
-```swift
-for await _ in Observations { model.count } {
-    print("Count changed to \(model.count)")
+let episodes = try await withThrowingTaskGroup(of: Episode.self) { group in
+    for id in episodeIDs {
+        group.addTask { try await api.episode(id) }
+    }
+    var collected: [Episode] = []
+    for try await episode in group { collected.append(episode) }
+    return collected
 }
 ```
 
-### Isolated Conformances
-
-A conformance that needs MainActor state is called an *isolated conformance*.
-The compiler ensures it is only used in a matching isolation context.
+SE-0493 lets a `defer` body `await`, but the Swift 6.3.1 compiler in Xcode
+26.4 still rejects it with "'async' call cannot occur in a defer body". Until
+your toolchain accepts it, run async cleanup on every exit path yourself:
 
 ```swift
-protocol Exportable {
-    func export()
-}
-
-// Isolated conformance: only usable on MainActor
-extension StickerModel: @MainActor Exportable {
-    func export() {
-        photoProcessor.exportAsPNG()
+func exportSession() async throws -> Int {
+    let file = try await LogFile.open(named: "session")
+    do {
+        let written = try await file.write(pendingEntries)
+        await file.close()
+        return written
+    } catch {
+        await file.close()
+        throw error
     }
 }
-
-@MainActor
-struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // OK -- ImageExporter is on MainActor
-    }
-}
-```
-
-If `ImageExporter` were `nonisolated`, adding a `StickerModel` would fail:
-"Main actor-isolated conformance of 'StickerModel' to 'Exportable' cannot be
-used in nonisolated context."
-
-### Clock Epochs
-
-`ContinuousClock` and `SuspendingClock` now expose `.epoch` (SE-0473), enabling instant comparison and conversion between clock types.
-
-```swift
-let continuous = ContinuousClock()
-let elapsed = continuous.now - continuous.epoch  // Duration since system boot
 ```
 
-## Actor Isolation Rules
-
-1. All mutable shared state MUST be protected by an actor or global actor.
-2. `@MainActor` for all UI-touching code. No exceptions.
-3. Use `nonisolated` only for methods that access immutable (`let`) properties
-   or are pure computations.
-4. Use `@concurrent` to explicitly move work off the caller's actor.
-5. Never use `nonisolated(unsafe)` unless you have proven internal
-   synchronization and exhausted all other options.
-6. Never add manual locks (`NSLock`, `DispatchSemaphore`) inside actors.
-
-## Sendable Rules
+## Cancellation
 
-1. Value types (structs, enums) are automatically `Sendable` when all stored
-   properties are `Sendable`.
-2. Actors are implicitly `Sendable`.
-3. `@MainActor` classes are implicitly `Sendable`. Do NOT add redundant
-   `Sendable` conformance.
-4. Non-actor classes: must be `final` with all stored properties `let` and
-   `Sendable`.
-5. `@unchecked Sendable` is a last resort. Document why the compiler cannot
-   prove safety.
-6. Use `sending` parameters (SE-0430) for finer-grained isolation control.
-7. Use `@preconcurrency import` only for third-party libraries you cannot
-   modify. Plan to remove it.
+Cancellation is a request the task must honor itself.
 
-## Structured Concurrency Patterns
+- In loops, test `Task.isCancelled` or call `try Task.checkCancellation()`.
+- In SwiftUI, start work with `.task`; it is cancelled when the view goes away.
+- Release resources on cancellation with `withTaskCancellationHandler`.
+- A `Task` you store must be cancelled by you, in `deinit` or `onDisappear`.
+  An unstructured task is never cancelled because its creator was.
 
-### Async Defer
+## Actor reentrancy
 
-`defer` blocks can now contain `await` (SE-0493). Use for async cleanup  -  closing connections, flushing buffers, or releasing resources that require an async call.
+An actor runs one piece of code at a time, but every `await` inside it lets
+other calls in. State read before an `await` may be stale after it.
 
 ```swift
-func fetchData() async throws -> Data {
-    let connection = try await openConnection()
-    defer { await connection.close() }
-    return try await connection.read()
-}
-```
+actor TicketCounter {
+    private var sold = 0
+    private let audit: AuditLog
 
-**Task:** Unstructured, inherits caller context.
-```swift
-Task { await doWork() }
-```
+    init(audit: AuditLog) { self.audit = audit }
 
-**Task.detached:** No inherited context. Use only when you explicitly need to
-break isolation inheritance.
-
-**Task.immediate:** Starts immediately on current actor. Use for
-latency-sensitive work.
-```swift
-Task.immediate { await handleUserInput() }
-```
-
-**async let:** Fixed number of concurrent operations.
-```swift
-async let a = fetchA()
-async let b = fetchB()
-let result = try await (a, b)
-```
-
-**TaskGroup:** Dynamic number of concurrent operations.
-```swift
-try await withThrowingTaskGroup(of: Item.self) { group in
-    for id in ids {
-        group.addTask { try await fetch(id) }
+    func sellLosingUpdates() async {
+        let current = sold
+        await audit.record(current)
+        sold = current + 1          // another call may have run during the await
     }
-    for try await item in group { process(item) }
-}
-```
-
-## Task Cancellation
-
-- Cancellation is cooperative. Check `Task.isCancelled` or call
-  `try Task.checkCancellation()` in loops.
-- Use `.task` modifier in SwiftUI -- it handles cancellation on view disappear.
-- Use `withTaskCancellationHandler` for cleanup.
-- Cancel stored tasks in `deinit` or `onDisappear`.
-
-## Actor Reentrancy
 
-Actors are reentrant. State can change across suspension points.
-
-```swift
-// WRONG: State may change during await
-actor Counter {
-    var count = 0
-    func increment() async {
-        let current = count
-        await someWork()
-        count = current + 1  // BUG: count may have changed
+    func sell() async {
+        sold += 1                   // read and write with no suspension between them
+        await audit.record(sold)
     }
 }
-
-// CORRECT: Mutate synchronously, no reentrancy risk
-actor Counter {
-    var count = 0
-    func increment() { count += 1 }
-}
 ```
 
-## AsyncSequence and AsyncStream
+## Streams and continuations
 
-Use `AsyncStream` to bridge callback/delegate APIs:
+Bridge APIs that call back many times with `AsyncStream`, and single-shot
+callbacks with `withCheckedContinuation` or `withCheckedThrowingContinuation`.
+A continuation is resumed exactly once on every path.
 
 ```swift
-let stream = AsyncStream<Location> { continuation in
-    let delegate = LocationDelegate { location in
-        continuation.yield(location)
+func readings(from scale: BluetoothScale) -> AsyncStream<Measurement<UnitMass>> {
+    AsyncStream { continuation in
+        let subscription = scale.observe { continuation.yield($0) }
+        continuation.onTermination = { _ in subscription.cancel() }
+        scale.startStreaming()
     }
-    continuation.onTermination = { _ in delegate.stop() }
-    delegate.start()
 }
 ```
 
-Use `withCheckedContinuation` / `withCheckedThrowingContinuation` for
-single-value callbacks. Resume exactly once.
-
-## `@Observable` and Concurrency
-
-- `@Observable` classes should be `@MainActor` for view models.
-- Use `@State` to own an `@Observable` instance (replaces `@StateObject`).
-- Use `Observations { }` (SE-0475) for async observation of `@Observable`
-  properties as an `AsyncSequence`.
-
-## Synchronization Primitives
-
-When actors are not the right fit  -  synchronous access, performance-critical
-paths, or bridging C/ObjC  -  use low-level synchronization primitives:
-
-- **`Mutex<Value>`** (iOS 18+, `Synchronization` module): Preferred lock for
-  new code. Stores protected state inside the lock. `withLock { }` pattern.
-- **`OSAllocatedUnfairLock`** (iOS 16+, `os` module): Use when targeting
-  older iOS versions. Supports ownership assertions for debugging.
-- **`Atomic<Value>`** (iOS 18+, `Synchronization` module): Lock-free atomics
-  for simple counters and flags. Requires explicit memory ordering.
-
-**Key rule:** Never put locks inside actors (double synchronization), and never
-hold a lock across `await` (deadlock risk). See
-[references/synchronization-primitives.md](references/synchronization-primitives.md) for full API details, code examples,
-and a decision guide for choosing locks vs actors.
-
-## Common Mistakes
-
-1. **Blocking the main actor.** Heavy computation on `@MainActor` freezes UI.
-   Move to a `@concurrent` function.
-2. **Unnecessary @MainActor.** Network layers, data processing, and model code
-   do not need `@MainActor`. Only UI-touching code does.
-3. **Actors for stateless code.** No mutable state means no actor needed. Use a
-   plain struct or function.
-4. **Actors for immutable data.** Use a `Sendable` struct, not an actor.
-5. **Task.detached without good reason.** Loses priority, task-local values,
-   and cancellation propagation.
-6. **Forgetting task cancellation.** Store `Task` references and cancel them, or
-   use the `.task` view modifier.
-7. **Retain cycles in Tasks.** Use `[weak self]` when capturing `self` in
-   long-lived stored tasks.
-8. **Semaphores in async context.** `DispatchSemaphore.wait()` in async code
-   will deadlock. Use structured concurrency instead.
-9. **Split isolation.** Mixing `@MainActor` and `nonisolated` properties in one
-   type. Isolate the entire type consistently.
-10. **MainActor.run instead of static isolation.** Prefer `@MainActor func`
-    over `await MainActor.run { }`.
-11. **Using GCD APIs.** Never use DispatchQueue, DispatchGroup, DispatchSemaphore, or any GCD API. Use async/await, actors, and TaskGroups instead. GCD has no data-race safety guarantees.
-
-## Review Checklist
-
-- [ ] All mutable shared state is actor-isolated
-- [ ] No data races (no unprotected cross-isolation access)
-- [ ] Tasks are cancelled when no longer needed
-- [ ] No blocking calls on `@MainActor`
-- [ ] No manual locks inside actors
-- [ ] `Sendable` conformance is correct (no unjustified `@unchecked`)
-- [ ] Actor reentrancy is handled (no state assumptions across awaits)
-- [ ] `@preconcurrency` imports are documented with removal plan
-- [ ] Heavy work uses `@concurrent`, not `@MainActor`
-- [ ] `.task` modifier used in SwiftUI instead of manual Task management
+Delegate bridges, cancellation-aware continuations and the full GCD mapping are
+in [bridging-interop.md](references/bridging-interop.md).
+
+## Observable models
+
+- Isolate `@Observable` view models to `@MainActor`.
+- Own them in a view with `@State`, which replaces `@StateObject`.
+- Read their changes from async code with `Observations { }` (SE-0475).
+
+## Locks and atomics
+
+Actors are the default for shared mutable state. Locks fit when callers must
+stay synchronous, when a path is hot enough that an actor hop costs too much,
+or when C and Objective-C callbacks touch the state.
+
+| Primitive | Minimum OS | Module | Use |
+|---|---|---|---|
+| `Mutex<Value>` | iOS 18 | `Synchronization` | First choice in new code; owns the state it guards, accessed through `withLock` |
+| `OSAllocatedUnfairLock` | iOS 16 | `os` | Older deployment targets; offers ownership preconditions for debugging |
+| `Atomic<Value>` | iOS 18 | `Synchronization` | Lock-free counters and flags; every call names a memory ordering |
+
+Two absolute rules: no lock inside an actor, since that synchronizes twice, and
+no lock held across an `await`, since that can deadlock. Details and a decision
+guide: [synchronization-primitives.md](references/synchronization-primitives.md).
+
+## Choosing how code moves between contexts
+
+The same rule covers GCD, `MainActor.run` and `Task.detached`: **state
+isolation in the declaration first, hop dynamically only when the declaration
+cannot say it, and keep Dispatch only where an API requires a queue.** A
+declaration is checked by the compiler; a hop inside a function body and a
+Dispatch queue are not visible to that checking in the same way, so each step
+down this list gives up guarantees.
+
+| Goal | Default | Acceptable when | Do not |
+|---|---|---|---|
+| Run on the main actor | `@MainActor` on the type, function or closure | `await MainActor.run { }` for one short batch of UI updates inside an async function that must itself stay `nonisolated`; `Task { @MainActor in }` from synchronous nonisolated code; `MainActor.assumeIsolated { }` in a synchronous callback documented to arrive on the main thread | `DispatchQueue.main.async` in new code |
+| Run away from the caller | `@concurrent` async function (6.2+); on 6.0 and 6.1 a `nonisolated` async function | `Task.detached` when the work must not inherit the actor, priority or task-local values, and you will cancel it yourself | `DispatchQueue.global().async` in new code |
+| Protect state | An actor | `Mutex`, `Atomic` or `OSAllocatedUnfairLock` for synchronous callers | A serial queue used as a lock in new code |
+| Fan out and join | `async let`, task groups | | `DispatchGroup`, `concurrentPerform` |
+| Wait for a result | `await` | | `DispatchSemaphore.wait()` or `DispatchGroup.wait()` from async code, ever |
+| API demands a queue | Pass a `DispatchQueue` and enter isolation at once in the callback | Back a custom actor with a `DispatchSerialQueue` as its executor (iOS 17) when it must share a queue with such an API | Mix queue-confined state with actor state |
+
+So GCD is not banned as a type in the codebase; it is banned as the way new code
+expresses isolation or coordination, because the compiler cannot prove what a
+custom queue protects. `MainActor.run` and `Task.detached` are legitimate but
+second choices, each with a named reason.
+
+## Mistakes to catch
+
+- Heavy computation on the main actor freezes the UI; move it to `@concurrent`.
+- `@MainActor` on networking, parsing or model code that never touches the UI.
+- An actor for code with no mutable state; use a struct or a free function.
+- An actor wrapping immutable data; use a `Sendable` struct.
+- `Task.detached` with no stated reason: it discards the actor, priority and
+  task-local values. Like any unstructured task it is also not cancelled with
+  its creator.
+- Tasks started and forgotten; keep the handle and cancel it, or use `.task`.
+- A long-lived stored task capturing `self` strongly; capture `[weak self]`.
+- `DispatchSemaphore.wait()` in async code: it blocks a cooperative thread and
+  can deadlock the pool.
+- Mutable state split across isolations in one type, for example some `var`s
+  on the main actor and others `nonisolated`. `nonisolated let` constants and
+  pure helpers next to isolated state are fine.
+- `await MainActor.run { }` where `@MainActor` on the function would do.
+- New Dispatch code for isolation or coordination (see the rule above).
+
+## Review checklist
+
+- [ ] Every piece of shared mutable state has one isolation owner.
+- [ ] No access crosses isolation without the compiler's approval.
+- [ ] Tasks are cancelled when their result is no longer wanted.
+- [ ] Nothing blocking runs on `@MainActor`.
+- [ ] No manual locks inside actors.
+- [ ] `Sendable` conformances are true; each `@unchecked` names its invariant.
+- [ ] No assumption about actor state survives an `await`.
+- [ ] Each `@preconcurrency import` has a removal plan.
+- [ ] CPU-heavy work is `@concurrent`, not on the main actor.
+- [ ] SwiftUI work starts from `.task`, not hand-managed tasks.
 
 ## References
 
-- [references/concurrency-patterns.md](references/concurrency-patterns.md)  -  detailed concurrency patterns and migration examples
-- [references/approachable-concurrency.md](references/approachable-concurrency.md)  -  approachable concurrency mode quick-reference
-- [references/swiftui-concurrency.md](references/swiftui-concurrency.md)  -  SwiftUI-specific concurrency guidance
-- [references/synchronization-primitives.md](references/synchronization-primitives.md)  -  Mutex, OSAllocatedUnfairLock, locks vs actors
-- [references/bridging-interop.md](references/bridging-interop.md)  -  checked continuations, delegate bridging, GCD migration table
-- [references/diagnostics.md](references/diagnostics.md)  -  compiler diagnostic → fix reference, strict concurrency adoption
-- [references/async-algorithms.md](references/async-algorithms.md)  -  swift-async-algorithms: debounce, throttle, merge, combineLatest, chunks
+- [concurrency-patterns.md](references/concurrency-patterns.md): approachable
+  concurrency in depth, before and after examples, `weak let`, global state,
+  build settings and migration.
+- [approachable-concurrency.md](references/approachable-concurrency.md): quick
+  reference for detecting the mode and fixing code inside it.
+- [swiftui-concurrency.md](references/swiftui-concurrency.md): main-actor
+  views, framework callbacks that run off the main thread, `.task`, view models.
+- [synchronization-primitives.md](references/synchronization-primitives.md):
+  `Mutex`, `OSAllocatedUnfairLock`, `Atomic`, memory ordering, locks versus
+  actors.
+- [bridging-interop.md](references/bridging-interop.md): continuations,
+  delegates, streams from callbacks, and replacing GCD.
+- [diagnostics.md](references/diagnostics.md): compiler messages and fixes,
+  adoption order, Thread Sanitizer.
+- [async-algorithms.md](references/async-algorithms.md): the
+  swift-async-algorithms package.