@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -1,500 +1,411 @@
 ---
 name: cloudkit-sync
-description: "Implement, review, or improve CloudKit and iCloud sync in iOS/macOS apps. Use when working with CKContainer, CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKShare, NSUbiquitousKeyValueStore, or iCloud Drive file coordination; when syncing SwiftData models via ModelConfiguration with cloudKitDatabase; when handling CKError codes for conflict resolution, network failures, or quota limits; or when checking iCloud account status before performing sync operations."
+description: "CloudKit and iCloud sync on iOS and macOS: CKContainer public, private and shared databases, CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKShare, NSUbiquitousKeyValueStore, iCloud Drive file coordination, SwiftData sync via ModelConfiguration cloudKitDatabase, CKError handling for conflicts, network failures and quota, iCloud account status checks. Use when implementing, reviewing or improving how an app stores or shares user data through iCloud."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# CloudKit
-
-Sync data across devices using CloudKit, iCloud key-value storage, and iCloud
-Drive. Covers container setup, record CRUD, queries, subscriptions, CKSyncEngine,
-SwiftData integration, conflict resolution, and error handling. Targets iOS 26+
-with Swift 6.3; older availability noted where relevant.
-
-## Contents
-
-- [Container and Database Setup](#container-and-database-setup)
-- [CKRecord CRUD](#ckrecord-crud)
-- [CKQuery](#ckquery)
-- [CKSubscription](#cksubscription)
-- [CKSyncEngine (iOS 17+)](#cksyncengine-ios-17)
-- [SwiftData + CloudKit](#swiftdata--cloudkit)
-- [NSUbiquitousKeyValueStore](#nsubiquitouskeyvaluestore)
-- [iCloud Drive File Sync](#icloud-drive-file-sync)
-- [Account Status and Error Handling](#account-status-and-error-handling)
-- [Conflict Resolution](#conflict-resolution)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Container and Database Setup
-
-Enable iCloud + CloudKit in Signing & Capabilities. A container provides three databases:
-
-| Database | Scope | Requires iCloud | Storage Quota |
-|----------|-------|-----------------|---------------|
-| Public   | All users | Read: No, Write: Yes | App quota |
-| Private  | Current user | Yes | User quota |
-| Shared   | Shared records | Yes | Owner quota |
+
+# CloudKit Sync
+
+Everything iCloud offers for app data: CloudKit databases, the key-value
+store, and iCloud Drive documents. This file covers containers, record
+operations, queries, subscriptions, `CKSyncEngine`, SwiftData integration,
+error handling and conflict merges for Swift 6.3 on iOS 26, with older
+availability noted where it matters.
+
+Incremental fetch operations, change tokens, sharing, zones, assets, batching,
+quality of service, encrypted fields and the Dashboard are in the
+[CloudKit patterns reference](references/cloudkit-patterns.md). Core Data
+stacks that sync through `NSPersistentCloudKitContainer` start in `core-data`;
+background push handling in general is `push-notifications`.
+
+## Containers and databases
+
+Enable **iCloud** with the **CloudKit** service under Signing & Capabilities.
+
+| Database | Who sees it | Needs an iCloud account | Storage charged to |
+|---|---|---|---|
+| Public | Every user of the app | Only for writes; reads work signed out | The app |
+| Private | The signed-in user | Yes | The user |
+| Shared | Records others shared with the user | Yes | The owner |
 
 ```swift
 import CloudKit
 
-let container = CKContainer.default()
-// Or named: CKContainer(identifier: "iCloud.com.example.app")
-
-let publicDB  = container.publicCloudDatabase
+let container = CKContainer(identifier: "iCloud.app.gardenlog")   // or CKContainer.default()
+let publicDB = container.publicCloudDatabase
 let privateDB = container.privateCloudDatabase
-let sharedDB  = container.sharedCloudDatabase
+let sharedDB = container.sharedCloudDatabase
 ```
 
-## CKRecord CRUD
+## Records
 
-Records are key-value pairs. Max 1 MB per record (excluding CKAsset data).
+A `CKRecord` is a typed dictionary. One record can hold up to 1 MB, not
+counting the files behind any `CKAsset` fields.
 
 ```swift
-// CREATE
-let record = CKRecord(recordType: "Note")
-record["title"] = "Meeting Notes" as CKRecordValue
-record["body"] = "Discussed Q3 roadmap" as CKRecordValue
-record["createdAt"] = Date() as CKRecordValue
-record["tags"] = ["work", "planning"] as CKRecordValue
-let saved = try await privateDB.save(record)
-
-// FETCH by ID
-let recordID = CKRecord.ID(recordName: "unique-id-123")
-let fetched = try await privateDB.record(for: recordID)
-
-// UPDATE -- fetch first, modify, then save
-fetched["title"] = "Updated Title" as CKRecordValue
-let updated = try await privateDB.save(fetched)
-
-// DELETE
-try await privateDB.deleteRecord(withID: recordID)
+func plant(named name: String, in db: CKDatabase) async throws -> CKRecord {
+    let plant = CKRecord(recordType: "Plant")
+    plant["name"] = name as CKRecordValue
+    plant["plantedOn"] = Date.now as CKRecordValue
+    plant["tags"] = ["herb", "sunny"] as CKRecordValue
+    return try await db.save(plant)
+}
+
+func rename(_ recordName: String, to newName: String, in db: CKDatabase) async throws {
+    let id = CKRecord.ID(recordName: recordName)
+    let existing = try await db.record(for: id)       // always fetch before editing
+    existing["name"] = newName as CKRecordValue
+    _ = try await db.save(existing)
+}
+
+func uproot(_ recordName: String, in db: CKDatabase) async throws {
+    _ = try await db.deleteRecord(withID: CKRecord.ID(recordName: recordName))
+}
 ```
 
-### Custom Record Zones
+### Custom zones
 
-Apps create custom zones in the private database. Shared databases expose zones
-that other users share with the current user. Custom zones support atomic
-commits, change tracking, and sharing; public databases do not support custom
+The private database accepts zones the app creates; the shared database
+exposes the zones other people shared with the user. Custom zones unlock
+atomic commits, change tracking and sharing. The public database has no custom
 zones.
 
 ```swift
-let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
-let zone = CKRecordZone(zoneID: zoneID)
-try await privateDB.save(zone)
+let beds = CKRecordZone.ID(zoneName: "GardenBeds")
+_ = try await privateDB.save(CKRecordZone(zoneID: beds))
 
-let recordID = CKRecord.ID(recordName: UUID().uuidString, zoneID: zoneID)
-let record = CKRecord(recordType: "Note", recordID: recordID)
+let bedID = CKRecord.ID(recordName: UUID().uuidString, zoneID: beds)
+let bed = CKRecord(recordType: "Bed", recordID: bedID)
 ```
 
-## CKQuery
-
-Query records with NSPredicate. Supported: `==`, `!=`, `<`, `>`, `<=`, `>=`,
-`BEGINSWITH`, `CONTAINS`, `IN`, `AND`, `NOT`, `BETWEEN`,
-`distanceToLocation:fromLocation:`.
+## Queries
 
-`CONTAINS` tests list membership except for tokenized full-text search with
-`self CONTAINS`. `BEGINSWITH` is the string-prefix operator; unsupported
-operators, key paths, or field types fail when the query executes.
-For every encryption review, explicitly call out field eligibility: encrypted
-values cannot be queried or sorted; `CKAsset` is encrypted by default; and
-`CKRecord.Reference` cannot be encrypted because CloudKit needs it server-side.
+CloudKit accepts a subset of `NSPredicate`:
 
-```swift
-let predicate = NSPredicate(format: "title BEGINSWITH %@", "Meeting")
-let query = CKQuery(recordType: "Note", predicate: predicate)
-query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]
-
-let (results, _) = try await privateDB.records(matching: query)
-for (_, result) in results {
-    let record = try result.get()
-    print(record["title"] as? String ?? "")
-}
+- comparisons `==`, `!=`, `<`, `>`, `<=`, `>=`
+- `BEGINSWITH` for string prefixes
+- `CONTAINS` for membership in a list field, except `self CONTAINS`, which runs a tokenized full-text search
+- `IN`, `AND`, `NOT`, `BETWEEN`
+- `distanceToLocation:fromLocation:` for location fields
 
-// Fetch all records of a type
-let allQuery = CKQuery(recordType: "Note", predicate: NSPredicate(value: true))
+An unsupported operator, key path or field type is only rejected when the
+query executes, not when you build it.
 
-// Full-text search across string fields
-let searchQuery = CKQuery(
-    recordType: "Note",
-    predicate: NSPredicate(format: "self CONTAINS %@", "roadmap")
-)
+Encrypted values cannot be queried or sorted. `CKAsset` contents are already
+encrypted, and a `CKRecord.Reference` can never be encrypted because the
+server needs it. Say all three whenever you review encryption.
 
-// Compound predicate
-let compound = NSCompoundPredicate(andPredicateWithSubpredicates: [
-    NSPredicate(format: "createdAt > %@", cutoffDate as NSDate),
-    NSPredicate(format: "tags CONTAINS %@", "work")
-])
+```swift
+func recentHerbs(in db: CKDatabase) async throws -> [CKRecord] {
+    let weekAgo = Date.now.addingTimeInterval(-7 * 86_400)
+    let predicate = NSCompoundPredicate(andPredicateWithSubpredicates: [
+        NSPredicate(format: "plantedOn > %@", weekAgo as NSDate),
+        NSPredicate(format: "tags CONTAINS %@", "herb"),
+    ])
+    let query = CKQuery(recordType: "Plant", predicate: predicate)
+    query.sortDescriptors = [NSSortDescriptor(key: "plantedOn", ascending: false)]
+
+    let (matches, _) = try await db.records(matching: query)
+    return matches.compactMap { try? $0.1.get() }
+}
 ```
 
-## CKSubscription
+Use `NSPredicate(value: true)` to match every record of a type.
 
-Subscriptions trigger push notifications when records change server-side.
-CloudKit/Xcode handles the APNs entitlement when CloudKit is enabled; no
-separate explicit App ID push setup is needed. Silent/background processing
-still needs Background Modes > Remote notifications.
+## Subscriptions
+
+A subscription makes CloudKit push a notification when server data changes.
+With CloudKit enabled, Xcode manages the push entitlement; no separate App ID
+push setup is needed. Silent pushes still require **Background Modes >
+Remote notifications**.
 
 ```swift
-// Query subscription -- fires when matching records change
-let subscription = CKQuerySubscription(
-    recordType: "Note",
-    predicate: NSPredicate(format: "tags CONTAINS %@", "urgent"),
-    subscriptionID: "urgent-notes",
+let newPlants = CKQuerySubscription(
+    recordType: "Plant",
+    predicate: NSPredicate(value: true),
+    subscriptionID: "plant-changes",
     options: [.firesOnRecordCreation, .firesOnRecordUpdate]
 )
-let notifInfo = CKSubscription.NotificationInfo()
-notifInfo.shouldSendContentAvailable = true  // silent push
-subscription.notificationInfo = notifInfo
-try await privateDB.save(subscription)
-
-// Database subscription -- fires on any database change
-let dbSub = CKDatabaseSubscription(subscriptionID: "private-db-changes")
-dbSub.notificationInfo = notifInfo
-try await privateDB.save(dbSub)
-
-// Record zone subscription -- fires on changes within a zone
-let zoneSub = CKRecordZoneSubscription(
-    zoneID: CKRecordZone.ID(zoneName: "NotesZone"),
-    subscriptionID: "notes-zone-changes"
-)
-zoneSub.notificationInfo = notifInfo
-try await privateDB.save(zoneSub)
-```
+let info = CKSubscription.NotificationInfo()
+info.shouldSendContentAvailable = true      // silent
+newPlants.notificationInfo = info
+_ = try await publicDB.save(newPlants)
 
-Handle in AppDelegate:
+let everything = CKDatabaseSubscription(subscriptionID: "private-db")          // any change in the DB
+let oneZone = CKRecordZoneSubscription(zoneID: beds, subscriptionID: "beds")   // changes in one zone
+```
 
 ```swift
-func application(
-    _ application: UIApplication,
-    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
-) async -> UIBackgroundFetchResult {
-    let notification = CKNotification(fromRemoteNotificationDictionary: userInfo)
-    guard notification?.subscriptionID == "private-db-changes" else { return .noData }
-    // Fetch changes using CKSyncEngine or CKFetchRecordZoneChangesOperation
-    return .newData
+import UIKit
+
+// UIApplicationDelegate
+func application(_ application: UIApplication,
+                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
+    guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo),
+          note.subscriptionID == "private-db" else { return .noData }
+    do {
+        try await GardenSync.shared.pullNow()   // CKSyncEngine or CKFetchRecordZoneChangesOperation
+        return .newData
+    } catch {
+        return .failed
+    }
 }
 ```
 
 ## CKSyncEngine (iOS 17+)
 
-`CKSyncEngine` is the recommended sync approach for custom model data. It
-handles scheduling, transient retries, change tokens, and database
-subscriptions, but not app-specific save failures: `CKError.serverRecordChanged`
-from `sentRecordZoneChanges.failedRecordSaves` still requires custom conflict
-resolution and rescheduling. Automatic sync timing is indeterminate. Requires
-CloudKit capability + Remote notifications; private/shared databases only.
+For custom model data, `CKSyncEngine` is the recommended route. It schedules
+work, retries transient failures, keeps change tokens and manages the
+database subscription for you. It does **not** resolve app-level save
+failures: a `CKError.serverRecordChanged` inside
+`sentRecordZoneChanges.failedRecordSaves` needs your merge and a reschedule.
+Its automatic timing is not predictable. It needs the CloudKit capability plus
+Remote notifications, and works only with private and shared databases, never
+public.
 
 ```swift
-import CloudKit
-
-final class SyncManager: CKSyncEngineDelegate {
-    let syncEngine: CKSyncEngine
+actor GardenSync: CKSyncEngineDelegate {
+    static let shared = GardenSync()
+    private var engine: CKSyncEngine?
 
-    init(container: CKContainer = .default()) {
+    func start() {
+        guard engine == nil else { return }
         let config = CKSyncEngine.Configuration(
-            database: container.privateCloudDatabase,
-            stateSerialization: Self.loadState(),
+            database: CKContainer.default().privateCloudDatabase,
+            stateSerialization: StateFile.load(),   // CKSyncEngine.State.Serialization?
             delegate: self
         )
-        self.syncEngine = CKSyncEngine(config)
+        engine = CKSyncEngine(config)
     }
 
     func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
         switch event {
         case .stateUpdate(let update):
-            Self.saveState(update.stateSerialization)
+            StateFile.save(update.stateSerialization)      // resume from the right token next launch
         case .accountChange(let change):
-            handleAccountChange(change)
-        case .fetchedRecordZoneChanges(let changes):
-            for mod in changes.modifications { processRemoteRecord(mod.record) }
-            for del in changes.deletions { processRemoteDeletion(del.recordID) }
+            await LocalStore.shared.handle(change)
+        case .fetchedRecordZoneChanges(let fetched):
+            for mod in fetched.modifications { await LocalStore.shared.upsert(mod.record) }
+            for gone in fetched.deletions { await LocalStore.shared.remove(gone.recordID) }
         case .sentRecordZoneChanges(let sent):
-            for saved in sent.savedRecords { markSynced(saved) }
-            for fail in sent.failedRecordSaves { handleSaveFailure(fail) }
-        default: break
+            for saved in sent.savedRecords { await LocalStore.shared.markSynced(saved) }
+            for failure in sent.failedRecordSaves { await resolve(failure, engine: syncEngine) }
+        default:
+            break
         }
     }
 
-    func nextRecordZoneChangeBatch(
-        _ context: CKSyncEngine.SendChangesContext,
-        syncEngine: CKSyncEngine
-    ) async -> CKSyncEngine.RecordZoneChangeBatch? {
-        let pending = syncEngine.state.pendingRecordZoneChanges
-            .filter { context.options.zoneIDs.contains($0) }
-        return await CKSyncEngine.RecordZoneChangeBatch(
-            pendingChanges: pending
-        ) { recordID in self.recordToSend(for: recordID) }
+    func nextRecordZoneChangeBatch(_ context: CKSyncEngine.SendChangesContext,
+                                   syncEngine: CKSyncEngine) async -> CKSyncEngine.RecordZoneChangeBatch? {
+        let scope = context.options.scope
+        let pending = syncEngine.state.pendingRecordZoneChanges.filter { scope.contains($0) }
+        return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { id in
+            await LocalStore.shared.record(for: id)
+        }
     }
-}
 
-// Schedule changes
-let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
-let recordID = CKRecord.ID(recordName: noteID, zoneID: zoneID)
-syncEngine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
+    func queueUpload(of id: CKRecord.ID) {
+        engine?.state.add(pendingRecordZoneChanges: [.saveRecord(id)])
+    }
 
-// Trigger immediate sync (pull-to-refresh)
-try await syncEngine.fetchChanges()
-try await syncEngine.sendChanges()
+    func pullNow() async throws {
+        guard let engine else { return }
+        try await engine.fetchChanges()     // pull-to-refresh or push arrival
+        try await engine.sendChanges()
+    }
+}
 ```
 
-**Key point**: persist `stateSerialization` across launches; the engine needs it
-to resume from the correct change token.
+`context.options.scope` says which zones (for example `.zoneIDs([...])`) or
+records this send covers; filter the pending changes to it rather than
+sending everything. Both delegate methods are `async`. Persist
+`stateSerialization` on every `.stateUpdate`; without it the engine starts
+over on the next launch.
 
-## SwiftData + CloudKit
+## SwiftData with CloudKit
 
-`ModelConfiguration` supports CloudKit sync. In every SwiftData CloudKit
-implementation or review, always report two verdicts:
+`ModelConfiguration` can sync a SwiftData store to CloudKit. Any
+implementation or review has to state **two verdicts**:
 
-- **Model compatibility**: no `#Unique` or unique constraints, optional
-  relationships, no `.deny`, and external storage for large `Data`.
-- **Schema rollout**: initialize the development schema in nonproduction builds,
-  verify it in CloudKit Dashboard, promote it before release, and after
-  production promotion only add schema; don't delete model types or change
-  existing attributes.
+1. **Model compatibility** - no `#Unique` macro or unique attributes, every
+   relationship optional, no `.deny` delete rule, and large `Data` marked for
+   external storage. Scalar properties do not all need to be optional; they
+   just need defaults or optionality where CloudKit requires it.
+2. **Schema rollout** - initialize the development schema from a non-release
+   build, inspect it in CloudKit Dashboard, and promote it to production before
+   shipping. After promotion, changes are additive only: never delete a model
+   type or change an existing attribute.
 
 ```swift
 import SwiftData
 
 @Model
-class Note {
-    var title: String
-    var body: String?
-    var createdAt: Date?
-    @Attribute(.externalStorage) var imageData: Data?
-
-    init(title: String, body: String? = nil) {
-        self.title = title
-        self.body = body
-        self.createdAt = Date()
-    }
+final class Harvest {
+    var crop: String = ""
+    var weightGrams: Double = 0
+    var pickedOn: Date = Date.now
+    @Attribute(.externalStorage) var photo: Data?
+    var bed: GardenBed?                 // optional relationship
+    init() {}
 }
+```
 
-let config = ModelConfiguration(
-    "Notes",
-    cloudKitDatabase: .private("iCloud.com.example.app")
-)
-let container = try ModelContainer(for: Note.self, configurations: config)
+```swift
+let config = ModelConfiguration("Garden", cloudKitDatabase: .private("iCloud.app.gardenlog"))
+let container = try ModelContainer(for: Harvest.self, GardenBed.self, configurations: config)
 ```
 
-## NSUbiquitousKeyValueStore
+## Key-value store
 
-Simple key-value sync. Max 1024 keys, 1 MB total, 1 MB per value. Stores
-locally when iCloud is unavailable.
+`NSUbiquitousKeyValueStore` holds small preferences: at most 1024 keys, 1 MB
+in total and 1 MB per value. It writes locally when iCloud is unavailable and
+syncs later.
 
 ```swift
-let kvStore = NSUbiquitousKeyValueStore.default
-
-// Write
-kvStore.set("dark", forKey: "theme")
-kvStore.set(14.0, forKey: "fontSize")
-kvStore.set(true, forKey: "notificationsEnabled")
-kvStore.synchronize()
+let kv = NSUbiquitousKeyValueStore.default
+kv.set("celsius", forKey: "temperatureUnit")
+kv.synchronize()
+let unit = kv.string(forKey: "temperatureUnit")
 
-// Read
-let theme = kvStore.string(forKey: "theme") ?? "system"
-
-// Observe external changes
 NotificationCenter.default.addObserver(
     forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
-    object: kvStore, queue: .main
-) { notification in
-    guard let userInfo = notification.userInfo,
-          let reason = userInfo[NSUbiquitousKeyValueStoreChangeReasonKey] as? Int,
-          let keys = userInfo[NSUbiquitousKeyValueStoreChangedKeysKey] as? [String]
-    else { return }
-
+    object: kv, queue: .main
+) { note in
+    let reason = note.userInfo?[NSUbiquitousKeyValueStoreChangeReasonKey] as? Int
+    let keys = note.userInfo?[NSUbiquitousKeyValueStoreChangedKeysKey] as? [String] ?? []
     switch reason {
-    case NSUbiquitousKeyValueStoreServerChange:
-        for key in keys { applyRemoteChange(key: key) }
-    case NSUbiquitousKeyValueStoreInitialSyncChange:
-        reloadAllSettings()
-    case NSUbiquitousKeyValueStoreQuotaViolationChange:
-        handleQuotaExceeded()
+    case NSUbiquitousKeyValueStoreServerChange:       Preferences.apply(keys)
+    case NSUbiquitousKeyValueStoreInitialSyncChange:  Preferences.reloadAll()
+    case NSUbiquitousKeyValueStoreQuotaViolationChange: Preferences.trimStorage()
     default: break
     }
 }
 ```
 
-## iCloud Drive File Sync
+## iCloud Drive documents
 
-Use `FileManager` ubiquity APIs for document-level sync. Call
-`url(forUbiquityContainerIdentifier:)` and `setUbiquitous` off the main thread;
-`setUbiquitous` performs coordinated file work and can block. If the app is
-presenting the file, configure an active file presenter before moving it.
+Documents sync through the `FileManager` ubiquity APIs. Both
+`url(forUbiquityContainerIdentifier:)` and
+`setUbiquitous(_:itemAt:destinationURL:)` can block (the second performs
+coordinated file operations), so call them off the main thread. A `nil`
+container URL means iCloud is not available. If the app is currently
+presenting the file, register a file presenter before moving it.
 
 ```swift
-Task.detached {
-    guard let ubiquityURL = FileManager.default.url(
-        forUbiquityContainerIdentifier: "iCloud.com.example.app"
-    ) else { return }  // iCloud not available
-
-    let docsURL = ubiquityURL.appendingPathComponent("Documents")
-    try FileManager.default.createDirectory(at: docsURL, withIntermediateDirectories: true)
-    let cloudURL = docsURL.appendingPathComponent("report.pdf")
-    try FileManager.default.setUbiquitous(true, itemAt: localURL, destinationURL: cloudURL)
+func moveToCloud(_ local: URL) {
+    Task.detached {
+        let fm = FileManager.default
+        guard let root = fm.url(forUbiquityContainerIdentifier: nil) else { return }
+        let docs = root.appending(path: "Documents", directoryHint: .isDirectory)
+        try? fm.createDirectory(at: docs, withIntermediateDirectories: true)
+        try? fm.setUbiquitous(true, itemAt: local, destinationURL: docs.appending(path: local.lastPathComponent))
+    }
 }
 ```
 
-Monitor files with `NSMetadataQuery` scoped to
-`NSMetadataQueryUbiquitousDocumentsScope` or
-`NSMetadataQueryUbiquitousDataScope`.
+Watch for changes with an `NSMetadataQuery` whose search scope is
+`NSMetadataQueryUbiquitousDocumentsScope` or `NSMetadataQueryUbiquitousDataScope`.
 
-## Account Status and Error Handling
+## Account status
 
-Always check account status before sync. Listen for `.CKAccountChanged`.
+Check the account before any sync, and listen for `.CKAccountChanged`.
 
 ```swift
-func checkiCloudStatus() async throws -> CKAccountStatus {
-    let status = try await CKContainer.default().accountStatus()
-    switch status {
-    case .available: return status
-    case .noAccount: throw SyncError.noiCloudAccount
-    case .restricted: throw SyncError.restricted
-    case .temporarilyUnavailable: throw SyncError.temporarilyUnavailable
-    case .couldNotDetermine: throw SyncError.unknown
-    @unknown default: throw SyncError.unknown
-    }
+switch try await CKContainer.default().accountStatus() {
+case .available:              await GardenSync.shared.start()
+case .noAccount:              showSignInToICloudHint()
+case .restricted:             showRestrictedNotice()
+case .temporarilyUnavailable: scheduleAccountRecheck()
+case .couldNotDetermine:      scheduleAccountRecheck()
+@unknown default:             scheduleAccountRecheck()
 }
 ```
 
-### CKError Handling
+## CKError handling
 
-| Error Code | Strategy |
-|-----------|----------|
-| `.networkFailure`, `.networkUnavailable` | Queue for retry when network returns |
-| `.serverRecordChanged` | Three-way merge (see Conflict Resolution) |
-| `.requestRateLimited`, `.zoneBusy`, `.serviceUnavailable` | Retry after `retryAfterSeconds` |
-| `.quotaExceeded` | Notify user; reduce data usage |
-| `.notAuthenticated` | Prompt iCloud sign-in |
-| `.partialFailure` | Inspect `partialErrorsByItemID` per item |
-| `.changeTokenExpired` | Reset token, refetch all changes |
-| `.userDeletedZone` | Recreate zone and re-upload data |
+| Code | Response |
+|---|---|
+| `.networkFailure`, `.networkUnavailable` | Queue the work and retry once connectivity returns |
+| `.serverRecordChanged` | Three-way merge (below) |
+| `.requestRateLimited`, `.zoneBusy`, `.serviceUnavailable` | Wait `retryAfterSeconds` before retrying |
+| `.quotaExceeded` | Tell the user; reduce stored data |
+| `.notAuthenticated` | Ask the user to sign in to iCloud |
+| `.partialFailure` | Walk `partialErrorsByItemID` and handle each item's error |
+| `.changeTokenExpired` | Drop the token and refetch everything |
+| `.userDeletedZone` | Recreate the zone and upload again |
 
 ```swift
-func handleCloudKitError(_ error: Error) {
-    guard let ckError = error as? CKError else { return }
-    switch ckError.code {
-    case .networkFailure, .networkUnavailable:
-        scheduleRetryWhenOnline()
-    case .serverRecordChanged:
-        resolveConflict(ckError)
-    case .requestRateLimited, .zoneBusy, .serviceUnavailable:
-        let delay = ckError.retryAfterSeconds ?? 3.0
-        scheduleRetry(after: delay)
-    case .quotaExceeded:
-        notifyUserStorageFull()
-    case .partialFailure:
-        if let partial = ckError.partialErrorsByItemID {
-            for (_, itemError) in partial { handleCloudKitError(itemError) }
-        }
-    case .changeTokenExpired:
-        resetChangeToken()
-    case .userDeletedZone:
-        recreateZoneAndResync()
-    default: logError(ckError)
-    }
+func retryDelay(for error: CKError) -> TimeInterval {
+    error.retryAfterSeconds ?? 3
 }
 ```
 
-## Conflict Resolution
+## Conflict resolution
 
-When saving a record that changed server-side, CloudKit returns
-`.serverRecordChanged` with three record versions. Always merge into
-`serverRecord` -- it has the correct change tag.
+A `.serverRecordChanged` error carries `ancestorRecord`, `clientRecord` and
+`serverRecord`. Always merge **into `serverRecord`**, because it holds the
+current change tag; saving the client copy just fails again.
 
 ```swift
-func resolveConflict(_ error: CKError) {
-    guard error.code == .serverRecordChanged,
-          let ancestor = error.ancestorRecord,
-          let client = error.clientRecord,
-          let server = error.serverRecord
-    else { return }
-
-    // Merge client changes into server record
-    for key in client.changedKeys() {
-        if server[key] == ancestor[key] {
-            server[key] = client[key]           // Server unchanged, use client
-        } else if client[key] == ancestor[key] {
-            // Client unchanged, keep server (already there)
+func merged(_ error: CKError) -> CKRecord? {
+    guard let server = error.serverRecord, let mine = error.clientRecord else { return nil }
+    let base = error.ancestorRecord
+    for key in mine.changedKeys() {
+        let serverValue = server[key] as? NSObject
+        let baseValue = base?[key] as? NSObject
+        let myValue = mine[key] as? NSObject
+        if serverValue == baseValue {
+            server[key] = mine[key]                  // only I changed it
+        } else if myValue == baseValue {
+            continue                                 // only the server changed it
         } else {
-            server[key] = mergeValues(          // Both changed, custom merge
-                ancestor: ancestor[key], client: client[key], server: server[key])
+            server[key] = resolveBothChanged(key, mine: mine[key], theirs: server[key])
         }
     }
-
-    Task { try await CKContainer.default().privateCloudDatabase.save(server) }
+    return server                                    // save this one
 }
 ```
 
-## Common Mistakes
-
-**DON'T:** Perform sync operations without checking account status.
-**DO:** Check `CKContainer.accountStatus()` first; handle `.noAccount`.
-```swift
-// WRONG
-try await privateDB.save(record)
-// CORRECT
-guard try await CKContainer.default().accountStatus() == .available
-else { throw SyncError.noiCloudAccount }
-try await privateDB.save(record)
-```
-
-**DON'T:** Ignore `.serverRecordChanged` errors.
-**DO:** Implement three-way merge using ancestor, client, and server records.
-
-**DON'T:** Store user-specific data in the public database.
-**DO:** Use private database for personal data; public only for app-wide content.
-
-**DON'T:** Poll for changes on a timer.
-**DO:** Use `CKDatabaseSubscription` or `CKSyncEngine` for push-based sync.
-```swift
-// WRONG
-Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in fetchAll() }
-// CORRECT
-let sub = CKDatabaseSubscription(subscriptionID: "db-changes")
-sub.notificationInfo = CKSubscription.NotificationInfo()
-sub.notificationInfo?.shouldSendContentAvailable = true
-try await privateDB.save(sub)
-```
-
-**DON'T:** Retry immediately on rate limiting.
-**DO:** Use `CKError.retryAfterSeconds` to wait the required duration.
-
-**DON'T:** Assume `CKSyncEngine` handles `.serverRecordChanged` conflicts for you.
-**DO:** Resolve `failedRecordSaves` with a three-way merge, then reschedule the save.
-
-**DON'T:** Pass nil change token on every fetch.
-**DO:** Persist change tokens to disk and supply them on subsequent fetches.
-
-## Review Checklist
-
-- [ ] iCloud + CloudKit capability enabled in Signing & Capabilities
-- [ ] Account status checked before sync; `.noAccount` handled gracefully
-- [ ] Private database used for user data; public only for shared content
-- [ ] Custom record zones created in private DB; shared DB zones discovered from shares
-- [ ] `CKError.serverRecordChanged` handled with three-way merge into `serverRecord`
-- [ ] Network failures queued for retry; `retryAfterSeconds` respected
-- [ ] `CKDatabaseSubscription` or `CKSyncEngine` used for push-based sync; Remote notifications enabled for background delivery
-- [ ] Change tokens persisted to disk; `changeTokenExpired` resets and refetches
-- [ ] `.partialFailure` errors inspected per-item via `partialErrorsByItemID`
-- [ ] `.userDeletedZone` handled by recreating zone and resyncing
-- [ ] SwiftData CloudKit review reports model compatibility and schema rollout: initialized/verified development schema, promoted before release, and additive-only production changes
-- [ ] `NSUbiquitousKeyValueStore.didChangeExternallyNotification` observed
-- [ ] Encryption review says `CKRecord.Reference` cannot use `encryptedValues` because CloudKit needs it server-side; no query/sort on encrypted fields; `CKAsset` is encrypted by default
-- [ ] `CKSyncEngine` state serialization persisted across launches (iOS 17+)
+## Common mistakes
+
+- Starting sync without confirming `accountStatus() == .available`.
+- Ignoring `.serverRecordChanged`, which silently loses edits.
+- Putting personal data in the public database. Private is for user data;
+  public is only for content every user should see.
+- Polling on a timer. Use a `CKDatabaseSubscription` with silent pushes or `CKSyncEngine`.
+- Retrying a rate-limited request immediately instead of waiting `retryAfterSeconds`.
+- Expecting `CKSyncEngine` to settle `.serverRecordChanged`. Merge the
+  `failedRecordSaves` yourself and reschedule them.
+- Fetching with a `nil` change token every time. Store tokens on disk.
+
+## Review checklist
+
+- [ ] iCloud capability with CloudKit enabled
+- [ ] Account status checked; `.noAccount` handled
+- [ ] User data kept in the private database
+- [ ] Custom zones in the private database; shared zones discovered from accepted shares
+- [ ] `.serverRecordChanged` merged into `serverRecord`
+- [ ] Network failures queued; `retryAfterSeconds` honored
+- [ ] Sync driven by pushes; Remote notifications background mode on
+- [ ] Change tokens persisted; `.changeTokenExpired` resets them
+- [ ] `.partialFailure` examined item by item
+- [ ] `.userDeletedZone` handled
+- [ ] SwiftData review gives both the model-compatibility and schema-rollout verdicts
+- [ ] Key-value store external-change notification observed
+- [ ] Encryption review mentions: references cannot be encrypted, encrypted fields cannot be queried or sorted, assets are encrypted already
+- [ ] `CKSyncEngine` state serialization saved (iOS 17+)
 
 ## References
 
-- See [references/cloudkit-patterns.md](references/cloudkit-patterns.md) for incremental sync, CKShare, zones, CKAsset storage, batch operations, and Dashboard usage.
-- [CloudKit Framework](https://sosumi.ai/documentation/cloudkit)
-- [CKContainer](https://sosumi.ai/documentation/cloudkit/ckcontainer)
-- [CKRecord](https://sosumi.ai/documentation/cloudkit/ckrecord)
-- [CKQuery](https://sosumi.ai/documentation/cloudkit/ckquery)
-- [CKSubscription](https://sosumi.ai/documentation/cloudkit/cksubscription)
-- [CKSyncEngine](https://sosumi.ai/documentation/cloudkit/cksyncengine)
-- [CKShare](https://sosumi.ai/documentation/cloudkit/ckshare)
-- [CKError](https://sosumi.ai/documentation/cloudkit/ckerror)
-- [NSUbiquitousKeyValueStore](https://sosumi.ai/documentation/foundation/nsubiquitouskeyvaluestore)
-- [SwiftData CloudKit sync](https://sosumi.ai/documentation/swiftdata/syncing-model-data-across-a-persons-devices)
+- [CloudKit patterns](references/cloudkit-patterns.md) - incremental fetches, tokens, sharing, zones, assets, batches, QoS, encryption, Dashboard
+- [CloudKit](https://developer.apple.com/documentation/cloudkit)
+- [CKContainer](https://developer.apple.com/documentation/cloudkit/ckcontainer)
+- [CKRecord](https://developer.apple.com/documentation/cloudkit/ckrecord)
+- [CKQuery](https://developer.apple.com/documentation/cloudkit/ckquery)
+- [CKSubscription](https://developer.apple.com/documentation/cloudkit/cksubscription)
+- [CKSyncEngine](https://developer.apple.com/documentation/cloudkit/cksyncengine-5sie5)
+- [CKShare](https://developer.apple.com/documentation/cloudkit/ckshare)
+- [CKError](https://developer.apple.com/documentation/cloudkit/ckerror)
+- [NSUbiquitousKeyValueStore](https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore)
+- SwiftData: the article on syncing model data across a person's devices