cmux-architecture

Source excerpt starting at line 1.

1# Concurrency Carve-outs2 3Examples and review guidance for the Swift 6 concurrency rules in [../SKILL.md](../SKILL.md).4 5## Actor-owned responsibilities6 7State with a lifecycle, multiple operations, or observers belongs in an `actor`: process registry, file watcher state, socket session table, retry/idempotency state, provider lifecycle state.8 9## Single-method actor smell10 11```swift12actor ResumeGuard {13    func claim() -> Bool { ... }14}15```16 17A synchronous callback needs an immediate compare-and-set, not a `Task { await ... }` hop. Use the lock carve-out.18 19## Lock carve-out20 21Canonical case: a process termination handler, a timeout callback, and a spawn failure callback all race to resume exactly one `withCheckedContinuation`. Keep the guard private to the type, non-blocking, and documented on the declaration. Never for ongoing domain state.22 23## Sendability escape hatches24 25```swift26// Wraps DispatchSourceFileSystemObject; every mutation happens on `queue`.27private final class WatcherAttachment: @unchecked Sendable { ... }28 29// UserDefaults is Apple-documented thread-safe; OK to read nonisolated.30private nonisolated(unsafe) let defaults: UserDefaults31```32 33Narrow the escape hatch to one property rather than marking an entire actor or value type unchecked.34 35## Review reject-list36 37Reject diffs introducing any of these in new code without a documented carve-out:38 39- `@Published`, `ObservableObject`40- `DispatchQueue.main.async`, `DispatchQueue.asyncAfter`41- `addObserver(_:forKeyPath:...)`42- queue-as-lock synchronization43- a lock guarding ongoing mutable state44- an `actor` whose only job is guarding a flag45- `Task.sleep` / `Clock.sleep` used to poll, settle, or race46- `@unchecked Sendable` or `nonisolated(unsafe)` without a safety comment47