@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/swift-pro/references/protocol-and-generics.md

@@ -0,0 +1,172 @@
+# Protocol and Generics
+
+## Protocol design principles
+
+### Minimal protocol requirements
+
+```swift
+// Good — focused contract
+protocol Identifiable {
+    associatedtype ID: Hashable
+    var id: ID { get }
+}
+
+// Bad — too many requirements force unnecessary implementations
+protocol DataSource {
+    func count() -> Int
+    func item(at: Int) -> Any
+    func add(_ item: Any)       // not all data sources are mutable
+    func remove(at: Int)        // not all data sources support removal
+}
+```
+
+- Define the smallest set of requirements that captures the abstraction.
+- Split large protocols into composable pieces (`Readable`, `Writable` instead of `ReadWriteStore`).
+- Use protocol extensions for default implementations of non-essential behavior.
+
+### Protocol composition
+
+```swift
+typealias UserStore = Identifiable & Codable & Sendable
+
+func save<T: Identifiable & Encodable>(_ item: T) throws {
+    let data = try JSONEncoder().encode(item)
+    try storage.write(data, forKey: "\(T.ID.self):\(item.id)")
+}
+```
+
+- Use `&` composition to combine protocols at use sites instead of creating combined protocols.
+- Use `typealias` for frequently used compositions.
+
+## Opaque types (`some`)
+
+```swift
+// Return type is known to the compiler, hidden from callers
+func makeParser() -> some Parser {
+    JSONParser()  // concrete type is fixed
+}
+
+// In SwiftUI — the canonical use case
+var body: some View {
+    VStack {
+        Text("Hello")
+        Button("Tap") { action() }
+    }
+}
+```
+
+- `some Protocol` preserves type identity — the compiler tracks the concrete type at compile time.
+- Zero runtime overhead compared to existentials.
+- Cannot return different concrete types from different code paths.
+- Use `some` in return types and stored properties when the caller doesn't need to know the concrete type.
+
+## Existential types (`any`)
+
+```swift
+// Dynamic dispatch — concrete type resolved at runtime
+var repositories: [any Repository] = [
+    PostgresRepository(),
+    InMemoryRepository(),
+]
+
+func process(repo: any Repository) {
+    // uses dynamic dispatch
+}
+```
+
+- `any Protocol` has boxing overhead: heap allocation for the existential container.
+- Required when you need heterogeneous collections of protocol-conforming types.
+- Required when the concrete type varies at runtime.
+- Cannot use protocols with `Self` requirements or associated types directly as `any` (use type erasure or constrained generics).
+
+### Opening existentials
+
+```swift
+func processAny(_ item: any Identifiable) {
+    // Swift 5.7+ can "open" existentials into generics
+    process(item)  // calls the generic version below
+}
+
+func process<T: Identifiable>(_ item: T) {
+    print(item.id)
+}
+```
+
+## Associated types
+
+```swift
+protocol Collection {
+    associatedtype Element
+    associatedtype Index: Comparable
+
+    var startIndex: Index { get }
+    var endIndex: Index { get }
+    subscript(position: Index) -> Element { get }
+}
+```
+
+- Use associated types when the protocol needs to express relationships between types.
+- Add constraints to associated types (`associatedtype Element: Sendable`) to propagate requirements.
+- Use `where` clauses for complex constraints:
+
+```swift
+extension Collection where Element: Equatable {
+    func contains(_ element: Element) -> Bool {
+        // ...
+    }
+}
+```
+
+## Generic constraint patterns
+
+### Constrained extensions
+
+```swift
+extension Array where Element: Numeric {
+    var sum: Element {
+        reduce(.zero, +)
+    }
+}
+
+extension Sequence where Element: Hashable {
+    var unique: [Element] {
+        var seen = Set<Element>()
+        return filter { seen.insert($0).inserted }
+    }
+}
+```
+
+### Generic type with constraints
+
+```swift
+struct Cache<Key: Hashable & Sendable, Value: Sendable> {
+    private var storage: [Key: Value] = [:]
+
+    mutating func set(_ value: Value, forKey key: Key) {
+        storage[key] = value
+    }
+
+    func get(_ key: Key) -> Value? {
+        storage[key]
+    }
+}
+```
+
+### Primary associated types (Swift 5.7+)
+
+```swift
+protocol Repository<Model> {
+    associatedtype Model: Identifiable
+
+    func find(id: Model.ID) async throws -> Model?
+    func save(_ model: Model) async throws
+}
+
+// Use in constrained contexts without full generic signatures
+func processRepo(_ repo: some Repository<User>) async throws {
+    let user = try await repo.find(id: userID)
+}
+```
+
+- Primary associated types simplify common generic usage with `some Protocol<ConcreteType>` syntax.
+- Reduces the need for manual type erasure wrappers.

