@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/cloudkit-sync/references/cloudkit-patterns.md

@@ -1,464 +1,336 @@
 # CloudKit Patterns
 
-Advanced CloudKit patterns including incremental sync with
-CKFetchRecordZoneChangesOperation, sharing with CKShare, record zone
-management, CKAsset file storage, batch operations, and CloudKit Dashboard.
+Lower-level operations and features behind the [skill overview](../SKILL.md):
+incremental fetching, tokens, sharing, zones, files, batching, scheduling,
+encryption and the Dashboard.
 
 ## Contents
 
-- [CKFetchRecordZoneChangesOperation (Incremental Sync)](#ckfetchrecordzonechangesoperation-incremental-sync)
-- [Server Change Token Management](#server-change-token-management)
-- [CKShare and Collaboration](#ckshare-and-collaboration)
-- [UICloudSharingController](#uicloudsharingcontroller)
-- [Record Zone Management](#record-zone-management)
-- [CKAsset File Storage](#ckasset-file-storage)
-- [Batch Operations](#batch-operations)
-- [Operation Queues and QoS](#operation-queues-and-qos)
-- [Encrypted Fields](#encrypted-fields)
+- [Incremental zone fetches](#incremental-zone-fetches)
+- [Server change tokens](#server-change-tokens)
+- [Sharing with `CKShare`](#sharing-with-ckshare)
+- [`UICloudSharingController`](#uicloudsharingcontroller)
+- [Zones](#zones)
+- [Files with `CKAsset`](#files-with-ckasset)
+- [Batches](#batches)
+- [Quality of service and groups](#quality-of-service-and-groups)
+- [Encrypted fields](#encrypted-fields)
 - [CloudKit Dashboard](#cloudkit-dashboard)
-- [CKFetchDatabaseChangesOperation](#ckfetchdatabasechangesoperation)
+- [Discovering changed zones](#discovering-changed-zones)
 
-## CKFetchRecordZoneChangesOperation (Incremental Sync)
+## Incremental zone fetches
 
-Fetches only records that changed since the last sync. Works with private and
-shared databases only. Provide a server change token per zone; use `nil` for
-the initial fetch.
+`CKFetchRecordZoneChangesOperation` returns only what changed since the last
+token, per zone, in the private or shared database. Pass `nil` as the token for
+the first full fetch.
 
 ```swift
 import CloudKit
 
-final class IncrementalSyncManager {
-    private let database: CKDatabase
-    private var changeTokens: [CKRecordZone.ID: CKServerChangeToken] = [:]
-    private let tokenCacheURL: URL
+func pullZone(_ zone: CKRecordZone.ID, from db: CKDatabase, tokens: TokenStore) {
+    let settings = CKFetchRecordZoneChangesOperation.ZoneConfiguration()
+    settings.previousServerChangeToken = tokens.token(for: zone)
 
-    init(database: CKDatabase, cacheDirectory: URL) {
-        self.database = database
-        self.tokenCacheURL = cacheDirectory.appendingPathComponent("changeTokens.data")
-        loadTokens()
-    }
-
-    func fetchChanges(in zoneIDs: [CKRecordZone.ID]) async throws {
-        var configs: [CKRecordZone.ID: CKFetchRecordZoneChangesOperation.ZoneConfiguration] = [:]
-        for zoneID in zoneIDs {
-            let config = CKFetchRecordZoneChangesOperation.ZoneConfiguration()
-            config.previousServerChangeToken = changeTokens[zoneID]
-            configs[zoneID] = config
-        }
+    let op = CKFetchRecordZoneChangesOperation(recordZoneIDs: [zone],
+                                               configurationsByRecordZoneID: [zone: settings])
+    op.fetchAllChanges = true
 
-        let operation = CKFetchRecordZoneChangesOperation(
-            recordZoneIDs: zoneIDs,
-            configurationsByRecordZoneID: configs
-        )
-        operation.fetchAllChanges = true
-
-        // Process changed records
-        operation.recordWasChangedBlock = { recordID, result in
-            switch result {
-            case .success(let record):
-                self.processChangedRecord(record)
-            case .failure(let error):
-                self.handleRecordError(recordID, error: error)
-            }
-        }
-
-        // Process deleted records
-        operation.recordWithIDWasDeletedBlock = { recordID, recordType in
-            self.processDeletedRecord(recordID, type: recordType)
+    op.recordWasChangedBlock = { id, result in
+        if case .success(let record) = result { Inbox.upsert(record) }
+    }
+    op.recordWithIDWasDeletedBlock = { id, recordType in
+        Inbox.delete(id, type: recordType)
+    }
+    op.recordZoneFetchResultBlock = { zoneID, result in
+        switch result {
+        case .success(let outcome):
+            tokens.set(outcome.serverChangeToken, for: zoneID)       // cache right away
+        case .failure(let error as CKError) where error.code == .changeTokenExpired:
+            tokens.set(nil, for: zoneID)                              // start over next time
+        case .failure:
+            break
         }
+    }
+    op.fetchRecordZoneChangesResultBlock = { overall in
+        if case .failure(let error) = overall { SyncLog.record(error) }
+    }
+    op.qualityOfService = .utility
+    db.add(op)
+}
+```
 
-        // Update change token as zones complete
-        operation.recordZoneFetchResultBlock = { zoneID, result in
-            switch result {
-            case .success(let (serverChangeToken, _, _)):
-                self.changeTokens[zoneID] = serverChangeToken
-                self.saveTokens()
-            case .failure(let error):
-                if let ckError = error as? CKError,
-                   ckError.code == .changeTokenExpired {
-                    // Clear token and refetch from scratch
-                    self.changeTokens[zoneID] = nil
-                    self.saveTokens()
-                }
-            }
-        }
+### Writing tokens to disk
 
-        operation.fetchRecordZoneChangesResultBlock = { result in
-            if case .failure(let error) = result {
-                print("Fetch zone changes failed: \(error)")
-            }
+```swift
+final class TokenStore: @unchecked Sendable {
+    private let file: URL
+    private var tokens: [CKRecordZone.ID: CKServerChangeToken] = [:]
+    private let lock = NSLock()
+
+    init(file: URL) {
+        self.file = file
+        if let archived = try? Data(contentsOf: file),
+           let dict = try? NSKeyedUnarchiver.unarchivedObject(
+               ofClasses: [NSDictionary.self, CKRecordZone.ID.self, CKServerChangeToken.self],
+               from: archived) as? [CKRecordZone.ID: CKServerChangeToken] {
+            tokens = dict
         }
-
-        operation.qualityOfService = .utility
-        database.add(operation)
     }
 
-    // MARK: - Token Persistence
-
-    private func loadTokens() {
-        guard let data = try? Data(contentsOf: tokenCacheURL),
-              let tokens = try? NSKeyedUnarchiver.unarchivedObject(
-                  ofClasses: [NSDictionary.self, CKRecordZone.ID.self,
-                              CKServerChangeToken.self],
-                  from: data) as? [CKRecordZone.ID: CKServerChangeToken]
-        else { return }
-        changeTokens = tokens
+    func token(for zone: CKRecordZone.ID) -> CKServerChangeToken? {
+        lock.withLock { tokens[zone] }
     }
 
-    private func saveTokens() {
-        guard let data = try? NSKeyedArchiver.archivedData(
-            withRootObject: changeTokens, requiringSecureCoding: true)
-        else { return }
-        try? data.write(to: tokenCacheURL)
+    func set(_ token: CKServerChangeToken?, for zone: CKRecordZone.ID) {
+        lock.withLock {
+            tokens[zone] = token
+            let snapshot = tokens as NSDictionary
+            if let encoded = try? NSKeyedArchiver.archivedData(withRootObject: snapshot, requiringSecureCoding: true) {
+                try? encoded.write(to: file, options: .atomic)
+            }
+        }
     }
 }
 ```
 
-## Server Change Token Management
+## Server change tokens
 
-Change tokens are opaque pointers to a point in a zone's change history. Rules:
+- A token is an opaque bookmark into one zone's (or one database's) change history.
+- Tokens adopt `NSSecureCoding`, so they can be archived and stored.
+- A zone token and a database token are different things; never swap them.
+- `.changeTokenExpired` means the bookmark is too old. Set it to `nil` and refetch everything.
+- Save the new token as soon as `recordZoneFetchResultBlock` delivers it.
 
-- Tokens conform to `NSSecureCoding` -- safe to persist to disk.
-- Zone change tokens are NOT interchangeable with database change tokens.
-- A `.changeTokenExpired` error means the token is too old; reset to `nil` and
-  refetch all changes.
-- On `recordZoneFetchResultBlock`, cache the returned token immediately.
+For a handful of zones, `UserDefaults` works too:
 
 ```swift
-// Persist token alongside zone ID
-func cacheToken(_ token: CKServerChangeToken?, for zoneID: CKRecordZone.ID) {
-    guard let token else {
-        UserDefaults.standard.removeObject(forKey: "token-\(zoneID.zoneName)")
+func remember(_ token: CKServerChangeToken?, zone: String) {
+    let key = "ck.token.\(zone)"
+    guard let token,
+          let blob = try? NSKeyedArchiver.archivedData(withRootObject: token as NSSecureCoding, requiringSecureCoding: true)
+    else {
+        UserDefaults.standard.removeObject(forKey: key)
         return
     }
-    let data = try? NSKeyedArchiver.archivedData(
-        withRootObject: token, requiringSecureCoding: true)
-    UserDefaults.standard.set(data, forKey: "token-\(zoneID.zoneName)")
-}
-
-func cachedToken(for zoneID: CKRecordZone.ID) -> CKServerChangeToken? {
-    guard let data = UserDefaults.standard.data(forKey: "token-\(zoneID.zoneName)")
-    else { return nil }
-    return try? NSKeyedUnarchiver.unarchivedObject(
-        ofClass: CKServerChangeToken.self, from: data)
+    UserDefaults.standard.set(blob, forKey: key)
 }
 ```
 
-## CKShare and Collaboration
-
-CKShare manages shared access to records or entire record zones. Limit: 100
-participants per share. Available iOS 10+.
+## Sharing with `CKShare`
 
-### Hierarchy-Based Sharing
-
-Share a root record and its children (linked via `parent` references).
+`CKShare` (iOS 10+) shares one record hierarchy or an entire zone, with up to
+100 participants per share.
 
 ```swift
-import CloudKit
-
-// Create a share for a root record
-let rootRecord = CKRecord(recordType: "Album", recordID: albumRecordID)
-let share = CKShare(rootRecord: rootRecord)
-share.publicPermission = .readOnly
-
-// Customize share appearance
-share[CKShare.SystemFieldKey.title] = "Vacation Photos" as CKRecordValue
-share[CKShare.SystemFieldKey.shareType] = "com.example.album" as CKRecordValue
-
-// Save share and root record together
-let operation = CKModifyRecordsOperation(
-    recordsToSave: [rootRecord, share],
-    recordIDsToDelete: nil
-)
-operation.modifyRecordsResultBlock = { result in
-    switch result {
-    case .success:
-        print("Share URL: \(share.url?.absoluteString ?? "nil")")
-    case .failure(let error):
-        print("Sharing failed: \(error)")
+func shareGarden(_ root: CKRecord, in db: CKDatabase) async throws -> URL? {
+    let share = CKShare(rootRecord: root)       // children follow via their `parent` reference
+    share[CKShare.SystemFieldKey.title] = "Community Garden" as CKRecordValue
+    share[CKShare.SystemFieldKey.shareType] = "app.gardenlog.garden" as CKRecordValue
+    share.publicPermission = .readOnly
+
+    return try await withCheckedThrowingContinuation { (done: CheckedContinuation<URL?, Error>) in
+        let op = CKModifyRecordsOperation(recordsToSave: [root, share], recordIDsToDelete: nil)
+        op.modifyRecordsResultBlock = { result in
+            switch result {
+            case .success: done.resume(returning: share.url)
+            case .failure(let problem): done.resume(throwing: problem)
+            }
+        }
+        db.add(op)
     }
 }
-privateDB.add(operation)
 ```
 
-### Zone-Wide Sharing
+Save the root and the share **in the same operation**; `share.url` is set only
+after that save succeeds. To share a whole zone, use
+`CKShare(recordZoneID:)` instead.
 
-Share all records in a custom zone.
+### Adding people
 
 ```swift
-let zoneID = CKRecordZone.ID(zoneName: "SharedAlbums")
-let share = CKShare(recordZoneID: zoneID)
-share.publicPermission = .readWrite
+func invite(_ emails: [String], to share: CKShare, container: CKContainer) async throws {
+    let people = try await container.shareParticipants(
+        for: emails.map { CKUserIdentity.LookupInfo(emailAddress: $0) })
+    for (_, result) in people {
+        let person = try result.get()
+        person.permission = .readWrite
+        share.addParticipant(person)
+    }
+    _ = try await container.privateCloudDatabase.save(share)
+}
 ```
 
-### Adding Participants
+`container.shareParticipants(forEmailAddresses:)` is the shorter variant when
+you only have addresses.
 
-```swift
-// Look up participants by email
-let lookupInfo = CKUserIdentity.LookupInfo(emailAddress: "friend@example.com")
-let participants = try await container.shareParticipants(
-    forEmailAddresses: ["friend@example.com"])
-
-for participant in participants {
-    participant.permission = .readWrite
-    share.addParticipant(participant)
-}
+### Accepting a share
 
-// Save the updated share
-try await privateDB.save(share)
-```
-
-### Accepting a Share
+Share links open the app only when Info.plist sets `CKSharingSupported` to `YES`.
 
 ```swift
-// In AppDelegate or SceneDelegate
-func userDidAcceptCloudKitShare(with metadata: CKShare.Metadata) {
-    let container = CKContainer(identifier: metadata.containerIdentifier)
+func windowScene(_ scene: UIWindowScene, userDidAcceptCloudKitShareWith metadata: CKShare.Metadata) {
     Task {
-        do {
-            try await container.accept([metadata])
-            // Fetch shared records from container.sharedCloudDatabase
-        } catch {
-            print("Accept failed: \(error)")
-        }
+        let owner = CKContainer(identifier: metadata.containerIdentifier)
+        _ = try await owner.accept([metadata])
+        try await GardenSync.shared.pullNow()     // records now appear in sharedCloudDatabase
     }
 }
 ```
 
-**Required**: add `CKSharingSupported = YES` to Info.plist so the system can
-launch your app from share URLs.
+The app delegate variant is `userDidAcceptCloudKitShare(with:)`.
 
-## UICloudSharingController
+## `UICloudSharingController`
 
-Present the system sharing UI (iOS only).
+The system sharing sheet, iOS only:
 
 ```swift
 import UIKit
 import CloudKit
 
-func presentSharingUI(for share: CKShare, container: CKContainer,
-                      from viewController: UIViewController) {
-    let sharingController = UICloudSharingController(share: share, container: container)
-    sharingController.delegate = self
-    sharingController.availablePermissions = [.allowReadOnly, .allowReadWrite, .allowPrivate]
-    viewController.present(sharingController, animated: true)
-}
-
-// UICloudSharingControllerDelegate
-extension MyClass: UICloudSharingControllerDelegate {
-    func cloudSharingController(
-        _ csc: UICloudSharingController,
-        failedToSaveShareWithError error: Error
-    ) {
-        print("Save share error: \(error)")
+final class GardenDetailViewController: UIViewController, UICloudSharingControllerDelegate {
+    func presentSharing(_ share: CKShare, in container: CKContainer) {
+        let sheet = UICloudSharingController(share: share, container: container)
+        sheet.availablePermissions = [.allowReadOnly, .allowReadWrite, .allowPrivate]
+        sheet.delegate = self
+        present(sheet, animated: true)
     }
 
-    func itemTitle(for csc: UICloudSharingController) -> String? {
-        return "My Shared Album"
+    func cloudSharingController(_ controller: UICloudSharingController, failedToSaveShareWithError saveError: Error) {
+        SyncLog.record(saveError)
     }
+
+    func itemTitle(for controller: UICloudSharingController) -> String? { "Community Garden" }
 }
 ```
 
-## Record Zone Management
+## Zones
 
-Custom record zones in the private database enable atomic commits, change
-tracking with tokens, and record sharing.
+Only zones you create yourself in the private store give you atomic commits,
+token-based change tracking and sharing. The default zone has neither custom
+change tokens nor atomic operations, so sync code should always use custom zones.
 
 ```swift
-// Create
-let zoneID = CKRecordZone.ID(zoneName: "NotesZone", ownerName: CKCurrentUserDefaultName)
-let zone = CKRecordZone(zoneID: zoneID)
-try await privateDB.save(zone)
-
-// Fetch all zones
-let zones = try await privateDB.allRecordZones()
-
-// Delete
-try await privateDB.deleteRecordZone(withID: zoneID)
+let zoneID = CKRecordZone.ID(zoneName: "Harvests", ownerName: CKCurrentUserDefaultName)
+_ = try await privateDB.save(CKRecordZone(zoneID: zoneID))
+let everyZone = try await privateDB.allRecordZones()        // list
+_ = try await privateDB.deleteRecordZone(withID: zoneID)   // remove
 ```
 
-**Note**: the default zone does not support custom change tokens or atomic
-operations. Always use custom zones for sync.
-
-## CKAsset File Storage
+## Files with `CKAsset`
 
-Use CKAsset for files, images, and binary data larger than a few KB. Assets do
-not count toward the 1 MB record limit.
+Anything bigger than a few kilobytes (photos, audio, blobs) belongs in a
+`CKAsset`; asset bytes are stored apart from the record and are exempt from its 1 MB cap.
 
 ```swift
-// Save an image as a CKAsset
-let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("photo.jpg")
-try imageData.write(to: tempURL)
-
-let record = CKRecord(recordType: "Photo")
-record["image"] = CKAsset(fileURL: tempURL)
-record["caption"] = "Sunset at the beach" as CKRecordValue
-try await privateDB.save(record)
-
-// Fetch and read the asset
-let fetched = try await privateDB.record(for: record.recordID)
-if let asset = fetched["image"] as? CKAsset,
-   let fileURL = asset.fileURL {
-    let data = try Data(contentsOf: fileURL)
-    // Move to app container immediately -- staging area is temporary
-    let permanentURL = documentsDir.appendingPathComponent("photo.jpg")
-    try FileManager.default.moveItem(at: fileURL, to: permanentURL)
+func attachPhoto(_ jpeg: Data, to record: CKRecord) throws {
+    let tmp = FileManager.default.temporaryDirectory.appending(path: UUID().uuidString + ".jpg")
+    try jpeg.write(to: tmp)
+    record["photo"] = CKAsset(fileURL: tmp)
 }
 
-// Remove an asset (orphan it)
-record["image"] = nil
-try await privateDB.save(record)
-// CloudKit periodically deletes orphaned assets from the server
+func keepPhoto(from record: CKRecord, into folder: URL) throws -> URL? {
+    guard let asset = record["photo"] as? CKAsset, let staged = asset.fileURL else { return nil }
+    let destination = folder.appending(path: record.recordID.recordName + ".jpg")
+    try FileManager.default.moveItem(at: staged, to: destination)   // staging copy is temporary
+    return destination
+}
 ```
 
-**Exclude assets from fetch when not needed** using `desiredKeys` on operations
-to save bandwidth.
+To delete an asset, set the field to `nil` and save; CloudKit cleans up
+orphaned asset files on its own schedule. Use `desiredKeys` on fetch
+operations to skip asset fields you do not need.
 
-## Batch Operations
+## Batches
 
-Use `CKModifyRecordsOperation` for atomic saves and deletes.
+`CKModifyRecordsOperation` saves and deletes in bulk:
 
 ```swift
-let recordsToSave: [CKRecord] = [record1, record2, record3]
-let idsToDelete: [CKRecord.ID] = [oldRecordID]
-
-let operation = CKModifyRecordsOperation(
-    recordsToSave: recordsToSave,
-    recordIDsToDelete: idsToDelete
-)
-operation.savePolicy = .changedKeys       // Only upload modified fields
-operation.isAtomic = true                 // All or nothing (custom zones only)
-
-operation.perRecordSaveBlock = { recordID, result in
-    switch result {
-    case .success(let record): print("Saved: \(recordID)")
-    case .failure(let error): print("Failed: \(recordID) \(error)")
-    }
-}
-
-operation.perRecordDeleteBlock = { recordID, result in
-    switch result {
-    case .success: print("Deleted: \(recordID)")
-    case .failure(let error): print("Delete failed: \(recordID) \(error)")
-    }
-}
-
-operation.modifyRecordsResultBlock = { result in
-    if case .failure(let error) = result {
-        print("Batch failed: \(error)")
-    }
-}
-
-// CloudKit limits: 400 records per operation
-operation.qualityOfService = .userInitiated
-privateDB.add(operation)
+let op = CKModifyRecordsOperation(recordsToSave: changed, recordIDsToDelete: removed)
+op.savePolicy = .changedKeys        // upload only modified fields
+op.isAtomic = true                  // every change lands or none does (custom zones)
+op.perRecordSaveBlock = { id, result in Outbox.note(id, result) }
+op.perRecordDeleteBlock = { id, result in Outbox.noteDeletion(id, result) }
+op.modifyRecordsResultBlock = { result in Outbox.finish(result) }
+privateDB.add(op)
 ```
 
-**Max 400 records per operation.** For larger batches, split into chunks.
-
-## Operation Queues and QoS
+One operation takes at most 400 records. Split larger sets into chunks.
 
-Set appropriate quality of service:
+## Quality of service and groups
 
-| Scenario | QoS |
-|----------|-----|
-| User triggered action | `.userInitiated` |
-| Background sync | `.utility` |
-| Pre-fetch / maintenance | `.background` |
+| Work | QoS |
+|---|---|
+| The user is waiting on it | `.userInitiated` |
+| Routine background sync | `.utility` |
+| Prefetching, cleanup | `.background` |
 
 ```swift
-// Use operation groups for related operations
-let group = CKOperationGroup()
-group.expectedSendSize = .kilobytes
-group.expectedReceiveSize = .megabytes
-
-let config = CKOperation.Configuration()
-config.qualityOfService = .utility
-config.group = group
-
-let operation = CKQueryOperation(query: query)
-operation.configuration = config
-database.add(operation)
+func tagAsBackgroundSync(_ op: CKOperation) {
+    let group = CKOperationGroup()
+    group.expectedSendSize = .kilobytes
+    group.expectedReceiveSize = .megabytes
+
+    let configuration = CKOperation.Configuration()
+    configuration.qualityOfService = .utility
+    op.configuration = configuration
+    op.group = group                  // the group is set on the operation itself
+}
 ```
 
-## Encrypted Fields
-
-Use `encryptedValues` (iOS 15+) for sensitive private or shared data that does
-not need query or sort indexes. CloudKit can encrypt only new schema fields;
-you cannot convert an existing field to encrypted storage, and encrypted values
-are unavailable for public database records. `CKAsset` data is encrypted by
-default, while `CKRecord.Reference` is not encrypted because CloudKit needs it
-for server-side relationship handling.
+## Encrypted fields
 
-```swift
-let record = CKRecord(recordType: "HealthEntry")
-record.encryptedValues["heartRate"] = 72 as CKRecordValue
-record.encryptedValues["notes"] = "Resting" as CKRecordValue
-// Non-sensitive fields remain in plain text
-record["date"] = Date() as CKRecordValue
+`encryptedValues` (iOS 15+) encrypts sensitive fields in private and shared
+databases, as long as you never need to query or sort on them.
 
-try await privateDB.save(record)
+- Only a **new** schema field can be encrypted; an existing field cannot be converted.
+- Public database records cannot use encrypted values.
+- `CKAsset` data is encrypted already.
+- `CKRecord.Reference` fields stay unencrypted because the server needs them for relationships.
 
-// Read encrypted values
-let fetched = try await privateDB.record(for: record.recordID)
-let heartRate = fetched.encryptedValues["heartRate"] as? Int
+```swift
+let journal = CKRecord(recordType: "Journal")
+journal["title"] = "Tomato notes" as CKRecordValue               // plain, can be queried
+journal.encryptedValues["body"] = "Blight on bed 3" as NSString   // encrypted
+let body = fetched.encryptedValues["body"] as? String
 ```
 
 ## CloudKit Dashboard
 
-Access at [iCloud Dashboard](https://icloud.developer.apple.com/dashboard).
-Key capabilities:
+Open it at `icloud.developer.apple.com` (the `/dashboard` path).
 
-- **Schema**: view/edit record types, fields, indexes. Add indexes only for
-  queried fields in production.
-- **Records**: browse, create, edit, delete records in any database.
-- **Subscriptions**: view active subscriptions.
-- **Logs**: monitor API calls, errors, and latency.
-- **Telemetry**: track request counts, error rates, latency percentiles.
-- **Environment toggle**: switch between Development and Production. Simulator
-  only works with Development.
-- **Deploy to Production**: migrate schema changes from dev to prod. Production
-  does not allow adding new record types or fields programmatically.
+- **Schema**: record types, fields and indexes. In production, add indexes only for fields you actually query.
+- **Records**: browse and edit data.
+- **Subscriptions**: see what is registered.
+- **Logs**: API calls, errors, latency.
+- **Telemetry**: how many requests, how often they fail, and latency percentiles.
+- **Environment switch**: Development or Production. The Simulator only talks to Development.
+- **Deploy to Production** copies the schema. Production refuses to create record types or fields from code.
 
-## CKFetchDatabaseChangesOperation
+## Discovering changed zones
 
-Discover which zones changed in a database. Use with shared database where you
-do not know zone IDs in advance.
+`CKFetchDatabaseChangesOperation` reports the zones whose contents moved since a database token.
+It is how you find zones in the shared database when you do not know their IDs.
 
 ```swift
-var dbChangeToken: CKServerChangeToken? = loadDatabaseChangeToken()
-
-let operation = CKFetchDatabaseChangesOperation(
-    previousServerChangeToken: dbChangeToken
-)
-operation.fetchAllChanges = true
-
-var changedZoneIDs: [CKRecordZone.ID] = []
-var deletedZoneIDs: [CKRecordZone.ID] = []
-
-operation.recordZoneWithIDChangedBlock = { zoneID in
-    changedZoneIDs.append(zoneID)
-}
-
-operation.recordZoneWithIDWasDeletedBlock = { zoneID in
-    deletedZoneIDs.append(zoneID)
-}
-
-operation.fetchDatabaseChangesResultBlock = { result in
-    switch result {
-    case .success(let (token, _)):
-        dbChangeToken = token
-        saveDatabaseChangeToken(token)
-        // Now fetch zone changes for changedZoneIDs
-    case .failure(let error):
-        if let ckError = error as? CKError,
-           ckError.code == .changeTokenExpired {
-            dbChangeToken = nil
-            // Refetch from scratch
+func changedZones(in db: CKDatabase, since token: CKServerChangeToken?,
+                  store: @escaping @Sendable (CKServerChangeToken?) -> Void,
+                  then fetchZones: @escaping @Sendable ([CKRecordZone.ID]) -> Void) {
+    let op = CKFetchDatabaseChangesOperation(previousServerChangeToken: token)
+    op.fetchAllChanges = true
+    let collected = ZoneCollector()
+    op.recordZoneWithIDChangedBlock = { collected.add($0) }
+    op.recordZoneWithIDWasDeletedBlock = { LocalStore.dropZone($0) }
+    op.fetchDatabaseChangesResultBlock = { result in
+        switch result {
+        case .success(let outcome):
+            store(outcome.serverChangeToken)
+            fetchZones(collected.all)          // then run the zone-changes operation
+        case .failure(let error as CKError) where error.code == .changeTokenExpired:
+            store(nil)
+        case .failure:
+            break
         }
     }
+    db.add(op)
 }
-
-operation.qualityOfService = .utility
-sharedDB.add(operation)
 ```