crossmate

SyncEngine.swift (85729B)

---

 import CloudKit
 import CoreData
 import Foundation
 import SwiftUI
 
 extension EnvironmentValues {
     @Entry var syncEngine: SyncEngine? = nil
     @Entry var resetDatabase: (() async -> Void)? = nil
 }
 
 extension Notification.Name {
     /// Posted by `SyncEngine` after applying fetched record zone changes
     /// that affected one or more games. `userInfo["gameIDs"]` is a
     /// `Set<UUID>`. `PlayerRoster` observes this to refresh in response
     /// to remote name updates and new participants joining.
     static let playerRosterShouldRefresh = Notification.Name("playerRosterShouldRefresh")
 }
 
 /// What a Ping record represents. Stored as a string in the CKRecord's
 /// `kind` field.
 enum PingKind: String, Sendable {
     case session
     case join
     case win
     case check
     case reveal
 }
 
 /// Granularity of a check/reveal action. Stored as a string in the CKRecord's
 /// `scope` field; nil for kinds where it doesn't apply.
 enum PingScope: String, Sendable {
     case square
     case word
     case puzzle
 }
 
 struct Ping: Sendable {
     let recordName: String
     let gameID: UUID
     let authorID: String
     let playerName: String
     let puzzleTitle: String
     let kind: PingKind
     let scope: PingScope?
 }
 
 /// Owns the CloudKit sync lifecycle via two `CKSyncEngine` instances — one for
 /// the private database (owned games and shares) and one for the shared
 /// database (joined games). Zone creation, subscription setup, change-token
 /// management, batching, and retry are all delegated to the framework.
 /// This actor's job is to:
 ///
 /// - Start and persist each engine's state across launches.
 /// - Translate outbound edits (from `MovesUpdater`) into pending record zone
 ///   changes that CKSyncEngine will batch and send.
 /// - Apply incoming `Moves`, `Game`, and `Player` records to Core Data and
 ///   replay them onto the `CellEntity` cache.
 /// - Notify the main actor so the in-memory `Game` stays current.
 actor SyncEngine {
     let container: CKContainer
     let persistence: PersistenceController
 
     private var privateEngine: CKSyncEngine?
     private var sharedEngine: CKSyncEngine?
 
     /// In-memory map for Ping records pending send. Pings have no Core Data
     /// backing — they're write-once-and-forget — so we stash the minimal data
     /// here keyed by record name and look it up in `buildRecord`.
     private var pendingPings: [String: PingPayload] = [:]
 
     private struct PingPayload {
         let gameID: UUID
         let authorID: String
         let playerName: String
         let puzzleTitle: String
         let eventTimestampMs: Int64
         let kind: PingKind
         let scope: PingScope?
     }
 
     /// Label for the in-flight fetch — surfaced in traces so the diagnostics
     /// log can distinguish push-driven fetches from polls / foreground / etc.
     /// `nil` means CKSyncEngine drove the fetch itself (its internal scheduler).
     private var currentFetchSource: String?
     /// One-shot flag — set the first time we observe shared-DB content
     /// arriving via a push-triggered fetch. Confirms the silent-push path is
     /// actually wired up end-to-end.
     private var loggedFirstSharedPushPayload = false
 
     private var onRemoteMovesUpdated: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     private var onPings: (@MainActor @Sendable ([Ping]) async -> Void)?
     private var onAccountChange: (@MainActor @Sendable () async -> Void)?
     private var onGameAccessRevoked: (@MainActor @Sendable (UUID) async -> Void)?
     private var onGameRemoved: (@MainActor @Sendable (UUID) async -> Void)?
     private var localAuthorIDProvider: (@MainActor @Sendable () -> String?)?
     private var tracer: (@MainActor @Sendable (String) -> Void)?
     private var liveQueryCheckpoints: [String: Date] = [:]
     private let liveQueryCheckpointOverlap: TimeInterval = 5
 
     /// Per-scope checkpoint for the background ping fast path. Independent of
     /// CKSyncEngine's change tokens and of `liveQueryCheckpoints` (which are
     /// per-zone and Moves/Player oriented). Keyed by databaseScope value
     /// (0 = private, 1 = shared).
     private var pingPushCheckpoints: [Int16: Date] = [:]
     private let pingPushCheckpointOverlap: TimeInterval = 30
 
     func setTracer(_ t: @MainActor @Sendable @escaping (String) -> Void) {
         tracer = t
     }
 
     func setOnRemoteMovesUpdated(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemoteMovesUpdated = cb
     }
 
     func setOnPings(_ cb: @MainActor @Sendable @escaping ([Ping]) async -> Void) {
         onPings = cb
     }
 
     func setOnAccountChange(_ cb: @MainActor @Sendable @escaping () async -> Void) {
         onAccountChange = cb
     }
 
     func setOnGameAccessRevoked(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
         onGameAccessRevoked = cb
     }
 
     func setOnGameRemoved(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
         onGameRemoved = cb
     }
 
     func setLocalAuthorIDProvider(_ cb: @MainActor @Sendable @escaping () -> String?) {
         localAuthorIDProvider = cb
     }
 
     init(container: CKContainer, persistence: PersistenceController) {
         self.container = container
         self.persistence = persistence
     }
 
     // MARK: - Lifecycle
 
     /// Database subscription IDs. Stable, per-scope, idempotent on re-creation
     /// so we can always attempt a save without first listing.
     private static let privateSubscriptionID = "crossmate-private-db-subscription"
     private static let sharedSubscriptionID = "crossmate-shared-db-subscription"
 
     /// Creates both `CKSyncEngine` instances, restoring previously-saved state
     /// so pending changes and change tokens survive restarts. Call once after
     /// wiring callbacks.
     func start() {
         let bgCtx = persistence.container.newBackgroundContext()
 
         let privateState: CKSyncEngine.State.Serialization? = bgCtx.performAndWait {
             guard let data = SyncStateEntity.current(in: bgCtx).ckPrivateEngineState else {
                 return nil
             }
             return try? JSONDecoder().decode(CKSyncEngine.State.Serialization.self, from: data)
         }
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: privateState,
             delegate: self
         ))
 
         let sharedState: CKSyncEngine.State.Serialization? = bgCtx.performAndWait {
             guard let data = SyncStateEntity.current(in: bgCtx).ckSharedEngineState else {
                 return nil
             }
             return try? JSONDecoder().decode(CKSyncEngine.State.Serialization.self, from: data)
         }
         sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.sharedCloudDatabase,
             stateSerialization: sharedState,
             delegate: self
         ))
 
         // CKSyncEngine's automatic subscription creation is unreliable in
         // practice — diagnostics on real devices showed both scopes with zero
         // subscriptions even after a healthy initial fetch and push, which
         // means CloudKit never fires pushes and the engine silently degrades
         // to its periodic poll. Create the database subscriptions ourselves;
         // CKDatabase.save is idempotent for an existing subscriptionID.
         Task { await ensureDatabaseSubscriptions() }
     }
 
     private func ensureDatabaseSubscriptions() async {
         await ensureDatabaseSubscription(
             database: container.privateCloudDatabase,
             subscriptionID: Self.privateSubscriptionID,
             label: "private"
         )
         await ensureDatabaseSubscription(
             database: container.sharedCloudDatabase,
             subscriptionID: Self.sharedSubscriptionID,
             label: "shared"
         )
     }
 
     private func ensureDatabaseSubscription(
         database: CKDatabase,
         subscriptionID: String,
         label: String
     ) async {
         do {
             let existing = try await database.allSubscriptions()
             if existing.contains(where: { $0.subscriptionID == subscriptionID }) {
                 await trace("\(label) subscription already present (\(subscriptionID))")
                 return
             }
         } catch {
             await trace("\(label) allSubscriptions probe failed: \(describe(error)) — attempting save anyway")
         }
         let subscription = CKDatabaseSubscription(subscriptionID: subscriptionID)
         let info = CKSubscription.NotificationInfo()
         info.shouldSendContentAvailable = true
         subscription.notificationInfo = info
         do {
             _ = try await database.save(subscription)
             await trace("\(label) subscription created (\(subscriptionID))")
         } catch {
             await trace("\(label) subscription save FAILED: \(describe(error))")
         }
     }
 
     // MARK: - Outbound
 
     /// Registers each game's local-device Moves record as a pending save and
     /// kicks the affected engines to send immediately. Called by the
     /// `MovesUpdater` sink after the device's `MovesEntity` row has been
     /// merged and persisted; the sink already debounces edits, so this fires
     /// at most once per typing burst per game. Routes per-game to the correct
     /// engine. Going through `sendChanges()` rather than relying on the
     /// framework's own scheduler matters because every keystroke targets the
     /// same `CKRecord.ID` — the scheduler treats repeated `state.add` calls
     /// as the same already-queued intent and may sit on the change for a
     /// while before deciding to ship it.
     func enqueueMoves(gameIDs: Set<UUID>) {
         guard !gameIDs.isEmpty else { return }
         var kickPrivate = false
         var kickShared = false
         let ctx = persistence.container.newBackgroundContext()
         ctx.performAndWait {
             for gameID in gameIDs {
                 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { continue }
                 let isShared = info.scope == 1
                 let engine = isShared ? sharedEngine : privateEngine
                 guard let engine else { continue }
                 let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 req.predicate = NSPredicate(
                     format: "game.id == %@ AND deviceID == %@",
                     gameID as CVarArg,
                     RecordSerializer.localDeviceID
                 )
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first,
                       let recordName = entity.ckRecordName
                 else { continue }
                 let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
                 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
                 if isShared { kickShared = true } else { kickPrivate = true }
             }
         }
         if kickPrivate, let engine = privateEngine {
             Task { try? await engine.sendChanges() }
         }
         if kickShared, let engine = sharedEngine {
             Task { try? await engine.sendChanges() }
         }
     }
 
     /// Re-enqueues locally persisted Moves rows that do not yet have CloudKit
     /// system fields. Covers crash/relaunch recovery and any save that reached
     /// Core Data before CKSyncEngine recorded the pending change.
     @discardableResult
     func enqueueUnconfirmedMoves() -> Int {
         let ctx = persistence.container.newBackgroundContext()
         let gameIDs: Set<UUID> = ctx.performAndWait {
             let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
             req.predicate = NSPredicate(
                 format: "ckSystemFields == nil AND deviceID == %@",
                 RecordSerializer.localDeviceID
             )
             let entities = (try? ctx.fetch(req)) ?? []
             return Set(entities.compactMap { $0.game?.id })
         }
         enqueueMoves(gameIDs: gameIDs)
         return gameIDs.count
     }
 
     /// Registers record deletions as pending sends. Extracts the game UUID
     /// from the record name and routes to the correct engine.
     /// Registers the game's CloudKit zone for deletion. Each game owns its
     /// own zone, so this removes all remote records for the puzzle, including
     /// moves, player records, session pings, and share metadata.
     func enqueueDeleteGame(_ deletion: GameCloudDeletion) {
         let zoneID = CKRecordZone.ID(
             zoneName: deletion.ckZoneName,
             ownerName: deletion.ckZoneOwnerName
         )
         let engine = deletion.databaseScope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         engine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
         Task { try? await engine.sendChanges() }
     }
 
     /// Registers a Ping record as a pending send. Pings cover session-start,
     /// join, win, check, and reveal events; sender-only state — the payload is
     /// stashed in `pendingPings` and only used to build the outgoing
     /// `CKRecord`; nothing is persisted.
     func enqueuePing(
         kind: PingKind,
         scope: PingScope?,
         gameID: UUID,
         authorID: String,
         playerName: String
     ) {
         let ctx = persistence.container.newBackgroundContext()
         let zoneAndTitle: (info: ZoneInfo, title: String)? = ctx.performAndWait {
             guard let info = self.zoneInfo(forGameID: gameID, in: ctx) else { return nil }
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             let entity = try? ctx.fetch(req).first
             let title = Self.notificationTitle(for: entity)
             return (info, title)
         }
         guard let zoneAndTitle else { return }
         let engine = zoneAndTitle.info.scope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
         let recordName = RecordSerializer.recordName(
             forPingInGame: gameID,
             authorID: authorID,
             eventTimestampMs: eventTimestampMs
         )
         pendingPings[recordName] = PingPayload(
             gameID: gameID,
             authorID: authorID,
             playerName: playerName,
             puzzleTitle: zoneAndTitle.title,
             eventTimestampMs: eventTimestampMs,
             kind: kind,
             scope: scope
         )
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneAndTitle.info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         Task { try? await engine.sendChanges() }
     }
 
     /// Deletes transient Ping records for a completed owned game while keeping
     /// every `.win` ping. Participants see the owner's zone through the share,
     /// so the owner-side deletion removes the records from the cooperative
     /// game without risking the final win notification.
     func deleteNonWinPings(forCompletedGame gameID: UUID) async throws {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx),
               info.scope == 0
         else { return }
 
         removePendingNonWinPings(for: gameID, zoneID: info.zoneID)
 
         let records = try await queryLiveRecords(
             type: "Ping",
             database: container.privateCloudDatabase,
             zoneID: info.zoneID,
             since: nil,
             desiredKeys: ["kind"]
         )
         let recordIDsToDelete = records.compactMap { record -> CKRecord.ID? in
             guard (record["kind"] as? String) != PingKind.win.rawValue else { return nil }
             return record.recordID
         }
         try await deleteRecords(withIDs: recordIDsToDelete, in: container.privateCloudDatabase)
         if !recordIDsToDelete.isEmpty {
             await trace("ping cleanup: deleted \(recordIDsToDelete.count) non-win ping(s) for \(gameID.uuidString)")
         }
     }
 
     private func removePendingNonWinPings(for gameID: UUID, zoneID: CKRecordZone.ID) {
         let namesToRemove = Set(pendingPings.compactMap { name, payload in
             payload.gameID == gameID && payload.kind != .win ? name : nil
         })
         guard !namesToRemove.isEmpty else { return }
 
         for name in namesToRemove {
             pendingPings.removeValue(forKey: name)
         }
         guard let privateEngine else { return }
         let changesToRemove = privateEngine.state.pendingRecordZoneChanges.filter { change in
             switch change {
             case .saveRecord(let id):
                 return id.zoneID == zoneID && namesToRemove.contains(id.recordName)
             case .deleteRecord:
                 return false
             @unknown default:
                 return false
             }
         }
         if !changesToRemove.isEmpty {
             privateEngine.state.remove(pendingRecordZoneChanges: changesToRemove)
         }
     }
 
     private nonisolated static func notificationTitle(for entity: GameEntity?) -> String {
         guard let entity else { return "" }
         return PuzzleNotificationText.title(
             entity.title ?? "",
             publisher: entity.cachedPublisher,
             date: entity.cachedPuzzleDate
         )
     }
 
     /// Registers a Player record as a pending send. Used by `PlayerNamePublisher`
     /// when the local user renames; one record per (game, authorID), so
     /// participants only ever write their own slot.
     func enqueuePlayerRecord(gameID: UUID, authorID: String) {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
         let engine = info.scope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         let recordName = RecordSerializer.recordName(forPlayerInGame: gameID, authorID: authorID)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         Task { try? await engine.sendChanges() }
     }
 
     /// Registers a Game record as a pending send and ensures its zone is
     /// created in CloudKit first. Called when a new game is created locally.
     func enqueueGame(ckRecordName: String) {
         guard let gameID = gameID(fromRecordName: ckRecordName) else { return }
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
         let engine = info.scope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         // Save the zone before the game record so it exists when records arrive.
         engine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: info.zoneID))])
         let recordID = CKRecord.ID(recordName: ckRecordName, zoneID: info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         Task { try? await engine.sendChanges() }
     }
 
     // MARK: - Explicit sync triggers (called by AppServices / diagnostics view)
 
     func fetchChanges(source: String = "manual") async throws {
         currentFetchSource = source
         defer { currentFetchSource = nil }
         async let p: Void = privateEngine?.fetchChanges() ?? ()
         async let s: Void = sharedEngine?.fetchChanges() ?? ()
         _ = try await (p, s)
     }
 
     /// Push-only fallback path for the currently open game. On device,
     /// CKSyncEngine.fetchChanges() can return successfully from a silent-push
     /// wake without delivering database or record-zone events until a later
     /// foreground fetch. This direct pull is deliberately narrow: it refreshes
     /// the active game's Game record and recently-modified Moves/Player
     /// records in that game's zone, then applies them through the same
     /// idempotent merge path used by CKSyncEngine events. Event-like records
     /// such as Ping are intentionally ignored because live play only needs the
     /// current collaboration state.
     @discardableResult
     func fetchPushChangesDirect(scope: CKDatabase.Scope, gameID: UUID) async throws -> Bool {
         let database: CKDatabase
         let scopeValue: Int16
         let label: String
         switch scope {
         case .private:
             database = container.privateCloudDatabase
             scopeValue = 0
             label = "private"
         case .shared:
             database = container.sharedCloudDatabase
             scopeValue = 1
             label = "shared"
         case .public:
             return false
         @unknown default:
             return false
         }
 
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx),
               info.scope == scopeValue
         else {
             await trace("\(label) live query skipped: no active game in scope")
             return false
         }
 
         let checkpointKey = "\(scopeValue):\(gameID.uuidString)"
         let since = liveQueryCheckpoints[checkpointKey]?
             .addingTimeInterval(-liveQueryCheckpointOverlap)
 
         let gameRecordID = CKRecord.ID(
             recordName: RecordSerializer.recordName(forGameID: gameID),
             zoneID: info.zoneID
         )
         // The Game fetch and the Moves/Player queries are independent CK
         // round-trips. Fire them in parallel so total latency is bounded by
         // the slowest of the three rather than their sum.
         async let gameResultsTask = database.records(
             for: [gameRecordID],
             desiredKeys: ["title", "completedAt", "shareRecordName"]
         )
         async let movesTask = queryLiveRecords(
             type: "Moves",
             database: database,
             zoneID: info.zoneID,
             since: since,
             desiredKeys: ["authorID", "deviceID", "cells", "updatedAt"]
         )
         async let playersTask = queryLiveRecords(
             type: "Player",
             database: database,
             zoneID: info.zoneID,
             since: since,
             desiredKeys: ["authorID", "name", "updatedAt", "selRow", "selCol", "selDir"]
         )
         let gameResults = try await gameResultsTask
         let moves = try await movesTask
         let players = try await playersTask
 
         var records: [CKRecord] = []
         let fetchedGameRecord: Bool
         if case .success(let record)? = gameResults[gameRecordID] {
             records.append(record)
             fetchedGameRecord = true
         } else {
             fetchedGameRecord = false
         }
         records.append(contentsOf: moves)
         records.append(contentsOf: players)
 
         await applyDirectRecordZoneChanges(
             records: records,
             deletions: [],
             scopeValue: scopeValue
         )
 
         let latestModification = records.compactMap(\.modificationDate).max()
         if let latestModification {
             liveQueryCheckpoints[checkpointKey] = latestModification
         }
 
         await trace(
             "\(label) live query fetch \(gameID.uuidString.prefix(8)): " +
             "game=\(fetchedGameRecord ? 1 : 0), " +
             "moves=\(moves.count), players=\(players.count)"
         )
         return true
     }
 
     /// Background-wake fast path for surfacing collaborator notifications.
     /// Queries every known zone in the given scope for Ping records modified
     /// since the per-scope checkpoint and feeds them to `onPings`. Bypasses
     /// `CKSyncEngine.fetchChanges()` because that path can return without
     /// delivering events from a silent-push wake (same Apple quirk that
     /// motivated `fetchPushChangesDirect`). Moves / Player / Game records are
     /// deliberately left for the engine-driven or foreground fetch.
     @discardableResult
     func fetchPushPingsDirect(scope: CKDatabase.Scope) async throws -> Int {
         let database: CKDatabase
         let scopeValue: Int16
         let label: String
         switch scope {
         case .private:
             database = container.privateCloudDatabase
             scopeValue = 0
             label = "private"
         case .shared:
             database = container.sharedCloudDatabase
             scopeValue = 1
             label = "shared"
         case .public:
             return 0
         @unknown default:
             return 0
         }
 
         let ctx = persistence.container.newBackgroundContext()
         let zones = knownZones(forScope: scopeValue, in: ctx)
         guard !zones.isEmpty else {
             await trace("\(label) ping fast-path: no known zones")
             return 0
         }
 
         let scopeCheckpoint = pingPushCheckpoints[scopeValue]?
             .addingTimeInterval(-pingPushCheckpointOverlap)
 
         // Fan the per-zone Ping queries out concurrently. The actor's await
         // points release isolation between round-trips, so the per-zone CK
         // requests overlap; a serial N-zone scan becomes a single parallel
         // batch. Per-zone errors are caught and traced so one transient
         // failure doesn't suppress notifications from healthy zones.
         let perZoneRecords = await withTaskGroup(of: [CKRecord].self) { group in
             for (zoneID, createdAt) in zones {
                 // Scope checkpoint (if present) wins — it's forward-moving
                 // across all zones. On first run for a given scope we fall
                 // back to the game's createdAt floor so the ping that
                 // triggered this wake is still in range, but pings older
                 // than the device's first knowledge of the game are not.
                 let since = scopeCheckpoint
                     ?? createdAt.addingTimeInterval(-pingPushCheckpointOverlap)
                 group.addTask { [weak self] in
                     guard let self else { return [] }
                     do {
                         return try await self.queryLiveRecords(
                             type: "Ping",
                             database: database,
                             zoneID: zoneID,
                             since: since,
                             desiredKeys: ["authorID", "playerName", "puzzleTitle", "kind", "scope"]
                         )
                     } catch {
                         await self.trace(
                             "\(label) ping fast-path: zone \(zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return []
                     }
                 }
             }
             var all: [[CKRecord]] = []
             for await batch in group {
                 all.append(batch)
             }
             return all
         }
         let collected: [CKRecord] = perZoneRecords.flatMap { $0 }
 
         let pings = collected.compactMap(Self.parsePingRecord)
         if let latest = collected.compactMap(\.modificationDate).max() {
             pingPushCheckpoints[scopeValue] = latest
         }
         await trace(
             "\(label) ping fast-path: zones=\(zones.count), pings=\(pings.count)"
         )
 
         if !pings.isEmpty, let onPings {
             await onPings(pings)
         }
         return pings.count
     }
 
     /// Discovers games whose zones the device has never seen and pulls their
     /// Game / Moves / Player records directly, bypassing CKSyncEngine.
     ///
     /// CKSyncEngine is supposed to deliver database-scope change events that
     /// announce new zones, but on a silent-push wake those events can be
     /// withheld until the next foreground (the same quirk that motivated
     /// `fetchPushChangesDirect` and `fetchPushPingsDirect`). Without zone
     /// discovery, a game created on one device only appears on a second
     /// device after CKSyncEngine eventually catches up — which can be a long
     /// time if the second device only ever opens the app briefly.
     ///
     /// Enumerates zones via `CKDatabase.allRecordZones()`, diffs against
     /// `knownZones`, and pulls every record type we care about for each new
     /// zone. The pull is unbounded in time because, by definition, the
     /// device has no checkpoint for a zone it hasn't seen.
     ///
     /// Returns the number of newly-discovered zones.
     @discardableResult
     func discoverNewZonesDirect(scope: CKDatabase.Scope) async throws -> Int {
         let database: CKDatabase
         let scopeValue: Int16
         let label: String
         switch scope {
         case .private:
             database = container.privateCloudDatabase
             scopeValue = 0
             label = "private"
         case .shared:
             database = container.sharedCloudDatabase
             scopeValue = 1
             label = "shared"
         case .public:
             return 0
         @unknown default:
             return 0
         }
 
         let serverZones = try await database.allRecordZones()
         let ctx = persistence.container.newBackgroundContext()
         let known = knownZones(forScope: scopeValue, in: ctx)
         let knownKeys = Set(known.map { "\($0.zoneID.ownerName)|\($0.zoneID.zoneName)" })
 
         let candidates: [CKRecordZone.ID] = serverZones
             .map(\.zoneID)
             .filter { id in
                 id != CKRecordZone.ID.default &&
                 !knownKeys.contains("\(id.ownerName)|\(id.zoneName)")
             }
 
         guard !candidates.isEmpty else {
             await trace(
                 "\(label) zone discovery: nothing new " +
                 "(server=\(serverZones.count), known=\(known.count))"
             )
             return 0
         }
 
         // Two layers of concurrency. Outer: fan the per-zone work out
         // through a TaskGroup so N candidate zones don't serialize. Inner:
         // fire Game / Moves / Player against each zone with `async let` so
         // a single zone's three round-trips also overlap. The Game query
         // gates whether the zone hosts a Crossmate puzzle, but Moves and
         // Player against a non-puzzle zone simply return empty, so always
         // pulling all three in parallel and discarding when Game is empty
         // is cheaper than waiting on Game first. Per-zone errors are
         // caught and traced so one bad zone doesn't abort the rest.
         struct PerZoneResult: Sendable {
             let records: [CKRecord]
             let hasGame: Bool
         }
         let perZoneResults = await withTaskGroup(of: PerZoneResult.self) { group in
             for zoneID in candidates {
                 group.addTask { [weak self] in
                     guard let self else {
                         return PerZoneResult(records: [], hasGame: false)
                     }
                     do {
                         async let games = try await self.queryLiveRecords(
                             type: "Game",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: ["title", "completedAt", "shareRecordName", "puzzleSource"]
                         )
                         async let moves = try await self.queryLiveRecords(
                             type: "Moves",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: ["authorID", "deviceID", "cells", "updatedAt"]
                         )
                         async let players = try await self.queryLiveRecords(
                             type: "Player",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: ["authorID", "name", "updatedAt", "selRow", "selCol", "selDir"]
                         )
                         let (g, m, p) = try await (games, moves, players)
                         guard !g.isEmpty else {
                             return PerZoneResult(records: [], hasGame: false)
                         }
                         return PerZoneResult(records: g + m + p, hasGame: true)
                     } catch {
                         await self.trace(
                             "\(label) zone discovery: zone \(zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return PerZoneResult(records: [], hasGame: false)
                     }
                 }
             }
             var all: [PerZoneResult] = []
             for await result in group {
                 all.append(result)
             }
             return all
         }
         let collected: [CKRecord] = perZoneResults.flatMap(\.records)
         let zonesWithGame = perZoneResults.reduce(into: 0) { $0 += $1.hasGame ? 1 : 0 }
 
         await applyDirectRecordZoneChanges(
             records: collected,
             deletions: [],
             scopeValue: scopeValue
         )
 
         await trace(
             "\(label) zone discovery: candidates=\(candidates.count), " +
             "withGame=\(zonesWithGame), records=\(collected.count)"
         )
         return zonesWithGame
     }
 
     /// Pulls incremental updates for every game the device already knows
     /// about in the given scope, bypassing CKSyncEngine. Pairs with
     /// `discoverNewZonesDirect` so that pull-to-refresh covers both halves
     /// of "what might have changed elsewhere": new zones *and* updates to
     /// existing ones. Each game is dispatched to the existing
     /// `fetchPushChangesDirect`, which uses the `liveQueryCheckpoints`
     /// cursor so we only pull Moves/Player records newer than the last
     /// direct fetch. Per-game errors are caught and traced so one bad zone
     /// doesn't abort the rest.
     ///
     /// Returns the number of games for which the direct fetch reported
     /// records were applied.
     @discardableResult
     func fetchKnownZoneUpdatesDirect(scope: CKDatabase.Scope) async throws -> Int {
         let scopeValue: Int16
         let label: String
         switch scope {
         case .private:
             scopeValue = 0
             label = "private"
         case .shared:
             scopeValue = 1
             label = "shared"
         case .public:
             return 0
         @unknown default:
             return 0
         }
 
         let ctx = persistence.container.newBackgroundContext()
         let gameIDs = knownGameIDs(forScope: scopeValue, in: ctx)
         guard !gameIDs.isEmpty else {
             await trace("\(label) known-zone refresh: no known games")
             return 0
         }
 
         // Fan the per-game fetches out concurrently. Each fetchPushChangesDirect
         // call hits a different zone with a different checkpoint key, so they
         // don't race on shared state. The actor still serializes access to
         // liveQueryCheckpoints at non-await points, but the actual CK round-
         // trips overlap, turning a serial 1s-per-game wait into a single
         // parallel batch.
         let handled = await withTaskGroup(of: Bool.self) { group in
             for gameID in gameIDs {
                 group.addTask { [weak self] in
                     guard let self else { return false }
                     do {
                         return try await self.fetchPushChangesDirect(
                             scope: scope,
                             gameID: gameID
                         )
                     } catch {
                         await self.trace(
                             "\(label) known-zone refresh: game " +
                             "\(gameID.uuidString.prefix(8)) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return false
                     }
                 }
             }
             var count = 0
             for await result in group where result {
                 count += 1
             }
             return count
         }
         await trace(
             "\(label) known-zone refresh: games=\(gameIDs.count), handled=\(handled)"
         )
         return handled
     }
 
     private func queryLiveRecords(
         type: CKRecord.RecordType,
         database: CKDatabase,
         zoneID: CKRecordZone.ID,
         since: Date?,
         desiredKeys: [CKRecord.FieldKey]
     ) async throws -> [CKRecord] {
         let since = since ?? Date(timeIntervalSince1970: 0)
         let predicate = NSPredicate(format: "modificationDate > %@", since as NSDate)
         let query = CKQuery(recordType: type, predicate: predicate)
 
         var records: [CKRecord] = []
         var result = try await database.records(
             matching: query,
             inZoneWith: zoneID,
             desiredKeys: desiredKeys,
             resultsLimit: CKQueryOperation.maximumResults
         )
         records.append(contentsOf: result.matchResults.compactMap { _, recordResult in
             try? recordResult.get()
         })
 
         while let cursor = result.queryCursor {
             result = try await database.records(
                 continuingMatchFrom: cursor,
                 desiredKeys: desiredKeys,
                 resultsLimit: CKQueryOperation.maximumResults
             )
             records.append(contentsOf: result.matchResults.compactMap { _, recordResult in
                 try? recordResult.get()
             })
         }
         return records
     }
 
     private func deleteRecords(
         withIDs recordIDs: [CKRecord.ID],
         in database: CKDatabase
     ) async throws {
         guard !recordIDs.isEmpty else { return }
         let batchSize = 200
         var index = recordIDs.startIndex
         while index < recordIDs.endIndex {
             let end = recordIDs.index(index, offsetBy: batchSize, limitedBy: recordIDs.endIndex)
                 ?? recordIDs.endIndex
             let batch = Array(recordIDs[index..<end])
             try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
                 let op = CKModifyRecordsOperation(
                     recordsToSave: nil,
                     recordIDsToDelete: batch
                 )
                 op.qualityOfService = .utility
                 op.modifyRecordsResultBlock = { result in
                     cont.resume(with: result)
                 }
                 database.add(op)
             }
             index = end
         }
     }
 
     private func applyDirectRecordZoneChanges(
         records: [CKRecord],
         deletions: [(CKRecord.ID, CKRecord.RecordType)],
         scopeValue: Int16
     ) async {
         guard !records.isEmpty || !deletions.isEmpty else { return }
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let localAuthorID = await currentLocalAuthorID()
         let (movesUpdatedGameIDs, affectedGameIDs): (Set<UUID>, Set<UUID>) = ctx.performAndWait {
             var movesUpdated = Set<UUID>()
             var affected = Set<UUID>()
             for record in records {
                 switch record.recordType {
                 case "Game":
                     let entity = RecordSerializer.applyGameRecord(record, to: ctx, databaseScope: scopeValue)
                     if let id = entity.id { affected.insert(id) }
                 case "Moves":
                     if let value = RecordSerializer.parseMovesRecord(record) {
                         RecordSerializer.applyMovesRecord(
                             record,
                             value: value,
                             to: ctx,
                             localAuthorID: localAuthorID
                         )
                         movesUpdated.insert(value.gameID)
                         affected.insert(value.gameID)
                     }
                 case "Player":
                     if let (gameID, _) = RecordSerializer.parsePlayerRecordName(record.recordID.recordName) {
                         self.applyPlayerRecord(record, in: ctx)
                         affected.insert(gameID)
                     }
                 default:
                     break
                 }
             }
             for deletion in deletions {
                 self.applyDeletion(
                     recordID: deletion.0,
                     recordType: deletion.1,
                     in: ctx
                 )
                 if let id = self.gameID(fromRecordName: deletion.0.recordName) {
                     affected.insert(id)
                 }
             }
             for gameID in movesUpdated {
                 self.replayCellCache(for: gameID, in: ctx)
             }
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     print(
                         "SyncEngine: direct-push ctx.save failed " +
                         "— domain=\(nsError.domain) code=\(nsError.code) " +
                         "\(nsError.localizedDescription)"
                     )
                 }
             }
             return (movesUpdated, affected)
         }
 
         if let onRemoteMovesUpdated, !movesUpdatedGameIDs.isEmpty {
             await onRemoteMovesUpdated(movesUpdatedGameIDs)
         }
         if !affectedGameIDs.isEmpty {
             NotificationCenter.default.post(
                 name: .playerRosterShouldRefresh,
                 object: nil,
                 userInfo: ["gameIDs": affectedGameIDs]
             )
         }
     }
 
     func pushChanges() async throws {
         async let p: Void = privateEngine?.sendChanges() ?? ()
         async let s: Void = sharedEngine?.sendChanges() ?? ()
         _ = try await (p, s)
     }
 
     // MARK: - Diagnostics
 
     struct DiagnosticSnapshot: Sendable {
         let accountStatus: CKAccountStatus
         let engineRunning: Bool
         let pendingChangesCount: Int
         let privatePendingCount: Int
         let sharedPendingCount: Int
     }
 
     /// Record names of pending `.saveRecord` changes queued on the given
     /// scope's engine. Used by tests to verify that outbound enqueues route
     /// to the correct database.
     func pendingSaveRecordNames(scope: CKDatabase.Scope) -> [String] {
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return [] }
         return engine.state.pendingRecordZoneChanges.compactMap {
             if case .saveRecord(let id) = $0 { return id.recordName }
             return nil
         }
     }
 
     /// Zone names queued for deletion on the given scope's engine. Used by
     /// tests to verify delete routing after the local GameEntity is gone.
     func pendingDeletedZoneNames(scope: CKDatabase.Scope) -> [String] {
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return [] }
         return engine.state.pendingDatabaseChanges.compactMap {
             if case .deleteZone(let id) = $0 { return id.zoneName }
             return nil
         }
     }
 
     func diagnosticSnapshot() async -> DiagnosticSnapshot {
         let status: CKAccountStatus
         do { status = try await container.accountStatus() }
         catch { status = .couldNotDetermine }
         let running = privateEngine != nil
         let privateCount = privateEngine.map { $0.state.pendingRecordZoneChanges.count } ?? 0
         let sharedCount = sharedEngine.map { $0.state.pendingRecordZoneChanges.count } ?? 0
         return DiagnosticSnapshot(
             accountStatus: status,
             engineRunning: running,
             pendingChangesCount: privateCount + sharedCount,
             privatePendingCount: privateCount,
             sharedPendingCount: sharedCount
         )
     }
 
     /// Runs a series of lightweight CloudKit probes and returns human-readable
     /// (name, result) pairs for display in the diagnostics view.
     func probeContainer() async -> [(name: String, result: String)] {
         var results: [(String, String)] = []
         results.append(("containerIdentifier", container.containerIdentifier ?? "nil"))
         do {
             let s = try await container.accountStatus()
             results.append(("accountStatus", describeStatus(s)))
         } catch {
             results.append(("accountStatus", describe(error)))
         }
         do {
             let id = try await container.userRecordID()
             results.append(("userRecordID", id.recordName))
         } catch {
             results.append(("userRecordID", describe(error)))
         }
         do {
             let zones = try await container.privateCloudDatabase.allRecordZones()
             let names = zones.map(\.zoneID.zoneName).joined(separator: ", ")
             results.append(("privateZones", "\(zones.count) zone(s): [\(names)]"))
         } catch {
             results.append(("privateZones", describe(error)))
         }
         do {
             let zones = try await container.sharedCloudDatabase.allRecordZones()
             let names = zones.map(\.zoneID.zoneName).joined(separator: ", ")
             results.append(("sharedZones", "\(zones.count) zone(s): [\(names)]"))
         } catch {
             results.append(("sharedZones", describe(error)))
         }
         // CKSyncEngine creates a CKDatabaseSubscription per scope on first
         // start. If subscription creation silently failed, no push will ever
         // fire for that scope — surface what's actually present so a missing
         // entry is visible from the diagnostics view rather than diagnosed
         // by elimination.
         results.append(await probeSubscriptions(database: container.privateCloudDatabase, label: "privateSubs"))
         results.append(await probeSubscriptions(database: container.sharedCloudDatabase, label: "sharedSubs"))
         return results
     }
 
     private func probeSubscriptions(
         database: CKDatabase,
         label: String
     ) async -> (String, String) {
         do {
             let subs = try await database.allSubscriptions()
             if subs.isEmpty {
                 return (label, "0 subscriptions — pushes will not fire")
             }
             let descriptions = subs.map { sub -> String in
                 let kind: String
                 switch sub {
                 case is CKDatabaseSubscription: kind = "database"
                 case is CKQuerySubscription: kind = "query"
                 case is CKRecordZoneSubscription: kind = "zone"
                 default: kind = "other(\(type(of: sub)))"
                 }
                 let silent = sub.notificationInfo?.shouldSendContentAvailable == true ? "silent" : "alert-only"
                 return "\(kind):\(sub.subscriptionID)[\(silent)]"
             }
             return (label, "\(subs.count): [\(descriptions.joined(separator: ", "))]")
         } catch {
             return (label, describe(error))
         }
     }
 
     /// Fetches a single record by ID for the in-app record editor. Bypasses
     /// CKSyncEngine's tracked changes — caller is responsible for triggering a
     /// reconciling fetch if the record corresponds to a tracked local entity.
     func fetchRecordForEdit(
         scope: CKDatabase.Scope,
         recordID: CKRecord.ID
     ) async throws -> CKRecord {
         let database = scope == .shared
             ? container.sharedCloudDatabase
             : container.privateCloudDatabase
         return try await database.record(for: recordID)
     }
 
     /// Saves a record edited in the in-app record editor and runs a follow-up
     /// `fetchChanges` so any locally-tracked entity picks up the new server
     /// change tag via CKSyncEngine rather than going stale.
     func saveRecordForEdit(
         scope: CKDatabase.Scope,
         record: CKRecord
     ) async throws -> CKRecord {
         let database = scope == .shared
             ? container.sharedCloudDatabase
             : container.privateCloudDatabase
         let saved = try await database.save(record)
         try? await fetchChanges(source: "record-editor")
         return saved
     }
 
     /// Clears the saved state for both engines and replaces the in-memory
     /// engine instances so subsequent fetches walk every zone from scratch.
     /// Clearing the persisted state alone is ineffective: the running engines
     /// hold their tokens in memory and the next `stateUpdate` event saves
     /// those tokens back, so the wipe is undone before the user can act on it.
     /// Pending records already in CloudKit are unaffected. Locally-unconfirmed
     /// moves are re-enqueued so the new engines push them on the next cycle.
     func resetSyncState() async {
         let ctx = persistence.container.newBackgroundContext()
         ctx.performAndWait {
             let entity = SyncStateEntity.current(in: ctx)
             entity.ckPrivateEngineState = nil
             entity.ckSharedEngineState = nil
             try? ctx.save()
         }
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.sharedCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         pendingPings = [:]
         pingPushCheckpoints = [:]
         liveQueryCheckpoints = [:]
         loggedFirstSharedPushPayload = false
         _ = enqueueUnconfirmedMoves()
     }
 
     // MARK: - Private helpers
 
     private func currentLocalAuthorID() async -> String? {
         guard let localAuthorIDProvider else { return nil }
         return await MainActor.run {
             localAuthorIDProvider()
         }
     }
 
     private struct ZoneInfo {
         let scope: Int16
         let zoneID: CKRecordZone.ID
     }
 
     /// Looks up a game's scope and zone ID from Core Data. Returns `nil` if
     /// the entity can't be found. Not `async` — uses `performAndWait` so it
     /// can be called from non-async actor context.
     private nonisolated func zoneInfo(
         forGameID gameID: UUID,
         in ctx: NSManagedObjectContext
     ) -> ZoneInfo? {
         ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first else { return nil }
             let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
             let ownerName = entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
             return ZoneInfo(
                 scope: entity.databaseScope,
                 zoneID: CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
             )
         }
     }
 
     /// Game UUIDs for every locally-known *in-progress* game in the given
     /// database scope. Used by the known-zone refresh path so each game can
     /// be routed through `fetchPushChangesDirect`. Games with a non-nil
     /// `completedAt` are excluded: once a game is completed no further moves
     /// or player updates can arrive, so refreshing those zones is wasted
     /// round-trips.
     private nonisolated func knownGameIDs(
         forScope scope: Int16,
         in ctx: NSManagedObjectContext
     ) -> [UUID] {
         ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "databaseScope == %d AND completedAt == nil",
                 scope
             )
             guard let entities = try? ctx.fetch(req) else { return [] }
             return entities.compactMap(\.id)
         }
     }
 
     /// Enumerates every known game zone for the given database scope, paired
     /// with the `createdAt` of the corresponding GameEntity. The createdAt
     /// timestamp is used as the per-zone floor for the ping fast path: pings
     /// older than the moment this device first knew about the game can't be
     /// of interest (for shared games, they pre-date our join; for owned
     /// games, they pre-date the game's existence).
     private nonisolated func knownZones(
         forScope scope: Int16,
         in ctx: NSManagedObjectContext
     ) -> [(zoneID: CKRecordZone.ID, createdAt: Date)] {
         ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "databaseScope == %d", scope)
             guard let entities = try? ctx.fetch(req) else { return [] }
             var seen = Set<String>()
             var result: [(CKRecordZone.ID, Date)] = []
             for entity in entities {
                 guard let gameID = entity.id else { continue }
                 let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
                 let ownerName = entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
                 let key = "\(ownerName)|\(zoneName)"
                 guard seen.insert(key).inserted else { continue }
                 let createdAt = entity.createdAt ?? Date(timeIntervalSince1970: 0)
                 result.append((CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName), createdAt))
             }
             return result
         }
     }
 
     /// Extracts the game UUID from any of our record name formats:
     /// `game-<UUID>`, `moves-<UUID>-…`, `player-<UUID>-…`, `ping-<UUID>-…`.
     private nonisolated func gameID(fromRecordName name: String) -> UUID? {
         if name.hasPrefix("game-") {
             return UUID(uuidString: String(name.dropFirst("game-".count)))
         }
         let prefix: String
         if name.hasPrefix("moves-") { prefix = "moves-" }
         else if name.hasPrefix("player-") { prefix = "player-" }
         else if name.hasPrefix("ping-") { prefix = "ping-" }
         else { return nil }
         let rest = name.dropFirst(prefix.count)
         return UUID(uuidString: String(rest.prefix(36)))
     }
 
     private func trace(_ message: String) async {
         guard let tracer else { return }
         await tracer(message)
     }
 
     private func saveEngineState(
         _ serialization: CKSyncEngine.State.Serialization,
         isPrivate: Bool
     ) {
         let ctx = persistence.container.newBackgroundContext()
         ctx.performAndWait {
             guard let data = try? JSONEncoder().encode(serialization) else { return }
             let entity = SyncStateEntity.current(in: ctx)
             if isPrivate {
                 entity.ckPrivateEngineState = data
             } else {
                 entity.ckSharedEngineState = data
             }
             try? ctx.save()
         }
     }
 
     /// Builds the `CKRecord` for a pending change. Uses the zone ID already
     /// embedded in the `recordID` — set correctly at enqueue time.
     /// `pings` is a snapshot taken from the actor before this is invoked,
     /// since the framework calls back synchronously off-actor.
     private nonisolated func buildRecord(
         for recordID: CKRecord.ID,
         pings: [String: PingPayload]
     ) -> CKRecord? {
         let name = recordID.recordName
         let zoneID = recordID.zoneID
         if name.hasPrefix("ping-") {
             guard let payload = pings[name] else { return nil }
             return RecordSerializer.pingRecord(
                 gameID: payload.gameID,
                 authorID: payload.authorID,
                 playerName: payload.playerName,
                 puzzleTitle: payload.puzzleTitle,
                 eventTimestampMs: payload.eventTimestampMs,
                 kind: payload.kind,
                 scope: payload.scope,
                 zone: zoneID
             )
         }
         let ctx = persistence.container.newBackgroundContext()
         return ctx.performAndWait {
             if name.hasPrefix("game-") {
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(format: "ckRecordName == %@", name)
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first else { return nil }
                 return RecordSerializer.gameRecord(
                     from: entity,
                     recordID: recordID,
                     includePuzzleSource: entity.ckSystemFields == nil
                 )
             } else if name.hasPrefix("moves-") {
                 let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 req.predicate = NSPredicate(format: "ckRecordName == %@", name)
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first,
                       let gameID = entity.game?.id,
                       let authorID = entity.authorID,
                       let deviceID = entity.deviceID,
                       let updatedAt = entity.updatedAt
                 else { return nil }
                 let cells = (entity.cells.flatMap { try? MovesCodec.decode($0) }) ?? [:]
                 let value = MovesValue(
                     gameID: gameID,
                     authorID: authorID,
                     deviceID: deviceID,
                     cells: cells,
                     updatedAt: updatedAt
                 )
                 return try? RecordSerializer.movesRecord(
                     from: value,
                     zone: zoneID,
                     systemFields: entity.ckSystemFields
                 )
             } else if name.hasPrefix("player-") {
                 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 req.predicate = NSPredicate(format: "ckRecordName == %@", name)
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first,
                       let gameID = entity.game?.id,
                       let authorID = entity.authorID,
                       let renderedName = entity.name,
                       let updatedAt = entity.updatedAt
                 else { return nil }
                 let selection: PlayerSelection?
                 if let row = entity.selRow,
                    let col = entity.selCol,
                    let dir = entity.selDir,
                    let direction = Puzzle.Direction(rawValue: dir.intValue) {
                     selection = PlayerSelection(
                         row: row.intValue,
                         col: col.intValue,
                         direction: direction
                     )
                 } else {
                     selection = nil
                 }
                 return RecordSerializer.playerRecord(
                     gameID: gameID,
                     authorID: authorID,
                     name: renderedName,
                     updatedAt: updatedAt,
                     selection: selection,
                     zone: zoneID,
                     systemFields: entity.ckSystemFields
                 )
             }
             return nil
         }
     }
 
     // MARK: - Incoming record application
 
     private nonisolated func applyPlayerRecord(
         _ record: CKRecord,
         in ctx: NSManagedObjectContext
     ) {
         let ckName = record.recordID.recordName
         guard let (gameID, authorID) = RecordSerializer.parsePlayerRecordName(ckName) else {
             return
         }
         guard let renderedName = record["name"] as? String else { return }
         let updatedAt = record["updatedAt"] as? Date
             ?? record.modificationDate
             ?? Date()
 
         let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", ckName)
         req.fetchLimit = 1
 
         let entity: PlayerEntity
         if let existing = try? ctx.fetch(req).first {
             entity = existing
         } else {
             let game = RecordSerializer.ensureGameEntity(
                 forGameID: gameID,
                 zoneID: record.recordID.zoneID,
                 in: ctx
             )
             entity = PlayerEntity(context: ctx)
             entity.game = game
         }
 
         // Always adopt the server's system fields — that's etag tracking and
         // is independent of which side has the freshest data. The value
         // fields, however, are only adopted when the incoming record is at
         // least as new as what we have locally; otherwise a stale-but-current
         // server record (e.g. our own pending writes haven't landed yet)
         // would clobber the user's live selection on every fetch.
         entity.ckRecordName = ckName
         entity.ckSystemFields = RecordSerializer.encodeSystemFields(of: record)
         entity.authorID = authorID
         let localUpdatedAt = entity.updatedAt
         let incomingIsFresher = localUpdatedAt.map { updatedAt >= $0 } ?? true
         guard incomingIsFresher else { return }
         // An empty `name` is what older builds shipped from the selection publisher
         // before the fix; treat it as "no information" rather than letting it
         // clobber a previously-resolved name.
         if !renderedName.isEmpty {
             entity.name = renderedName
         }
         entity.updatedAt = updatedAt
         if let selection = RecordSerializer.parsePlayerSelection(from: record) {
             entity.selRow = NSNumber(value: Int64(selection.row))
             entity.selCol = NSNumber(value: Int64(selection.col))
             entity.selDir = NSNumber(value: Int64(selection.direction.rawValue))
         } else {
             entity.selRow = nil
             entity.selCol = nil
             entity.selDir = nil
         }
     }
 
     /// Merges every device's `MovesEntity` row for `gameID` and reconciles the
     /// `CellEntity` cache against the resulting grid. Must be called inside a
     /// `performAndWait` block on the same context.
     private nonisolated func replayCellCache(
         for gameID: UUID,
         in ctx: NSManagedObjectContext
     ) {
         let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         gameReq.fetchLimit = 1
         guard let game = try? ctx.fetch(gameReq).first else { return }
 
         let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         movesReq.predicate = NSPredicate(format: "game == %@", game)
         let movesEntities = (try? ctx.fetch(movesReq)) ?? []
         let values: [MovesValue] = movesEntities.compactMap { Self.movesValue(from: $0) }
         let gridState = GridStateMerger.merge(values)
 
         let existingCells = (game.cells as? Set<CellEntity>) ?? []
         var byPosition: [GridPosition: CellEntity] = [:]
         for cell in existingCells {
             byPosition[GridPosition(row: Int(cell.row), col: Int(cell.col))] = cell
         }
 
         for (pos, gridCell) in gridState {
             let cell: CellEntity
             if let existing = byPosition[pos] {
                 cell = existing
             } else {
                 cell = CellEntity(context: ctx)
                 cell.game = game
                 cell.row = Int16(pos.row)
                 cell.col = Int16(pos.col)
             }
             cell.letter = gridCell.letter
             cell.markKind = gridCell.markKind
             cell.checkedWrong = gridCell.checkedWrong
             cell.letterAuthorID = gridCell.authorID
         }
 
         for (pos, cell) in byPosition where gridState[pos] == nil {
             cell.letter = ""
             cell.markKind = 0
             cell.checkedWrong = false
             cell.letterAuthorID = nil
         }
     }
 
     /// Hydrates a `MovesValue` from a `MovesEntity`. Returns `nil` if the row
     /// is missing required fields (e.g. an unpopulated stub from a partial
     /// fetch).
     private nonisolated static func movesValue(from entity: MovesEntity) -> MovesValue? {
         guard let gameID = entity.game?.id,
               let authorID = entity.authorID,
               let deviceID = entity.deviceID,
               let updatedAt = entity.updatedAt
         else { return nil }
         let cells = (entity.cells.flatMap { try? MovesCodec.decode($0) }) ?? [:]
         return MovesValue(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             cells: cells,
             updatedAt: updatedAt
         )
     }
 
     // MARK: - Event handlers
 
     private func handleFetchedDatabaseChanges(
         _ event: CKSyncEngine.Event.FetchedDatabaseChanges,
         isPrivate: Bool
     ) async {
         let src = currentFetchSource ?? "framework"
         await trace(
             "\(isPrivate ? "private" : "shared") db changes [src=\(src)]: " +
             "\(event.modifications.count) zone mods, \(event.deletions.count) zone deletions"
         )
 
         // Private-DB zone deletions reflect the user removing one of their own
         // games on another device — hard-delete locally so the row stops
         // hanging around forever. Shared-DB zone deletions reflect the owner
         // removing this account from the share — mark access-revoked instead
         // so the UI can surface "no longer have access" rather than silently
         // vanishing the row mid-game. Modifications on the shared DB also
         // create placeholder GameEntities for newly-joined shares.
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let (removedIDs, revokedIDs): ([UUID], [UUID]) = ctx.performAndWait {
             var removed: [UUID] = []
             var revoked: [UUID] = []
             if !isPrivate {
                 for mod in event.modifications {
                     let zoneID = mod.zoneID
                     let zoneName = zoneID.zoneName
                     guard zoneName.hasPrefix("game-") else { continue }
                     let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                     req.predicate = NSPredicate(format: "ckZoneName == %@", zoneName)
                     req.fetchLimit = 1
                     if (try? ctx.fetch(req).first) == nil {
                         // Placeholder until the Game record arrives.
                         let entity = GameEntity(context: ctx)
                         let uuidString = String(zoneName.dropFirst("game-".count))
                         entity.id = UUID(uuidString: uuidString)
                         entity.ckRecordName = zoneName
                         entity.ckZoneName = zoneName
                         entity.ckZoneOwnerName = zoneID.ownerName
                         entity.databaseScope = 1
                         entity.title = "Joining\u{2026}"
                         entity.puzzleSource = ""
                         entity.createdAt = Date()
                         entity.updatedAt = Date()
                     }
                 }
             }
             for deletion in event.deletions {
                 let zoneName = deletion.zoneID.zoneName
                 guard zoneName.hasPrefix("game-") else { continue }
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(format: "ckZoneName == %@", zoneName)
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first else { continue }
                 if isPrivate {
                     if let id = entity.id { removed.append(id) }
                     ctx.delete(entity)
                 } else {
                     entity.isAccessRevoked = true
                     if let id = entity.id { revoked.append(id) }
                 }
             }
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     print(
                         "SyncEngine: db-changes ctx.save failed — domain=\(nsError.domain) " +
                         "code=\(nsError.code) \(nsError.localizedDescription)"
                     )
                 }
             }
             return (removed, revoked)
         }
 
         for id in removedIDs {
             if let cb = onGameRemoved { await cb(id) }
         }
         for id in revokedIDs {
             if let cb = onGameAccessRevoked { await cb(id) }
         }
     }
 
     private func handleFetchedRecordZoneChanges(
         _ event: CKSyncEngine.Event.FetchedRecordZoneChanges,
         isPrivate: Bool
     ) async {
         let scope: Int16 = isPrivate ? 0 : 1
         let src = currentFetchSource ?? "framework"
         await trace(
             "\(isPrivate ? "private" : "shared") fetch [src=\(src)]: " +
             "\(event.modifications.count) modifications, \(event.deletions.count) deletions"
         )
         if !isPrivate, !loggedFirstSharedPushPayload, src == "push",
            event.modifications.count + event.deletions.count > 0 {
             loggedFirstSharedPushPayload = true
             await trace("✅ first shared-DB push payload received — silent-push path is live")
         }
 
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let localAuthorID = await currentLocalAuthorID()
         let (movesUpdatedGameIDs, affectedGameIDs, pings): (Set<UUID>, Set<UUID>, [Ping]) = ctx.performAndWait {
             var movesUpdated = Set<UUID>()
             var affected = Set<UUID>()
             var pings: [Ping] = []
             for mod in event.modifications {
                 let record = mod.record
                 switch record.recordType {
                 case "Game":
                     let entity = RecordSerializer.applyGameRecord(record, to: ctx, databaseScope: scope)
                     if let id = entity.id { affected.insert(id) }
                 case "Moves":
                     if let value = RecordSerializer.parseMovesRecord(record) {
                         RecordSerializer.applyMovesRecord(
                             record,
                             value: value,
                             to: ctx,
                             localAuthorID: localAuthorID
                         )
                         movesUpdated.insert(value.gameID)
                         affected.insert(value.gameID)
                     }
                 case "Player":
                     if let (gameID, _) = RecordSerializer.parsePlayerRecordName(record.recordID.recordName) {
                         self.applyPlayerRecord(record, in: ctx)
                         affected.insert(gameID)
                     }
                 case "Ping":
                     if let ping = Self.parsePingRecord(record) {
                         pings.append(ping)
                     }
                 default:
                     break
                 }
             }
             for deletion in event.deletions {
                 self.applyDeletion(
                     recordID: deletion.recordID,
                     recordType: deletion.recordType,
                     in: ctx
                 )
                 if let id = self.gameID(fromRecordName: deletion.recordID.recordName) {
                     affected.insert(id)
                 }
             }
             for gameID in movesUpdated {
                 self.replayCellCache(for: gameID, in: ctx)
             }
             // CKSyncEngine advances its change token whenever the delegate
             // returns from fetchedRecordZoneChanges, regardless of whether we
             // persisted anything. A silent failure here means the records are
             // gone from the engine's "to deliver" set — they won't come back
             // without a `resetSyncState`. Surface failures so we can act.
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     print(
                         "SyncEngine: fetchedRecordZoneChanges ctx.save failed " +
                         "— domain=\(nsError.domain) code=\(nsError.code) " +
                         "\(nsError.localizedDescription)"
                     )
                 }
             }
             return (movesUpdated, affected, pings)
         }
 
         if let onRemoteMovesUpdated, !movesUpdatedGameIDs.isEmpty {
             await onRemoteMovesUpdated(movesUpdatedGameIDs)
         }
         if let onPings, !pings.isEmpty {
             await onPings(pings)
         }
         if !affectedGameIDs.isEmpty {
             NotificationCenter.default.post(
                 name: .playerRosterShouldRefresh,
                 object: nil,
                 userInfo: ["gameIDs": affectedGameIDs]
             )
         }
     }
 
     private nonisolated static func parsePingRecord(_ record: CKRecord) -> Ping? {
         let name = record.recordID.recordName
         let gameID: UUID?
         if name.hasPrefix("ping-") {
             let rest = name.dropFirst("ping-".count)
             gameID = UUID(uuidString: String(rest.prefix(36)))
         } else if record.recordID.zoneID.zoneName.hasPrefix("game-") {
             gameID = UUID(uuidString: String(record.recordID.zoneID.zoneName.dropFirst("game-".count)))
         } else {
             gameID = nil
         }
         guard let gameID,
               let authorID = record["authorID"] as? String,
               let kindRaw = record["kind"] as? String,
               let kind = PingKind(rawValue: kindRaw)
         else { return nil }
         let scope: PingScope? = (record["scope"] as? String).flatMap(PingScope.init(rawValue:))
         return Ping(
             recordName: name,
             gameID: gameID,
             authorID: authorID,
             playerName: (record["playerName"] as? String) ?? "",
             puzzleTitle: (record["puzzleTitle"] as? String) ?? "",
             kind: kind,
             scope: scope
         )
     }
 
     private nonisolated func applyDeletion(
         recordID: CKRecord.ID,
         recordType: CKRecord.RecordType,
         in ctx: NSManagedObjectContext
     ) {
         let name = recordID.recordName
         let entityName: String
         if name.hasPrefix("moves-") {
             entityName = "MovesEntity"
         } else if name.hasPrefix("player-") {
             entityName = "PlayerEntity"
         } else if name.hasPrefix("game-") {
             entityName = "GameEntity"
         } else {
             switch recordType {
             case "Moves": entityName = "MovesEntity"
             case "Player": entityName = "PlayerEntity"
             case "Game": entityName = "GameEntity"
             default: return
             }
         }
         let req = NSFetchRequest<NSManagedObject>(entityName: entityName)
         req.predicate = NSPredicate(format: "ckRecordName == %@", name)
         req.fetchLimit = 1
         if let obj = try? ctx.fetch(req).first {
             ctx.delete(obj)
         }
     }
 
     private func handleSentRecordZoneChanges(
         _ event: CKSyncEngine.Event.SentRecordZoneChanges,
         isPrivate: Bool
     ) async {
         await trace(
             "\(isPrivate ? "private" : "shared") sent: " +
             "\(event.savedRecords.count) saved, " +
             "\(event.failedRecordSaves.count) failed, " +
             "\(event.deletedRecordIDs.count) deleted"
         )
         for record in event.savedRecords {
             let name = record.recordID.recordName
             if name.hasPrefix("ping-") {
                 pendingPings.removeValue(forKey: name)
             }
         }
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let (failureMessages, orphanedZones): ([String], Set<CKRecordZone.ID>) = ctx.performAndWait {
             var messages: [String] = []
             var orphaned = Set<CKRecordZone.ID>()
             for record in event.savedRecords {
                 self.writeBackSystemFields(record: record, in: ctx)
             }
             for failure in event.failedRecordSaves {
                 let name = failure.record.recordID.recordName
                 let err = failure.error as NSError
                 if err.domain == CKErrorDomain,
                    err.code == CKError.zoneNotFound.rawValue {
                     orphaned.insert(failure.record.recordID.zoneID)
                 } else if self.recoverServerChangedSave(failure.error, failedRecordName: name, in: ctx) {
                     messages.append(
                         "send: recovered stale system fields for \(name) from CloudKit server record"
                     )
                 }
                 let userInfo = err.userInfo
                     .map { "\($0.key)=\($0.value)" }
                     .joined(separator: " | ")
                 messages.append(
                     "send: failed to save \(name) — domain=\(err.domain) code=\(err.code) \(err.localizedDescription) | userInfo: \(userInfo)"
                 )
             }
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     messages.append(
                         "send: writeBack ctx.save failed — domain=\(nsError.domain) code=\(nsError.code) \(nsError.localizedDescription)"
                     )
                 }
             }
             return (messages, orphaned)
         }
         if !orphanedZones.isEmpty {
             await applyZoneOrphaning(orphanedZones, isPrivate: isPrivate)
         }
         for message in failureMessages {
             await trace(message)
         }
     }
 
     /// Reacts to per-record `.zoneNotFound` failures discovered during a push
     /// by reflecting the missing-zone reality locally. The framework reports
     /// the same failure on every retry without ever clearing the queued change,
     /// so we drop pending sends that target the zone, mirror the fetch-side
     /// deletion handling on the local game (delete on private, mark
     /// access-revoked on shared), and notify upstream observers. Without this,
     /// `Last Error` stays stuck on `Failed to send changes` indefinitely.
     /// Internal-rather-than-private so the test suite can drive it directly;
     /// `CKSyncEngine.Event` payloads have no public initializer so we cannot
     /// exercise `handleSentRecordZoneChanges` end-to-end.
     func applyZoneOrphaning(
         _ zones: Set<CKRecordZone.ID>,
         isPrivate: Bool
     ) async {
         let engine = isPrivate ? privateEngine : sharedEngine
         if let engine {
             let toRemove = engine.state.pendingRecordZoneChanges.filter { change in
                 switch change {
                 case .saveRecord(let id):
                     return zones.contains(id.zoneID)
                 case .deleteRecord(let id):
                     return zones.contains(id.zoneID)
                 @unknown default:
                     return false
                 }
             }
             if !toRemove.isEmpty {
                 engine.state.remove(pendingRecordZoneChanges: toRemove)
             }
         }
 
         for (name, _) in pendingPings {
             guard let gameID = gameID(fromRecordName: name) else { continue }
             if zones.contains(where: { $0.zoneName == "game-\(gameID.uuidString)" }) {
                 pendingPings.removeValue(forKey: name)
             }
         }
 
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let (removedIDs, revokedIDs): ([UUID], [UUID]) = ctx.performAndWait {
             var removed: [UUID] = []
             var revoked: [UUID] = []
             for zone in zones {
                 let zoneName = zone.zoneName
                 guard zoneName.hasPrefix("game-") else { continue }
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(format: "ckZoneName == %@", zoneName)
                 req.fetchLimit = 1
                 guard let entity = try? ctx.fetch(req).first else { continue }
                 if isPrivate {
                     if let id = entity.id { removed.append(id) }
                     ctx.delete(entity)
                 } else {
                     if !entity.isAccessRevoked, let id = entity.id {
                         revoked.append(id)
                     }
                     entity.isAccessRevoked = true
                 }
             }
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     print(
                         "SyncEngine: orphan-zone ctx.save failed — domain=\(nsError.domain) " +
                         "code=\(nsError.code) \(nsError.localizedDescription)"
                     )
                 }
             }
             return (removed, revoked)
         }
 
         await trace(
             "\(isPrivate ? "private" : "shared") orphaned \(zones.count) zone(s) on send: " +
             zones.map(\.zoneName).sorted().joined(separator: ", ")
         )
 
         for id in removedIDs {
             if let cb = onGameRemoved { await cb(id) }
         }
         for id in revokedIDs {
             if let cb = onGameAccessRevoked { await cb(id) }
         }
     }
 
     /// CKSyncEngine reports optimistic-lock conflicts as failed saves, but the
     /// error payload often includes the current server record. Adopt only that
     /// record's system fields so a retry can use the fresh change tag while
     /// preserving the local values that caused the pending save.
     private nonisolated func recoverServerChangedSave(
         _ error: Error,
         failedRecordName: String,
         in ctx: NSManagedObjectContext
     ) -> Bool {
         let nsError = error as NSError
         guard nsError.domain == CKErrorDomain,
               nsError.code == CKError.serverRecordChanged.rawValue,
               let serverRecord = nsError.userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord,
               serverRecord.recordID.recordName == failedRecordName
         else { return false }
 
         writeBackSystemFields(record: serverRecord, in: ctx)
         return true
     }
 
     private nonisolated func writeBackSystemFields(
         record: CKRecord,
         in ctx: NSManagedObjectContext
     ) {
         let name = record.recordID.recordName
         let entityName: String
         if name.hasPrefix("moves-") { entityName = "MovesEntity" }
         else if name.hasPrefix("player-") { entityName = "PlayerEntity" }
         else if name.hasPrefix("game-") { entityName = "GameEntity" }
         else { return }
 
         let req = NSFetchRequest<NSManagedObject>(entityName: entityName)
         req.predicate = NSPredicate(format: "ckRecordName == %@", name)
         req.fetchLimit = 1
         guard let obj = try? ctx.fetch(req).first else { return }
         obj.setValue(RecordSerializer.encodeSystemFields(of: record), forKey: "ckSystemFields")
         if entityName == "GameEntity" {
             obj.setValue(Date(), forKey: "lastSyncedAt")
         }
     }
 
     // MARK: - Logging helpers
 
     private nonisolated func trace(_ message: String) {
         print("SyncEngine: \(message)")
     }
 
     private nonisolated func describe(_ error: Error) -> String {
         let nsError = error as NSError
         return "ERROR domain=\(nsError.domain) code=\(nsError.code) \(nsError.localizedDescription)"
     }
 
     private nonisolated func describeStatus(_ status: CKAccountStatus) -> String {
         switch status {
         case .available: return "available"
         case .noAccount: return "noAccount"
         case .restricted: return "restricted"
         case .couldNotDetermine: return "couldNotDetermine"
         case .temporarilyUnavailable: return "temporarilyUnavailable"
         @unknown default: return "unknown(\(status.rawValue))"
         }
     }
 }
 
 // MARK: - CKSyncEngineDelegate
 
 extension SyncEngine: CKSyncEngineDelegate {
     func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
         let isPrivate = syncEngine === privateEngine
         switch event {
         case .stateUpdate(let e):
             saveEngineState(e.stateSerialization, isPrivate: isPrivate)
 
         case .accountChange(let e):
             await trace("account change: \(e.changeType)")
             if let onAccountChange { await onAccountChange() }
 
         case .fetchedDatabaseChanges(let e):
             await handleFetchedDatabaseChanges(e, isPrivate: isPrivate)
 
         case .fetchedRecordZoneChanges(let e):
             await handleFetchedRecordZoneChanges(e, isPrivate: isPrivate)
 
         case .sentDatabaseChanges:
             break
 
         case .sentRecordZoneChanges(let e):
             await handleSentRecordZoneChanges(e, isPrivate: isPrivate)
 
         case .willFetchChanges, .didFetchChanges,
              .willFetchRecordZoneChanges, .didFetchRecordZoneChanges,
              .willSendChanges, .didSendChanges:
             break
 
         @unknown default:
             break
         }
     }
 
     func nextRecordZoneChangeBatch(
         _ context: CKSyncEngine.SendChangesContext,
         syncEngine: CKSyncEngine
     ) async -> CKSyncEngine.RecordZoneChangeBatch? {
         let pending = syncEngine.state.pendingRecordZoneChanges
         guard !pending.isEmpty else { return nil }
         let pingSnapshot = pendingPings
         return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { [weak self] recordID in
             guard let self else { return nil }
             return self.buildRecord(for: recordID, pings: pingSnapshot)
         }
     }
 }