package/workflows/powers/swift-pro/references/sendable-and-isolation.md

@@ -0,0 +1,116 @@
+# Sendable and Isolation
+
+## Sendable conformance checklist
+
+| Type                                                      | Sendable?             | Notes                                             |
+| --------------------------------------------------------- | --------------------- | ------------------------------------------------- |
+| `struct` with all `Sendable` stored properties            | Automatic             | No annotation needed in most cases.               |
+| `enum` with all `Sendable` associated values              | Automatic             | Including cases with no associated values.        |
+| `actor`                                                   | Always `Sendable`     | Actors are `Sendable` by definition.              |
+| `final class` with immutable `Sendable` stored properties | Explicit              | Must declare `: Sendable` conformance.            |
+| `class` with mutable state and manual synchronization     | `@unchecked Sendable` | Requires manual audit of all access paths.        |
+| `class` with no synchronization                           | Not Sendable          | Must be redesigned or isolated to a single actor. |
+
+## Isolation boundaries
+
+### Crossing isolation domains
+
+```swift
+actor DataStore {
+    private var items: [Item] = []
+
+    // Value types cross boundaries safely
+    func snapshot() -> [Item] {
+        items  // [Item] is Sendable if Item is Sendable
+    }
+}
+
+// From non-isolated context:
+let store = DataStore()
+let items = await store.snapshot()  // crosses isolation boundary
+```
+
+### The `sending` parameter (Swift 6)
+
+```swift
+// Transfer ownership of a non-Sendable value into an actor
+func process(_ item: sending Item) async {
+    // item is now owned by this isolation domain
+    // caller cannot use item after this call
+}
+```
+
+- `sending` allows passing non-Sendable values across boundaries when ownership is transferred.
+- The compiler enforces that the caller does not retain a reference after the call.
+- Prefer `sending` over `@unchecked Sendable` when transferring ownership is the real intent.
+
+## Auditing @unchecked Sendable
+
+When marking a class `@unchecked Sendable`, verify:
+
+1. **All mutable state** is protected by a lock, serial queue, or other synchronization mechanism.
+2. **No stored property** is a non-Sendable reference type accessed without synchronization.
+3. **No method** exposes internal mutable state by reference.
+4. **Subclasses** (if any) cannot break the synchronization contract.
+
+```swift
+final class AtomicCounter: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _value: Int = 0
+
+    var value: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return _value
+    }
+
+    func increment() {
+        lock.lock()
+        defer { lock.unlock() }
+        _value += 1
+    }
+}
+```
+
+- Always use `final class` with `@unchecked Sendable` to prevent subclass violations.
+- Prefer `OSAllocatedUnfairLock` (iOS 16+/macOS 13+) over `NSLock` for better performance.
+- Document the synchronization strategy in a comment next to the conformance.
+
+## Closure isolation
+
+```swift
+// @Sendable closure — can only capture Sendable values
+func runDetached(_ work: @escaping @Sendable () async -> Void) {
+    Task.detached { await work() }
+}
+
+// Non-Sendable capture will produce a compiler error
+class ViewController {
+    var state: [String] = []  // not Sendable
+
+    func bad() {
+        runDetached {
+            self.state.append("oops")  // ERROR: captured non-Sendable self
+        }
+    }
+
+    func good() {
+        let snapshot = state  // copy to Sendable value
+        runDetached { [snapshot] in
+            print(snapshot)  // OK — snapshot is Sendable
+        }
+    }
+}
+```
+
+- `@Sendable` closures enforce Sendable captures at compile time.
+- Capture value copies or Sendable references in the capture list.
+- Use `@MainActor in` closure syntax to isolate closures to the main actor.
+
+## Migration strategy
+
+1. Enable `-strict-concurrency=targeted` first to see warnings without breaking the build.
+2. Fix `Sendable` conformance for types that cross boundaries (DTOs, config, events).
+3. Escalate to `-strict-concurrency=complete` once targeted warnings are resolved.
+4. Convert `@unchecked Sendable` uses to proper actors where feasible.
+5. Use `sending` parameters to eliminate remaining `@unchecked Sendable` workarounds.

