crossmate

SyncEngine.swift (111338B)

---

 import CloudKit
 import CoreData
 import Foundation
 import SwiftUI
 
 extension EnvironmentValues {
     @Entry var syncEngine: SyncEngine? = nil
     @Entry var resetDatabase: (() async -> Void)? = nil
     /// `(gameID, friendAuthorID)` — re-invites an existing friend to a game.
     @Entry var inviteFriend: ((UUID, String) async throws -> Void)? = nil
     /// `(shareURL, pingRecordName)` — accepts a pending game invite.
     @Entry var acceptInvite: ((String, String) async throws -> Void)? = nil
     /// `(gameID)` — declines a pending game invite (tombstone + badge refresh).
     @Entry var declineInvite: ((UUID) async throws -> Void)? = nil
     /// `(friendAuthorID)` — blocks a collaborator: suppress future invites,
     /// leave their shared games, tear down the friend zone.
     @Entry var blockFriend: ((String) async -> Void)? = nil
     /// `(friendAuthorID, nickname)` — sets the user's private nickname for a
     /// friend; an empty nickname clears it back to the friend's own name.
     @Entry var renameFriend: ((String, String) async -> Void)? = nil
     /// `(gameID)` — fires the completion APN after a game is resigned from
     /// the library (the in-puzzle path uses `onResign` directly).
     @Entry var sendResignPings: ((UUID) async -> Void)? = nil
 }
 
 extension Notification.Name {
     /// Posted by `SyncEngine` after applying fetched record zone changes that
     /// touched a game's roster-relevant state — a Player record, a Game record,
     /// a deletion, or a new contributor's first Moves row (see
     /// `BatchEffects.rosterRelevant`). `userInfo["gameIDs"]` is a `Set<UUID>`.
     /// `PlayerRoster` observes this to refresh in response to remote name /
     /// cursor updates and new participants joining. Repeat Moves from a known
     /// contributor (peer letters) are excluded — they don't change the roster.
     static let playerRosterShouldRefresh = Notification.Name("playerRosterShouldRefresh")
 
     /// Posted by `SyncEngine` when an inbound `Journal` record lands for one or
     /// more games. `userInfo["gameIDs"]` is a `Set<UUID>`. The finish-banner
     /// replay observes this to re-check completeness the moment a contributor's
     /// journal syncs, instead of polling.
     static let replayJournalDidSync = Notification.Name("replayJournalDidSync")
 }
 
 
 /// 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
 
     var privateEngine: CKSyncEngine?
     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] = [:]
     /// Payloads for `Decision` records pending send, keyed by
     /// `decisionStateKey` (zone + record name — the same decision record can
     /// be pending in several zones at once, e.g. a name Decision fanned out
     /// to every friend zone, and one zone's save must not strip the others').
     /// Unlike a ping body, these must survive an app kill: CKSyncEngine persists
     /// the pending `.saveRecord`, so on relaunch `buildRecord` would otherwise
     /// emit a payload-less Decision (e.g. an empty `pushSecret`) that uploads as
     /// a poison record other devices can't parse and this device never
     /// republishes. Mirrored to UserDefaults on every mutation and restored in
     /// `start()`.
     private var pendingDecisionPayloads: [String: String] = [:]
 
     private static let pendingDecisionPayloadsDefaultsKey =
         "SyncEngine.pendingDecisionPayloads"
 
     /// Intended generation for a versioned `Decision` pending send, keyed by
     /// `decisionStateKey`. Mirrors `pendingDecisionPayloads`' lifecycle and
     /// durability: the version must survive an app kill so a rebuilt rotation
     /// re-asserts at the right generation rather than a stale one. The push
     /// secret and display name are versioned; unversioned decisions
     /// (block/left/pushAddress) have no entry and stay write-once on conflict.
     private var pendingDecisionVersions: [String: Int64] = [:]
 
     private static let pendingDecisionVersionsDefaultsKey =
         "SyncEngine.pendingDecisionVersions"
 
     /// Server system fields adopted while recovering a *versioned* Decision that
     /// lost the change-tag race but won on version — stashed so the next
     /// `buildRecord` carries the server's tag and the overwrite is accepted
     /// rather than re-colliding. In-memory only: the version in
     /// `pendingDecisionVersions` carries correctness across a relaunch (a
     /// tagless re-send simply re-hits the conflict and re-recovers), so this is
     /// a round-trip optimization, not durable state. Keyed by
     /// `decisionStateKey` — the same record name carries a different change
     /// tag in each zone it lives in. Cleared once the record saves or settles.
     private var decisionSystemFields: [String: Data] = [:]
 
     /// Key for the per-zone decision state above. A decision's record name is
     /// deterministic, so the same name can be pending in the account zone and
     /// several friend zones simultaneously; the zone name disambiguates.
     nonisolated static func decisionStateKey(_ recordID: CKRecord.ID) -> String {
         "\(recordID.zoneID.zoneName)/\(recordID.recordName)"
     }
 
     struct PingPayload {
         let gameID: UUID
         let authorID: String
         let deviceID: String
         let playerName: String
         let puzzleTitle: String
         let eventTimestampMs: Int64
         let kind: PingKind
         let payload: String?
         let addressee: String?
     }
 
     /// 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
 
     var onRemoteMovesUpdated: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     /// Fires with the game IDs for which a collaborator's `Player` record was
     /// seen for the **first time** (a new `PlayerEntity` was created) — not on
     /// their subsequent name / cursor updates. Independent of moves; the
     /// friendship bootstrap keys off this so a collaborator becomes a friend
     /// once, as soon as their identity syncs, without waiting for a move.
     var onRemotePlayersUpdated: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     /// Fires when a remote collaborator's `Player` record updates active
     /// presence state (selection set/cleared or refreshed). Unlike
     /// `onRemotePlayersUpdated`, this fires for existing Player records too,
     /// so live engagement can start when a known collaborator opens a puzzle.
     var onRemotePlayerPresenceChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     /// Fires with the game IDs whose Game-record `engagement` creds just
     /// changed (a peer minted or rotated the room). Drives the receiver to
     /// reconcile its live connection toward the new creds.
     var onRemoteEngagementChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     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)?
     /// Fires when an inbound Game record transitions a local row to completed.
     /// App-level side effects that are not sync-engine state (for example
     /// closing public share tickets) hang off this edge.
     var onGameCompleted: (@MainActor @Sendable (UUID) async -> Void)?
     /// Fires with the game ID of a shared zone that just appeared locally —
     /// the user joined the game here or on a sibling device. Drives cleanup
     /// of the now-redundant pending invite row.
     private var onGameJoined: (@MainActor @Sendable (UUID) async -> Void)?
     /// Fires with Ping records that were just deleted on the server (a sibling
     /// device consumed a directed ping). Drives cross-device withdrawal of the
     /// notification and any local durable invite row this device may hold.
     var onPingDeleted: (@MainActor @Sendable ([(recordName: String, gameID: UUID)]) async -> Void)?
     /// Fires with (gameID, readAt) pairs lifted from inbound Player records
     /// whose authorID matches the local user. A sibling device has recorded
     /// the account's read horizon; active sessions may move it into the near
     /// future and later close it with a lower current-time value.
     var onIncomingReadCursor: (@MainActor @Sendable ([(UUID, Date, Data?)]) async -> Void)?
     var onAccountPushAddress: (@MainActor @Sendable (String) async -> Void)?
     var onAccountPushSecret: (@MainActor @Sendable (String, Int64) async -> Void)?
     private var localAuthorIDProvider: (@MainActor @Sendable () -> String?)?
     private var tracer: (@MainActor @Sendable (String) -> Void)?
     /// Fires when a delegate event reports a successful round-trip with the
     /// CloudKit server (fetched DB changes, fetched zone changes, or sent
     /// zone changes with no failures). Bumps `Last Success` in the
     /// diagnostics view so the timestamp reflects actual engine activity
     /// rather than only instrumented phases run through `SyncMonitor.run`.
     private var successCheckpoint: (@MainActor @Sendable () -> Void)?
     var liveQueryCheckpoints: [String: Date] = [:]
     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).
     var pingPushCheckpoints: [Int16: Date] = [:]
     let pingPushCheckpointOverlap: TimeInterval = 30
     /// Per-scope record-name → modificationDate of Ping records already
     /// surfaced by the fast path. The time-window query deliberately re-fetches
     /// anything within `pingPushCheckpointOverlap` of the floor (skew safety),
     /// so without this a record — unboundedly, the newest one — would re-emit
     /// on every push. Pruned to the overlap window each scan, so it stays
     /// small. Mirrors the presentation-layer dedupe in `NotificationState`.
     var seenPingRecords: [Int16: [String: Date]] = [:]
     let backgroundSessionLookback: TimeInterval = 10 * 60
 
     func setTracer(_ t: @MainActor @Sendable @escaping (String) -> Void) {
         tracer = t
     }
 
     func setSuccessCheckpoint(_ cb: @MainActor @Sendable @escaping () -> Void) {
         successCheckpoint = cb
     }
 
     private func noteRoundTripSuccess() async {
         guard let successCheckpoint else { return }
         await successCheckpoint()
     }
 
     func setOnRemoteMovesUpdated(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemoteMovesUpdated = cb
     }
 
     func setOnRemotePlayersUpdated(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemotePlayersUpdated = cb
     }
 
     func setOnRemotePlayerPresenceChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemotePlayerPresenceChanged = cb
     }
 
     func setOnRemoteEngagementChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemoteEngagementChanged = 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 setOnGameCompleted(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
         onGameCompleted = cb
     }
 
     func setOnGameJoined(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
         onGameJoined = cb
     }
 
     func setOnPingDeleted(
         _ cb: @MainActor @Sendable @escaping ([(recordName: String, gameID: UUID)]) async -> Void
     ) {
         onPingDeleted = cb
     }
 
     func setOnIncomingReadCursor(_ cb: @MainActor @Sendable @escaping ([(UUID, Date, Data?)]) async -> Void) {
         onIncomingReadCursor = cb
     }
 
     func setOnAccountPushAddress(_ cb: @MainActor @Sendable @escaping (String) async -> Void) {
         onAccountPushAddress = cb
     }
 
     func setOnAccountPushSecret(_ cb: @MainActor @Sendable @escaping (String, Int64) async -> Void) {
         onAccountPushSecret = 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. Idempotent — extra calls are no-ops so a race between
     /// `services.start()` and a scene-active foreground sync can't double-
     /// initialise the engines or re-fire subscription setup.
     func start() async {
         guard privateEngine == nil, sharedEngine == nil else { return }
 
         // CKSyncEngine restores its pending `.saveRecord` changes from the
         // serialized state below; restore the matching Decision payloads so a
         // pending decision rebuilds with its body instead of as a poison record.
         restorePendingDecisionPayloads()
         restorePendingDecisionVersions()
 
         let bgCtx = persistence.container.newBackgroundContext()
 
         let privateData: Data? = bgCtx.performAndWait {
             SyncStateEntity.current(in: bgCtx).ckPrivateEngineState
         }
         let privateState = await decodeEngineState(privateData, label: "private")
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: privateState,
             delegate: self
         ))
 
         let sharedData: Data? = bgCtx.performAndWait {
             SyncStateEntity.current(in: bgCtx).ckSharedEngineState
         }
         let sharedState = await decodeEngineState(sharedData, label: "shared")
         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() }
         Task { await purgeLegacyLeasePings_v1() }
         Task { await purgeLegacyInvitePings_v1() }
         Task { await purgeStaleHailPings_v1() }
         Task { await purgeDebugPreviewFriends_v1() }
         Task { await purgeLegacyPlayPings_v1() }
     }
 
     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))")
         }
     }
 
     /// Kicks CKSyncEngine's outbound drain after pending state has been queued.
     /// This must be detached: several enqueue paths are reachable from
     /// CKSyncEngine delegate callbacks, and a plain `Task {}` can inherit the
     /// callback's executor and re-enter CKSyncEngine before the callback
     /// unwinds, tripping CloudKit's serialization guard.
     private func sendChangesDetached(on engine: CKSyncEngine) {
         Task.detached { [engine] in try? await engine.sendChanges() }
     }
 
     /// Per-scope burst depth. `enqueuePlayer` consults this — while
     /// non-zero for a scope, it records that a drain is owed instead of
     /// firing `sendChanges` immediately. The outermost frame issues one
     /// `sendChanges` on exit if any enqueue landed during the burst.
     /// Replaces an earlier time-window coalesce that had to be tuned to
     /// match `PlayerSelectionPublisher`'s debounce: the open path now
     /// explicitly fans out read cursor, name, and the initial selection
     /// inside a burst, so the batch is bounded by the work that produces
     /// it rather than by a wall-clock window.
     private var playerSendBurstDepth: [Int16: Int] = [:]
     private var playerSendBurstPending: Set<Int16> = []
 
     /// Opens a Player-record send burst for `gameID`'s scope. Subsequent
     /// `enqueuePlayer` calls on that scope skip their immediate
     /// drain; the caller must pair this with `endPlayerSendBurst(scope:)`,
     /// which fires one `sendChanges` if any enqueue landed in between.
     /// Returns the scope so the caller can close the matching burst even
     /// if the game's zone routing changes after the call.
     func beginPlayerSendBurst(gameID: UUID) -> Int16? {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return nil }
         playerSendBurstDepth[info.scope, default: 0] += 1
         return info.scope
     }
 
     /// Closes a burst opened by `beginPlayerSendBurst`. The outermost
     /// frame drains the affected engine if any enqueue landed during the
     /// burst; nested frames just decrement the counter.
     func endPlayerSendBurst(scope: Int16) {
         guard let depth = playerSendBurstDepth[scope], depth > 0 else { return }
         if depth > 1 {
             playerSendBurstDepth[scope] = depth - 1
             return
         }
         playerSendBurstDepth.removeValue(forKey: scope)
         guard playerSendBurstPending.remove(scope) != nil else { return }
         let engine = scope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         sendChangesDetached(on: engine)
     }
 
     // MARK: - Outbound
 
     /// Registers each game's local-device Moves record as a pending save,
     /// routed per-game to the correct engine. Called by the `MovesUpdater`
     /// sink after the device's `MovesEntity` row has been merged and persisted.
     ///
     /// `drain` controls whether to force an eager `sendChanges()`:
     ///
     /// - `false` (live typing debounce): the engagement socket already carries
     ///   the letters via `cellEdit`/`cellEditBatch`, so CloudKit is the durable
     ///   backstop ("appears on sync"), not the live path. With no peer watching
     ///   the durable write in real time, leaving the drain to CKSyncEngine's
     ///   automatic scheduler lets it coalesce a typing burst into far fewer
     ///   round-trips and avoids the self-induced oplock races two concurrent
     ///   drains produced over the same `CKRecord.ID`.
     /// - `true` (explicit `flush()` on leave/background, and recovery via
     ///   `enqueueUnconfirmedMoves`): the solver's final letters must reach
     ///   CloudKit promptly even when no peer is on the socket, so force the
     ///   send rather than waiting for the next foreground.
     func enqueueMoves(gameIDs: Set<UUID>, drain: Bool = true) async {
         guard !gameIDs.isEmpty else { return }
         // The local-device row is matched by author as well as device: after
         // an iCloud account switch this device's old rows persist under the
         // previous authorID (the record name embeds the author, so they are
         // distinct rows), and a device-only `fetchLimit = 1` lookup could pick
         // the old account's record and push a save the user no longer owns.
         // When no author is known yet (provider unset, first launch) fall back
         // to the device-only match, which is unambiguous until a switch has
         // happened.
         let localAuthorID = await currentLocalAuthorID()
         let ctx = persistence.container.newBackgroundContext()
         let (privateRecordIDs, sharedRecordIDs): ([CKRecord.ID], [CKRecord.ID]) = ctx.performAndWait {
             var privateIDs: [CKRecord.ID] = []
             var sharedIDs: [CKRecord.ID] = []
             for gameID in gameIDs {
                 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { continue }
                 let isShared = info.scope == 1
                 let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 if let localAuthorID, !localAuthorID.isEmpty {
                     req.predicate = NSPredicate(
                         format: "game.id == %@ AND deviceID == %@ AND authorID == %@",
                         gameID as CVarArg,
                         RecordSerializer.localDeviceID,
                         localAuthorID
                     )
                 } else {
                     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)
                 if isShared {
                     sharedIDs.append(recordID)
                 } else {
                     privateIDs.append(recordID)
                 }
             }
             return (privateIDs, sharedIDs)
         }
         if !privateRecordIDs.isEmpty, let engine = privateEngine {
             engine.state.add(
                 pendingRecordZoneChanges: privateRecordIDs.map { .saveRecord($0) }
             )
             if drain { sendChangesDetached(on: engine) }
         }
         if !sharedRecordIDs.isEmpty, let engine = sharedEngine {
             engine.state.add(
                 pendingRecordZoneChanges: sharedRecordIDs.map { .saveRecord($0) }
             )
             if drain { sendChangesDetached(on: engine) }
         }
     }
 
     /// 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. Scoped to the
     /// current author for the same reason as `enqueueMoves`: an account
     /// switch leaves the old account's unconfirmed rows behind on this device,
     /// and recovery must not push them under the new account.
     @discardableResult
     func enqueueUnconfirmedMoves() async -> Int {
         let localAuthorID = await currentLocalAuthorID()
         let ctx = persistence.container.newBackgroundContext()
         let gameIDs: Set<UUID> = ctx.performAndWait {
             let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
             if let localAuthorID, !localAuthorID.isEmpty {
                 req.predicate = NSPredicate(
                     format: "ckSystemFields == nil AND deviceID == %@ AND authorID == %@",
                     RecordSerializer.localDeviceID,
                     localAuthorID
                 )
             } else {
                 req.predicate = NSPredicate(
                     format: "ckSystemFields == nil AND deviceID == %@",
                     RecordSerializer.localDeviceID
                 )
             }
             let entities = (try? ctx.fetch(req)) ?? []
             return Set(entities.compactMap { $0.game?.id })
         }
         await 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, 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)])
         sendChangesDetached(on: engine)
 
         // A finished participant game keeps a self-contained backup in a
         // separate archive-<id> zone (see GameArchiver). The live game lives in
         // the shared database, so the deletion above never reaches that backup —
         // tear it down here. The archive is always in this account's private
         // database, so it routes through the private engine regardless of the
         // game's own scope.
         guard let archiveZoneName = deletion.archiveZoneName,
               let privateEngine else { return }
         let archiveZoneID = CKRecordZone.ID(
             zoneName: archiveZoneName,
             ownerName: CKCurrentUserDefaultName
         )
         privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(archiveZoneID)])
         sendChangesDetached(on: privateEngine)
     }
 
     /// Registers a Ping record as a pending send. Pings now only cover
     /// bootstrap kinds (`.join` / `.friend` / `.invite` / `.hail`) — the
     /// user-facing play events go through the push worker. Sender-only
     /// state: the payload is stashed in `pendingPings` and only used to
     /// build the outgoing `CKRecord`; nothing is persisted.
     func enqueuePing(
         kind: PingKind,
         gameID: UUID,
         authorID: String,
         playerName: String,
         payload: String? = nil,
         addressee: String? = nil
     ) {
         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 = PuzzleNotificationText.title(for: entity)
             return (info, title)
         }
         guard let zoneAndTitle else {
             Task {
                 await trace(
                     "ping send: SKIPPED kind=\(kind.rawValue) " +
                     "game=\(gameID.uuidString) " +
                     "— no zone info (game not yet synced/shared on this device)"
                 )
             }
             return
         }
         let engine = zoneAndTitle.info.scope == 1 ? sharedEngine : privateEngine
         guard let engine else {
             Task {
                 await trace(
                     "ping send: SKIPPED kind=\(kind.rawValue) " +
                     "game=\(gameID.uuidString) " +
                     "— no CKSyncEngine for " +
                     "\(zoneAndTitle.info.scope == 1 ? "shared" : "private") scope"
                 )
             }
             return
         }
         let deviceID = RecordSerializer.localDeviceID
         let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
         let recordName = RecordSerializer.recordName(
             forPingInGame: gameID,
             authorID: authorID,
             deviceID: deviceID,
             eventTimestampMs: eventTimestampMs
         )
         pendingPings[recordName] = PingPayload(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             playerName: playerName,
             puzzleTitle: zoneAndTitle.title,
             eventTimestampMs: eventTimestampMs,
             kind: kind,
             payload: payload,
             addressee: addressee
         )
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneAndTitle.info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         Task {
             await trace(
                 "ping send: enqueued kind=\(kind.rawValue) " +
                 "game=\(gameID.uuidString) " +
                 "target=\(zoneAndTitle.info.scope == 1 ? "shared" : "private") " +
                 "zone=\(zoneAndTitle.info.zoneID.zoneName) record=\(recordName)"
             )
         }
         sendChangesDetached(on: engine)
     }
 
     /// Registers an `.opened` Ping for cross-device notification dismissal.
     /// Written to the account zone in the private database, so only the
     /// authoring user's own devices receive it. The receive side filters
     /// self-sends by (authorID, deviceID).
     /// One-shot cleanup of legacy `.opened`/`.closed` lease pings from this
     /// device's slot in the private-DB account zone. The lease subsystem is
     /// gone (cross-device read state now rides `Player.readAt`), so any
     /// remaining records are dead weight — every device cleans its own slice
     /// the first time it launches the new build. Gated by an App-Group flag;
     /// failures retry on the next launch. Slated for removal in a future
     /// release once every device of every user has run it.
     func purgeLegacyLeasePings_v1() async {
         guard NotificationState.legacyLeasePurgeNeeded() else { return }
         let predicate = NSPredicate(
             format: "kind IN %@ AND deviceID == %@",
             ["opened", "closed"],
             RecordSerializer.localDeviceID
         )
         do {
             let records = try await queryRecords(
                 type: "Ping",
                 database: container.privateCloudDatabase,
                 zoneID: RecordSerializer.accountZoneID,
                 predicate: predicate,
                 desiredKeys: []
             )
             try await deleteRecords(
                 withIDs: records.map(\.recordID),
                 in: container.privateCloudDatabase
             )
             NotificationState.markLegacyLeasePurged()
             if !records.isEmpty {
                 await trace("legacy-lease purge: deleted \(records.count) record(s)")
             }
         } catch {
             await trace("legacy-lease purge failed: \(describe(error))")
         }
     }
 
     /// One-shot cleanup of legacy broadcast `.invite` pings from pairwise
     /// friend zones. Current invites are addressed with `addressee`; older
     /// ones were broadcast within the friend zone and can resurrect stale
     /// Game List rows after a device restores or replays zone history.
     func purgeLegacyInvitePings_v1() async {
         guard NotificationState.legacyInvitePurgeNeeded() else { return }
         let privateZones = friendZoneIDs(forScope: 0)
         let sharedZones = friendZoneIDs(forScope: 1)
         do {
             let privateDeleted = try await purgeLegacyInvitePings(
                 in: privateZones,
                 database: container.privateCloudDatabase
             )
             let sharedDeleted = try await purgeLegacyInvitePings(
                 in: sharedZones,
                 database: container.sharedCloudDatabase
             )
             NotificationState.markLegacyInvitePurged()
             let total = privateDeleted + sharedDeleted
             if total > 0 {
                 await trace("legacy-invite purge: deleted \(total) record(s)")
             }
         } catch {
             await trace("legacy-invite purge failed: \(describe(error))")
         }
     }
 
     private func purgeLegacyInvitePings(
         in zoneIDs: [CKRecordZone.ID],
         database: CKDatabase
     ) async throws -> Int {
         var deleted = 0
         let predicate = NSPredicate(format: "kind == %@", PingKind.invite.rawValue)
         for zoneID in zoneIDs {
             let records = try await queryRecords(
                 type: "Ping",
                 database: database,
                 zoneID: zoneID,
                 predicate: predicate,
                 desiredKeys: ["addressee"]
             )
             let legacyIDs = records
                 .filter { ($0["addressee"] as? String)?.isEmpty != false }
                 .map(\.recordID)
             try await deleteRecords(withIDs: legacyIDs, in: database)
             deleted += legacyIDs.count
         }
         return deleted
     }
 
     /// One-shot cleanup of stale legacy `.hail` records from known game
     /// zones. Hails are ephemeral bootstrap envelopes; any records written
     /// before the current cleanup/deletion path shipped can only replay
     /// obsolete handshakes, so remove them once per device.
     func purgeStaleHailPings_v1() async {
         guard NotificationState.staleHailPurgeNeeded() else { return }
         do {
             let privateDeleted = try await purgeStaleHailPings(
                 in: gameZoneIDs(forScope: 0),
                 database: container.privateCloudDatabase
             )
             let sharedDeleted = try await purgeStaleHailPings(
                 in: gameZoneIDs(forScope: 1),
                 database: container.sharedCloudDatabase
             )
             NotificationState.markStaleHailPurged()
             let total = privateDeleted + sharedDeleted
             await trace("stale-hail purge: deleted \(total) record(s)")
         } catch {
             await trace("stale-hail purge failed: \(describe(error))")
         }
     }
 
     private func purgeStaleHailPings(
         in zoneIDs: [CKRecordZone.ID],
         database: CKDatabase
     ) async throws -> Int {
         var deleted = 0
         let predicate = NSPredicate(format: "kind == %@", PingKind.hail.rawValue)
         for zoneID in zoneIDs {
             let records = try await queryRecords(
                 type: "Ping",
                 database: database,
                 zoneID: zoneID,
                 predicate: predicate,
                 desiredKeys: []
             )
             try await deleteRecords(withIDs: records.map(\.recordID), in: database)
             deleted += records.count
         }
         return deleted
     }
 
     /// One-shot cleanup of Ping records whose kinds were retired when the
     /// push worker took over user-facing event notifications:
     /// `.check`, `.reveal`, `.resign`, `.win`, and the old session-start
     /// `.join`. Those kinds are gone from `PingKind`, but records written
     /// by pre-cutover builds linger in shared game zones and will replay
     /// as obsolete announcements after a zone fetch. Every device drains
     /// the game zones it can reach exactly once.
     func purgeLegacyPlayPings_v1() async {
         guard NotificationState.legacyPlayPingPurgeNeeded() else { return }
         do {
             let privateDeleted = try await purgeLegacyPlayPings(
                 in: gameZoneIDs(forScope: 0),
                 database: container.privateCloudDatabase
             )
             let sharedDeleted = try await purgeLegacyPlayPings(
                 in: gameZoneIDs(forScope: 1),
                 database: container.sharedCloudDatabase
             )
             NotificationState.markLegacyPlayPingPurged()
             let total = privateDeleted + sharedDeleted
             if total > 0 {
                 await trace("legacy play-ping purge: deleted \(total) record(s)")
             }
         } catch {
             await trace("legacy play-ping purge failed: \(describe(error))")
         }
     }
 
     private func purgeLegacyPlayPings(
         in zoneIDs: [CKRecordZone.ID],
         database: CKDatabase
     ) async throws -> Int {
         var deleted = 0
         let predicate = NSPredicate(
             format: "kind IN %@",
             ["check", "reveal", "resign", "win", "join"]
         )
         for zoneID in zoneIDs {
             let records = try await queryRecords(
                 type: "Ping",
                 database: database,
                 zoneID: zoneID,
                 predicate: predicate,
                 desiredKeys: []
             )
             try await deleteRecords(withIDs: records.map(\.recordID), in: database)
             deleted += records.count
         }
         return deleted
     }
 
     private func gameZoneIDs(forScope scope: Int16) -> [CKRecordZone.ID] {
         let ctx = persistence.container.newBackgroundContext()
         return ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "databaseScope == %d AND isAccessRevoked == NO",
                 scope
             )
             var seen = Set<String>()
             var result: [CKRecordZone.ID] = []
             for entity in (try? ctx.fetch(req)) ?? [] {
                 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 }
                 result.append(CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName))
             }
             return result
         }
     }
 
     /// One-shot local cleanup for pre-release debug friend rows whose
     /// `friend-debug-preview-*` zones no longer exist or have invalid
     /// participants. These rows are local metadata, but while present they
     /// make the ping fast-path query dead zones on every poll.
     func purgeDebugPreviewFriends_v1() async {
         guard NotificationState.debugPreviewFriendPurgeNeeded() else { return }
         let ctx = persistence.container.newBackgroundContext()
         let deleted = ctx.performAndWait {
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(format: "friendZoneName BEGINSWITH %@", "friend-debug-preview-")
             let rows = (try? ctx.fetch(req)) ?? []
             for row in rows {
                 ctx.delete(row)
             }
             do {
                 if ctx.hasChanges {
                     try ctx.save()
                 }
                 return rows.count
             } catch {
                 ctx.rollback()
                 return -1
             }
         }
 
         guard deleted >= 0 else {
             await trace("debug-preview friend purge failed")
             return
         }
         NotificationState.markDebugPreviewFriendPurged()
         await trace("debug-preview friend purge: deleted \(deleted) row(s)")
     }
 
     /// Registers a directed Ping (`.invite` or `.decline`) into an existing
     /// *friend* zone. Unlike `enqueuePing`, the target zone is the friend zone
     /// (not the game zone), so the zone and engine are passed in explicitly:
     /// `scope == 1` means we joined the friend zone (it lives in our shared DB
     /// → shared engine); `scope == 0` means we own it (private DB → private
     /// engine). The zone already exists by the time an invite or decline is
     /// possible, so no `saveZone`. `gameID` is the game in question; it rides
     /// the record name so the recipient resolves it without reading the game
     /// zone. `authorID` is the sender, so an invite carries the inviter and a
     /// decline carries the decliner.
     func enqueueFriendZonePing(
         kind: PingKind,
         gameID: UUID,
         gameTitle: String,
         authorID: String,
         playerName: String,
         addressee: String,
         friendZoneID: CKRecordZone.ID,
         friendZoneScope: Int16,
         payload: String? = nil
     ) {
         let engine = friendZoneScope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         let deviceID = RecordSerializer.localDeviceID
         let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
         let recordName = RecordSerializer.recordName(
             forPingInGame: gameID,
             authorID: authorID,
             deviceID: deviceID,
             eventTimestampMs: eventTimestampMs
         )
         pendingPings[recordName] = PingPayload(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             playerName: playerName,
             puzzleTitle: gameTitle,
             eventTimestampMs: eventTimestampMs,
             kind: kind,
             payload: payload,
             addressee: addressee
         )
         let recordID = CKRecord.ID(recordName: recordName, zoneID: friendZoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     /// Registers a durable `Decision` record into the account zone so the fact
     /// reaches the user's own other devices. Decisions without payloads are
     /// reconstructable from their names; payload-bearing decisions mirror their
     /// body to UserDefaults so CKSyncEngine's persisted pending save survives an
     /// app kill without rebuilding as a payload-less record. Idempotent — a
     /// re-send of an existing decision is a benign conflict the send path drops.
     func enqueueDecision(
         kind: String,
         key: String,
         payload: String? = nil,
         version: Int64? = nil
     ) {
         guard let engine = privateEngine else { return }
         let zoneID = RecordSerializer.accountZoneID
         // CKSyncEngine dedupes redundant saveZone requests, so it's safe to
         // repeat — block may be the first thing ever written to this zone.
         engine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: zoneID))])
         registerDecisionSave(
             kind: kind, key: key, payload: payload, version: version,
             zoneID: zoneID, engine: engine
         )
     }
 
     /// Registers a `Decision` into an existing *friend* zone — the channel a
     /// display name rides to reach the other participant. Engine selection
     /// mirrors `enqueueFriendInvitePing`: `scope == 1` means we joined the
     /// zone (shared engine), `scope == 0` means we own it (private engine).
     /// The zone already exists by the time a friendship is recorded, so no
     /// `saveZone`.
     func enqueueFriendDecision(
         kind: String,
         key: String,
         payload: String? = nil,
         version: Int64? = nil,
         friendZoneID: CKRecordZone.ID,
         friendZoneScope: Int16
     ) {
         guard let engine = friendZoneScope == 1 ? sharedEngine : privateEngine else { return }
         registerDecisionSave(
             kind: kind, key: key, payload: payload, version: version,
             zoneID: friendZoneID, engine: engine
         )
     }
 
     /// Routes a display-name Decision to its zone. The account zone may not
     /// exist yet, so that path rides `enqueueDecision`'s `saveZone` backstop;
     /// a friend zone always exists by the time a friendship is recorded.
     func enqueueNameDecision(
         authorID: String,
         name: String,
         version: Int64,
         zoneID: CKRecordZone.ID,
         scope: Int16
     ) {
         if zoneID == RecordSerializer.accountZoneID {
             enqueueDecision(
                 kind: RecordSerializer.nameDecisionKind,
                 key: authorID,
                 payload: name,
                 version: version
             )
         } else {
             enqueueFriendDecision(
                 kind: RecordSerializer.nameDecisionKind,
                 key: authorID,
                 payload: name,
                 version: version,
                 friendZoneID: zoneID,
                 friendZoneScope: scope
             )
         }
     }
 
     private func registerDecisionSave(
         kind: String,
         key: String,
         payload: String?,
         version: Int64?,
         zoneID: CKRecordZone.ID,
         engine: CKSyncEngine
     ) {
         let name = RecordSerializer.decisionRecordName(kind: kind, key: key)
         let recordID = CKRecord.ID(recordName: name, zoneID: zoneID)
         let stateKey = Self.decisionStateKey(recordID)
         if let payload {
             pendingDecisionPayloads[stateKey] = payload
             persistPendingDecisionPayloads()
         }
         if let version {
             pendingDecisionVersions[stateKey] = version
             persistPendingDecisionVersions()
         }
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     /// Deletes a durable `Decision` record (account zone) so a fact that no
     /// longer holds stops propagating — e.g. a `left` decision is voided when
     /// the user re-joins that game. Deleting an absent record is benign
     /// (CloudKit reports it gone; the send path does not retry-loop it).
     func enqueueDecisionDeletion(kind: String, key: String) {
         guard let engine = privateEngine else { return }
         let name = RecordSerializer.decisionRecordName(kind: kind, key: key)
         let recordID = CKRecord.ID(recordName: name, zoneID: RecordSerializer.accountZoneID)
         engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     /// Mirrors `pendingDecisionPayloads` to durable storage. CKSyncEngine
     /// persists the pending `.saveRecord` on its own, so the payload must be
     /// equally durable or a relaunch sends a payload-less Decision.
     private func persistPendingDecisionPayloads() {
         if pendingDecisionPayloads.isEmpty {
             UserDefaults.standard.removeObject(
                 forKey: Self.pendingDecisionPayloadsDefaultsKey
             )
         } else {
             UserDefaults.standard.set(
                 pendingDecisionPayloads,
                 forKey: Self.pendingDecisionPayloadsDefaultsKey
             )
         }
     }
 
     private func restorePendingDecisionPayloads() {
         pendingDecisionPayloads = (UserDefaults.standard.dictionary(
             forKey: Self.pendingDecisionPayloadsDefaultsKey
         ) as? [String: String]) ?? [:]
     }
 
     /// Mirrors `pendingDecisionVersions` to durable storage, alongside
     /// `persistPendingDecisionPayloads`. NSNumber/Int64 is plist-representable.
     private func persistPendingDecisionVersions() {
         if pendingDecisionVersions.isEmpty {
             UserDefaults.standard.removeObject(
                 forKey: Self.pendingDecisionVersionsDefaultsKey
             )
         } else {
             UserDefaults.standard.set(
                 pendingDecisionVersions.mapValues { NSNumber(value: $0) },
                 forKey: Self.pendingDecisionVersionsDefaultsKey
             )
         }
     }
 
     private func restorePendingDecisionVersions() {
         let raw = (UserDefaults.standard.dictionary(
             forKey: Self.pendingDecisionVersionsDefaultsKey
         ) as? [String: NSNumber]) ?? [:]
         pendingDecisionVersions = raw.mapValues { $0.int64Value }
     }
 
     /// Consume-deletes a single Ping the local account has handled (shown,
     /// suppressed, or a duplicate). The deletion syncs through the game zone so
     /// this user's other devices withdraw any notification they showed for it.
     /// Deleting an absent record is benign (CloudKit reports it gone; the send
     /// path does not retry-loop it). The deletion is queued into `engine.state`
     /// synchronously; only the `sendChanges` drain is deferred — and via
     /// `Task.detached`, not a plain `Task {}`. The completion-ack consume path
     /// (`presentPings` → `consumeIfDirected`) reaches this from inside the
     /// `onPings` delegate callback, so an un-detached Task could re-enter
     /// CKSyncEngine before the callback unwinds (same class as the
     /// friend-invite `fetchChanges` trap). Detaching keeps it off the
     /// callback's actor; the drain only needs to land eventually.
     func deletePing(recordName: String, gameID: UUID) {
         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 }
         pendingPings.removeValue(forKey: recordName)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     /// Deletes a Ping from a known non-game zone, currently used for accepted
     /// friend invites. Unlike `deletePing(recordName:gameID:)`, the GameEntity
     /// may not exist before acceptance, so the caller supplies the friend-zone
     /// route directly.
     func deletePing(recordName: String, zoneID: CKRecordZone.ID, databaseScope: Int16) {
         let engine = databaseScope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         pendingPings.removeValue(forKey: recordName)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
         engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     /// Registers a Player record as a pending send. One record per
     /// (game, authorID), so participants only ever write their own slot.
     /// `reason` is logged so the diagnostics view can attribute each enqueue
     /// to its caller (rename, read cursor, cursor track, …); it does not
     /// affect routing. Drains immediately unless a burst is open for this
     /// scope (see `beginPlayerSendBurst`) — the open path uses a burst to
     /// ship read cursor + name + initial selection in one round-trip.
     ///
     /// `drain: false` enqueues the change durably but does not force an
     /// immediate `sendChanges()`; the record ships on CKSyncEngine's own
     /// schedule instead. Used on the way to the background / on puzzle leave,
     /// where a forced drain would race the scarce suspension budget to deliver
     /// a presence write the engagement socket already carries live (and that
     /// CloudKit delivers durably regardless).
     func enqueuePlayer(gameID: UUID, authorID: String, reason: String, drain: Bool = true) async {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
         // The shared zone has already been confirmed missing server-side
         // (see `applyZoneOrphaning`). Re-saving a Player record would just
         // fail with `.zoneNotFound` and drag the orphan handler through
         // another round of the same teardown work — open-game UI keeps
         // calling here for read-cursor / selection / name-open while the
         // user lingers on the revoked puzzle. Silently dropping the enqueue
         // is the only sensible response.
         guard !info.isAccessRevoked else {
             await trace(
                 "enqueue Player[\(gameID.uuidString.prefix(8))] skipped " +
                 "(access revoked) reason=\(reason)"
             )
             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)])
         await trace("enqueue Player[\(gameID.uuidString.prefix(8))] reason=\(reason)")
         // Durably enqueued above. A `drain: false` caller leaves the send to
         // CKSyncEngine's automatic scheduling — and skips the burst-pending
         // mark too, so a concurrent burst won't drain on this record's behalf.
         guard drain else { return }
         if (playerSendBurstDepth[info.scope] ?? 0) > 0 {
             playerSendBurstPending.insert(info.scope)
         } else {
             sendChangesDetached(on: engine)
         }
     }
 
     /// 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)])
         sendChangesDetached(on: engine)
     }
 
     /// Registers this device's move journal as a pending send, into the game's
     /// existing zone (no `saveZone` — by completion the zone is long since
     /// created). One `Journal` record per (game, author, device); the asset is
     /// rebuilt from the durable local `JournalEntity` log in `buildRecord`, so
     /// no payload is stashed here. Called once at completion; a re-send is a
     /// benign conflict the send path drops. Skipped on an access-revoked game,
     /// where any save would just fail with `.zoneNotFound`.
     func enqueueJournalUpload(gameID: UUID, authorID: String) {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx),
               !info.isAccessRevoked else { return }
         // A device that logged nothing produces no JournalEntity rows, so the
         // build-time reap drops the save before it reaches CloudKit — an empty
         // journal never uploads, so it can't add a phantom device key to
         // replay's present set. No need to guard the enqueue itself.
         let engine = info.scope == 1 ? sharedEngine : privateEngine
         guard let engine else { return }
         let recordName = RecordSerializer.recordName(
             forJournalInGame: gameID,
             authorID: authorID,
             deviceID: RecordSerializer.localDeviceID
         )
         let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         sendChangesDetached(on: engine)
     }
 
     // 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)
     }
 
     /// Zone-scoped fetch for a single game. Returns `false` if the game's zone
     /// isn't known locally (e.g. a freshly-invited share before its zone has
     /// landed) so the caller can fall back to a full `fetchChanges`. Records
     /// arrive via the normal `fetchedRecordZoneChanges` delegate path; the
     /// engine's change token is the only checkpoint.
     func fetchChangesForGame(
         scope: CKDatabase.Scope,
         gameID: UUID,
         source: String = "manual"
     ) async throws -> Bool {
         let engine: CKSyncEngine?
         let scopeValue: Int16
         switch scope {
         case .private:
             engine = privateEngine
             scopeValue = 0
         case .shared:
             engine = sharedEngine
             scopeValue = 1
         case .public:
             return false
         @unknown default:
             return false
         }
         guard let engine else { return false }
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx),
               info.scope == scopeValue
         else { return false }
         currentFetchSource = source
         defer { currentFetchSource = nil }
         let options = CKSyncEngine.FetchChangesOptions(scope: .zoneIDs([info.zoneID]))
         try await engine.fetchChanges(options)
         return true
     }
 
     func pushChanges() async throws {
         async let p: Void = privateEngine?.sendChanges() ?? ()
         async let s: Void = sharedEngine?.sendChanges() ?? ()
         _ = try await (p, s)
     }
 
     // MARK: - Diagnostics
 
 
     /// 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
             do {
                 try ctx.save()
             } catch {
                 trace("resetSyncState ctx.save failed — \(error)")
             }
         }
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.sharedCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         pendingPings = [:]
         pendingDecisionPayloads = [:]
         persistPendingDecisionPayloads()
         pendingDecisionVersions = [:]
         persistPendingDecisionVersions()
         decisionSystemFields = [:]
         pingPushCheckpoints = [:]
         seenPingRecords = [:]
         liveQueryCheckpoints = [:]
         loggedFirstSharedPushPayload = false
         playerSendBurstDepth = [:]
         playerSendBurstPending = []
         _ = await enqueueUnconfirmedMoves()
     }
 
     // MARK: - Private helpers
 
     func currentLocalAuthorID() async -> String? {
         guard let localAuthorIDProvider else { return nil }
         return await MainActor.run {
             localAuthorIDProvider()
         }
     }
 
 
     func trace(_ message: String) async {
         guard let tracer else { return }
         await tracer(message)
     }
 
     /// Decodes a persisted `CKSyncEngine.State.Serialization` payload.
     /// On failure, traces the cold-start cause so it isn't silent in the
     /// diagnostics log — the engine will rebuild change tokens and resend
     /// pending changes from scratch, which is visible-to-the-user behavior.
     private func decodeEngineState(_ data: Data?, label: String) async -> CKSyncEngine.State.Serialization? {
         guard let data else { return nil }
         do {
             return try JSONDecoder().decode(CKSyncEngine.State.Serialization.self, from: data)
         } catch {
             await trace("\(label) engine state decode failed (\(data.count) bytes) — cold-starting sync: \(describe(error))")
             return nil
         }
     }
 
     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
             }
             do {
                 try ctx.save()
             } catch {
                 trace("saveEngineState ctx.save failed — \(error)")
             }
         }
     }
 
     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"
         )
         await noteRoundTripSuccess()
 
         // 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, rejoinedIDs, failureMessages):
             ([UUID], [UUID], [UUID], [String]) = ctx.performAndWait {
             var removed: [UUID] = []
             var revoked: [UUID] = []
             var rejoined: [UUID] = []
             var messages: [String] = []
             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))
                         let gid = UUID(uuidString: uuidString)
                         entity.id = gid
                         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()
                         // Gaining access to this shared zone means the user
                         // (re)joined. Any prior `left` decision for this game
                         // is now void — clear it so a re-invited game isn't
                         // re-deleted on this or a sibling device by the stale
                         // durable fact — and any pending invite row for it is
                         // now redundant.
                         if let gid { rejoined.append(gid) }
                     }
                 }
             }
             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 {
                     // A dropped save here loses placeholder rows / revocation
                     // flags with no redelivery (the change token advances on
                     // return) — trace it so the diagnostics log shows the drop.
                     let nsError = error as NSError
                     messages.append(
                         "db-changes ctx.save FAILED — domain=\(nsError.domain) " +
                         "code=\(nsError.code) \(nsError.localizedDescription)"
                     )
                 }
             }
             return (removed, revoked, rejoined, messages)
         }
 
         for message in failureMessages {
             await trace(message)
         }
         for id in removedIDs {
             if let cb = onGameRemoved { await cb(id) }
         }
         for id in revokedIDs {
             if let cb = onGameAccessRevoked { await cb(id) }
         }
         // enqueueDecisionDeletion defers its CKSyncEngine work via Task — it
         // never awaits sync from this delegate callback's context. onGameJoined
         // only touches Core Data, so awaiting it directly is safe.
         for id in rejoinedIDs {
             enqueueDecisionDeletion(kind: "left", key: id.uuidString)
             if let cb = onGameJoined { 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"
         )
         await noteRoundTripSuccess()
         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 effects: BatchEffects = ctx.performAndWait {
             var effects = BatchEffects()
             for mod in event.modifications {
                 let record = mod.record
                 switch record.recordType {
                 case "Game":
                     let entity = RecordSerializer.applyGameRecord(
                         record,
                         to: ctx,
                         databaseScope: scope,
                         onEngagementChange: { effects.engagementChanged.insert($0) },
                         onCompletedTransition: { effects.completedTransitions.insert($0) },
                         onContentKeyChange: { effects.contentKeysChanged.insert($0) }
                     )
                     if let id = entity.id { effects.rosterRelevant.insert(id) }
                 case "Moves":
                     if let value = RecordSerializer.parseMovesRecord(record) {
                         let cellsChanged = RecordSerializer.applyMovesRecord(
                             record,
                             value: value,
                             to: ctx,
                             localAuthorID: localAuthorID,
                             onNewAuthor: { _ in effects.rosterRelevant.insert(value.gameID) }
                         )
                         if cellsChanged { effects.movesUpdated.insert(value.gameID) }
                     }
                 case "Player":
                     if let (gameID, _) = RecordSerializer.parsePlayerRecordName(record.recordID.recordName) {
                         self.applyPlayerRecord(
                             record,
                             in: ctx,
                             localAuthorID: localAuthorID,
                             onFirstTime: { effects.playersUpdated.insert($0) },
                             onPresenceChange: { effects.playerPresenceChanged.insert($0) },
                             onReadCursor: { effects.readCursors.append(($0, $1, $2)) }
                         )
                         effects.rosterRelevant.insert(gameID)
                     }
                 case "Ping":
                     if let ping = Ping.parseRecord(record) {
                         effects.pings.append(ping)
                     }
                 case "Decision":
                     if let address = RecordSerializer.parseAccountPushAddressDecision(record) {
                         effects.accountPushAddresses.append(address)
                     }
                     if let parsed = RecordSerializer.parseAccountPushSecretDecision(record) {
                         effects.accountPushSecrets.append(parsed)
                     }
                     let wrote = RecordSerializer.applyDecisionRecord(
                         record,
                         to: ctx,
                         localAuthorID: localAuthorID,
                         databaseScope: scope
                     )
                     // The decision-apply path is otherwise silent, which makes
                     // a "synced fact that never landed" (e.g. a nickname that
                     // applied on the sender but not here) impossible to diagnose
                     // from the on-device log. Record the fetched decision name,
                     // its zone, and whether it applied so the receive side is
                     // observable.
                     effects.traces.append(
                         "decision applied=\(wrote) " +
                         "\(record.recordID.recordName) " +
                         "zone=\(record.recordID.zoneID.zoneName)/" +
                         "\(record.recordID.zoneID.ownerName) scope=\(scope)"
                     )
                     // Our own name Decision echoed back from the account zone
                     // (or a friend zone a sibling seeded): adopt its version so
                     // this device's next rename supersedes it rather than
                     // colliding at an equal generation.
                     if let (subject, _, version) = RecordSerializer.parseNameDecision(record),
                        let localAuthorID, subject == localAuthorID {
                         effects.selfNameVersions.append(version)
                     }
                     // A `left` decision hard-deletes a game row; surface it so
                     // an open PuzzleView / the game list reacts, the same as
                     // the private zone-deletion path does via onGameRemoved.
                     if wrote,
                        let (dKind, dKey) = RecordSerializer.parseDecisionRecordName(
                            record.recordID.recordName
                        ) {
                         if dKind == "left", let gid = UUID(uuidString: dKey) {
                             effects.removed.insert(gid)
                         }
                         // A friend's own rename or this user's nickname landed
                         // — either side of an App Group nickname-directory
                         // entry, so it's rebuilt after the batch saves.
                         if dKind == RecordSerializer.nameDecisionKind
                             || dKind == RecordSerializer.nicknameDecisionKind {
                             effects.friendNamesChanged = true
                         }
                     }
                 case "Journal":
                     // Journals are never applied to Core Data from the sync
                     // delegate — the replay loader (`fetchReplay`) pulls them on
                     // demand with a plain CKQuery. But the record landing is the
                     // signal a contributor finished and uploaded, so note the
                     // game to wake a waiting replay banner (posted below).
                     if let (gid, _, _) = RecordSerializer.parseJournalRecordName(
                         record.recordID.recordName
                     ) {
                         effects.journalsSynced.insert(gid)
                     }
                 case Archive.recordType:
                     // A finished shared game this user archived to their own
                     // private DB. Inert where the live original still exists;
                     // hydrated into a standalone completed game on a device that
                     // lacks it (fresh install / after the original was revoked).
                     if let id = self.applyArchiveRecord(record, in: ctx) {
                         effects.rosterRelevant.insert(id)
                     }
                 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) {
                     effects.rosterRelevant.insert(id)
                 }
             }
             for gameID in effects.movesUpdated {
                 effects.traces += 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 —
             // through the tracer, which is the only channel that reaches the
             // on-device diagnostics log this project debugs Production from.
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     let nsError = error as NSError
                     effects.traces.append(
                         "fetchedRecordZoneChanges ctx.save FAILED " +
                         "— domain=\(nsError.domain) code=\(nsError.code) " +
                         "\(nsError.localizedDescription)"
                     )
                 }
             }
             // Re-mirror the App Group key directory once the batch is saved, so
             // a just-adopted content key is available to the NSE immediately.
             if !effects.contentKeysChanged.isEmpty {
                 GameEntity.rebuildContentKeyDirectory(in: ctx)
             }
             return effects
         }
 
         for message in effects.traces {
             await trace(message)
         }
         if let onRemoteMovesUpdated, !effects.movesUpdated.isEmpty {
             await onRemoteMovesUpdated(effects.movesUpdated)
         }
         if let onRemotePlayersUpdated, !effects.playersUpdated.isEmpty {
             await onRemotePlayersUpdated(effects.playersUpdated)
         }
         if let onRemotePlayerPresenceChanged, !effects.playerPresenceChanged.isEmpty {
             await onRemotePlayerPresenceChanged(effects.playerPresenceChanged)
         }
         if let onRemoteEngagementChanged, !effects.engagementChanged.isEmpty {
             await onRemoteEngagementChanged(effects.engagementChanged)
         }
         if let onIncomingReadCursor, !effects.readCursors.isEmpty {
             await onIncomingReadCursor(effects.readCursors)
         }
         if let onPings, !effects.pings.isEmpty {
             await onPings(effects.pings)
         }
         if let onAccountPushAddress {
             for address in effects.accountPushAddresses {
                 await onAccountPushAddress(address)
             }
         }
         // The push secret converges across the account's own devices purely
         // through this inbound path (the account zone lives in the private DB,
         // which reliably syncs to every one of the account's devices). On a
         // simultaneous-mint race the loser adopts the winner's secret here on
         // the next fetch — no send-failure-recovery shortcut needed.
         if let onAccountPushSecret {
             for entry in effects.accountPushSecrets {
                 await onAccountPushSecret(entry.secret, entry.version)
             }
         }
         if let localAuthorID, !localAuthorID.isEmpty,
            let maxVersion = effects.selfNameVersions.max() {
             NameVersionStore.adopt(maxVersion, authorID: localAuthorID)
         }
         if effects.friendNamesChanged {
             let mirrorCtx = persistence.container.newBackgroundContext()
             mirrorCtx.performAndWait {
                 FriendEntity.rebuildNicknameDirectory(in: mirrorCtx)
             }
         }
         for id in effects.removed {
             if let cb = onGameRemoved { await cb(id) }
         }
         // A game just learned it's complete via sync: upload this device's
         // journal (no-op if it logged nothing) so replay can converge. The
         // enqueue defers its CKSyncEngine drain via `sendChangesDetached`, so
         // it never awaits sync from inside this delegate callback.
         if let localAuthorID, !localAuthorID.isEmpty {
             for id in effects.completedTransitions {
                 enqueueJournalUpload(gameID: id, authorID: localAuthorID)
             }
         }
         if let onGameCompleted {
             for id in effects.completedTransitions {
                 await onGameCompleted(id)
             }
         }
         let deletedPings = event.deletions.compactMap { deletion -> (recordName: String, gameID: UUID)? in
             let recordName = deletion.recordID.recordName
             guard recordName.hasPrefix("ping-"),
                   let gameID = gameID(fromRecordName: recordName)
             else { return nil }
             return (recordName, gameID)
         }
         if let onPingDeleted, !deletedPings.isEmpty {
             await onPingDeleted(deletedPings)
         }
         if !effects.rosterRelevant.isEmpty {
             NotificationCenter.default.post(
                 name: .playerRosterShouldRefresh,
                 object: nil,
                 userInfo: ["gameIDs": effects.rosterRelevant]
             )
         }
         if !effects.journalsSynced.isEmpty {
             NotificationCenter.default.post(
                 name: .replayJournalDidSync,
                 object: nil,
                 userInfo: ["gameIDs": effects.journalsSynced]
             )
         }
     }
 
 
     private nonisolated static func recordTypeSummary(_ counts: [String: Int]) -> String {
         counts
             .filter { $0.value > 0 }
             .sorted { lhs, rhs in
                 if lhs.key == rhs.key { return lhs.value > rhs.value }
                 return lhs.key < rhs.key
             }
             .map { "\($0.key)=\($0.value)" }
             .joined(separator: ", ")
     }
 
     private nonisolated static func inferredRecordType(for recordID: CKRecord.ID) -> String {
         let name = recordID.recordName
         if name.hasPrefix("moves-") { return "Moves" }
         if name.hasPrefix("journal-") { return "Journal" }
         if name.hasPrefix("player-") { return "Player" }
         if name.hasPrefix("game-") { return "Game" }
         if name.hasPrefix("ping-") { return "Ping" }
         if name.hasPrefix("decision-") { return "Decision" }
         return "Unknown"
     }
 
     private func handleSentRecordZoneChanges(
         _ event: CKSyncEngine.Event.SentRecordZoneChanges,
         isPrivate: Bool
     ) async {
         let savedTypes = Dictionary(
             grouping: event.savedRecords,
             by: \.recordType
         ).mapValues(\.count)
         let failedTypes = Dictionary(
             grouping: event.failedRecordSaves,
             by: { $0.record.recordType }
         ).mapValues(\.count)
         let deletedTypes = Dictionary(
             grouping: event.deletedRecordIDs,
             by: Self.inferredRecordType(for:)
         ).mapValues(\.count)
         let savedSummary = Self.recordTypeSummary(savedTypes)
         let failedSummary = Self.recordTypeSummary(failedTypes)
         let deletedSummary = Self.recordTypeSummary(deletedTypes)
 
         await trace(
             "\(isPrivate ? "private" : "shared") sent: " +
             "\(event.savedRecords.count) saved" +
             "\(savedSummary.isEmpty ? "" : " (\(savedSummary))"), " +
             "\(event.failedRecordSaves.count) failed" +
             "\(failedSummary.isEmpty ? "" : " (\(failedSummary))"), " +
             "\(event.deletedRecordIDs.count) deleted" +
             "\(deletedSummary.isEmpty ? "" : " (\(deletedSummary))")"
         )
         // Only bump on a clean batch: a round trip with per-record failures
         // is not "success" from the user's point of view, and the existing
         // SyncMonitor.recordError path owns reporting whatever did break.
         if event.failedRecordSaves.isEmpty {
             await noteRoundTripSuccess()
         }
         for record in event.savedRecords {
             let name = record.recordID.recordName
             if name.hasPrefix("ping-") {
                 pendingPings.removeValue(forKey: name)
             } else if name.hasPrefix("decision-") {
                 let stateKey = Self.decisionStateKey(record.recordID)
                 pendingDecisionPayloads.removeValue(forKey: stateKey)
                 persistPendingDecisionPayloads()
                 pendingDecisionVersions.removeValue(forKey: stateKey)
                 persistPendingDecisionVersions()
                 decisionSystemFields.removeValue(forKey: stateKey)
             }
         }
         // Snapshot the intended versions on-actor so the off-actor conflict
         // resolution can tell a deliberate, newer write from a stale one.
         let pendingVersionsSnapshot = pendingDecisionVersions
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let (failureMessages, orphanedZones, resolvedDecisions, settledJournals,
              resolvedAccountAddresses, resolvedAccountSecrets, decisionWins, recoveredSaves):
             ([String], Set<CKRecordZone.ID>, Set<CKRecord.ID>, Set<CKRecord.ID>,
              [String], [(secret: String, version: Int64)],
              [(recordID: CKRecord.ID, stateKey: String, systemFields: Data)],
              [CKRecord.ID]) = ctx.performAndWait {
             var messages: [String] = []
             var orphaned = Set<CKRecordZone.ID>()
             var settledDecisions = Set<CKRecord.ID>()
             var settledJournals = Set<CKRecord.ID>()
             var accountAddresses: [String] = []
             var accountSecrets: [(secret: String, version: Int64)] = []
             // Versioned decisions that lost the change-tag race but win on
             // version: (decision state key, server system fields to adopt for
             // the overwrite retry).
             var decisionWins: [(recordID: CKRecord.ID, stateKey: String, systemFields: Data)] = []
             // Game/Moves/Player saves that lost a change-tag race and had the
             // server's system fields written back: re-enqueued below. Like
             // decisions, a `serverRecordChanged` failure leaves nothing pending,
             // so without the re-add these heal only when unrelated activity
             // happens to re-enqueue the record — reliable enough for the
             // keystroke-cadence Moves/Player writes, but a Game record (share
             // metadata, completion) can strand on an idle game until its next
             // change.
             var recoveredSaves: [CKRecord.ID] = []
             for record in event.savedRecords {
                 self.writeBackSystemFields(record: record, in: ctx)
                 let savedName = record.recordID.recordName
                 if savedName.hasPrefix("game-") {
                     self.clearPendingSaveFlag(for: savedName, in: ctx)
                 } else if savedName.hasPrefix("journal-"),
                           let (gid, _, _) = RecordSerializer.parseJournalRecordName(savedName) {
                     // Confirmed durable upload of this device's journal — record
                     // it so the level-triggered backstop
                     // (`reconcilePendingJournalUploads`) stops re-enqueuing it.
                     self.markJournalUploaded(gameID: gid, in: ctx)
                 }
             }
             for failure in event.failedRecordSaves {
                 let name = failure.record.recordID.recordName
                 let err = failure.error as NSError
                 // A settled failure is one CloudKit rejected but we treat as
                 // success (the durable record already exists), so it skips the
                 // verbose "failed to save" log below — that line reads as an
                 // error and is pure noise next to the "settled" message.
                 var settled = false
                 if err.domain == CKErrorDomain,
                    err.code == CKError.zoneNotFound.rawValue {
                     orphaned.insert(failure.record.recordID.zoneID)
                 } else if !isPrivate,
                           self.isInvalidSharedZoneOwnerError(err) {
                     orphaned.insert(failure.record.recordID.zoneID)
                 } else if name.hasPrefix("decision-"),
                           err.domain == CKErrorDomain,
                           err.code == CKError.serverRecordChanged.rawValue {
                     let serverRecord = err.userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord
                     let stateKey = Self.decisionStateKey(failure.record.recordID)
                     let intended = pendingVersionsSnapshot[stateKey]
                     let serverVersion = serverRecord.map(RecordSerializer.decisionVersion)
                     if let intended, let serverRecord, let serverVersion,
                        intended > serverVersion,
                        let serverFields = RecordSerializer.encodeSystemFields(of: serverRecord) {
                         // A deliberate, newer write (e.g. a rotated push secret
                         // or a rename) that lost only the change-tag race. Adopt
                         // the server's tag so the next build overwrites instead
                         // of re-colliding, then re-enqueue the save below: a
                         // `serverRecordChanged` failure does NOT leave the change
                         // in CKSyncEngine's pending state (the original code
                         // assumed it did), so the retry must re-add it explicitly
                         // or the overwrite is silently dropped.
                         decisionWins.append((failure.record.recordID, stateKey, serverFields))
                         settled = true
                         messages.append(
                             "send: decision \(name) lost tag race but wins on version " +
                             "(\(intended) > \(serverVersion)) — overwriting"
                         )
                     } else {
                         // Write-once (block/left/pushAddress) or an equal/older
                         // version: the durable fact already on the server wins.
                         // Drop the pending change so the record doesn't
                         // retry-loop, and adopt the winner's payload straight off
                         // the conflict instead of waiting for a later fetch — for
                         // the push secret that closes the window in which this
                         // device would keep deriving divergent per-game addresses.
                         settledDecisions.insert(failure.record.recordID)
                         if let serverRecord {
                             if let address = RecordSerializer.parseAccountPushAddressDecision(serverRecord) {
                                 accountAddresses.append(address)
                             }
                             if let parsed = RecordSerializer.parseAccountPushSecretDecision(serverRecord) {
                                 accountSecrets.append(parsed)
                             }
                         }
                         settled = true
                         messages.append("send: decision \(name) already present — settled")
                     }
                 } else if name.hasPrefix("journal-"),
                           err.domain == CKErrorDomain,
                           err.code == CKError.serverRecordChanged.rawValue,
                           let (gid, _, _) = RecordSerializer.parseJournalRecordName(name) {
                     // Journals are write-once at completion: "record to insert
                     // already exists" means this device's journal is already
                     // durable server-side (a backstop re-enqueue, or a first
                     // upload on a build predating the `journalUploaded` flag).
                     // There is no system-fields archive to adopt for an update
                     // and the content is frozen, so the re-send is a no-op —
                     // settle it like a Decision: drop the pending change and
                     // mark the game uploaded so `reconcilePendingJournalUploads`
                     // stops re-enqueuing it. Without this the save fails every
                     // sweep and `Pending Changes` never drains.
                     settledJournals.insert(failure.record.recordID)
                     self.markJournalUploaded(gameID: gid, in: ctx)
                     settled = true
                     messages.append("send: journal \(name) already present — settled")
                 } else if self.recoverServerChangedSave(failure.error, failedRecordName: name, in: ctx) {
                     recoveredSaves.append(failure.record.recordID)
                     messages.append(
                         "send: recovered stale system fields for \(name) from CloudKit server record"
                     )
                 }
                 guard !settled else { continue }
                 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, settledDecisions, settledJournals,
                     accountAddresses, accountSecrets, decisionWins, recoveredSaves)
         }
         if !orphanedZones.isEmpty {
             await applyZoneOrphaning(orphanedZones, isPrivate: isPrivate)
         }
         // Settle/retry against the engine this sent-event belongs to: account-
         // zone decisions ride the private engine, but a name Decision in a
         // joined friend zone rides the shared one.
         let decisionEngine = isPrivate ? privateEngine : sharedEngine
         if !resolvedDecisions.isEmpty, let decisionEngine {
             decisionEngine.state.remove(
                 pendingRecordZoneChanges: resolvedDecisions.map { .saveRecord($0) }
             )
             for recordID in resolvedDecisions {
                 let stateKey = Self.decisionStateKey(recordID)
                 pendingDecisionPayloads.removeValue(forKey: stateKey)
                 pendingDecisionVersions.removeValue(forKey: stateKey)
                 decisionSystemFields.removeValue(forKey: stateKey)
             }
             persistPendingDecisionPayloads()
             persistPendingDecisionVersions()
         }
         // Adopt the server's tag for each versioned decision we're overwriting,
         // re-enqueue the save (the failed change is no longer pending), then
         // nudge the send loop so the retry (now carrying the tag) goes out
         // promptly rather than on CKSyncEngine's own cadence.
         if !decisionWins.isEmpty, let decisionEngine {
             for win in decisionWins {
                 decisionSystemFields[win.stateKey] = win.systemFields
                 decisionEngine.state.add(
                     pendingRecordZoneChanges: [.saveRecord(win.recordID)]
                 )
             }
             sendChangesDetached(on: decisionEngine)
         }
         // Re-enqueue Game/Moves/Player saves whose stale system fields we just
         // healed: a `serverRecordChanged` failure leaves nothing pending (see
         // `decisionWins`), so the now-current record must be re-added or the
         // local change waits for the next unrelated enqueue. The engine for
         // this sent-event is the same one decisions ride.
         if !recoveredSaves.isEmpty, let engine = isPrivate ? privateEngine : sharedEngine {
             engine.state.add(
                 pendingRecordZoneChanges: recoveredSaves.map { .saveRecord($0) }
             )
             sendChangesDetached(on: engine)
         }
         if let onAccountPushAddress {
             for address in resolvedAccountAddresses {
                 await onAccountPushAddress(address)
             }
         }
         if let onAccountPushSecret {
             for entry in resolvedAccountSecrets {
                 await onAccountPushSecret(entry.secret, entry.version)
             }
         }
         if !settledJournals.isEmpty {
             // Drop from whichever engine owns the zone (private for solo games,
             // shared for collaborations) — unlike decisions, journals ride both.
             let engine = isPrivate ? privateEngine : sharedEngine
             engine?.state.remove(
                 pendingRecordZoneChanges: settledJournals.map { .saveRecord($0) }
             )
         }
         for message in failureMessages {
             await trace(message)
         }
     }
 
     nonisolated func isInvalidSharedZoneOwnerError(_ error: NSError) -> Bool {
         let values = [error.localizedDescription] + error.userInfo.map { "\($0.value)" }
         return values.contains {
             $0.localizedCaseInsensitiveContains("Cannot convert userId to dsId") ||
             $0.localizedCaseInsensitiveContains("invalid userId")
         }
     }
 
     /// 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, failureMessages): ([UUID], [UUID], [String]) = ctx.performAndWait {
             var removed: [UUID] = []
             var revoked: [UUID] = []
             var messages: [String] = []
             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
                     messages.append(
                         "orphan-zone ctx.save FAILED — domain=\(nsError.domain) " +
                         "code=\(nsError.code) \(nsError.localizedDescription)"
                     )
                 }
             }
             return (removed, revoked, messages)
         }
 
         for message in failureMessages {
             await trace(message)
         }
         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")
         }
     }
 
     /// Clears the `hasPendingSave` guard on `GameEntity` after a successful
     /// push so future inbound fetches resume adopting server fields. Called
     /// from `handleSentRecordZoneChanges` only on confirmed saves — *not* from
     /// the oplock-recovery path, which only adopts a fresh etag for retry.
     /// Also clears `hasPushPending`, the one-shot flag that forces the next
     /// push to re-include the `puzzleSource` asset (used by the NYT re-upgrade
     /// path to replace an already-uploaded puzzle).
     private nonisolated func clearPendingSaveFlag(
         for recordName: String,
         in ctx: NSManagedObjectContext
     ) {
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         req.fetchLimit = 1
         guard let entity = try? ctx.fetch(req).first else { return }
         entity.hasPendingSave = false
         entity.hasPushPending = false
     }
 
     private nonisolated func markJournalUploaded(
         gameID: UUID,
         in ctx: NSManagedObjectContext
     ) {
         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 }
         entity.journalUploaded = true
     }
 
     // MARK: - Logging helpers
 
     private nonisolated func trace(_ message: String) {
         print("SyncEngine: \(message)")
     }
 
 }
 
 // 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? {
         await makeRecordZoneChangeBatch(for: syncEngine)
     }
 
     /// Builds the next outbound batch for `engine`, reaping any pending
     /// `.saveRecord` whose record can no longer be reconstructed. For a ping
     /// that means its ephemeral `pendingPings` payload was lost across a
     /// relaunch (CKSyncEngine persists pending changes; the ping body is
     /// in-memory only); for game/moves/player it means the Core Data entity
     /// was deleted. Either way the save can never succeed, so the change is
     /// dropped instead of returning a nil batch that leaves it queued forever
     /// — `Pending Changes` would never drain and no error is ever surfaced.
     /// Mirrors Apple's CKSyncEngine reference implementation, which reaps
     /// un-buildable changes inside the record provider. Internal-rather-than-
     /// private so the test suite can drive it directly; the delegate entry
     /// point can't be exercised because `CKSyncEngine.SendChangesContext` has
     /// no public initializer.
     func makeRecordZoneChangeBatch(
         for engine: CKSyncEngine
     ) async -> CKSyncEngine.RecordZoneChangeBatch? {
         let pending = engine.state.pendingRecordZoneChanges
         guard !pending.isEmpty else { return nil }
         await traceForeignPlayerWrites(in: pending)
         let pingSnapshot = pendingPings
         let decisionSnapshot = pendingDecisionPayloads
         let decisionVersionSnapshot = pendingDecisionVersions
         let decisionSystemFieldsSnapshot = decisionSystemFields
         return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { [weak self] recordID in
             guard let self else { return nil }
             if let record = self.buildRecord(
                 for: recordID,
                 pings: pingSnapshot,
                 decisions: decisionSnapshot,
                 decisionVersions: decisionVersionSnapshot,
                 decisionSystemFields: decisionSystemFieldsSnapshot
             ) {
                 return record
             }
             engine.state.remove(pendingRecordZoneChanges: [.saveRecord(recordID)])
             return nil
         }
     }
 
     /// Diagnostic for the recurring "ghost peer": flags any *peer's* Player
     /// slot in our outbound batch. A participant must only ever write its own
     /// `(game, authorID)` record — `enqueuePlayer` is keyed to the local
     /// author. A foreign authorID here means this device is about to upload
     /// someone else's presence, which `RecordBuilder` stamps with our own
     /// game-wide `lastReadOtherMoveAt` (`RecordBuilder.swift:131`). If that
     /// horizon is a live read lease, the peer is resurrected as present with
     /// our future `readAt`. We log the value the build will send so a future
     /// lease (the ghost) is distinguishable from a current-time close, and so
     /// the next recurrence names the culprit in one line rather than leaving it
     /// to inference. Silent in the normal case (own slot only), so it adds no
     /// noise until the bug actually fires.
     private func traceForeignPlayerWrites(
         in pending: [CKSyncEngine.PendingRecordZoneChange]
     ) async {
         guard let localAuthorID = await currentLocalAuthorID() else { return }
         var foreign: [(UUID, String)] = []
         for change in pending {
             guard case .saveRecord(let recordID) = change,
                   let (gameID, authorID) =
                     RecordSerializer.parsePlayerRecordName(recordID.recordName),
                   authorID != localAuthorID
             else { continue }
             foreign.append((gameID, authorID))
         }
         guard !foreign.isEmpty else { return }
         let ctx = persistence.container.newBackgroundContext()
         for (gameID, authorID) in foreign {
             let readAt: Date? = ctx.performAndWait {
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
                 req.fetchLimit = 1
                 return (try? ctx.fetch(req).first)?.lastReadOtherMoveAt
             }
             let leaseDesc: String
             if let readAt {
                 let delta = Int(readAt.timeIntervalSinceNow)
                 leaseDesc = "readAt=\(readAt.ISO8601Format()) " +
                     (delta > 0 ? "(future +\(delta)s)" : "(past \(-delta)s)")
             } else {
                 leaseDesc = "readAt=nil"
             }
             await trace(
                 "‼️ OUTBOUND peer Player[\(gameID.uuidString.prefix(8))] " +
                 "author=\(authorID.prefix(8)) local=\(localAuthorID.prefix(8)) " +
                 "\(leaseDesc) — uploading a peer's slot"
             )
         }
     }
 
     /// Test seam: drives `makeRecordZoneChangeBatch` for the given scope's
     /// engine. Mirrors `pendingSaveRecordNames(scope:)`'s scope routing.
     func makeRecordZoneChangeBatch(
         forTestingScope scope: CKDatabase.Scope
     ) async -> CKSyncEngine.RecordZoneChangeBatch? {
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return nil }
         return await makeRecordZoneChangeBatch(for: engine)
     }
 }