@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

package/pipeline/skills/shared/external/ios-networking/references/file-storage-patterns.md

@@ -0,0 +1,354 @@
+# File Storage Patterns
+
+Guidance on choosing the right directory, applying file protection, managing
+backup exclusions, and handling storage pressure on iOS.
+
+## Contents
+
+- [Directory Selection Guide](#directory-selection-guide)
+- [FileProtectionType Levels](#fileprotectiontype-levels)
+- [Backup Exclusion (isExcludedFromBackup)](#backup-exclusion-isexcludedfrombackup)
+- [Storage Pressure Handling](#storage-pressure-handling)
+
+## Directory Selection Guide
+
+iOS provides four primary directories for app data. Choose based on whether
+the data is user-generated, re-creatable, or temporary.
+
+| Directory | Backed Up | Purged by System | Use For |
+|---|---|---|---|
+| `Documents/` | Yes | No | User-generated content (documents, exports, user files) |
+| `Library/Application Support/` | Yes | No | App-generated supporting files (databases, config, caches that should survive updates) |
+| `Library/Caches/` | No | Yes (low storage) | Re-creatable data (downloaded images, API responses, computed data) |
+| `tmp/` | No | Yes (anytime) | Truly temporary files (in-progress uploads, scratch files) |
+
+### Accessing Standard Directories
+
+Use `FileManager.default.urls(for:in:)` to get the correct path. Never
+hardcode paths.
+
+```swift
+import Foundation
+
+// Documents/  -  user-generated content, backed up by iCloud/iTunes
+let documentsURL = FileManager.default.urls(
+    for: .documentDirectory, in: .userDomainMask
+).first!
+
+// Library/Application Support/  -  app-generated supporting data, backed up
+let appSupportURL = FileManager.default.urls(
+    for: .applicationSupportDirectory, in: .userDomainMask
+).first!
+// Create if it doesn't exist (not auto-created)
+try FileManager.default.createDirectory(
+    at: appSupportURL, withIntermediateDirectories: true
+)
+
+// Library/Caches/  -  re-creatable data, not backed up, may be purged
+let cachesURL = FileManager.default.urls(
+    for: .cachesDirectory, in: .userDomainMask
+).first!
+
+// tmp/  -  temporary files, purged by system periodically
+let tmpURL = FileManager.default.temporaryDirectory
+```
+
+### Choosing the Right Directory
+
+```swift
+// User's exported PDF  -  Documents/
+let exportURL = documentsURL.appendingPathComponent("Report.pdf")
+try pdfData.write(to: exportURL)
+
+// App's SQLite database  -  Library/Application Support/
+let dbURL = appSupportURL.appendingPathComponent("AppData.sqlite")
+
+// Downloaded thumbnail cache  -  Library/Caches/
+let thumbURL = cachesURL.appendingPathComponent("thumbnails/\(imageID).jpg")
+
+// In-progress upload  -  tmp/
+let uploadURL = tmpURL.appendingPathComponent(UUID().uuidString + ".tmp")
+```
+
+## FileProtectionType Levels
+
+iOS encrypts files at rest using Data Protection. The protection level
+determines when the file is accessible relative to the device lock state.
+
+Docs: [FileProtectionType](https://sosumi.ai/documentation/foundation/fileprotectiontype),
+[Encrypting Your App's Files](https://sosumi.ai/documentation/uikit/encrypting-your-app-s-files)
+
+| Level | Constant | When Accessible | Use For |
+|---|---|---|---|
+| Complete | `.complete` | Only when device is unlocked | Sensitive user data (health records, financial data) |
+| Complete Unless Open | `.completeUnlessOpen` | Can finish if opened before lock | Active downloads, recordings in progress |
+| Until First Auth | `.completeUntilFirstUserAuthentication` | After first unlock (default) | Most app data; background-accessible content |
+| None | `.none` | Always, even before first unlock | Non-sensitive system-required data |
+
+### Setting File Protection
+
+```swift
+import Foundation
+
+// Option 1: Set protection when writing data
+try sensitiveData.write(to: fileURL, options: .completeFileProtection)
+
+// Option 2: Set protection via FileManager attributes
+try FileManager.default.setAttributes(
+    [.protectionKey: FileProtectionType.complete],
+    ofItemAtPath: fileURL.path
+)
+
+// Option 3: Set protection on a directory (applies to new files within)
+try FileManager.default.setAttributes(
+    [.protectionKey: FileProtectionType.complete],
+    ofItemAtPath: secureDirectoryURL.path
+)
+```
+
+### Checking Current Protection Level
+
+```swift
+let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
+if let protection = attributes[.protectionKey] as? FileProtectionType {
+    switch protection {
+    case .complete:
+        print("File is fully protected")
+    case .completeUnlessOpen:
+        print("Protected unless already open")
+    case .completeUntilFirstUserAuthentication:
+        print("Protected until first unlock (default)")
+    case .none:
+        print("No encryption")
+    default:
+        break
+    }
+}
+```
+
+### Handling Protected Data Availability
+
+Files with `.complete` protection are inaccessible when the device is locked.
+Check availability before accessing:
+
+```swift
+import UIKit
+
+// Check if protected data is currently available
+if UIApplication.shared.isProtectedDataAvailable {
+    // Safe to read .complete files
+    let data = try Data(contentsOf: protectedFileURL)
+} else {
+    // Wait for device unlock
+}
+
+// Observe availability changes
+NotificationCenter.default.addObserver(
+    forName: UIApplication.protectedDataDidBecomeAvailableNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Protected files are now accessible
+}
+
+NotificationCenter.default.addObserver(
+    forName: UIApplication.protectedDataWillBecomeUnavailableNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Close file handles to .complete files
+}
+```
+
+## Backup Exclusion (isExcludedFromBackup)
+
+Exclude large re-downloadable content from iCloud/iTunes backup to avoid
+bloating the user's backup. Apple may reject apps that back up excessive
+re-creatable data.
+
+Docs: [URLResourceValues](https://sosumi.ai/documentation/foundation/urlresourcevalues)
+
+### Setting the Exclusion Flag
+
+```swift
+import Foundation
+
+// Exclude a file or directory from backup
+func excludeFromBackup(_ url: URL) throws {
+    var resourceValues = URLResourceValues()
+    resourceValues.isExcludedFromBackup = true
+    var mutableURL = url
+    try mutableURL.setResourceValues(resourceValues)
+}
+
+// Usage
+let largeCache = cachesURL.appendingPathComponent("video-cache")
+try excludeFromBackup(largeCache)
+```
+
+### Checking the Exclusion Flag
+
+```swift
+func isExcludedFromBackup(_ url: URL) throws -> Bool {
+    let values = try url.resourceValues(forKeys: [.isExcludedFromBackupKey])
+    return values.isExcludedFromBackup ?? false
+}
+```
+
+### When to Exclude from Backup
+
+| Exclude | Keep in Backup |
+|---|---|
+| Downloaded media (images, videos, audio) | User-created documents |
+| API response caches | User preferences and settings |
+| Generated thumbnails or previews | App databases with user data |
+| Offline map tiles | In-app purchase receipts |
+| Pre-computed search indexes | User-generated content |
+
+### Common Pattern: Application Support with Exclusion
+
+Store re-downloadable data in Application Support but exclude from backup:
+
+```swift
+let offlineDataURL = appSupportURL.appendingPathComponent("OfflineData")
+try FileManager.default.createDirectory(
+    at: offlineDataURL, withIntermediateDirectories: true
+)
+try excludeFromBackup(offlineDataURL)
+
+// Files in this directory persist across app updates but don't bloat backup
+try downloadedData.write(to: offlineDataURL.appendingPathComponent("map-tiles.db"))
+```
+
+## Storage Pressure Handling
+
+When the device runs low on storage, iOS may purge files in `Library/Caches/`
+and `tmp/`. Apps should proactively manage storage and respond to low-space
+conditions.
+
+### Checking Available Storage
+
+```swift
+import Foundation
+
+func availableDiskSpace() throws -> Int64 {
+    let values = try URL(fileURLWithPath: NSHomeDirectory())
+        .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
+    return values.volumeAvailableCapacityForImportantUsage ?? 0
+}
+
+// Use .volumeAvailableCapacityForImportantUsageKey for important operations
+// Use .volumeAvailableCapacityForOpportunisticUsageKey for optional operations
+// The opportunistic value is always <= the important value
+
+func hasSpaceForDownload(bytes: Int64) throws -> Bool {
+    let available = try availableDiskSpace()
+    return available > bytes
+}
+```
+
+### Responding to Low Storage Notifications
+
+```swift
+import UIKit
+
+// iOS posts this when storage is critically low (UIKit apps)
+NotificationCenter.default.addObserver(
+    forName: UIApplication.didReceiveMemoryWarningNotification,
+    object: nil,
+    queue: .main
+) { _ in
+    // Clear in-memory caches; consider trimming disk caches too
+    clearImageCache()
+}
+
+// Check storage proactively at app launch or before large operations
+func checkStorageAndCleanup() throws {
+    let availableBytes = try availableDiskSpace()
+    let threshold: Int64 = 100 * 1024 * 1024  // 100 MB
+
+    if availableBytes < threshold {
+        try performCleanup()
+    }
+}
+```
+
+### Implementing Cleanup Strategies
+
+```swift
+import Foundation
+
+struct StorageCleaner {
+    let cachesURL: URL
+    let maxCacheAge: TimeInterval  // e.g., 7 days
+    let maxCacheSize: Int64        // e.g., 500 MB
+
+    /// Remove files older than maxCacheAge
+    func removeExpiredFiles() throws {
+        let contents = try FileManager.default.contentsOfDirectory(
+            at: cachesURL,
+            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
+            options: .skipsHiddenFiles
+        )
+
+        let cutoff = Date.now.addingTimeInterval(-maxCacheAge)
+
+        for fileURL in contents {
+            let values = try fileURL.resourceValues(
+                forKeys: [.contentModificationDateKey]
+            )
+            if let modified = values.contentModificationDate, modified < cutoff {
+                try FileManager.default.removeItem(at: fileURL)
+            }
+        }
+    }
+
+    /// Trim cache to maxCacheSize using LRU eviction
+    func trimToSize() throws {
+        let contents = try FileManager.default.contentsOfDirectory(
+            at: cachesURL,
+            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
+            options: .skipsHiddenFiles
+        )
+
+        // Sort oldest first
+        let sorted = try contents.sorted { a, b in
+            let aDate = try a.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate ?? .distantPast
+            let bDate = try b.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate ?? .distantPast
+            return aDate < bDate
+        }
+
+        // Calculate total size
+        var totalSize: Int64 = 0
+        for fileURL in sorted {
+            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
+            totalSize += Int64(values.fileSize ?? 0)
+        }
+
+        // Delete oldest files until under budget
+        for fileURL in sorted {
+            guard totalSize > maxCacheSize else { break }
+            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
+            let fileSize = Int64(values.fileSize ?? 0)
+            try FileManager.default.removeItem(at: fileURL)
+            totalSize -= fileSize
+        }
+    }
+
+    /// Full cleanup: expired files first, then trim to size
+    func performCleanup() throws {
+        try removeExpiredFiles()
+        try trimToSize()
+    }
+}
+
+// Usage
+let cleaner = StorageCleaner(
+    cachesURL: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!,
+    maxCacheAge: 7 * 24 * 60 * 60,   // 7 days
+    maxCacheSize: 500 * 1024 * 1024    // 500 MB
+)
+try cleaner.performCleanup()
+```

package/pipeline/skills/shared/external/ios-networking/references/network-framework.md

@@ -3,7 +3,7 @@
 Low-level networking with the Network framework. Use when you need TCP/UDP
 connections, WebSockets, Bonjour service discovery, local servers, or network
 path monitoring beyond what URLSession provides. All examples target
-Swift 6.2 / iOS 26+.
+Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -254,25 +254,11 @@ constrained paths (Low Data Mode).
 **Documentation:**
 [sosumi.ai/documentation/network/nwpathmonitor](https://sosumi.ai/documentation/network/nwpathmonitor)
 
-### Basic Reachability with AsyncStream
+### Basic Reachability with AsyncSequence
 
 ```swift
 import Network
 
-func networkStatusStream() -> AsyncStream<NWPath> {
-    AsyncStream { continuation in
-        let monitor = NWPathMonitor()
-        monitor.pathUpdateHandler = { path in
-            continuation.yield(path)
-        }
-        continuation.onTermination = { _ in
-            monitor.cancel()
-        }
-        monitor.start(queue: DispatchQueue(label: "NetworkMonitor"))
-    }
-}
-
-// Usage in a view model
 @MainActor @Observable
 class ConnectivityModel {
     var isConnected = true
@@ -280,7 +266,9 @@ class ConnectivityModel {
     var isConstrained = false
 
     func startMonitoring() async {
-        for await path in networkStatusStream() {
+        let monitor = NWPathMonitor()
+
+        for await path in monitor {
             isConnected = path.status == .satisfied
             isExpensive = path.isExpensive       // Cellular
             isConstrained = path.isConstrained   // Low Data Mode
@@ -314,7 +302,9 @@ wifiMonitor.start(queue: .global())
 ### Adapting Behavior
 
 ```swift
-for await path in networkStatusStream() {
+let monitor = NWPathMonitor()
+
+for await path in monitor {
     if path.isConstrained {
         // Low Data Mode: reduce image quality, skip prefetch
         imageQuality = .low
@@ -372,6 +362,11 @@ let connection = NWConnection(
 ## TLS Configuration
 
 Configure TLS for secure connections using `NWProtocolTLS.Options`.
+Network.framework operates below the URL Loading System, so ATS does not
+automatically enforce URLSession-style policy here. When you use
+Network.framework for a secure protocol, configure TLS parameters and trust
+handling for that protocol stack; keep deep certificate-trust and SPKI pinning
+implementation in `swift-security`.
 
 ```swift
 import Network
@@ -511,52 +506,82 @@ with async/await via closure-based state handlers.
 | **Wi-Fi Aware** | Not supported | `wifiAware` property |
 | **API style** | Callback-based | Closure-based with `Sendable` support |
 
-### Basic Usage
+### Basic Usage Shape
 
 ```swift
 import Network
 
-// Create with protocol stack parameters
-let connection = NetworkConnection(
-    to: .hostPort(host: "api.example.com", port: 443),
-    using: .tls
-)
+let endpoint = NWEndpoint.hostPort(host: "api.example.com", port: 443)
+```
 
-connection.onStateUpdate { state in
-    switch state {
-    case .ready:
-        print("Connected")
-    case .failed(let error):
-        print("Failed: \(error)")
-    case .cancelled:
-        print("Cancelled")
-    default:
-        break
-    }
+Use the initializer variant that matches your protocol stack. The documented
+forms are:
+
+```swift
+// Protocol-stack builder form.
+NetworkConnection(to: endpoint) {
+    // ProtocolStackBuilder<ApplicationProtocol>
 }
 
-connection.start()
+// Parameters-builder form.
+NetworkConnection(to: endpoint, using: builder)
 ```
 
+After constructing a concrete connection for your app's protocol stack, install
+state handlers and start it:
+
+```swift
+func startConnection<ApplicationProtocol>(
+    _ connection: NetworkConnection<ApplicationProtocol>
+) where ApplicationProtocol: NetworkProtocolOptions {
+    connection.onStateUpdate { state in
+        switch state {
+        case .ready:
+            print("Connected")
+        case .failed(let error):
+            print("Failed: \(error)")
+        case .cancelled:
+            print("Cancelled")
+        default:
+            break
+        }
+    }
+
+    connection.start()
+}
+```
+
+`NetworkConnection` is for lower-level protocol stacks and QUIC-style transport
+work. Keep ordinary HTTP APIs on `URLSession` unless you need capabilities that
+the URL Loading System does not provide.
+
 ### QUIC Multiplexed Streams
 
-`NetworkConnection` supports QUIC stream multiplexing natively:
+`NetworkConnection<QUIC>` supports QUIC stream multiplexing natively.
+Opening and accepting streams are asynchronous and throwing operations.
 
 ```swift
-// Open a new bidirectional stream
-let stream = connection.openStream(directionality: .bidirectional)
+func openBidirectionalStream(
+    on connection: NetworkConnection<QUIC>
+) async throws -> QUIC.Stream<QUICStream> {
+    try await connection.openStream(directionality: .bidirectional)
+}
 
-// Handle inbound streams
-connection.inboundStreams { stream in
-    // Process incoming stream
+func handleInboundStreams(
+    on connection: NetworkConnection<QUIC>
+) async throws {
+    try await connection.inboundStreams { stream in
+        // Process each incoming QUIC stream.
+    }
 }
 ```
 
 ### Migration Guidance
 
-For new iOS 26+ projects, prefer `NetworkConnection` over `NWConnection`:
+For new iOS 26+ low-level networking work, evaluate `NetworkConnection` before
+adding new `NWConnection` code:
 - It provides stronger type safety through its generic `ApplicationProtocol`.
-- Stream multiplexing is a first-class concept.
+- Stream multiplexing is a first-class concept for QUIC.
 - The API is designed for modern Swift with `Sendable` conformance.
 
 For projects supporting iOS versions before 26, continue using `NWConnection`.

package/pipeline/skills/shared/external/ios-networking/references/urlsession-patterns.md

@@ -1,13 +1,13 @@
 # URLSession Patterns Reference
 
-Complete implementation patterns for URLSession-based networking. Each
-section is self-contained with production-ready code.
+Complete implementation patterns for URLSession-based networking.
 
 ---
 
 ## Contents
 
 - [Complete API Client with Protocol](#complete-api-client-with-protocol)
+- [Request Middleware](#request-middleware)
 - [Request Builder Pattern](#request-builder-pattern)
 - [Multipart Form Upload](#multipart-form-upload)
 - [Download with Progress Tracking](#download-with-progress-tracking)
@@ -251,6 +251,25 @@ struct APIErrorBody: Decodable, Sendable {
 }
 ```
 
+### Request Middleware
+
+```swift
+protocol RequestMiddleware: Sendable {
+    func prepare(_ request: URLRequest) async throws -> URLRequest
+}
+
+struct AuthMiddleware: RequestMiddleware {
+    let tokenProvider: @Sendable () async throws -> String
+
+    func prepare(_ request: URLRequest) async throws -> URLRequest {
+        var request = request
+        let token = try await tokenProvider()
+        request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        return request
+    }
+}
+```
+
 ---
 
 ## Request Builder Pattern
@@ -465,8 +484,7 @@ func downloadWithProgress(
 ```
 
 For large files, prefer `URLSessionDownloadTask` with a delegate for
-better memory efficiency and background support. See
-`references/background-websocket.md`.
+better memory efficiency and background support.
 
 ### Download to File with Progress (Delegate-Based)
 
@@ -832,76 +850,18 @@ let users = try await withRetry {
 
 ## Certificate Pinning (URLSessionDelegate)
 
-Pin the server's public key hash rather than the certificate itself.
-Certificates rotate; public keys are more stable. Always include a
-backup pin.
-
-```swift
-import CryptoKit
-
-final class PinningDelegate: NSObject, URLSessionDelegate, Sendable {
-    /// SHA-256 hashes of Subject Public Key Info (SPKI) in base64
-    private let pinnedKeyHashes: Set<String>
-
-    init(pinnedKeyHashes: Set<String>) {
-        self.pinnedKeyHashes = pinnedKeyHashes
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        didReceive challenge: URLAuthenticationChallenge
-    ) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
-        guard challenge.protectionSpace.authenticationMethod
-                == NSURLAuthenticationMethodServerTrust,
-              let trust = challenge.protectionSpace.serverTrust else {
-            return (.performDefaultHandling, nil)
-        }
-
-        // Evaluate the trust chain
-        var error: CFError?
-        guard SecTrustEvaluateWithError(trust, &error) else {
-            return (.cancelAuthenticationChallenge, nil)
-        }
-
-        // Extract the leaf certificate's public key
-        guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
-              let leafCert = chain.first,
-              let publicKey = SecCertificateCopyKey(leafCert),
-              let publicKeyData = SecKeyCopyExternalRepresentation(
-                  publicKey, nil
-              ) as Data? else {
-            return (.cancelAuthenticationChallenge, nil)
-        }
-
-        let keyHash = SHA256.hash(data: publicKeyData)
-        let hashString = Data(keyHash).base64EncodedString()
-
-        if pinnedKeyHashes.contains(hashString) {
-            return (.useCredential, URLCredential(trust: trust))
-        }
-
-        return (.cancelAuthenticationChallenge, nil)
-    }
-}
-
-// Usage
-let delegate = PinningDelegate(pinnedKeyHashes: [
-    "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",  // Primary
-    "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",  // Backup
-])
-
-let session = URLSession(
-    configuration: .default,
-    delegate: delegate,
-    delegateQueue: nil
-)
-```
+Prefer ATS `NSPinnedDomains` for declarative certificate pinning when the
+pinset can ship in `Info.plist`. For manual `URLSessionDelegate` trust work,
+defer to the `swift-security` skill: correct SPKI pinning requires hashing
+the Subject Public Key Info structure, not just the raw key bytes returned by
+`SecKeyCopyExternalRepresentation`.
 
 **Important considerations:**
 - Pin at least two keys (primary + backup) to avoid lockout during rotation.
 - Have a remote kill switch (feature flag) to disable pinning in emergencies.
 - Test certificate rotation in staging before deploying to production.
-- Do not pin intermediate CA certificates -- they rotate more frequently.
+- Always evaluate system trust before applying pins.
+- Keep certificate-trust implementation details in the security boundary.
 
 ---
 
@@ -1086,6 +1046,12 @@ func sseStream(from url: URL) -> AsyncThrowingStream<ServerSentEvent, Error> {
 
 ## Configured URLSession for Production
 
+Use a configured session for production clients instead of calling
+`URLSession.shared` from request methods. Set explicit request/resource
+timeouts, cache behavior, connectivity policy, and any delegates needed for
+authentication challenges, redirects, metrics, pinning boundaries, or
+background transfers before creating the `URLSession`.
+
 ```swift
 enum SessionFactory {
     static func makeDefault(delegate: (any URLSessionDelegate)? = nil) -> URLSession {