package/workflows/powers/swift-pro/references/swift-concurrency-and-protocols.md

@@ -0,0 +1,260 @@
+# Swift Concurrency and Protocols
+
+## Actor design
+
+### When to use actors
+
+```swift
+actor BankAccount {
+    private var balance: Decimal
+
+    init(initialBalance: Decimal) {
+        self.balance = initialBalance
+    }
+
+    func deposit(_ amount: Decimal) {
+        balance += amount
+    }
+
+    func withdraw(_ amount: Decimal) throws -> Decimal {
+        guard balance >= amount else {
+            throw BankError.insufficientFunds
+        }
+        balance -= amount
+        return amount
+    }
+
+    // nonisolated for properties that don't need isolation
+    nonisolated var description: String { "BankAccount" }
+}
+```
+
+- Use `actor` when mutable state needs thread-safe access from multiple callers.
+- Actor methods are implicitly `async` when called from outside the actor.
+- Use `nonisolated` for computed properties or methods that don't access mutable state.
+- Keep actor methods fast — long-running work blocks other callers waiting for the actor.
+
+### Global actors
+
+```swift
+@globalActor
+actor DatabaseActor {
+    static let shared = DatabaseActor()
+}
+
+@DatabaseActor
+class DatabaseManager {
+    func query(_ sql: String) async throws -> [Row] { /* ... */ }
+}
+```
+
+- Use `@MainActor` for all UI-bound code. Never dispatch to main queue manually.
+- Create custom global actors for subsystems that need serial execution (database, file system).
+- Annotate classes, methods, or properties — not entire modules.
+
+## Sendable conformance
+
+### Value types (automatic Sendable)
+
+```swift
+// Automatically Sendable — all stored properties are Sendable
+struct UserDTO: Sendable {
+    let id: UUID
+    let name: String
+    let email: String
+}
+
+// Enums with Sendable associated values are Sendable
+enum Result<Success: Sendable, Failure: Error>: Sendable {
+    case success(Success)
+    case failure(Failure)
+}
+```
+
+### Reference types (manual Sendable)
+
+```swift
+// Must prove thread safety manually
+final class ThreadSafeCache: @unchecked Sendable {
+    private let lock = NSLock()
+    private var storage: [String: Any] = [:]
+
+    func get(_ key: String) -> Any? {
+        lock.lock()
+        defer { lock.unlock() }
+        return storage[key]
+    }
+}
+```
+
+- `@unchecked Sendable` requires manual audit — the compiler trusts your claim.
+- Prefer actors over `@unchecked Sendable` classes when possible.
+- Use `sending` parameter modifier (Swift 6) to transfer ownership without requiring `Sendable`.
+
+### Closure Sendable rules
+
+```swift
+// Closure must capture only Sendable values
+func runOnBackground(_ work: @Sendable () async -> Void) {
+    Task { await work() }
+}
+
+// Capture list with Sendable values only
+let name = "Alice" // String is Sendable
+runOnBackground { [name] in
+    print(name) // OK — captured Sendable value
+}
+```
+
+## Structured concurrency
+
+### TaskGroup
+
+```swift
+func fetchAllUsers(ids: [Int]) async throws -> [User] {
+    try await withThrowingTaskGroup(of: User.self) { group in
+        for id in ids {
+            group.addTask {
+                try await api.fetchUser(id: id)
+            }
+        }
+        var users: [User] = []
+        for try await user in group {
+            users.append(user)
+        }
+        return users
+    }
+}
+```
+
+- Use `TaskGroup` for fan-out/fan-in patterns. Child tasks are automatically cancelled if the group scope exits.
+- `withThrowingTaskGroup` propagates the first error and cancels remaining child tasks.
+
+### Task cancellation
+
+```swift
+func processItems(_ items: [Item]) async throws {
+    for item in items {
+        // Check cancellation before each unit of work
+        try Task.checkCancellation()
+        await process(item)
+    }
+}
+
+// Or check without throwing
+if Task.isCancelled {
+    // Clean up and return partial results
+    return partialResults
+}
+```
+
+- Always check `Task.isCancelled` or call `Task.checkCancellation()` in loops.
+- Cancellation is cooperative — tasks are not killed automatically.
+- Clean up resources in cancellation paths (close files, cancel network requests).
+
+### AsyncSequence and AsyncStream
+
+```swift
+// Producing async events
+func events() -> AsyncStream<Event> {
+    AsyncStream { continuation in
+        let observer = NotificationCenter.default.addObserver(...) { notification in
+            continuation.yield(Event(from: notification))
+        }
+        continuation.onTermination = { _ in
+            NotificationCenter.default.removeObserver(observer)
+        }
+    }
+}
+
+// Consuming
+for await event in events() {
+    handle(event)
+}
+```
+
+## Protocol-oriented architecture
+
+### Protocol as capability contract
+
+```swift
+protocol UserRepository {
+    func find(id: UUID) async throws -> User?
+    func save(_ user: User) async throws
+    func delete(id: UUID) async throws
+}
+
+// Concrete implementation is internal
+struct PostgresUserRepository: UserRepository {
+    func find(id: UUID) async throws -> User? { /* ... */ }
+    func save(_ user: User) async throws { /* ... */ }
+    func delete(id: UUID) async throws { /* ... */ }
+}
+```
+
+### Protocol extensions for defaults
+
+```swift
+protocol Cacheable: Identifiable {
+    var cacheKey: String { get }
+    var ttl: TimeInterval { get }
+}
+
+extension Cacheable {
+    var cacheKey: String { "\(Self.self):\(id)" }
+    var ttl: TimeInterval { 300 } // 5 minutes default
+}
+```
+
+- Use extensions for sensible defaults. Keep required methods minimal.
+
+### Opaque vs existential types
+
+```swift
+// Opaque: compiler knows the concrete type (zero-cost)
+func makeUser() -> some UserRepository {
+    PostgresUserRepository()
+}
+
+// Existential: runtime type erasure (has boxing overhead)
+func getRepository() -> any UserRepository {
+    condition ? PostgresUserRepository() : InMemoryUserRepository()
+}
+```
+
+| Feature                | `some Protocol`                | `any Protocol`                     |
+| ---------------------- | ------------------------------ | ---------------------------------- |
+| Performance            | Zero-cost (static dispatch)    | Boxing overhead (dynamic dispatch) |
+| Can vary return type   | No — always same concrete type | Yes — different types allowed      |
+| Use as stored property | Only in generic context        | Yes, directly                      |
+
+- Prefer `some` by default. Use `any` only when you need heterogeneous collections or dynamic type selection.
+- Use `any Protocol` in function parameters when multiple concrete types must be accepted.
+
+## Testing with protocols
+
+```swift
+@Test
+func testUserCreation() async throws {
+    let repo = MockUserRepository()
+    let service = UserService(repository: repo)
+
+    let user = try await service.createUser(name: "Alice")
+
+    #expect(user.name == "Alice")
+    #expect(repo.savedUsers.count == 1)
+}
+
+struct MockUserRepository: UserRepository {
+    var savedUsers: [User] = []
+
+    mutating func save(_ user: User) async throws {
+        savedUsers.append(user)
+    }
+    // ...
+}
+```
+
+- Inject protocols, test with mocks. Never test against real databases in unit tests.
+- Use Swift Testing `@Test` and `#expect` for new test targets.
+- Use `confirmation()` for testing actor-isolated code that emits events.