crossmate

CloudQuery.swift (46815B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 extension SyncEngine {
     /// Manual/diagnostic fallback for durable Ping records. Normal
     /// collaboration no longer polls pings on foreground, push, or puzzle
     /// open; invites and friendship bootstrap ride normal zone application.
     @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()
         // Completed puzzles are excluded: the fast path only shaves push
         // latency for live collaboration, and finished zones' late pings
         // still land via CKSyncEngine's own change fetch. This trims the
         // per-push fan-out from every known zone to just the active ones.
         let zones = knownZones(
             forScope: scopeValue,
             onlyIncomplete: true,
             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.
         struct PerZonePings: Sendable {
             let records: [CKRecord]
             let orphanedZone: CKRecordZone.ID?
         }
         let perZoneRecords = await withTaskGroup(of: PerZonePings.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 PerZonePings(records: [], orphanedZone: nil) }
                     do {
                         let records = try await self.queryLiveRecords(
                             type: "Ping",
                             database: database,
                             zoneID: zoneID,
                             since: since,
                             desiredKeys: RecordSerializer.pingDesiredKeys
                         )
                         return PerZonePings(records: records, orphanedZone: nil)
                     } catch {
                         let orphan: CKRecordZone.ID?
                         if scope == .shared,
                            self.isInvalidSharedZoneOwnerError(error as NSError) {
                             orphan = zoneID
                         } else {
                             orphan = nil
                         }
                         await self.trace(
                             "\(label) ping fast-path: zone \(zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return PerZonePings(records: [], orphanedZone: orphan)
                     }
                 }
             }
             var all: [PerZonePings] = []
             for await batch in group {
                 all.append(batch)
             }
             return all
         }
         let collected: [CKRecord] = perZoneRecords.flatMap(\.records)
 
         // Dedupe by record name: the overlap window re-fetches recent pings on
         // every push, so emit each only on first sighting. Without this the
         // newest ping re-fires forever — the floor is the stored checkpoint
         // minus the overlap, so `modificationDate > floor` always re-matches it.
         var seen = seenPingRecords[scopeValue] ?? [:]
         var pings: [Ping] = []
         var fetchedCount = 0
         for record in collected {
             guard let ping = Ping.parseRecord(record) else { continue }
             fetchedCount += 1
             let modDate = record.modificationDate ?? Date()
             if seen.updateValue(modDate, forKey: record.recordID.recordName) == nil {
                 pings.append(ping)
             }
         }
 
         // Advance the checkpoint monotonically — `max(prior, latest)`, never
         // `= latest` — so a slow zone's older batch can't drag every zone's
         // window backward.
         if let latest = collected.compactMap(\.modificationDate).max() {
             let prior = pingPushCheckpoints[scopeValue] ?? .distantPast
             pingPushCheckpoints[scopeValue] = max(prior, latest)
         }
         // Forget names the next query's floor can no longer return, keeping
         // the seen set bounded to the overlap window rather than the session.
         if let checkpoint = pingPushCheckpoints[scopeValue] {
             let floor = checkpoint.addingTimeInterval(-pingPushCheckpointOverlap)
             seen = seen.filter { $0.value >= floor }
         }
         seenPingRecords[scopeValue] = seen
 
         let orphans = Set(perZoneRecords.compactMap(\.orphanedZone))
         if !orphans.isEmpty {
             await applyZoneOrphaning(orphans, isPrivate: scope == .private)
         }
 
         await trace(
             "\(label) ping fast-path: zones=\(zones.count), " +
             "pings=\(pings.count), dup=\(fetchedCount - pings.count)"
         )
 
         if !pings.isEmpty, let onPings {
             await onPings(pings)
         }
         return pings.count
     }
 
     /// Narrow fallback for game-list invite delivery. Re-invites live in
     /// pairwise friend zones, so game-list Game/Moves refreshes will never
     /// see them. This scans only friend zones and only `.invite` records,
     /// leaving broad Ping polling out of the live collaboration path.
     @discardableResult
     func fetchFriendInvitesDirect(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 targets = friendInviteScanTargets(forScope: scopeValue)
         guard !targets.isEmpty else {
             await trace("\(label) invite sync: no friend zones")
             return 0
         }
 
         struct PerZoneInvites: Sendable {
             let pings: [Ping]
             let recordNames: Set<String>
             let scannedAuthorID: String?
             let orphanedZone: CKRecordZone.ID?
         }
         let perZone = await withTaskGroup(of: PerZoneInvites.self) { group in
             for target in targets {
                 group.addTask { [weak self] in
                     guard let self else {
                         return PerZoneInvites(pings: [], recordNames: [], scannedAuthorID: nil, orphanedZone: nil)
                     }
                     do {
                         let records = try await self.queryRecords(
                             type: "Ping",
                             database: database,
                             zoneID: target.zoneID,
                             predicate: NSPredicate(format: "kind == %@", PingKind.invite.rawValue),
                             desiredKeys: RecordSerializer.pingDesiredKeys
                         )
                         return PerZoneInvites(
                             pings: records.compactMap(Ping.parseRecord),
                             recordNames: Set(records.map(\.recordID.recordName)),
                             scannedAuthorID: target.authorID,
                             orphanedZone: nil
                         )
                     } catch {
                         let orphan: CKRecordZone.ID?
                         if scope == .shared,
                            self.isInvalidSharedZoneOwnerError(error as NSError) {
                             orphan = target.zoneID
                         } else {
                             orphan = nil
                         }
                         await self.trace(
                             "\(label) invite sync: zone \(target.zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return PerZoneInvites(pings: [], recordNames: [], scannedAuthorID: nil, orphanedZone: orphan)
                     }
                 }
             }
 
             var all: [PerZoneInvites] = []
             for await result in group {
                 all.append(result)
             }
             return all
         }
 
         let orphans = Set(perZone.compactMap(\.orphanedZone))
         if !orphans.isEmpty {
             await applyZoneOrphaning(orphans, isPrivate: scope == .private)
         }
 
         let pings = perZone.flatMap(\.pings)
         let pruned = await pruneMissingPendingInvites(
             fromScannedInviters: Set(perZone.compactMap(\.scannedAuthorID)),
             livePingRecordNames: perZone.reduce(into: Set<String>()) { $0.formUnion($1.recordNames) },
             label: label
         )
         await trace("\(label) invite sync: zones=\(targets.count), invites=\(pings.count), pruned=\(pruned)")
         if !pings.isEmpty, let onPings {
             await onPings(pings)
         }
         return pings.count
     }
 
     private func friendInviteScanTargets(
         forScope scope: Int16
     ) -> [(zoneID: CKRecordZone.ID, authorID: String)] {
         let ctx = persistence.container.newBackgroundContext()
         return ctx.performAndWait {
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(
                 format: "databaseScope == %d AND isBlocked == NO",
                 scope
             )
             var seen = Set<String>()
             var result: [(zoneID: CKRecordZone.ID, authorID: String)] = []
             for friend in (try? ctx.fetch(req)) ?? [] {
                 guard let zoneName = friend.friendZoneName,
                       let ownerName = friend.friendZoneOwnerName,
                       let authorID = friend.authorID
                 else { continue }
                 let key = "\(ownerName)|\(zoneName)"
                 guard seen.insert(key).inserted else { continue }
                 result.append((
                     zoneID: CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName),
                     authorID: authorID
                 ))
             }
             return result
         }
     }
 
     /// Friend-zone invite scans are authoritative for the zones that completed.
     /// If a durable local InviteEntity still points at a Ping record absent
     /// from that scan, the source message has already been consumed elsewhere
     /// and the local row is stale.
     private func pruneMissingPendingInvites(
         fromScannedInviters scannedInviterAuthorIDs: Set<String>,
         livePingRecordNames: Set<String>,
         label: String
     ) async -> Int {
         guard !scannedInviterAuthorIDs.isEmpty else { return 0 }
         let ctx = persistence.container.newBackgroundContext()
         let result: Result<Int, Error> = ctx.performAndWait {
             let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
             req.predicate = NSPredicate(
                 format: "status == %@ AND inviterAuthorID IN %@",
                 "pending",
                 Array(scannedInviterAuthorIDs)
             )
             let rows = (try? ctx.fetch(req)) ?? []
             var removed = 0
             for row in rows {
                 guard let recordName = row.pingRecordName,
                       !livePingRecordNames.contains(recordName)
                 else { continue }
                 ctx.delete(row)
                 removed += 1
             }
             guard removed > 0 else { return .success(0) }
             do {
                 try ctx.save()
                 return .success(removed)
             } catch {
                 ctx.rollback()
                 return .failure(error)
             }
         }
         switch result {
         case .success(let removed):
             return removed
         case .failure(let error):
             await trace("\(label) invite sync: stale local invite prune failed: \(error.localizedDescription)")
             return 0
         }
     }
 
     /// Deletes the `.invite` Ping(s) for `gameID` from the user's friend zones.
     /// Called when leaving a shared game: the invite Ping is durable and its
     /// only other cleanup, `consumeStaleInvites`, keys off a local `GameEntity`
     /// that leaving has just removed — so without this the invite resurrects as
     /// a fresh card on the next cold start (and on any sibling device that
     /// re-syncs it). Deleting the source record clears it everywhere; a later
     /// re-invite is a new Ping with its own record name and still surfaces.
     /// Best-effort: a per-zone query failure is traced and skipped so leaving
     /// still completes. Scans both scopes because invite Pings live in either a
     /// private or shared friend zone depending on how the pair befriended.
     func deleteInvitePingsAfterLeave(forGameID gameID: UUID) async {
         for (scopeValue, database) in [
             (Int16(0), container.privateCloudDatabase),
             (Int16(1), container.sharedCloudDatabase)
         ] {
             for zoneID in friendZoneIDs(forScope: scopeValue) {
                 let records: [CKRecord]
                 do {
                     records = try await queryRecords(
                         type: "Ping",
                         database: database,
                         zoneID: zoneID,
                         predicate: NSPredicate(format: "kind == %@", PingKind.invite.rawValue),
                         desiredKeys: RecordSerializer.pingDeletionDesiredKeys
                     )
                 } catch {
                     await trace(
                         "leave invite cleanup: zone \(zoneID.zoneName) query failed: " +
                         "\(error.localizedDescription)"
                     )
                     continue
                 }
                 for record in records {
                     guard let ping = Ping.parseRecord(record), ping.gameID == gameID else { continue }
                     deletePing(recordName: ping.recordName, zoneID: zoneID, databaseScope: scopeValue)
                     await trace(
                         "leave invite cleanup: deleting invite ping \(ping.recordName) " +
                         "for \(gameID.uuidString)"
                     )
                 }
             }
         }
     }
 
     /// Lightweight background read for session presence. This intentionally
     /// reads only Player records; Ping records are durable bootstrap state,
     /// not part of the live/background notification path.
     @discardableResult
     func fetchBackgroundSessionsDirect(scope: CKDatabase.Scope) async throws -> [Session] {
         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 []
         @unknown default:
             return []
         }
 
         let ctx = persistence.container.newBackgroundContext()
         let zones = incompleteKnownZones(forScope: scopeValue, in: ctx)
         guard !zones.isEmpty else {
             await trace("\(label) background session scan: no incomplete zones")
             return []
         }
 
         let since = Date().addingTimeInterval(-backgroundSessionLookback)
         struct PerZoneActivity: Sendable {
             let records: [CKRecord]
             let players: [Session]
             let orphanedZone: CKRecordZone.ID?
         }
 
         let perZone = await withTaskGroup(of: PerZoneActivity.self) { group in
             for zone in zones {
                 group.addTask { [weak self] in
                     guard let self else {
                         return PerZoneActivity(records: [], players: [], orphanedZone: nil)
                     }
                     do {
                         let playerRecords = try await self.queryLiveRecords(
                             type: "Player",
                             database: database,
                             zoneID: zone.zoneID,
                             since: since,
                             desiredKeys: RecordSerializer.playerDesiredKeys
                         )
                         let activities = playerRecords.compactMap { record in
                             Session.parseRecord(record, puzzleTitle: zone.title)
                         }
                         return PerZoneActivity(
                             records: playerRecords,
                             players: activities,
                             orphanedZone: nil
                         )
                     } catch {
                         let orphan: CKRecordZone.ID?
                         if scope == .shared,
                            self.isInvalidSharedZoneOwnerError(error as NSError) {
                             orphan = zone.zoneID
                         } else {
                             orphan = nil
                         }
                         await self.trace(
                             "\(label) background session scan: zone \(zone.zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return PerZoneActivity(
                             records: [],
                             players: [],
                             orphanedZone: orphan
                         )
                     }
                 }
             }
             var all: [PerZoneActivity] = []
             for await result in group {
                 all.append(result)
             }
             return all
         }
 
         let records = perZone.flatMap(\.records)
         if !records.isEmpty {
             await applyDirectRecordZoneChanges(
                 records: records,
                 deletions: [],
                 scopeValue: scopeValue
             )
         }
 
         let orphans = Set(perZone.compactMap(\.orphanedZone))
         if !orphans.isEmpty {
             await applyZoneOrphaning(orphans, isPrivate: scope == .private)
         }
 
         let players = perZone.flatMap(\.players)
         await trace(
             "\(label) background session scan: zones=\(zones.count), " +
             "players=\(players.count)"
         )
         return players
     }
 
     /// 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
     /// `fetchLiveGameDirect` 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)" })
 
         // Server zones not already tracked as a game or friend zone.
         let untracked = serverZones
             .map(\.zoneID)
             .filter { id in
                 id != CKRecordZone.ID.default &&
                 !knownKeys.contains("\(id.ownerName)|\(id.zoneName)")
             }
         // Of those, skip the ones this probe can never resolve to a game: the
         // account-scoped zone and the private-DB archive backups of finished
         // shared games. Archive records arrive through the engine's own
         // fetchedRecordZoneChanges, not this Game query, so probing them here
         // only re-fans a wasted query on every pass.
         let candidates = untracked.filter { id in
             id.zoneName != RecordSerializer.accountZoneID.zoneName &&
             !Archive.isArchiveZone(id.zoneName)
         }
         let nonGameCount = untracked.count - candidates.count
 
         guard !candidates.isEmpty else {
             // Count non-default server zones so the figure matches what the
             // candidate filter actually compares: the private DB's
             // allRecordZones() always includes _defaultZone, which knownZones
             // never tracks, so a raw serverZones.count reads a permanent +1.
             let serverNonDefault = serverZones.lazy
                 .filter { $0.zoneID != .default }
                 .count
             // Name the account/archive zones held back above so the figures
             // reconcile at a glance: known games + non-game = server.
             let nonGameSuffix = nonGameCount > 0 ? ", non-game=\(nonGameCount)" : ""
             await trace(
                 "\(label) zone discovery: nothing new " +
                 "(server=\(serverNonDefault), known=\(known.count)\(nonGameSuffix))"
             )
             return 0
         }
 
         // Probe Game first. Most candidate zones are expected to be Crossmate
         // zones, but this path also sees friend/account/debug zones; fetching
         // Moves and Player before proving there is a Game record turns zone
         // discovery into a three-query fan-out for every non-game zone.
         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 {
                         let games = try await self.queryLiveRecords(
                             type: "Game",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: RecordSerializer.gameDesiredKeys
                         )
                         guard !games.isEmpty else {
                             return PerZoneResult(records: [], hasGame: false)
                         }
                         async let moves = try await self.queryLiveRecords(
                             type: "Moves",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: RecordSerializer.movesDesiredKeys
                         )
                         async let players = try await self.queryLiveRecords(
                             type: "Player",
                             database: database,
                             zoneID: zoneID,
                             since: nil,
                             desiredKeys: RecordSerializer.playerDesiredKeys
                         )
                         let (m, p) = try await (moves, players)
                         return PerZoneResult(records: games + 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
     }
 
     /// Foreground/open-puzzle catch-up for a single game zone. This is the
     /// latency-sensitive collaboration path, so it bypasses CKSyncEngine's
     /// broader fetch and pulls only the records the active grid needs.
     ///
     /// Returns `false` when the game zone is not known locally yet, allowing
     /// the caller to fall back to CKSyncEngine for the first discovery pass.
     @discardableResult
     func fetchGameDirect(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 { return false }
 
         // The zone has already been confirmed missing server-side (see
         // `applyZoneOrphaning`). Re-querying it just fails with `.zoneNotFound`
         // (CKError 26) every time the revoked puzzle appears, leaving the
         // diagnostics `Last Error` stuck on "Zone does not exist". Report the
         // freshen as handled so the caller skips the full-DB `fetchChanges`
         // fallback too — there is nothing left to converge.
         guard !info.isAccessRevoked else {
             await trace(
                 "\(label) game catch-up: \(gameID.uuidString.prefix(8)) skipped (access revoked)"
             )
             return true
         }
 
         let checkpointKey = "\(scopeValue):\(gameID.uuidString)"
         let since = liveQueryCheckpoints[checkpointKey]?
             .addingTimeInterval(-liveQueryCheckpointOverlap)
         let gameRecordID = CKRecord.ID(
             recordName: RecordSerializer.recordName(forGameID: gameID),
             zoneID: info.zoneID
         )
 
         let gameResults: [CKRecord.ID: Result<CKRecord, Error>]
         let moves: [CKRecord]
         let players: [CKRecord]
         do {
             async let gameResultsTask = database.records(
                 for: [gameRecordID],
                 desiredKeys: RecordSerializer.gameDesiredKeys
             )
             async let movesTask = queryLiveRecords(
                 type: "Moves",
                 database: database,
                 zoneID: info.zoneID,
                 since: since,
                 desiredKeys: RecordSerializer.movesDesiredKeys
             )
             async let playersTask = queryLiveRecords(
                 type: "Player",
                 database: database,
                 zoneID: info.zoneID,
                 since: since,
                 desiredKeys: RecordSerializer.playerDesiredKeys
             )
             (gameResults, moves, players) = try await (gameResultsTask, movesTask, playersTask)
         } catch {
             if scope == .private,
                !info.isCloudConfirmed,
                isZoneNotFoundError(error) {
                 await trace(
                     "\(label) game catch-up: \(gameID.uuidString.prefix(8)) " +
                     "skipped (zone pending creation)"
                 )
                 return true
             }
             throw error
         }
 
         var records = moves + players
         let gameCount: Int
         if case .success(let record)? = gameResults[gameRecordID] {
             records.append(record)
             gameCount = 1
         } else {
             gameCount = 0
         }
 
         if let latestModification = records.compactMap(\.modificationDate).max() {
             setLiveQueryCheckpoint(
                 latestModification,
                 scopeValue: scopeValue,
                 gameID: gameID
             )
         }
 
         await applyDirectRecordZoneChanges(
             records: records,
             deletions: [],
             scopeValue: scopeValue
         )
         await trace(
             "\(label) game catch-up: \(gameID.uuidString.prefix(8)), " +
             "game=\(gameCount), moves=\(moves.count), players=\(players.count)"
         )
         return true
     }
 
     /// Pulls a just-accepted shared game by the zone ID CloudKit returned in
     /// the share metadata. This is the latency-sensitive join path: the game
     /// is not known locally yet, so `fetchGameDirect(scope:gameID:)` cannot
     /// find its zone, and a full shared-zone discovery would query every
     /// unknown shared zone before opening the one the user just tapped.
     /// Pass `onlyGame: true` to fetch just the Game record. The join poll's
     /// playability gate reads only `puzzleSource`, so its backstop re-fetches
     /// don't need the two full-zone Moves/Player queries — the Puzzle Grid
     /// re-fetches those itself on open. A Game-only pass also leaves the
     /// live-query checkpoint untouched, since it hasn't comprehensively read the
     /// zone's Moves/Players and must not let a later `since:` query skip them.
     @discardableResult
     func fetchAcceptedSharedGameDirect(
         gameID: UUID,
         zoneID: CKRecordZone.ID,
         onlyGame: Bool = false
     ) async throws -> Bool {
         let database = container.sharedCloudDatabase
         let gameRecordID = CKRecord.ID(
             recordName: RecordSerializer.recordName(forGameID: gameID),
             zoneID: zoneID
         )
 
         let gameResults: [CKRecord.ID: Result<CKRecord, Error>]
         let moves: [CKRecord]
         let players: [CKRecord]
         do {
             async let gameResultsTask = database.records(
                 for: [gameRecordID],
                 desiredKeys: RecordSerializer.gameDesiredKeys
             )
             async let movesTask = onlyGame ? [] : queryLiveRecords(
                 type: "Moves",
                 database: database,
                 zoneID: zoneID,
                 since: nil,
                 desiredKeys: RecordSerializer.movesDesiredKeys
             )
             async let playersTask = onlyGame ? [] : queryLiveRecords(
                 type: "Player",
                 database: database,
                 zoneID: zoneID,
                 since: nil,
                 desiredKeys: RecordSerializer.playerDesiredKeys
             )
             (gameResults, moves, players) = try await (gameResultsTask, movesTask, playersTask)
         } catch {
             if isZoneNotFoundError(error) { return false }
             throw error
         }
 
         guard case .success(let game)? = gameResults[gameRecordID] else {
             return false
         }
 
         let records = moves + players + [game]
         // Only advance the checkpoint when this pass actually read the zone's
         // Moves/Players; a Game-only backstop hasn't, so leaving it alone keeps
         // a later `fetchGameDirect(since:)` from skipping unfetched moves.
         if !onlyGame,
            let latestModification = records.compactMap(\.modificationDate).max() {
             setLiveQueryCheckpoint(latestModification, scopeValue: 1, gameID: gameID)
         }
 
         await applyDirectRecordZoneChanges(
             records: records,
             deletions: [],
             scopeValue: 1
         )
         await trace(
             "shared accepted-game fetch: \(gameID.uuidString.prefix(8)), " +
             (onlyGame
                 ? "game=1 (game-only backstop)"
                 : "game=1, moves=\(moves.count), players=\(players.count)")
         )
         return true
     }
 
     nonisolated func isZoneNotFoundError(_ error: Error) -> Bool {
         let nsError = error as NSError
         return nsError.domain == CKErrorDomain &&
             nsError.code == CKError.zoneNotFound.rawValue
     }
 
     /// Background-push catch-up for library freshness. Intentionally skips
     /// Player records because the immediate background session scan already
     /// covers presence.
     /// The delayed caller exists to catch the common ordering where a cursor
     /// save triggers the silent push before the corresponding Moves record is
     /// visible in CloudKit.
     ///
     /// Returns the number of Moves records fetched. Game records are always
     /// fetched for metadata freshness, but delayed push catch-up uses the
     /// Moves count to decide whether a later safety pass is still useful.
     @discardableResult
     func fetchKnownGameMovesDirect(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 = incompleteKnownZones(forScope: scopeValue, in: ctx)
         guard !zones.isEmpty else {
             await trace("\(label) game/moves catch-up: no incomplete zones")
             return 0
         }
 
         struct PerZoneGameMoves: Sendable {
             let records: [CKRecord]
             let gameCount: Int
             let moveCount: Int
             let orphanedZone: CKRecordZone.ID?
         }
         let perZone = await withTaskGroup(of: PerZoneGameMoves.self) { group in
             for zone in zones {
                 group.addTask { [weak self] in
                     guard let self else {
                         return PerZoneGameMoves(
                             records: [],
                             gameCount: 0,
                             moveCount: 0,
                             orphanedZone: nil
                         )
                     }
                     do {
                         let checkpointKey = "\(scopeValue):\(zone.gameID.uuidString)"
                         let since = await self.liveQueryCheckpoints[checkpointKey]?
                             .addingTimeInterval(-self.liveQueryCheckpointOverlap)
                         let gameRecordID = CKRecord.ID(
                             recordName: RecordSerializer.recordName(forGameID: zone.gameID),
                             zoneID: zone.zoneID
                         )
                         async let gameResultsTask = database.records(
                             for: [gameRecordID],
                             desiredKeys: RecordSerializer.gameDesiredKeys
                         )
                         async let movesTask = self.queryLiveRecords(
                             type: "Moves",
                             database: database,
                             zoneID: zone.zoneID,
                             since: since,
                             desiredKeys: RecordSerializer.movesDesiredKeys
                         )
                         let (gameResults, moves) = try await (gameResultsTask, movesTask)
 
                         var records = moves
                         let gameCount: Int
                         if case .success(let record)? = gameResults[gameRecordID] {
                             records.append(record)
                             gameCount = 1
                         } else {
                             gameCount = 0
                         }
 
                         if let latestModification = records.compactMap(\.modificationDate).max() {
                             await self.setLiveQueryCheckpoint(
                                 latestModification,
                                 scopeValue: scopeValue,
                                 gameID: zone.gameID
                             )
                         }
 
                         return PerZoneGameMoves(
                             records: records,
                             gameCount: gameCount,
                             moveCount: moves.count,
                             orphanedZone: nil
                         )
                     } catch {
                         let orphan: CKRecordZone.ID?
                         if scope == .shared,
                            self.isInvalidSharedZoneOwnerError(error as NSError) {
                             orphan = zone.zoneID
                         } else {
                             orphan = nil
                         }
                         await self.trace(
                             "\(label) game/moves catch-up: zone \(zone.zoneID.zoneName) failed: " +
                             "\(error.localizedDescription)"
                         )
                         return PerZoneGameMoves(
                             records: [],
                             gameCount: 0,
                             moveCount: 0,
                             orphanedZone: orphan
                         )
                     }
                 }
             }
 
             var all: [PerZoneGameMoves] = []
             for await result in group {
                 all.append(result)
             }
             return all
         }
 
         let records = perZone.flatMap(\.records)
         await applyDirectRecordZoneChanges(
             records: records,
             deletions: [],
             scopeValue: scopeValue
         )
 
         let orphans = Set(perZone.compactMap(\.orphanedZone))
         if !orphans.isEmpty {
             await applyZoneOrphaning(orphans, isPrivate: scope == .private)
         }
 
         let gameCount = perZone.reduce(0) { $0 + $1.gameCount }
         let moveCount = perZone.reduce(0) { $0 + $1.moveCount }
         await trace(
             "\(label) game/moves catch-up: zones=\(zones.count), " +
             "game=\(gameCount), moves=\(moveCount)"
         )
         return moveCount
     }
 
     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)
         return try await queryRecords(
             type: type,
             database: database,
             zoneID: zoneID,
             predicate: NSPredicate(format: "modificationDate > %@", since as NSDate),
             desiredKeys: desiredKeys
         )
     }
 
     func queryRecords(
         type: CKRecord.RecordType,
         database: CKDatabase,
         zoneID: CKRecordZone.ID,
         predicate: NSPredicate,
         desiredKeys: [CKRecord.FieldKey]
     ) async throws -> [CKRecord] {
         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 setLiveQueryCheckpoint(
         _ date: Date,
         scopeValue: Int16,
         gameID: UUID
     ) {
         liveQueryCheckpoints["\(scopeValue):\(gameID.uuidString)"] = date
     }
 
     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
         }
     }
 
     /// Fetches every device's uploaded `Journal` record for a finished game,
     /// together with the set of devices that wrote grid state (from the `Moves`
     /// record names), so the caller can gate replay on completeness. A plain
     /// zone-scoped `CKQuery` — it reads on demand and does **not** disturb the
     /// sync engine's change token (inbound `Journal` records stay ignored in the
     /// delegate path). Returns `nil` when the game's zone isn't known locally or
     /// access has been revoked; the caller surfaces that as `.unavailable`.
     func fetchReplay(forGameID gameID: UUID) async throws -> JournalReplayFetch? {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx), !info.isAccessRevoked else {
             return nil
         }
         let database = info.scope == 1
             ? container.sharedCloudDatabase
             : container.privateCloudDatabase
 
         // Expected device set: every device that wrote grid state owns a Moves
         // record named `moves-<game>-<author>-<device>`. Keys only.
         let movesRecords = try await queryRecords(
             type: "Moves",
             database: database,
             zoneID: info.zoneID,
             predicate: NSPredicate(value: true),
             desiredKeys: []
         )
         var expected = Set<JournalDeviceKey>()
         for record in movesRecords {
             if let (_, authorID, deviceID) =
                 RecordSerializer.parseMovesRecordName(record.recordID.recordName) {
                 expected.insert(JournalDeviceKey(authorID: authorID, deviceID: deviceID))
             }
         }
 
         // Present journals: decode each device's `entries` asset into its log.
         let journalRecords = try await queryRecords(
             type: "Journal",
             database: database,
             zoneID: info.zoneID,
             predicate: NSPredicate(value: true),
             desiredKeys: ["entries"]
         )
         var journals: [DeviceJournal] = []
         for record in journalRecords {
             guard let (_, authorID, deviceID) =
                     RecordSerializer.parseJournalRecordName(record.recordID.recordName),
                   let asset = record["entries"] as? CKAsset,
                   let url = asset.fileURL
             else { continue }
             do {
                 let entries = try JournalCodec.decode(Data(contentsOf: url))
                 journals.append(
                     DeviceJournal(
                         key: JournalDeviceKey(authorID: authorID, deviceID: deviceID),
                         entries: entries
                     )
                 )
             } catch {
                 await trace(
                     "fetchReplay: journal decode failed for " +
                     "\(record.recordID.recordName): \(describe(error))"
                 )
             }
         }
         await trace(
             "fetchReplay \(gameID.uuidString.prefix(8)): scope=\(info.scope) " +
             "movesRecords=\(movesRecords.count) expectedDevices=\(expected.count) " +
             "journalRecords=\(journalRecords.count) " +
             "journalEntryCounts=[\(journals.map { String($0.entries.count) }.joined(separator: ","))]"
         )
         return JournalReplayFetch(journals: journals, expectedDevices: expected)
     }
 }