crossmate

SyncEngine.swift (137980B)

---

 import CloudKit
 import CoreData
 import Foundation
 import SwiftUI
 
 enum CompletionDurableRecordKind: String, Codable, Hashable, Sendable {
     case game
     case moves
     case journal
 }
 
 enum PingDeliveryState: Sendable {
     case queued
     case sent
     case failed
 }
 
 enum InviteDeliveryFailure: Equatable, Sendable {
     case quotaExceeded
     case other
 
     var title: LocalizedStringResource {
         "Invitation Not Sent"
     }
 
     var body: LocalizedStringResource {
         switch self {
         case .quotaExceeded:
             "The invitation was not received. This could be because your friend's iCloud storage is full."
         case .other:
             "The invitation could not be delivered. Try again."
         }
     }
 
     init(error: Error) {
         if let pingError = error as? SyncEngine.PingOutboxError,
            pingError.isQuotaExceeded {
             self = .quotaExceeded
         } else {
             self = .other
         }
     }
 }
 
 struct PingDeliveryUpdate: Sendable {
     let recordName: String
     let gameID: UUID
     let addressee: String
     let state: PingDeliveryState
     let rollbackParticipantOnFailure: Bool
     let failure: InviteDeliveryFailure?
 }
 
 extension EnvironmentValues {
     @Entry var syncEngine: SyncEngine? = 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")
 
     /// The private Chronicle zone changed. Its assets are deliberately excluded
     /// from CKSyncEngine and the Game List performs a bounded metadata query.
     static let chronicleZoneDidChange = Notification.Name("chronicleZoneDidChange")
 }
 
 
 /// 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 {
     enum PingOutboxError: Error, Equatable, LocalizedError {
         case syncEngineUnavailable
         case deliveryFailed(code: Int?)
         /// CloudKit did not confirm or reject the send within the caller's
         /// patience window. The Ping stays durably queued and its CKShare seat
         /// intact; this only unblocks the caller so the UI stops waiting.
         case deliveryPending
 
         var errorDescription: String? {
             switch self {
             case .syncEngineUnavailable:
                 return String(localized: "The invitation could not be queued for syncing.")
             case .deliveryFailed(let code)
                 where code == CKError.quotaExceeded.rawValue:
                 return String(localized: InviteDeliveryFailure.quotaExceeded.body)
             case .deliveryFailed:
                 return String(localized: InviteDeliveryFailure.other.body)
             case .deliveryPending:
                 return String(localized: "The invitation is queued and will keep trying.")
             }
         }
 
         var isQuotaExceeded: Bool {
             if case .deliveryFailed(let code) = self {
                 return code == CKError.quotaExceeded.rawValue
             }
             return false
         }
     }
 
     let container: CKContainer
     let persistence: PersistenceController
 
     var privateEngine: CKSyncEngine?
     var sharedEngine: CKSyncEngine?
 
     /// Dedicated serial context for the singleton `SyncStateEntity` row. Both
     /// scopes' engine state persists through this one context: `await
     /// ctx.perform` does not hold the actor the way `performAndWait` did, so
     /// per-call fresh contexts could otherwise race each other — two
     /// concurrent saves could each fetch-or-create the row (duplicating it on
     /// first launch) or fail on a row-level conflict. Automatic merging keeps
     /// the long-lived context coherent if the row is deleted externally (the
     /// database reset path).
     private lazy var syncStateContext: NSManagedObjectContext = {
         let ctx = persistence.container.newBackgroundContext()
         ctx.automaticallyMergesChangesFromParent = true
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         return ctx
     }()
 
     /// True while `start()` is between its idempotence guard and the engine
     /// assignments. The body suspends (engine-state read, state decode), so
     /// the `privateEngine == nil` guard alone no longer makes a concurrent
     /// second call a no-op.
     private var isStarting = false
 
     /// In-memory mirror of the durable PendingPingEntity outbox, keyed by
     /// record name. CKSyncEngine persists the pending record ID but not the
     /// body supplied by its record provider, so the outbox is what makes a
     /// queued invite reconstructable after process termination.
     private var pendingPings: [String: PingPayload] = [:]
     private var pingDeliveryWaiters: [
         String: CheckedContinuation<Void, Error>
     ] = [:]
     private var pingDeliveryTimeouts: [String: Task<Void, Never>] = [:]
     private var scheduledPingRetries: Set<String> = []
 
     /// How long a `waitForServerConfirmation` send blocks before it stops
     /// waiting and reports `.deliveryPending`. This is a UI-patience limit, not
     /// a delivery deadline: the Ping remains queued and the durable outbox keeps
     /// retrying, so a slow network no longer strands the caller on a spinner.
     private var pingConfirmationTimeout: Duration = .seconds(30)
 
     private lazy var pendingPingContext: NSManagedObjectContext = {
         let ctx = persistence.container.newBackgroundContext()
         ctx.automaticallyMergesChangesFromParent = true
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         return ctx
     }()
     /// 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, display name and block flag are versioned; unversioned decisions
     /// (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: Codable {
         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?
         let zoneName: String
         let zoneOwnerName: String
         let databaseScope: DatabaseScope
         /// Present only on game invitations whose CKShare seat was created by
         /// this Ping. Optional so durable outbox rows written by older builds
         /// continue to decode.
         let rollbackParticipantOnFailure: Bool?
 
         var recordZoneID: CKRecordZone.ID {
             CKRecordZone.ID(zoneName: zoneName, ownerName: zoneOwnerName)
         }
     }
 
     /// 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?
     /// Game zones whose root metadata says they completed before the initial
     /// seven-day Game List window. CKSyncEngine must not eagerly hydrate these;
     /// the metadata pager or the separate migration path fetches them directly.
     private var privateCompletedFetchExclusions: Set<CKRecordZone.ID>?
     private var sharedCompletedFetchExclusions: Set<CKRecordZone.ID>?
     /// 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)?
     /// Fires with the game IDs whose zone-wide share just lost a previously
     /// accepted participant. The handler rotates the game's push credentials
     /// so the departed device's cached copy stops granting push access.
     var onPushCredentialRotationNeeded: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     /// Fires with the game IDs whose inbound Game record changed the push
     /// credential blob (a peer minted — or rotated — it). The handler re-runs
     /// push registration so this device binds under the new credID promptly
     /// and drops its old binding, instead of waiting for the next launch or
     /// token refresh.
     var onRemoteCredentialsChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
     var onPings: (@MainActor @Sendable ([Ping]) async -> Void)?
     private var onPingDeliveryUpdate: (@MainActor @Sendable (PingDeliveryUpdate) -> 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 when late contributor journals land so provisional Chronicles can
     /// be rebuilt without waiting for the next cold-launch reconciliation.
     private var onReplayJournalsSynced:
         (@MainActor @Sendable (Set<UUID>) async -> Void)?
     private var onCompletionRecordsSaved: (@MainActor @Sendable ([UUID: Set<CompletionDurableRecordKind>]) 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, presenceUntil) 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, Date?)]) async -> Void)?
     var onAccountPushAddress: (@MainActor @Sendable (String) async -> Void)?
     var onAccountPushSecret: (@MainActor @Sendable (String, Int64) async -> Void)?
     var onBlockedFriendsChanged: (@MainActor @Sendable (Set<String>) async -> Void)?
     var onGameVisibilityCandidates: (@MainActor @Sendable (Set<UUID>) 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).
     var pingPushCheckpoints: [DatabaseScope: 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: [DatabaseScope: [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 setOnPushCredentialRotationNeeded(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onPushCredentialRotationNeeded = cb
     }
 
     func setOnRemoteCredentialsChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onRemoteCredentialsChanged = cb
     }
 
     func setOnPings(_ cb: @MainActor @Sendable @escaping ([Ping]) async -> Void) {
         onPings = cb
     }
 
     func setOnPingDeliveryUpdate(
         _ cb: @MainActor @Sendable @escaping (PingDeliveryUpdate) -> Void
     ) {
         onPingDeliveryUpdate = 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 setOnReplayJournalsSynced(
         _ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void
     ) {
         onReplayJournalsSynced = cb
     }
 
     func setOnCompletionRecordsSaved(
         _ cb: @MainActor @Sendable @escaping ([UUID: Set<CompletionDurableRecordKind>]) async -> Void
     ) {
         onCompletionRecordsSaved = 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, Date?)]) 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 setOnBlockedFriendsChanged(_ cb: @MainActor @Sendable @escaping (Set<String>) async -> Void) {
         onBlockedFriendsChanged = cb
     }
 
     func setOnGameVisibilityCandidates(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
         onGameVisibilityCandidates = cb
     }
 
     func setLocalAuthorIDProvider(_ cb: @MainActor @Sendable @escaping () -> String?) {
         localAuthorIDProvider = cb
     }
 
     init(container: CKContainer, persistence: PersistenceController) {
         self.container = container
         self.persistence = persistence
     }
 
     // MARK: - Lifecycle
 
     /// 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, !isStarting else { return }
         isStarting = true
         defer { isStarting = false }
 
         // CKSyncEngine restores its pending `.saveRecord` changes from the
         // serialized state below; restore the matching Ping/Decision payloads
         // so pending records rebuild with their bodies.
         await restorePendingPings()
         restorePendingDecisionPayloads()
         restorePendingDecisionVersions()
 
         let ctx = syncStateContext
         let (privateData, sharedData): (Data?, Data?) = await ctx.perform {
             let entity = SyncStateEntity.current(in: ctx)
             return (entity.ckPrivateEngineState, entity.ckSharedEngineState)
         }
 
         let privateState = await decodeEngineState(privateData, label: "private")
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: privateState,
             delegate: self
         ))
 
         let sharedState = await decodeEngineState(sharedData, label: "shared")
         sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.sharedCloudDatabase,
             stateSerialization: sharedState,
             delegate: self
         ))
 
         // The outbox is authoritative. A process can terminate after its row
         // commits but before CKSyncEngine serializes the matching pending ID,
         // so re-add every durable Ping on startup. Record IDs are stable and
         // CKSyncEngine deduplicates repeated pending saves.
         reconcilePendingPingOutbox()
     }
 
     /// 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. Keep one detached
     /// send in flight per scope so repeated enqueues for the same record
     /// coalesce instead of racing separate drains against adjacent etags.
     private func sendChangesDetached(on engine: CKSyncEngine) {
         let scope = scope(for: engine)
         if sendChangesInFlight.contains(scope) {
             sendChangesPending.insert(scope)
             return
         }
         sendChangesInFlight.insert(scope)
         Task.detached { [engine] in
             try? await engine.sendChanges()
             await self.finishDetachedSendChanges(for: scope)
         }
     }
 
     /// The database an engine is bound to. Read off the engine itself rather
     /// than compared against `privateEngine`/`sharedEngine`: `resetSyncState`
     /// (and the account-switch / v4-migration purges that call it) replaces
     /// both instances while their fetches are still in flight, and a retired
     /// engine matches neither property. Identity comparison then misreports
     /// the retired engine's scope — for `handleEvent` it silently resolved
     /// *private* events to shared, which minted "Joining…" placeholders for
     /// the user's own zones, cross-wrote engine state between scopes, and
     /// applied private zone deletions as share revocations. The binding is
     /// immutable for an engine's lifetime, so it stays correct after a swap.
     private nonisolated func scope(for engine: CKSyncEngine) -> DatabaseScope {
         DatabaseScope(isPrivate: engine.database.databaseScope == .private)
     }
 
     private func finishDetachedSendChanges(for scope: DatabaseScope) {
         sendChangesInFlight.remove(scope)
         guard sendChangesPending.remove(scope) != nil else { return }
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return }
         sendChangesDetached(on: engine)
     }
 
     /// 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: [DatabaseScope: Int] = [:]
     private var playerSendBurstPending: Set<DatabaseScope> = []
     private var sendChangesInFlight: Set<DatabaseScope> = []
     private var sendChangesPending: Set<DatabaseScope> = []
 
     /// 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) -> DatabaseScope? {
         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: DatabaseScope) {
         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 == .shared ? 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]) = await ctx.perform {
             var privateIDs: [CKRecord.ID] = []
             var sharedIDs: [CKRecord.ID] = []
             for gameID in gameIDs {
                 guard let info = self.zoneInfo(forGameID: gameID, in: ctx) else { continue }
                 let isShared = info.scope == .shared
                 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> = await ctx.perform {
             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) {
         if deletion.deletesLiveZone {
             let zoneID = CKRecordZone.ID(
                 zoneName: deletion.ckZoneName,
                 ownerName: deletion.ckZoneOwnerName
             )
             let engine = deletion.databaseScope == .shared ? sharedEngine : privateEngine
             if let engine {
                 engine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
                 sendChangesDetached(on: engine)
             }
         }
 
         guard let privateEngine else { return }
         if let archiveRecordName = deletion.archiveRecordName {
             let recordID = CKRecord.ID(
                 recordName: archiveRecordName,
                 zoneID: Archive.zoneID
             )
             privateEngine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
         }
         if let legacyZoneName = deletion.legacyArchiveZoneName {
             let legacyZoneID = CKRecordZone.ID(
                 zoneName: legacyZoneName,
                 ownerName: CKCurrentUserDefaultName
             )
             privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(legacyZoneID)])
         }
         sendChangesDetached(on: privateEngine)
     }
 
     /// Retires an owned completed game's live zone after its archive policy has
     /// been satisfied. Unlike user deletion, this deliberately leaves the
     /// account's Archive record intact.
     func enqueueRetireOwnedGameZone(_ zoneID: CKRecordZone.ID) {
         guard let privateEngine else { return }
         privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
         sendChangesDetached(on: privateEngine)
     }
 
     /// Removes a migrated legacy per-game archive zone after the compact record
     /// has saved in the common archive zone.
     func enqueueDeleteLegacyArchiveZone(_ zoneID: CKRecordZone.ID) {
         guard let privateEngine else { return }
         privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
         sendChangesDetached(on: privateEngine)
     }
 
     private func storePendingPing(
         _ ping: PingPayload,
         recordName: String
     ) async throws {
         let data = try JSONEncoder().encode(ping)
         let ctx = pendingPingContext
         try await ctx.perform {
             let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
             req.predicate = NSPredicate(format: "recordName == %@", recordName)
             req.fetchLimit = 1
             let entity = try ctx.fetch(req).first ?? PendingPingEntity(context: ctx)
             entity.recordName = recordName
             entity.zoneName = ping.zoneName
             entity.zoneOwnerName = ping.zoneOwnerName
             entity.databaseScope = ping.databaseScope.rawValue
             entity.payloadData = data
             try ctx.save()
         }
         pendingPings[recordName] = ping
         await publishPingDeliveryUpdate(.queued, recordName: recordName, ping: ping)
     }
 
     private func removePendingPing(recordName: String) async {
         pendingPings.removeValue(forKey: recordName)
         let ctx = pendingPingContext
         await ctx.perform {
             let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
             req.predicate = NSPredicate(format: "recordName == %@", recordName)
             for entity in (try? ctx.fetch(req)) ?? [] {
                 ctx.delete(entity)
             }
             if ctx.hasChanges { try? ctx.save() }
         }
     }
 
     private func confirmPendingPing(recordName: String) async {
         scheduledPingRetries.remove(recordName)
         if let ping = pendingPings[recordName] {
             await publishPingDeliveryUpdate(.sent, recordName: recordName, ping: ping)
         }
         await removePendingPing(recordName: recordName)
         clearPingDeliveryTimeout(recordName: recordName)
         pingDeliveryWaiters.removeValue(forKey: recordName)?.resume()
     }
 
     private func failPendingPing(recordName: String, error: NSError? = nil) async {
         scheduledPingRetries.remove(recordName)
         if let ping = pendingPings[recordName] {
             let failure: InviteDeliveryFailure = error?.code
                 == CKError.quotaExceeded.rawValue ? .quotaExceeded : .other
             await publishPingDeliveryUpdate(
                 .failed,
                 recordName: recordName,
                 ping: ping,
                 failure: failure
             )
         }
         await removePendingPing(recordName: recordName)
         clearPingDeliveryTimeout(recordName: recordName)
         pingDeliveryWaiters.removeValue(forKey: recordName)?
             .resume(throwing: PingOutboxError.deliveryFailed(code: error?.code))
     }
 
     private func waitForPingDelivery(recordName: String) async throws {
         try await withTaskCancellationHandler {
             try await withCheckedThrowingContinuation { continuation in
                 pingDeliveryWaiters[recordName] = continuation
                 armPingDeliveryTimeout(recordName: recordName)
             }
         } onCancel: {
             Task { await self.cancelPingDeliveryWait(recordName: recordName) }
         }
     }
 
     private func cancelPingDeliveryWait(recordName: String) {
         clearPingDeliveryTimeout(recordName: recordName)
         pingDeliveryWaiters.removeValue(forKey: recordName)?
             .resume(throwing: CancellationError())
     }
 
     /// Bounds a `waitForServerConfirmation` send so it never blocks forever.
     /// On expiry the Ping is left queued (the durable outbox keeps retrying and
     /// `confirmPendingPing`/`failPendingPing` still resolves its true outcome
     /// later); only the caller's wait ends, with `.deliveryPending`.
     private func armPingDeliveryTimeout(recordName: String) {
         pingDeliveryTimeouts[recordName]?.cancel()
         pingDeliveryTimeouts[recordName] = Task { [self] in
             try? await Task.sleep(for: pingConfirmationTimeout)
             guard !Task.isCancelled else { return }
             timeoutPingDeliveryWait(recordName: recordName)
         }
     }
 
     private func clearPingDeliveryTimeout(recordName: String) {
         pingDeliveryTimeouts.removeValue(forKey: recordName)?.cancel()
     }
 
     private func timeoutPingDeliveryWait(recordName: String) {
         pingDeliveryTimeouts.removeValue(forKey: recordName)
         pingDeliveryWaiters.removeValue(forKey: recordName)?
             .resume(throwing: PingOutboxError.deliveryPending)
     }
 
     private func restorePendingPings() async {
         let ctx = pendingPingContext
         pendingPings = await ctx.perform {
             let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
             let rows = (try? ctx.fetch(req)) ?? []
             var restored: [String: PingPayload] = [:]
             for row in rows {
                 guard let name = row.recordName,
                       let data = row.payloadData,
                       let ping = try? JSONDecoder().decode(PingPayload.self, from: data)
                 else {
                     ctx.delete(row)
                     continue
                 }
                 restored[name] = ping
             }
             if ctx.hasChanges { try? ctx.save() }
             return restored
         }
         for (recordName, ping) in pendingPings {
             await publishPingDeliveryUpdate(.queued, recordName: recordName, ping: ping)
         }
     }
 
     private func publishPingDeliveryUpdate(
         _ state: PingDeliveryState,
         recordName: String,
         ping: PingPayload,
         failure: InviteDeliveryFailure? = nil
     ) async {
         guard ping.kind == .invite,
               let addressee = ping.addressee,
               !addressee.isEmpty,
               let onPingDeliveryUpdate
         else { return }
         await onPingDeliveryUpdate(PingDeliveryUpdate(
             recordName: recordName,
             gameID: ping.gameID,
             addressee: addressee,
             state: state,
             rollbackParticipantOnFailure: ping.rollbackParticipantOnFailure == true,
             failure: failure
         ))
     }
 
     private func reconcilePendingPingOutbox() {
         for (recordName, ping) in pendingPings {
             let engine = ping.databaseScope == .shared ? sharedEngine : privateEngine
             let recordID = CKRecord.ID(recordName: recordName, zoneID: ping.recordZoneID)
             engine?.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         }
     }
 
     func pendingInvitationPingCount() -> Int {
         pendingPings.values.count { $0.kind == PingKind.invite }
     }
 
     /// Registers a Ping record as a pending send. Current clients only write
     /// bootstrap kinds (`.friend` / `.invite` / `.decline`) — the
     /// user-facing play events go through the push worker. Sender-only
     /// state: the payload is committed to a durable outbox before the
     /// CKSyncEngine save is queued, then retained until CloudKit confirms it.
     @discardableResult
     func enqueuePing(
         kind: PingKind,
         gameID: UUID,
         authorID: String,
         playerName: String,
         payload: String? = nil,
         addressee: String? = nil
     ) async -> Bool {
         let ctx = persistence.container.newBackgroundContext()
         let zoneAndTitle: (info: ZoneInfo, title: String)? = await ctx.perform {
             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 {
             await trace(
                 "ping send: SKIPPED kind=\(kind.rawValue) " +
                 "game=\(gameID.uuidString) " +
                 "— no zone info (game not yet synced/shared on this device)"
             )
             return false
         }
         let engine = zoneAndTitle.info.scope == .shared ? sharedEngine : privateEngine
         guard let engine else {
             await trace(
                 "ping send: SKIPPED kind=\(kind.rawValue) " +
                 "game=\(gameID.uuidString) " +
                 "— no CKSyncEngine for " +
                 "\(zoneAndTitle.info.scope == .shared ? "shared" : "private") scope"
             )
             return false
         }
         let deviceID = RecordSerializer.localDeviceID
         let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
         let recordName = RecordSerializer.recordName(
             forPingInGame: gameID,
             authorID: authorID,
             deviceID: deviceID,
             eventTimestampMs: eventTimestampMs
         )
         let ping = PingPayload(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             playerName: playerName,
             puzzleTitle: zoneAndTitle.title,
             eventTimestampMs: eventTimestampMs,
             kind: kind,
             payload: payload,
             addressee: addressee,
             zoneName: zoneAndTitle.info.zoneID.zoneName,
             zoneOwnerName: zoneAndTitle.info.zoneID.ownerName,
             databaseScope: zoneAndTitle.info.scope,
             rollbackParticipantOnFailure: nil
         )
         do {
             try await storePendingPing(ping, recordName: recordName)
         } catch {
             await trace("ping send: failed to persist outbox record \(recordName) — \(error)")
             return false
         }
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneAndTitle.info.zoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         await trace(
             "ping send: enqueued kind=\(kind.rawValue) " +
             "game=\(gameID.uuidString) " +
             "target=\(zoneAndTitle.info.scope == .shared ? "shared" : "private") " +
             "zone=\(zoneAndTitle.info.zoneID.zoneName) record=\(recordName)"
         )
         sendChangesDetached(on: engine)
         return true
     }
 
 
     /// 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:
     /// `.shared` means we joined the friend zone (it lives in our shared DB
     /// → shared engine); `.private` 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: DatabaseScope,
         payload: String? = nil,
         rollbackParticipantOnFailure: Bool = false,
         waitForServerConfirmation: Bool = false
     ) async throws {
         let engine = friendZoneScope == .shared ? sharedEngine : privateEngine
         guard let engine else {
             throw PingOutboxError.syncEngineUnavailable
         }
         let deviceID = RecordSerializer.localDeviceID
         let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
         let recordName = RecordSerializer.recordName(
             forPingInGame: gameID,
             authorID: authorID,
             deviceID: deviceID,
             eventTimestampMs: eventTimestampMs
         )
         let ping = PingPayload(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             playerName: playerName,
             puzzleTitle: gameTitle,
             eventTimestampMs: eventTimestampMs,
             kind: kind,
             payload: payload,
             addressee: addressee,
             zoneName: friendZoneID.zoneName,
             zoneOwnerName: friendZoneID.ownerName,
             databaseScope: friendZoneScope,
             rollbackParticipantOnFailure: rollbackParticipantOnFailure
         )
         try await storePendingPing(ping, recordName: recordName)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: friendZoneID)
         engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
         sendChangesDetached(on: engine)
         if waitForServerConfirmation {
             try await waitForPingDelivery(recordName: recordName)
         }
     }
 
     /// 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`: `.shared` means we joined the
     /// zone (shared engine), `.private` means we own it (private engine).
     /// The zone already exists by the time a friendship is recorded, so no
     /// `saveZone`.
     /// Returns whether the decision was actually enqueued. It is dropped when
     /// the target engine isn't up yet; callers that gate on a "published"
     /// marker must not record success on a drop, or the write never re-heals.
     @discardableResult
     func enqueueFriendDecision(
         kind: String,
         key: String,
         payload: String? = nil,
         version: Int64? = nil,
         friendZoneID: CKRecordZone.ID,
         friendZoneScope: DatabaseScope
     ) -> Bool {
         guard let engine = friendZoneScope == .shared ? sharedEngine : privateEngine else { return false }
         registerDecisionSave(
             kind: kind, key: key, payload: payload, version: version,
             zoneID: friendZoneID, engine: engine
         )
         return true
     }
 
     /// 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: DatabaseScope
     ) {
         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) async {
         let ctx = persistence.container.newBackgroundContext()
         guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
         let engine = info.scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return }
         await failPendingPing(recordName: 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: DatabaseScope) async {
         let engine = databaseScope == .shared ? sharedEngine : privateEngine
         guard let engine else { return }
         await failPendingPing(recordName: 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 == .shared ? 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 == .shared ? 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 == .shared ? 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: DatabaseScope
         switch scope {
         case .private:
             engine = privateEngine
             scopeValue = .private
         case .shared:
             engine = sharedEngine
             scopeValue = .shared
         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 = syncStateContext
         let failureMessage: String? = await ctx.perform {
             let entity = SyncStateEntity.current(in: ctx)
             entity.ckPrivateEngineState = nil
             entity.ckSharedEngineState = nil
             do {
                 try ctx.save()
                 return nil
             } catch {
                 return "resetSyncState ctx.save failed — \(error)"
             }
         }
         if let failureMessage { await trace(failureMessage) }
         privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.privateCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
             database: container.sharedCloudDatabase,
             stateSerialization: nil,
             delegate: self
         ))
         reconcilePendingPingOutbox()
         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
     ) async {
         let ctx = syncStateContext
         let failureMessage: String? = await ctx.perform {
             guard let data = try? JSONEncoder().encode(serialization) else {
                 return "saveEngineState encode failed — engine state not persisted"
             }
             let entity = SyncStateEntity.current(in: ctx)
             if isPrivate {
                 entity.ckPrivateEngineState = data
             } else {
                 entity.ckSharedEngineState = data
             }
             do {
                 try ctx.save()
                 return nil
             } catch {
                 return "saveEngineState ctx.save failed — \(error)"
             }
         }
         if let failureMessage { await trace(failureMessage) }
     }
 
     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()
         if isPrivate {
             privateCompletedFetchExclusions = nil
         } else {
             sharedCompletedFetchExclusions = nil
         }
 
         if isPrivate,
            event.modifications.contains(where: {
                $0.zoneID.zoneName == Archive.zoneName
            }) {
             await MainActor.run {
                 NotificationCenter.default.post(name: .chronicleZoneDidChange, object: nil)
             }
         }
 
         // 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 deletedGameZones = Set(event.deletions.map(\.zoneID).filter {
             $0.zoneName.hasPrefix("game-")
         })
         let (rejoinedIDs, failureMessages): ([UUID], [String]) = await ctx.perform {
             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 }
                     // A zone in the shared database always belongs to somebody
                     // else — CloudKit rejects any own-owner zone there ("Only
                     // shared zones can be accessed in the shared DB"). An
                     // own-owner zone reaching this branch therefore means the
                     // *private* database's changes were routed here, and
                     // seating a `databaseScope == 1` row for a zone the user
                     // owns produces a row no code path can ever heal: the
                     // private Game record that would fill it in matches on
                     // `ckZoneOwnerName == NIL` and so forks a second row
                     // instead, leaving this one permanently empty and shadowing
                     // the real game in every `id`-keyed lookup.
                     guard zoneID.ownerName != CKCurrentUserDefaultName else {
                         messages.append(
                             "refused shared placeholder for own-owner zone \(zoneName)"
                         )
                         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.syncVersion = GameSyncVersion.legacy
                         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) }
                     }
                 }
             }
             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 (rejoined, messages)
         }
 
         for message in failureMessages {
             await trace(message)
         }
         if !deletedGameZones.isEmpty {
             await applyZoneOrphaning(deletedGameZones, isPrivate: isPrivate, source: "fetch")
         }
         // 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 = DatabaseScope(isPrivate: isPrivate)
         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 = await ctx.perform {
             var effects = BatchEffects()
             for mod in event.modifications {
                 let record = mod.record
                 guard !RecordSerializer.isGameScopedRecordType(record.recordType)
                     || RecordSerializer.isTrustedGameScopedRecord(record)
                 else {
                     effects.traces.append(
                         "rejected untrusted fetched record \(record.recordType) " +
                         "\(record.recordID.recordName) in \(record.recordID.zoneID.zoneName)"
                     )
                     continue
                 }
                 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) },
                         onStaleCredentials: { effects.staleCredentialRecords.insert($0) },
                         onDiagnostic: { effects.traces.append($0) }
                     )
                     if let id = entity.id {
                         effects.rosterRelevant.insert(id)
                         effects.visibilityCandidateGameIDs.insert(id)
                     }
                 case "Moves":
                     if let value = RecordSerializer.parseMovesRecord(record) {
                         effects.visibilityCandidateGameIDs.insert(value.gameID)
                         let cellsChanged = RecordSerializer.applyMovesRecord(
                             record,
                             value: value,
                             to: ctx,
                             databaseScope: scope,
                             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) {
                         effects.visibilityCandidateGameIDs.insert(gameID)
                         self.applyPlayerRecord(
                             record,
                             in: ctx,
                             databaseScope: scope,
                             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, fetchedFrom: isPrivate ? .private : .shared) {
                         effects.pings.append(ping)
                     }
                 case "Decision":
                     if let address = RecordSerializer.parseAccountPushAddressDecision(record, databaseScope: scope) {
                         effects.accountPushAddresses.append(address)
                     }
                     if let parsed = RecordSerializer.parseAccountPushSecretDecision(record, databaseScope: scope) {
                         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)
                         }
                         if dKind == RecordSerializer.blockDecisionKind {
                             effects.blockedFriendAuthorIDs.insert(dKey)
                         }
                         // 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 and refresh its
                     // provisional Chronicle (dispatched below).
                     if let (gid, _, _) = RecordSerializer.parseJournalRecordName(
                         record.recordID.recordName
                     ) {
                         effects.journalsSynced.insert(gid)
                     }
                 case Archive.recordType, Archive.legacyRecordType:
                     // A compact Chronicle or legacy Archive in this user's
                     // private DB. Inert where the live original still exists;
                     // hydrated into a standalone completed game on a device
                     // that lacks it (fresh install / after revocation).
                     if let id = self.applyArchiveRecord(
                         record,
                         in: ctx,
                         onDiagnostic: { effects.traces.append($0) }
                     ) {
                         effects.rosterRelevant.insert(id)
                         effects.visibilityCandidateGameIDs.insert(id)
                     }
                 case CKRecord.SystemType.share:
                     // The zone-wide share is the authoritative membership. A
                     // previously accepted participant disappearing from it is
                     // the departure/revocation signal: rotate the game's push
                     // credentials so the departed device's cached copy stops
                     // granting push access.
                     if let share = record as? CKShare,
                        let gameID = self.applyShareRecord(share, databaseScope: scope, in: ctx) {
                         effects.credentialRotations.insert(gameID)
                         effects.traces.append(
                             "share roster shrank for \(gameID.uuidString) — rotating push credentials"
                         )
                     }
                 default:
                     break
                 }
             }
             for deletion in event.deletions {
                 guard !RecordSerializer.isGameScopedRecordType(deletion.recordType)
                     || RecordSerializer.isTrustedGameScopedDeletion(
                         recordID: deletion.recordID,
                         recordType: deletion.recordType
                     )
                 else {
                     effects.traces.append(
                         "rejected untrusted fetched deletion \(deletion.recordType) " +
                         "\(deletion.recordID.recordName) in \(deletion.recordID.zoneID.zoneName)"
                     )
                     continue
                 }
                 self.applyDeletion(
                     recordID: deletion.recordID,
                     recordType: deletion.recordType,
                     databaseScope: scope,
                     in: ctx
                 )
                 if let id = self.gameID(fromRecordName: deletion.recordID.recordName) {
                     effects.rosterRelevant.insert(id)
                     effects.visibilityCandidateGameIDs.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 onGameVisibilityCandidates, !effects.visibilityCandidateGameIDs.isEmpty {
             await onGameVisibilityCandidates(effects.visibilityCandidateGameIDs)
         }
         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 onPushCredentialRotationNeeded, !effects.credentialRotations.isEmpty {
             await onPushCredentialRotationNeeded(effects.credentialRotations)
         }
         if let onRemoteCredentialsChanged, !effects.contentKeysChanged.isEmpty {
             await onRemoteCredentialsChanged(effects.contentKeysChanged)
         }
         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()
             await mirrorCtx.perform {
                 FriendEntity.rebuildNicknameDirectory(in: mirrorCtx)
             }
         }
         if !effects.blockedFriendAuthorIDs.isEmpty {
             await onBlockedFriendsChanged?(effects.blockedFriendAuthorIDs)
         }
         for id in effects.removed {
             if let cb = onGameRemoved { await cb(id) }
         }
         // Re-push games whose inbound record tried to downgrade a rotated
         // credential: the local (newer) value was kept and marked pending, so
         // this send heals the server copy.
         for recordName in effects.staleCredentialRecords {
             enqueueGame(ckRecordName: recordName)
         }
         // 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]
             )
         }
         await notifyReplayJournalsSynced(effects.journalsSynced)
     }
 
     func notifyReplayJournalsSynced(_ gameIDs: Set<UUID>) async {
         guard !gameIDs.isEmpty else { return }
         NotificationCenter.default.post(
             name: .replayJournalDidSync,
             object: nil,
             userInfo: ["gameIDs": gameIDs]
         )
         await onReplayJournalsSynced?(gameIDs)
     }
 
     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"
     }
 
     /// A pending Ping remains durable for conditions CloudKit documents as
     /// retryable. These errors instead mean the particular write cannot
     /// succeed without a new user action or a corrected request, so leaving it
     /// queued would show a clock forever and retain an unusable CKShare seat.
     nonisolated static func isTerminalPingSaveError(_ error: NSError) -> Bool {
         guard error.domain == CKErrorDomain,
               let code = CKError.Code(rawValue: error.code)
         else { return false }
         switch code {
         case .badContainer,
              .missingEntitlement,
              .notAuthenticated,
              .permissionFailure,
              .unknownItem,
              .invalidArguments,
              .serverRejectedRequest,
              .incompatibleVersion,
              .constraintViolation,
              .badDatabase,
              .quotaExceeded,
              .zoneNotFound,
              .limitExceeded,
              .userDeletedZone,
              .tooManyParticipants,
              .referenceViolation,
              .managedAccountRestricted:
             return true
         default:
             return false
         }
     }
 
     nonisolated static func pingSaveRetryDelay(_ error: NSError) -> TimeInterval? {
         guard error.domain == CKErrorDomain,
               let code = CKError.Code(rawValue: error.code)
         else { return nil }
         switch code {
         case .internalError,
              .networkUnavailable,
              .networkFailure,
              .serviceUnavailable,
              .requestRateLimited,
              .zoneBusy,
              .operationCancelled,
              .serverResponseLost,
              .accountTemporarilyUnavailable:
             let serverDelay = (error.userInfo[CKErrorRetryAfterKey] as? NSNumber)?
                 .doubleValue
             return max(3, serverDelay ?? 0)
         default:
             return nil
         }
     }
 
     private func schedulePendingPingRetry(
         recordID: CKRecord.ID,
         isPrivate: Bool,
         after delay: TimeInterval
     ) {
         let recordName = recordID.recordName
         guard pendingPings[recordName] != nil,
               scheduledPingRetries.insert(recordName).inserted
         else { return }
         Task {
             try? await Task.sleep(for: .seconds(delay))
             scheduledPingRetries.remove(recordName)
             guard !Task.isCancelled, pendingPings[recordName] != nil else { return }
             let engine = isPrivate ? privateEngine : sharedEngine
             engine?.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
             if let engine { sendChangesDetached(on: engine) }
         }
     }
 
     private func handleSentRecordZoneChanges(
         _ event: CKSyncEngine.Event.SentRecordZoneChanges,
         isPrivate: Bool
     ) async {
         var completionRecords: [UUID: Set<CompletionDurableRecordKind>] = [:]
         for record in event.savedRecords {
             let name = record.recordID.recordName
             if record.recordType == "Game",
                name.hasPrefix("game-"),
                record["completedAt"] as? Date != nil,
                let gameID = UUID(uuidString: String(name.dropFirst("game-".count))) {
                 completionRecords[gameID, default: []].insert(.game)
             } else if record.recordType == "Moves",
                       let gameID = RecordSerializer.parseMovesRecordName(name)?.0 {
                 completionRecords[gameID, default: []].insert(.moves)
             } else if record.recordType == "Journal",
                       let gameID = RecordSerializer.parseJournalRecordName(name)?.0 {
                 completionRecords[gameID, default: []].insert(.journal)
             }
         }
         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-") {
                 await confirmPendingPing(recordName: 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, settledPings, settledJournals,
              resolvedAccountAddresses, resolvedAccountSecrets, decisionWins, recoveredSaves,
              batchFailedSaves, unresolvedFailureZones):
             ([String], Set<CKRecordZone.ID>, Set<CKRecord.ID>, Set<CKRecord.ID>, Set<CKRecord.ID>,
              [String], [(secret: String, version: Int64)],
              [(recordID: CKRecord.ID, stateKey: String, systemFields: Data)],
              [CKRecord.ID], [CKRecord.ID], Set<CKRecordZone.ID>) = await ctx.perform {
             var messages: [String] = []
             var orphaned = Set<CKRecordZone.ID>()
             var settledDecisions = Set<CKRecord.ID>()
             var settledPings = 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] = []
             // Atomic operations report the causal record's substantive error
             // and `.batchRequestFailed` for otherwise-valid siblings. The
             // latter have already fallen out of CKSyncEngine's pending state;
             // retain them for an explicit retry after every causal record in
             // their zone has been settled or recovered.
             var batchFailedSaves: [CKRecord.ID] = []
             var unresolvedFailureZones = Set<CKRecordZone.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.batchRequestFailed.rawValue {
                     batchFailedSaves.append(failure.record.recordID)
                     settled = true
                 } else 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("ping-"),
                           err.domain == CKErrorDomain,
                           err.code == CKError.serverRecordChanged.rawValue {
                     // Pings are immutable and their retry keeps the original
                     // record ID. A conflict therefore means the outbox item is
                     // already durable (for example, the app terminated after
                     // CloudKit saved it but before processing the sent event).
                     settledPings.insert(failure.record.recordID)
                     settled = true
                     messages.append("send: ping \(name) already present — settled")
                 } 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 (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 {
                             let scope = DatabaseScope(isPrivate: isPrivate)
                             if let address = RecordSerializer.parseAccountPushAddressDecision(serverRecord, databaseScope: scope) {
                                 accountAddresses.append(address)
                             }
                             if let parsed = RecordSerializer.parseAccountPushSecretDecision(serverRecord, databaseScope: scope) {
                                 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)
                     settled = true
                     messages.append(
                         "send: recovered stale system fields for \(name) from CloudKit server record"
                     )
                 }
                 guard !settled else { continue }
                 unresolvedFailureZones.insert(failure.record.recordID.zoneID)
                 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, settledPings, settledJournals,
                     accountAddresses, accountSecrets, decisionWins, recoveredSaves,
                     batchFailedSaves, unresolvedFailureZones)
         }
         if !orphanedZones.isEmpty {
             await applyZoneOrphaning(orphanedZones, isPrivate: isPrivate, source: "send")
         }
         let terminalPingFailures = event.failedRecordSaves.filter { failure in
             failure.record.recordID.recordName.hasPrefix("ping-")
                 && Self.isTerminalPingSaveError(failure.error as NSError)
         }
         if !terminalPingFailures.isEmpty {
             let engine = isPrivate ? privateEngine : sharedEngine
             let changes = terminalPingFailures.map {
                 CKSyncEngine.PendingRecordZoneChange.saveRecord($0.record.recordID)
             }
             engine?.state.remove(pendingRecordZoneChanges: changes)
             for failure in terminalPingFailures {
                 let recordName = failure.record.recordID.recordName
                 guard pendingPings[recordName] != nil else { continue }
                 await failPendingPing(
                     recordName: recordName,
                     error: failure.error as NSError
                 )
             }
         }
         for failure in event.failedRecordSaves {
             let recordID = failure.record.recordID
             guard recordID.recordName.hasPrefix("ping-"),
                   let delay = Self.pingSaveRetryDelay(failure.error as NSError)
             else { continue }
             schedulePendingPingRetry(
                 recordID: recordID,
                 isPrivate: isPrivate,
                 after: delay
             )
         }
         // 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 {
             settleDecisionRecords(resolvedDecisions, on: decisionEngine)
         }
         // 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) }
             )
         }
         if !settledPings.isEmpty {
             let engine = isPrivate ? privateEngine : sharedEngine
             engine?.state.remove(
                 pendingRecordZoneChanges: settledPings.map { .saveRecord($0) }
             )
             for recordID in settledPings {
                 await confirmPendingPing(recordName: recordID.recordName)
             }
         }
         let retryableBatchSiblings = batchFailedSaves.filter {
             !orphanedZones.contains($0.zoneID)
                 && !unresolvedFailureZones.contains($0.zoneID)
         }
         if !retryableBatchSiblings.isEmpty {
             await recoverBatchFailedSaves(retryableBatchSiblings, isPrivate: isPrivate)
         }
         for message in failureMessages {
             await trace(message)
         }
         if !completionRecords.isEmpty, let onCompletionRecordsSaved {
             await onCompletionRecordsSaved(completionRecords)
         }
     }
 
     private func settleDecisionRecords(
         _ recordIDs: Set<CKRecord.ID>,
         on engine: CKSyncEngine
     ) {
         engine.state.remove(
             pendingRecordZoneChanges: recordIDs.map { .saveRecord($0) }
         )
         for recordID in recordIDs {
             let stateKey = Self.decisionStateKey(recordID)
             pendingDecisionPayloads.removeValue(forKey: stateKey)
             pendingDecisionVersions.removeValue(forKey: stateKey)
             decisionSystemFields.removeValue(forKey: stateKey)
         }
         persistPendingDecisionPayloads()
         persistPendingDecisionVersions()
     }
 
     /// Re-adds only atomic-failure siblings whose records can still be built.
     /// The caller invokes this after resolving all substantive failures in the
     /// zone, preventing a blind retry of the original atomic batch.
     private func recoverBatchFailedSaves(
         _ recordIDs: [CKRecord.ID],
         isPrivate: Bool
     ) async {
         guard let engine = isPrivate ? privateEngine : sharedEngine else { return }
         let scope = DatabaseScope(isPrivate: isPrivate)
         let pingSnapshot = pendingPings
         let decisionSnapshot = pendingDecisionPayloads
         let decisionVersionSnapshot = pendingDecisionVersions
         let decisionSystemFieldsSnapshot = decisionSystemFields
         let ctx = persistence.container.newBackgroundContext()
         var recovered: [CKRecord.ID] = []
         for recordID in recordIDs {
             guard buildRecord(
                 for: recordID,
                 in: ctx,
                 databaseScope: scope,
                 pings: pingSnapshot,
                 decisions: decisionSnapshot,
                 decisionVersions: decisionVersionSnapshot,
                 decisionSystemFields: decisionSystemFieldsSnapshot
             ) != nil else {
                 await trace(
                     "send: atomic sibling \(recordID.recordName) is no longer reconstructable — dropped"
                 )
                 continue
             }
             recovered.append(recordID)
         }
         guard !recovered.isEmpty else { return }
         engine.state.add(
             pendingRecordZoneChanges: recovered.map { .saveRecord($0) }
         )
         await trace(
             "send: re-enqueued \(recovered.count) reconstructable atomic-failure sibling" +
             (recovered.count == 1 ? "" : "s")
         )
         sendChangesDetached(on: engine)
     }
 
     /// Test seam for the atomic-failure recovery sequence. CKSyncEngine's sent
     /// event has no public initializer, so tests supply the causal Decision and
     /// collateral record IDs directly after arranging their pending payloads.
     func recoverAtomicBatchForTesting(
         settledDecisionID: CKRecord.ID,
         batchFailedRecordIDs: [CKRecord.ID],
         scope: CKDatabase.Scope
     ) async {
         guard let engine = scope == .shared ? sharedEngine : privateEngine else { return }
         let allIDs = [settledDecisionID] + batchFailedRecordIDs
         engine.state.remove(
             pendingRecordZoneChanges: allIDs.map { .saveRecord($0) }
         )
         settleDecisionRecords([settledDecisionID], on: engine)
         await recoverBatchFailedSaves(
             batchFailedRecordIDs,
             isPrivate: scope != .shared
         )
     }
 
     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")
         }
     }
 
     /// Reflects missing game zones locally after CloudKit reports them gone.
     /// The same cleanup applies whether the absence arrives as a fetched
     /// database-zone deletion or as a `.zoneNotFound` send/query failure: drop
     /// pending sends that target the zone, delete private games or mark shared
     /// games access-revoked, and notify upstream observers. Without this,
     /// queued changes can retry forever and `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,
         source: String = "sync"
     ) 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)
             }
         }
 
         let orphanedPingNames = pendingPings.compactMap { name, ping in
             zones.contains(ping.recordZoneID) ? name : nil
         }
         for name in orphanedPingNames {
             await failPendingPing(recordName: name)
         }
 
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let (removedIDs, revokedIDs, failureMessages): ([UUID], [UUID], [String]) = await ctx.perform {
             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) [src=\(source)]: " +
             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)
         adoptNewerServerCredentials(from: serverRecord, in: ctx)
         return true
     }
 
     /// The oplock-recovery retry re-pushes the whole local Game record, and
     /// while this entity's `hasPendingSave` was set its inbound applies were
     /// skipped — so the local `notification` blob may predate a credential
     /// rotation a peer performed in the meantime. Re-pushing it verbatim would
     /// land the *old* credential back on the server and re-admit a departed
     /// participant's push access. Before the retry, adopt the server's
     /// credential whenever its rotation generation is at least ours (the tie
     /// goes to the server copy, converging concurrent rotations); a *lower*
     /// server generation is the stale state the retry exists to heal, so local
     /// wins there.
     private nonisolated func adoptNewerServerCredentials(
         from serverRecord: CKRecord,
         in ctx: NSManagedObjectContext
     ) {
         let name = serverRecord.recordID.recordName
         guard name.hasPrefix("game-") else { return }
         let serverBlob = (serverRecord["pushCredential"] as? Data)
             .flatMap { String(data: $0, encoding: .utf8) }
         guard let serverBlob, let serverCreds = GamePushCredentials.decode(serverBlob) else { return }
 
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", name)
         req.fetchLimit = 1
         guard let entity = try? ctx.fetch(req).first,
               entity.notification != serverBlob
         else { return }
         let localGen = GamePushCredentials.decode(entity.notification)?.generation
         guard localGen == nil || serverCreds.generation >= localGen! else { return }
         entity.notification = serverBlob
         // The adopted blob may carry a new content key; re-mirror the App Group
         // directory so the NSE can decrypt pushes sealed under it.
         GameEntity.rebuildContentKeyDirectory(in: ctx)
     }
 
     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
     }
 
     private func completedFetchExclusions(
         isPrivate: Bool
     ) async -> Set<CKRecordZone.ID> {
         if isPrivate, let privateCompletedFetchExclusions {
             return privateCompletedFetchExclusions
         }
         if !isPrivate, let sharedCompletedFetchExclusions {
             return sharedCompletedFetchExclusions
         }
 
         let database = isPrivate
             ? container.privateCloudDatabase
             : container.sharedCloudDatabase
         do {
             let zoneIDs = try await database.allRecordZones()
                 .map(\.zoneID)
                 .filter {
                     RecordSerializer.gameID(fromGameRecordName: $0.zoneName) != nil
                 }
             let recordIDs = zoneIDs.map {
                 CKRecord.ID(recordName: $0.zoneName, zoneID: $0)
             }
             let cutoff = Date().addingTimeInterval(-7 * 24 * 60 * 60)
             var exclusions = Set<CKRecordZone.ID>()
             for start in stride(from: 0, to: recordIDs.count, by: 200) {
                 let end = min(start + 200, recordIDs.count)
                 let results = try await database.records(
                     for: Array(recordIDs[start..<end]),
                     desiredKeys: ["completedAt"]
                 )
                 for (recordID, result) in results {
                     guard let record = try? result.get(),
                           let completedAt = record["completedAt"] as? Date,
                           completedAt < cutoff
                     else { continue }
                     exclusions.insert(recordID.zoneID)
                 }
             }
             if isPrivate {
                 privateCompletedFetchExclusions = exclusions
             } else {
                 sharedCompletedFetchExclusions = exclusions
             }
             await trace(
                 "\(isPrivate ? "private" : "shared") completed fetch exclusions: " +
                 "\(exclusions.count) zone(s)"
             )
             return exclusions
         } catch {
             await trace(
                 "\(isPrivate ? "private" : "shared") completed fetch exclusions failed: " +
                 describe(error)
             )
             return []
         }
     }
 
 }
 
 // MARK: - CKSyncEngineDelegate
 
 extension SyncEngine: CKSyncEngineDelegate {
     func nextFetchChangesOptions(
         _ context: CKSyncEngine.FetchChangesContext,
         syncEngine: CKSyncEngine
     ) async -> CKSyncEngine.FetchChangesOptions {
         var options = context.options
         let isPrivate = scope(for: syncEngine) == .private
         var excluded = await completedFetchExclusions(isPrivate: isPrivate)
         if isPrivate { excluded.insert(Archive.zoneID) }
 
         switch options.scope {
         case .all:
             options.scope = .allExcluding(Array(excluded))
         case .allExcluding(var zoneIDs):
             let existing = Set(zoneIDs)
             for zoneID in excluded where !existing.contains(zoneID) {
                 zoneIDs.append(zoneID)
             }
             options.scope = .allExcluding(zoneIDs)
         case .zoneIDs(let zoneIDs):
             options.scope = .zoneIDs(zoneIDs.filter {
                 !excluded.contains($0)
             })
         @unknown default:
             options.scope = .allExcluding(Array(excluded))
         }
         return options
     }
 
     func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
         let isPrivate = scope(for: syncEngine) == .private
         switch event {
         case .stateUpdate(let e):
             await 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 durable outbox row was missing or unreadable; 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 scope = scope(for: engine)
         let pingSnapshot = pendingPings
         let decisionSnapshot = pendingDecisionPayloads
         let decisionVersionSnapshot = pendingDecisionVersions
         let decisionSystemFieldsSnapshot = decisionSystemFields
         let buildContext = persistence.container.newBackgroundContext()
         return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { [weak self] recordID in
             guard let self else { return nil }
             if let record = self.buildRecord(
                 for: recordID,
                 in: buildContext,
                 databaseScope: scope,
                 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 `presenceUntil`. 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 presenceUntil: Date? = await ctx.perform {
                 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 presenceUntil {
                 let delta = Int(presenceUntil.timeIntervalSinceNow)
                 leaseDesc = "presenceUntil=\(presenceUntil.ISO8601Format()) " +
                     (delta > 0 ? "(future +\(delta)s)" : "(past \(-delta)s)")
             } else {
                 leaseDesc = "presenceUntil=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)
     }
 
     func pendingPingRecordNamesForTesting() -> [String] {
         Array(pendingPings.keys).sorted()
     }
 
     func confirmPendingPingForTesting(recordName: String) async {
         await confirmPendingPing(recordName: recordName)
     }
 
     func setPingConfirmationTimeoutForTesting(_ duration: Duration) {
         pingConfirmationTimeout = duration
     }
 }