crossmate

AppServices.swift (104632B)

---

 import CloudKit
 import CoreData
 import Foundation
 import UIKit
 import UserNotifications
 
 /// Fills a throwaway in-memory store with a handful of shared, in-progress
 /// games and crossmates so the Game List colour strips and the friends list can
 /// be inspected in the Simulator without an iCloud account or a real opponent.
 /// Driven solely by the `--crossmate-seed-demo` launch argument; a normal
 /// launch never reaches this. The same crossmate authorIDs are reused across
 /// both games on purpose, so one friend visibly takes a *different* colour in
 /// each game — the per-game colour derivation made visible.
 enum DemoSeed {
     private static let puzzleSource = """
     Title: Demo Puzzle
     Author: Crossmate
 
 
     ABC
     D#E
     FGH
 
 
     A1. Across 1 ~ ABC
     A4. Across 4 ~ DE
     A5. Across 5 ~ FGH
     D1. Down 1 ~ ADF
     D2. Down 2 ~ BG
     D3. Down 3 ~ CEH
     """
 
     /// A bundled 15×15 used for the one demo game seeded with letters already
     /// filled in, so the faint filled-cell author-attribution tints can be
     /// compared in a realistic grid rather than a 3×3 toy.
     private static let filledPuzzleResource = "cm-starter-0001"
 
     /// The local user's authorID in demo mode, injected into `AuthorIdentity`
     /// so the seeded crossmates classify as remote players. Kept distinct from
     /// every crossmate id below.
     static let localAuthorID = "_demo-you"
 
     private static let crossmates: [(id: String, name: String)] = [
         ("_demo-alice", "Alice"),
         ("_demo-bob", "Bob"),
         ("_demo-carol", "Carol"),
     ]
 
     @MainActor
     static func populate(persistence: PersistenceController, preferences: PlayerPreferences) {
         let ctx = persistence.viewContext
 
         // Keep the Game List out of its "set your profile name" empty state.
         if !preferences.hasName {
             preferences.name = "You"
         }
 
         guard let xd = try? XD.parse(puzzleSource) else { return }
         let puzzle = Puzzle(xd: xd)
 
         for crossmate in crossmates {
             seedFriend(crossmate, in: ctx)
         }
 
         seedGame(
             title: "Tuesday Mini",
             participants: ["_demo-alice", "_demo-bob"],
             puzzle: puzzle,
             source: puzzleSource,
             in: ctx
         )
         seedGame(
             title: "Sunday Giant",
             participants: ["_demo-alice", "_demo-bob", "_demo-carol"],
             puzzle: puzzle,
             source: puzzleSource,
             in: ctx
         )
 
         // A full 15×15 with letters already filled in, attributed across all
         // four players, so the desaturated filled-cell tints can be eyeballed
         // in a real grid. Reuse the catalog the new-game picker uses; it
         // resolves the bundled `.xd` for us and reads its source on demand.
         if let entry = PuzzleCatalog.source(matchingResourceID: filledPuzzleResource, title: nil),
            let bigSource = try? entry.loadSource(),
            let bigXD = try? XD.parse(bigSource) {
             let bigPuzzle = Puzzle(xd: bigXD)
             let game = seedGame(
                 title: entry.title,
                 participants: ["_demo-alice", "_demo-bob", "_demo-carol"],
                 puzzle: bigPuzzle,
                 source: bigSource,
                 in: ctx
             )
             seedFilledLetters(in: game, puzzle: bigPuzzle, in: ctx)
         }
 
         try? ctx.save()
     }
 
     private static func seedFriend(
         _ crossmate: (id: String, name: String),
         in ctx: NSManagedObjectContext
     ) {
         let friend = FriendEntity(context: ctx)
         friend.authorID = crossmate.id
         friend.createdAt = Date()
         friend.databaseScope = 0
         friend.displayName = crossmate.name
         friend.displayNameVersion = 0
         friend.friendZoneName = "demo-zone-\(crossmate.id)"
         friend.friendZoneOwnerName = "_demo-you"
         friend.isBlocked = false
         friend.nickname = ""
         friend.nicknameVersion = 0
         friend.pairKey = "demo-pair-\(crossmate.id)"
     }
 
     @discardableResult
     private static func seedGame(
         title: String,
         participants: [String],
         puzzle: Puzzle,
         source: String,
         in ctx: NSManagedObjectContext
     ) -> GameEntity {
         let game = GameEntity(context: ctx)
         game.id = UUID()
         game.title = title
         game.puzzleSource = source
         game.createdAt = Date()
         game.updatedAt = Date()
         // A non-nil share record name is what marks the game as shared, which is
         // the gate for the Game List participant colour strip.
         game.ckShareRecordName = "demo-share-\(title)"
         game.populateCachedSummaryFields(from: puzzle)
 
         for authorID in participants {
             let player = PlayerEntity(context: ctx)
             player.game = game
             player.authorID = authorID
             player.name = crossmates.first { $0.id == authorID }?.name
             player.ckRecordName = "demo-player-\(title)-\(authorID)"
             player.updatedAt = Date()
         }
         return game
     }
 
     /// Fills a realistic share of `game`'s grid with correct letters, handing
     /// each cell to one of the four demo players (you + the three crossmates)
     /// in small diagonal patches and leaving scattered gaps so the puzzle reads
     /// as in-progress. One `MovesEntity` per author carries that author's cells,
     /// exactly as a real co-solve would, so `GridStateMerger` rebuilds the
     /// attributed grid — and each filled cell renders that player's faint
     /// attribution tint.
     private static func seedFilledLetters(
         in game: GameEntity,
         puzzle: Puzzle,
         in ctx: NSManagedObjectContext
     ) {
         let authors = [localAuthorID] + crossmates.map(\.id)
         let now = Date()
         var cellsByAuthor: [String: [GridPosition: TimestampedCell]] = [:]
 
         for r in 0..<puzzle.height {
             for c in 0..<puzzle.width {
                 let cell = puzzle.cells[r][c]
                 guard !cell.isBlock,
                       let solution = cell.solution,
                       !solution.isEmpty,
                       !solution.allSatisfy(\.isWhitespace)
                 else { continue }
                 // Leave roughly one cell in seven blank for an in-progress look.
                 if (r * 5 + c) % 7 == 0 { continue }
                 let author = authors[((r / 2) + (c / 2)) % authors.count]
                 cellsByAuthor[author, default: [:]][GridPosition(row: r, col: c)] =
                     TimestampedCell(
                         letter: solution.uppercased(),
                         mark: .none,
                         updatedAt: now,
                         authorID: author
                     )
             }
         }
 
         for (author, cells) in cellsByAuthor {
             let entity = MovesEntity(context: ctx)
             entity.game = game
             entity.authorID = author
             entity.deviceID = "demo-device-\(author)"
             entity.ckRecordName = "demo-moves-\(game.id?.uuidString ?? "")-\(author)"
             entity.cells = (try? MovesCodec.encode(cells)) ?? Data()
             entity.updatedAt = now
         }
     }
 }
 
 @MainActor
 final class AppServices {
     enum ReadCursorPublishMode {
         case activeLease
         case currentTime
     }
 
     private static let readLeaseDuration: TimeInterval = 10 * 60
     private static let readLeaseRefreshFloor: TimeInterval = 5 * 60
 
     enum FreshenReason {
         case appeared
         case foreground
         case manual
         case remote
 
         var diagnosticLabel: String {
             switch self {
             case .appeared: return "appeared"
             case .foreground: return "foreground"
             case .manual: return "manual"
             case .remote: return "remote"
             }
         }
     }
 
     let persistence: PersistenceController
     let store: GameStore
     let syncEngine: SyncEngine
     let eventLog: EventLog
     let syncMonitor: SyncMonitor
     let nytAuth: NYTAuthService
     let driveMonitor: DriveMonitor
     let nytFetcher: NYTPuzzleFetcher
     let inputMonitor: InputMonitor
     let movesUpdater: MovesUpdater
     let sessionMonitor: SessionMonitor
     let announcements: AnnouncementCenter
     let playerSelectionPublisher: PlayerSelectionPublisher
     let identity: AuthorIdentity
     let pushClient: PushClient?
     /// Per-game play-session lifecycle: begin/end grace timers, sender-side
     /// session pushes, and the catch-up banner. See `SessionCoordinator`.
     let sessions: SessionCoordinator
     /// Account-scoped push credentials (secret/address mint, rotation,
     /// inbound adoption) + push-worker registration; see
     /// `AccountPushCoordinator`.
     let accountPush: AccountPushCoordinator
     /// Finished-game replay loading and the per-session timeline cache; see
     /// `ReplayLoader`.
     let replays: ReplayLoader
     let shareController: ShareController
     let friendController: FriendController
     let gameArchiver: GameArchiver
     let cursorStore: GameCursorStore
     /// Device-local record of when each game was last viewed; drives the
     /// "changed while you were away" cell borders. Never synced.
     let gameViewedStore: GameViewedStore
     /// Device-local onboarding-tip state: which tips have been dismissed and
     /// whether tips are turned off. Drives the Game List tip banner and the
     /// Settings tips archive. Never synced.
     let tips: TipStore
     let engagementStore: EngagementStore
     let cloudService: CloudService
     let importService: ImportService
     let engagementHost: EngagementHost
     let engagementStatus = EngagementStatus()
     /// Live-channel lifecycle (room reconcile/mint, teardown/reconnect/
     /// lease-expiry timers, inbound channel events); see `EngagementLifecycle`.
     /// Lazy so its callbacks into the read-cursor and sync-start paths can
     /// capture `self`.
     private(set) lazy var engagement = EngagementLifecycle(
         preferences: preferences,
         persistence: persistence,
         store: store,
         identity: identity,
         syncMonitor: syncMonitor,
         engagementHost: engagementHost,
         engagementStatus: engagementStatus,
         engagementStore: engagementStore,
         isAppForeground: { [weak self] in self?.isAppForeground ?? false },
         renewReadLease: { [weak self] gameID in
             await self?.publishReadCursor(for: gameID, mode: .activeLease)
         },
         ensureICloudSyncStarted: { [weak self] in
             await self?.ensureICloudSyncStarted() ?? false
         }
     )
     /// App-icon badge + delivered-notification reconciliation; see
     /// `BadgeCoordinator`. Lazy so the account-seen fan-out can capture `self`.
     private(set) lazy var badge = BadgeCoordinator(
         store: store,
         syncMonitor: syncMonitor,
         readLeaseDuration: Self.readLeaseDuration,
         publishAccountSeenPush: { [weak self] gameID, readAt in
             await self?.accountPush.publishAccountSeenPush(gameID: gameID, readAt: readAt)
         }
     )
     /// Friend-zone traffic — outbound invites, inbound ping handling, durable
     /// invite rows, friendship bootstrap, blocking; see `InviteCoordinator`.
     /// Lazy so the badge refresh can capture `self`.
     private(set) lazy var invites = InviteCoordinator(
         persistence: persistence,
         identity: identity,
         preferences: preferences,
         syncMonitor: syncMonitor,
         eventLog: eventLog,
         syncEngine: syncEngine,
         announcements: announcements,
         shareController: shareController,
         friendController: friendController,
         cloudService: cloudService,
         refreshAppBadge: { [weak self] reason in
             await self?.badge.refreshAppBadge(reason: reason)
         }
     )
 
     let preferences: PlayerPreferences
 
     private let ckContainer = CKContainer(identifier: "iCloud.net.inqk.crossmate.v3")
     private var started = false
     private var syncStarted = false
     /// In-flight `ensureICloudSyncStarted()` work, shared by concurrent
     /// callers so the cold-launch race between `services.start()` and a
     /// near-simultaneous `syncOnForeground()` doesn't admit two parallel
     /// `SyncEngine.start()` runs.
     private var syncStartTask: Task<Bool, Never>?
     private(set) var playerNamePublisher: PlayerNamePublisher?
     private var isReadyForShareAcceptance = false
     private var isProcessingShareAcceptanceQueue = false
     /// True while `processPendingShareAcceptances` is draining. A share accept
     /// holds the shared database to download the puzzle asset on the joining
     /// screen; shared-scope pushes that land in this window defer their heavy
     /// fan-out so collaborator activity doesn't contend with the join.
     private var isAcceptingSharedGame = false
     private var pendingShareMetadatas: [CKShare.Metadata] = []
     /// Wall-clock timestamp of the most recent inbound silent push. Bypasses
     /// the game-list freshen cooldown when a push has arrived since the last
     /// freshen, so a collaborator burst isn't held off by debounce.
     private var lastRemoteNotificationAt: Date?
     private var privatePushCatchUpTask: Task<Void, Never>?
     private var sharedPushCatchUpTask: Task<Void, Never>?
     private var privateSessionScanTask: Task<Void, Never>?
     private var sharedSessionScanTask: Task<Void, Never>?
     private var isHandlingPrivateRemoteNotification = false
     private var isHandlingSharedRemoteNotification = false
     private var gameListFreshenTask: Task<Void, Never>?
     private var isFresheningPrivateGameList = false
     private var isFresheningSharedGameList = false
     /// The archive backstop can scan many completed shared games. Run it once
     /// after the first cold-launch game-list freshen, not on every foreground,
     /// manual refresh, or remote-triggered refresh.
     private var shouldRunColdLaunchArchiveReconcile = true
     /// Wall-clock timestamp of the last successful game-list freshen per
     /// scope, used to suppress redundant polls when no inbound push has
     /// arrived since. Pushes own freshness; the freshen (zone discovery +
     /// game/moves catch-up) is only a backstop for the case where Apple
     /// drops a silent push or a share-accept notification.
     private var lastPrivateGameListFreshenAt: Date?
     private var lastSharedGameListFreshenAt: Date?
     /// Maximum staleness budget for the game list before an unprompted view
     /// event re-runs the freshen. Bypassed by `.manual` and by any push that
     /// arrived after the last successful freshen.
     private let gameListFreshenCooldown: TimeInterval = 300
     private var fresheningPuzzleGridKeys: Set<String> = []
     private var lastRemotePuzzleGridFreshenAt: [String: Date] = [:]
     /// Collapses bursts of remote-push grid refreshes, but only while the
     /// engagement websocket is live for the game (see
     /// `shouldSkipRecentRemotePuzzleGridFreshen`). When the live channel is
     /// down, the push path is the sole convergence mechanism and is not
     /// debounced.
     private let remotePuzzleGridFreshenDebounce: TimeInterval = 5
     private var isGameListVisible = false
     /// Whether the app is foreground-active — the single source of truth for
     /// "the user is actively using the app." `publishReadCursor(.activeLease)`
     /// consults it so a background CKSyncEngine wake can never re-arm our
     /// presence lease. Fed from `RootView`'s scene-phase observer; defaults to
     /// `true` because the app launches into the foreground and `.onChange` does
     /// not fire for the initial phase.
     private(set) var isAppForeground = true
 
     /// Whether an account-change event warrants purging this device's local
     /// store. True only when both the previously-known and the freshly-resolved
     /// author IDs are known and differ — i.e. a real switch to a different
     /// iCloud account. A first sign-in has no previous ID, and a transient
     /// sign-out leaves `AuthorIdentity.refresh` a no-op (so the ID is
     /// unchanged); neither should wipe local data.
     static func accountSwitchRequiresPurge(previousID: String?, newID: String?) -> Bool {
         guard let previousID, let newID else { return false }
         return previousID != newID
     }
 
     init() {
         let preferences = PlayerPreferences()
         self.preferences = preferences
         let eventLog = EventLog()
         self.eventLog = eventLog
         // `--crossmate-seed-demo` (set in the Run scheme's arguments) brings the
         // app up against a throwaway in-memory store pre-filled with a couple of
         // shared games and a few crossmates, purely so the Game List colour
         // strips and the friends list can be eyeballed in the Simulator without
         // iCloud. It never touches the real on-disk store.
         let isDemoSeed = ProcessInfo.processInfo.arguments.contains("--crossmate-seed-demo")
         let persistence = PersistenceController(inMemory: isDemoSeed, eventLog: eventLog)
         self.persistence = persistence
         if isDemoSeed {
             DemoSeed.populate(persistence: persistence, preferences: preferences)
         }
         let syncEngine = SyncEngine(container: self.ckContainer, persistence: persistence)
         self.syncEngine = syncEngine
         self.syncMonitor = SyncMonitor(log: eventLog)
         self.driveMonitor = DriveMonitor()
         self.nytAuth = NYTAuthService(log: { message in
             eventLog.note(message)
         })
         self.nytFetcher = NYTPuzzleFetcher { NYTAuthService.currentCookieResult() }
         self.inputMonitor = InputMonitor()
         // In demo mode, inject a fixed local authorID so the seeded peers
         // classify as remote — otherwise, with no iCloud user, the roster comes
         // up empty and the puzzle scoreboard (and its nudge button) never
         // populate. A real launch always resolves the ID from CloudKit.
         let identity = isDemoSeed ? AuthorIdentity(testing: DemoSeed.localAuthorID) : AuthorIdentity()
         self.identity = identity
         let pushSyncMonitor = self.syncMonitor
         self.pushClient = PushClient(log: { message in
             Task { @MainActor in pushSyncMonitor.note(message) }
         })
         self.pushClient?.updateAuthorID(identity.currentID)
 
         let movesUpdater = MovesUpdater(
             debounceInterval: .milliseconds(500),
             persistence: persistence,
             writerAuthorIDProvider: { await MainActor.run { identity.currentID } },
             sink: { [persistence] gameIDs, drain in
                 // MovesUpdater bumps game.updatedAt on a background context.
                 // viewContext.automaticallyMergesChangesFromParent applies that
                 // change in-memory but doesn't reliably fire the ObjectsDidChange
                 // notification that @FetchRequest's NSFetchedResultsController
                 // listens for, so the library list keeps showing the stale
                 // "last updated" time until something else nudges the context.
                 // The inbound path is masked by noteIncomingMovesUpdate's
                 // explicit viewContext save; the outbound path has no analog.
                 // Refreshing the affected entities re-emits ObjectsDidChange
                 // with refreshedObjects, which NSFRC treats as a per-entity
                 // update — that path runs unconditionally so local-only games
                 // get the same nudge even when iCloud sync is off.
                 await MainActor.run {
                     let viewContext = persistence.viewContext
                     for gameID in gameIDs {
                         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                         req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
                         req.fetchLimit = 1
                         guard let entity = try? viewContext.fetch(req).first else { continue }
                         viewContext.refresh(entity, mergeChanges: true)
                     }
                 }
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
                 await syncEngine.enqueueMoves(gameIDs: gameIDs, drain: drain)
             }
         )
         self.movesUpdater = movesUpdater
 
         self.announcements = AnnouncementCenter()
 
         let cursorStore = GameCursorStore()
         self.cursorStore = cursorStore
         let gameViewedStore = GameViewedStore()
         self.gameViewedStore = gameViewedStore
         self.tips = TipStore()
         let engagementStore = EngagementStore()
         self.engagementStore = engagementStore
         let onGameDeletedHandler = Self.makeOnGameDeleted(
             syncEngine: syncEngine,
             cursorStore: cursorStore,
             viewedStore: gameViewedStore
         )
 
         let store = GameStore(
             persistence: persistence,
             movesUpdater: movesUpdater,
             authorIDProvider: { identity.currentID },
             onGameCreated: { [preferences, syncEngine] ckRecordName in
                 Task {
                     guard await MainActor.run(body: { preferences.isICloudSyncEnabled }) else { return }
                     await syncEngine.enqueueGame(ckRecordName: ckRecordName)
                 }
             },
             onGameUpdated: { [preferences, syncEngine] ckRecordName in
                 Task {
                     guard await MainActor.run(body: { preferences.isICloudSyncEnabled }) else { return }
                     await syncEngine.enqueueGame(ckRecordName: ckRecordName)
                 }
             },
             onGameDeleted: { [preferences] deletion in
                 // Drop the badge ledger entry regardless of sync state — a
                 // deleted game has nothing left to open, so a stale unread
                 // horizon would count forever. `deleteGame` fires
                 // `onUnreadOtherMovesChanged` right after, which refreshes the
                 // app badge.
                 BadgeState.forget(gameID: deletion.gameID)
                 guard preferences.isICloudSyncEnabled else { return }
                 onGameDeletedHandler(deletion)
             },
             eventLog: eventLog
         )
         self.store = store
         // Publishes resolve (and mint) the game's shared push credential from
         // the store so the worker can verify participation.
         self.pushClient?.gameCredentialResolver = { [weak store] gameID in
             store?.ensurePushCredentials(for: gameID)
         }
         // Publishes encrypt the structured payload under the game's content key,
         // which rides in the same notification credential the push secret does
         // (minted/backfilled on first use) so the worker only ever forwards
         // ciphertext for the personal fields.
         self.pushClient?.contentKeyResolver = { [weak store] gameID in
             guard let keyString = store?.ensurePushCredentials(for: gameID)?.contentKey
             else { return nil }
             return PushPayloadCipher.key(fromBase64: keyString)
         }
 
         let sessionMonitor = SessionMonitor(
             store: store,
             localAuthorIDProvider: { identity.currentID }
         )
         self.sessionMonitor = sessionMonitor
 
         self.sessions = SessionCoordinator(
             persistence: persistence,
             store: store,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             sessionMonitor: sessionMonitor,
             gameViewedStore: gameViewedStore,
             announcements: self.announcements,
             identity: identity,
             preferences: preferences,
             pushClient: self.pushClient
         )
 
         self.accountPush = AccountPushCoordinator(
             identity: identity,
             preferences: preferences,
             store: store,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             pushClient: self.pushClient
         )
 
         self.replays = ReplayLoader(
             store: store,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor
         )
 
         self.shareController = ShareController(
             container: self.ckContainer,
             persistence: persistence,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor
         )
         self.playerSelectionPublisher = PlayerSelectionPublisher(
             // While the live room carries the cursor over the websocket, the
             // durable write is a lagging fallback — throttle it hard. When the
             // room is down it is the peer's only delivery path, so keep it snappy.
             debounceInterval: { [engagementStatus] gameID in
                 engagementStatus.isLive(gameID: gameID) ? .milliseconds(2500) : .milliseconds(500)
             },
             persistence: persistence,
             sink: { gameID, authorID, drain in
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
                 await syncEngine.enqueuePlayer(
                     gameID: gameID,
                     authorID: authorID,
                     reason: "selection",
                     drain: drain
                 )
             },
             peerPresent: { [persistence, identity] gameID in
                 let localAuthorID = await MainActor.run { identity.currentID }
                 return await Self.hasPresentPeer(
                     persistence: persistence,
                     gameID: gameID,
                     localAuthorID: localAuthorID
                 )
             }
         )
         self.friendController = FriendController(
             container: self.ckContainer,
             persistence: persistence,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             eventLog: eventLog
         )
         self.gameArchiver = GameArchiver(
             container: self.ckContainer,
             persistence: persistence,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             eventLog: eventLog
         )
         self.cloudService = CloudService(
             container: self.ckContainer,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             store: store,
             shareController: shareController
         )
         self.importService = ImportService(store: store, driveMonitor: self.driveMonitor)
         self.engagementHost = EngagementHost()
         self.engagementHost.onEvent = { [weak self] event in
             self?.engagement.handleEngagementEvent(event)
         }
         self.store.onLocalCellEdit = { [weak self] edit in
             self?.engagement.sendLocalCellEdit(edit)
         }
         self.store.onLocalCellEditBatch = { [weak self] edits in
             self?.engagement.sendLocalCellEdits(edits)
         }
         self.store.onJournalComplete = { [weak self] gameID, authorID in
             self?.beginCompletionJournalUpload(gameID: gameID, authorID: authorID)
         }
     }
 
     func start(appDelegate: AppDelegate) async {
         guard !started else { return }
         started = true
 
         // Surface one onboarding tip per cold launch. The in-memory
         // AnnouncementCenter is empty on a fresh process, so this re-posts the
         // next undismissed tip on each cold start; a warm resume doesn't re-run
         // start(), so no tip reappears mid-session. Independent of iCloud sync,
         // so it runs ahead of the sync-enablement guard below.
         if let tip = tips.currentTip() {
             announcements.post(tip.liveAnnouncement())
         }
 
         // Hydrate the persisted diagnostics history before live breadcrumbs
         // flow, so a log collected this morning still carries last night's
         // session. Ordering against startup notes is by timestamp, so a note
         // that races ahead of this isn't lost.
         await eventLog.loadPersisted()
 
         nytAuth.loadStoredSession()
         driveMonitor.start()
 
         store.onUnreadOtherMovesChanged = { [weak self] in
             guard let self else { return }
             Task { await self.badge.refreshAppBadge(reason: "unread changed") }
         }
         importVisibleNotificationReceipts()
         await badge.refreshAppBadge(reason: "startup")
         await badge.logNotificationStartupSnapshot()
 
         // Heal the App Group nickname directory from Core Data ground truth —
         // covers the first run after the feature shipped and any rebuild a
         // crash or extension write skipped. Cheap: one fetch over the (small)
         // friends table.
         let nicknameCtx = persistence.container.newBackgroundContext()
         nicknameCtx.performAndWait {
             FriendEntity.rebuildNicknameDirectory(in: nicknameCtx)
             // Heal the App Group content-key directory from the same context —
             // covers the first run after the feature shipped and any rebuild a
             // crash or extension write skipped. Cheap: one fetch over the games.
             GameEntity.rebuildContentKeyDirectory(in: nicknameCtx)
         }
 
         appDelegate.onRemoteNotification = {
             summary, scope, event, gameID, kind, senderDeviceID, readAt, isBackground in
             await self.handleRemoteNotification(
                 summary: summary,
                 scope: scope,
                 event: event,
                 gameID: gameID,
                 kind: kind,
                 senderDeviceID: senderDeviceID,
                 readAt: readAt,
                 isBackground: isBackground
             )
         }
         appDelegate.onVisibleNotificationReceiptsAvailable = { [weak self] in
             Task { @MainActor in
                 self?.importVisibleNotificationReceipts()
             }
         }
         appDelegate.onAPNsRegistrationResult = { [syncMonitor] message in
             syncMonitor.note(message)
         }
         appDelegate.onAPNsToken = { [weak self] data in
             Task { @MainActor in self?.pushClient?.updateAPNsToken(data) }
         }
         CloudShareAcceptanceBroker.shared.onAcceptShare = { metadata in
             await self.enqueueShareAcceptance(metadata)
         }
 
         await syncEngine.setTracer { [syncMonitor] message in
             syncMonitor.note(message)
         }
 
         await syncEngine.setSuccessCheckpoint { [syncMonitor] in
             syncMonitor.noteSuccess()
         }
 
         await syncEngine.setLocalAuthorIDProvider { [identity] in
             identity.currentID
         }
 
         await syncEngine.setOnRemoteMovesUpdated { [weak self, store, identity] gameIDs in
             store.noteIncomingMovesUpdate(
                 gameIDs: gameIDs,
                 currentAuthorID: identity.currentID
             )
             if let currentID = store.currentEntity?.id,
                gameIDs.contains(currentID) {
                 store.refreshCurrentGame()
                 // `readAt` doubles as the other-author read cursor: advancing it
                 // marks these incoming peer moves as seen. Gate on `isSuppressed`
                 // — "the user is viewing *this* puzzle right now" — so moves are
                 // marked read only while actually on screen, not merely because
                 // the app is foreground on some other view (`currentEntity`
                 // lingers after navigating away). The background re-lease is
                 // blocked separately by publishReadCursor's foreground gate.
                 if NotificationState.isSuppressed(gameID: currentID) {
                     await self?.publishReadCursor(for: currentID, mode: .activeLease)
                 }
             }
             // Maintain the per-cell letter-change ledger that the "changed while
             // you were away" borders and banner read. Captures peer fills/clears
             // (never check re-stamps) as they arrive, whether or not the game is
             // open. Fire-and-forget: the inbound-moves hot path must not wait on
             // this background write, so the next batch isn't throttled behind it.
             store.enqueuePeerChangeLedgerUpdate(for: gameIDs)
         }
 
         // Friendship bootstrap keys off the *first* sight of a collaborator's
         // Player record (their identity) — fires once per new collaborator,
         // not on moves and not on their later name / cursor updates.
         await syncEngine.setOnRemotePlayersUpdated { [weak self] gameIDs in
             await self?.invites.reconcileFriendships(forGameIDs: gameIDs)
             // A newly-arrived shared game means a new address slot to mint and
             // a token to register under it (so this device can receive the
             // game's pushes without opening it first).
             await self?.accountPush.reconcilePushRegistration()
         }
 
         // An inbound Player record may have updated a peer's cursor track;
         // nudge the selection publisher and engagement coordinator to
         // re-evaluate peer presence. This must fire for existing Player
         // records too: known collaborators opening a puzzle are the common
         // live co-solving path.
         await syncEngine.setOnRemotePlayerPresenceChanged { [weak self] gameIDs in
             await self?.playerSelectionPublisher.peerPresenceMayHaveChanged(gameIDs: gameIDs)
             guard let self else { return }
             for gameID in gameIDs {
                 await self.engagement.reconcileEngagement(gameID: gameID)
             }
         }
 
         // A peer minted or rotated the shared engagement room (the Game
         // record's `engagement` creds changed). Reconcile so this device joins
         // — or migrates onto — whatever room the record now advertises.
         await syncEngine.setOnRemoteEngagementChanged { [weak self] gameIDs in
             guard let self else { return }
             for gameID in gameIDs {
                 await self.engagement.reconcileEngagement(gameID: gameID)
             }
         }
 
         // A sibling device of the same iCloud account has published its read
         // horizon; apply it directly because SyncEngine has already accepted
         // the Player record under last-writer-wins freshness checks. A
         // future-dated readAt is an active-session lease — a sibling is in the
         // puzzle right now — so withdraw any session notifications we already
         // delivered for that game (e.g. "X is solving"); opening it here is no
         // longer something to nudge for. A past readAt is just a closed-session
         // horizon bump and leaves delivered notifications untouched.
         await syncEngine.setOnIncomingReadCursor { [weak self, store, gameViewedStore] pairs in
             let now = Date()
             for (gameID, readAt, seenBaselineData) in pairs {
                 let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, readAt: readAt)
                 self?.syncMonitor.note(
                     "cursor ADOPT[\(gameID.uuidString.prefix(8))] src=sync " +
                     "readAt=\(readAt.ISO8601Format()) " +
                     "was=\(previous?.ISO8601Format() ?? "—")" +
                     (adopted ? "" : " (no-op)")
                 )
                 // A sibling device shipped its "last viewed" baseline on its own
                 // `Player.sessionSnapshot`; fold it in monotonically so we
                 // converge on the latest view time across the account rather than
                 // recomputing from this device's (possibly stale) local view. An
                 // older or old-format payload simply fails to advance / decode.
                 if let data = seenBaselineData,
                    let baseline = try? JSONDecoder().decode(SeenBaseline.self, from: data) {
                     gameViewedStore.advance(baseline.viewedAt, forGame: gameID)
                 }
                 if readAt > now {
                     await self?.badge.dismissDeliveredNotifications(
                         for: gameID,
                         seenAt: readAt,
                         publishAccountSeen: false,
                         preserveUnread: true
                     )
                 } else if NotificationState.activePuzzleID() == gameID {
                     // A past-dated readAt is a sibling closing its session, which
                     // under last-writer-wins just pulled the shared account
                     // horizon back to that close time. This device is still
                     // actively viewing the same puzzle, so it still holds a
                     // presence lease — re-assert it now instead of waiting up to
                     // `readLeaseRefreshFloor` (5 min) for the next renewal tick.
                     // `requireActivePuzzle` re-checks inside the write so a leave
                     // racing this inbound can't strand a stale future lease.
                     // The local badge ledger keeps this device's own suppression
                     // horizon — a sibling's close doesn't mean *we* stopped
                     // looking.
                     await self?.publishReadCursor(
                         for: gameID,
                         mode: .activeLease,
                         requireActivePuzzle: true
                     )
                 } else {
                     // Sibling closed its session and nothing is on screen here:
                     // the account stopped looking at `readAt`. Pull the badge
                     // ledger's suppression horizon back to that instant (and
                     // advance the watermark to it) so a push arriving after the
                     // close badges here instead of staying swallowed under the
                     // sibling's old lease, which this device adopted when the
                     // lease was minted.
                     BadgeState.markSeen(gameID: gameID, at: readAt)
                     BadgeState.collapseSuppression(gameID: gameID, to: readAt)
                 }
             }
         }
 
         await syncEngine.setOnAccountPushAddress { [weak self] address in
             await self?.accountPush.adoptInboundPushAddress(address)
         }
 
         await syncEngine.setOnAccountPushSecret { [weak self] secret, version in
             await self?.accountPush.adoptInboundPushSecret(secret, version: version)
         }
 
         shareController.onShareSaved = { [weak self] gameID in
             guard let self else { return }
             self.store.markShared(gameID: gameID)
             // Mint the game's notification content key now, at share time,
             // rather than lazily on the first push. The key rides the Game
             // record (`setNotification` enqueues its push), so minting here
             // gives it time to propagate to participants before any encrypted
             // notification is sent. Lazy minting let the first push for a game
             // with no prior activity (e.g. an immediate resign on a game with
             // no moves) outrun the key's sync, leaving the recipient unable to
             // decrypt and falling back to the generic alert. Idempotent.
             self.store.ensurePushCredentials(for: gameID)
             // Register this device under the newly-shared game's derived push
             // address so peers can reach it.
             Task { @MainActor [weak self] in
                 await self?.accountPush.reconcilePushRegistration()
             }
             // Register the app for notifications now that the user has chosen
             // to collaborate. Surfaces the app in Settings > Notifications and
             // makes the icon-badge permission available before any inbound
             // moves can arrive.
             Task { await AppDelegate.requestNotificationAuthorizationIfNeeded() }
         }
 
         await syncEngine.setOnPings { [weak self] pings in
             guard let self else { return }
             await self.invites.presentPings(pings)
         }
 
         await syncEngine.setOnAccountChange { [weak self] in
             guard let self else { return }
             let previousID = self.identity.currentID
             await self.identity.refresh(using: self.ckContainer)
             let newID = self.identity.currentID
             // A switch to a *different* iCloud account: drop this device's
             // cache of the previous account's data so it neither lingers in
             // the library nor mixes with the new author's rows. Local only —
             // the previous account keeps its games in its own CloudKit; this
             // device just resyncs as the new account. Gated on the author ID
             // actually changing so a first sign-in (no previous) or a
             // transient sign-out (`refresh` no-ops, ID unchanged) doesn't
             // purge.
             if Self.accountSwitchRequiresPurge(previousID: previousID, newID: newID) {
                 do {
                     try await self.cloudService.purgeLocalData()
                 } catch {
                     self.syncMonitor.note("account-switch purge failed — \(error)")
                 }
             }
             self.pushClient?.updateAuthorID(newID)
             // Recompute the address set for the new account; addresses that
             // belonged to the old account drop out and are unregistered.
             await self.accountPush.reconcilePushRegistration()
         }
 
         await syncEngine.setOnGameAccessRevoked { [store, gameViewedStore, announcements, gameArchiver] gameID in
             store.markAccessRevoked(gameID: gameID)
             // Supersede any pending catch-up banner: advancing the view baseline
             // to now leaves nothing for the next open to diff against.
             gameViewedStore.advance(Date(), forGame: gameID)
             // Surface the revocation as a sticky, input-blocking banner on
             // the open puzzle, replacing the former AccessRevokedBanner
             // overlay. Game-scoped, so it only shows for this puzzle.
             announcements.post(.accessRevoked(gameID: gameID))
             // The owner deleted the shared zone. For a *finished* game, swap the
             // revoked tombstone for a durable owned copy rebuilt from the
             // private-zone archive (and from the still-present local data);
             // in-progress games are left as revoked rows.
             await gameArchiver.promoteRevoked(gameID: gameID)
         }
 
         await syncEngine.setOnGameRemoved { [weak self, store, gameViewedStore, announcements] gameID in
             let wasOpen = store.handleRemoteRemoval(gameID: gameID)
             gameViewedStore.advance(Date(), forGame: gameID)
             // The local row is gone, so drop its badge ledger entry: a seen
             // horizon can't clear it once there's no game left to open.
             BadgeState.forget(gameID: gameID)
             await self?.badge.refreshAppBadge(reason: "game removed")
             // A hard-deleted game (private zone gone, or a shared game left
             // elsewhere) only needs UI when its puzzle is on screen: a sticky,
             // input-blocking banner freezes the now-orphaned puzzle until the
             // user backs out. Off-screen removals just drop from the list.
             if wasOpen {
                 announcements.post(.gameRemoved(gameID: gameID))
             }
         }
 
         await syncEngine.setOnGameCompleted { [weak self] gameID in
             await self?.shareController.closeTicketForCompletedGame(gameID: gameID)
             // Completion learned purely via sync (this device wasn't present at
             // the finish, so persistCompletion never ran): drop the now-useless
             // peer-change ledger, the writer's terminal-game path doing the work.
             self?.store.enqueuePeerChangeLedgerUpdate(for: [gameID])
         }
 
         await syncEngine.setOnGameJoined { [weak self] gameID in
             guard let self else { return }
             // A shared zone just synced in for this game — joined here or on
             // a sibling device. Its "Invited" row is now redundant; drop it
             // so a freshly-synced game and its stale invite don't show side
             // by side. `applyInvitePings` GCs the same row, but only when a
             // ping is next fetched.
             do {
                 try self.invites.removePendingInvite(forGameID: gameID)
                 // The pending invite (if any) is gone; drop it from the badge.
                 await self.badge.refreshAppBadge(reason: "game joined")
             } catch {
                 self.announcements.post(Announcement(
                     id: "remove-pending-invite-error-\(gameID.uuidString)",
                     scope: .global,
                     severity: .error,
                     title: "Clearing Failed",
                     body: error.localizedDescription,
                     dismissal: .manual
                 ))
             }
             // Defer the sync enqueue out of the `onGameJoined` callback; the
             // actual CKSyncEngine send drain remains detached in SyncEngine.
             Task { @MainActor [weak self] in
                 await self?.accountPush.reconcilePushRegistration()
             }
         }
 
         // A sibling device consumed (deleted) a directed ping; withdraw any
         // copy of that game's notification we delivered before the deletion
         // reached us, and clear any durable invite row backed by that Ping.
         await syncEngine.setOnPingDeleted { [weak self] pings in
             guard let self else { return }
             try? self.invites.removePendingInvites(forPingRecordNames: Set(pings.map { $0.recordName }))
             await self.badge.refreshAppBadge(reason: "ping deleted")
             for gameID in Set(pings.map { $0.gameID }) {
                 await self.badge.dismissDeliveredNotifications(
                     for: gameID,
                     publishAccountSeen: false
                 )
             }
         }
 
         cloudService.onShareJoined = { [weak self] gameID in
             guard let self else { return }
             // Register the app for notifications now that the user has joined
             // a collaboration. Mirrors the owner path in `onShareSaved` so the
             // app is in Settings > Notifications before any inbound moves.
             await AppDelegate.requestNotificationAuthorizationIfNeeded()
             await self.accountPush.reconcilePushRegistration()
             // Stamp (minting if needed) this account's own derived push address
             // for the joined game, both so the room broadcast below can exclude
             // our own devices and so we're addressable for inbound pushes.
             let ownAddress = self.identity.currentID.flatMap {
                 self.accountPush.setDerivedPushAddress(gameID: gameID, authorID: $0)
             }
             await self.accountPush.publishAccountJoinedPush(gameID: gameID)
             // Tell everyone already in the room that we've joined.
             await self.sessions.publishJoinPush(gameID: gameID, excludeAddress: ownAddress)
         }
 
         // PlayerNamePublisher fans out name changes as `name` Decisions to the
         // account zone and every friend zone. PuzzleDisplayView publishes the
         // open game's Player-record name snapshot directly, which covers
         // first-sync-after-share-create / accept and pre-friendship display.
         playerNamePublisher = PlayerNamePublisher(
             preferences: preferences,
             persistence: persistence,
             authorIdentity: identity,
             enqueuePlayer: { [preferences, syncEngine] gameID, authorID, reason in
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
                 await syncEngine.enqueuePlayer(
                     gameID: gameID,
                     authorID: authorID,
                     reason: reason
                 )
             },
             enqueueNameDecision: { [preferences, syncEngine] authorID, name, version, zoneID, scope in
                 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
                 guard isEnabled else { return }
                 await syncEngine.enqueueNameDecision(
                     authorID: authorID,
                     name: name,
                     version: version,
                     zoneID: zoneID,
                     scope: scope
                 )
             }
         )
 
         guard await ensureICloudSyncStarted() else {
             syncMonitor.note("iCloud sync disabled — engine startup skipped")
             return
         }
         // The scene-active phase that fires alongside cold launch runs the
         // first fetch + push via `syncOnForeground`. Doing it here as well
         // would mean two concurrent CKSyncEngine fetches on a fresh engine.
     }
 
     func enqueueShareAcceptance(_ metadata: CKShare.Metadata) async {
         guard preferences.isICloudSyncEnabled else {
             syncMonitor.note("share acceptance ignored while iCloud sync is disabled")
             return
         }
         pendingShareMetadatas.append(metadata)
         syncMonitor.note(
             "share acceptance queued: container=\(metadata.containerIdentifier)"
         )
         await processPendingShareAcceptances()
     }
 
     func syncOnForeground() async {
         importVisibleNotificationReceipts()
         await movesUpdater.flush()
         guard await ensureICloudSyncStarted() else { return }
         let recoveredMoveCount = await syncEngine.enqueueUnconfirmedMoves()
         if recoveredMoveCount > 0 {
             syncMonitor.note("recovered \(recoveredMoveCount) unconfirmed move(s) for CloudKit enqueue")
         }
         await syncMonitor.run("foreground push") {
             try await syncEngine.pushChanges()
         }
         if isGameListVisible {
             syncMonitor.note("foreground fetch skipped: game list will refresh")
             await freshenGameList(reason: .foreground)
             return
         }
         if let (gameID, scope) = activePuzzleGridTarget() {
             syncMonitor.note("foreground fetch skipped: active puzzle will refresh")
             await freshenPuzzleGrid(gameID: gameID, scope: scope, reason: .foreground)
             return
         }
         await syncMonitor.run("foreground fetch") {
             try await syncEngine.fetchChanges(source: "foreground")
         }
         await refreshSnapshot()
     }
 
     private func importVisibleNotificationReceipts() {
         for entry in VisibleNotificationReceiptLog.drain() {
             eventLog.note(VisibleNotificationReceiptLog.message(for: entry))
         }
     }
 
     func gameListAppeared() async {
         isGameListVisible = true
         await freshenGameList(reason: .appeared)
     }
 
     func gameListDisappeared() {
         isGameListVisible = false
     }
 
     /// Runs `work` to completion under a `UIApplication` background-execution
     /// assertion, so a flush or enqueue that begins as the app heads to the
     /// background still reaches durable state before iOS suspends us. The
     /// assertion is taken **synchronously** — before `work`'s first await — and
     /// released exactly once: when `work` returns, or when iOS signals imminent
     /// expiration, whichever comes first. Best-effort: a force-quit before
     /// `work` lands is the one case this can't cover, so callers pair it with a
     /// foreground reconcile sweep that re-runs anything that didn't finish.
     ///
     /// The assertion owns its own lifetime — no instance slot — so overlapping
     /// calls each hold an independent assertion that self-releases. Correct
     /// only on the main actor: the expiration handler and the completion both
     /// run there, so the `released` latch serialises into a single
     /// `endBackgroundTask` (a double release is a UIKit fault). `name` is the
     /// debug label iOS shows for the assertion.
     func ensureInBackground(_ name: String, _ work: @escaping () async -> Void) {
         var token = UIBackgroundTaskIdentifier.invalid
         var released = false
         func release() {
             guard !released, token != .invalid else { return }
             released = true
             UIApplication.shared.endBackgroundTask(token)
         }
         token = UIApplication.shared.beginBackgroundTask(withName: name, expirationHandler: release)
         Task {
             await work()
             release()
         }
     }
 
     /// Flush buffered cell edits on the way to the background. Held under a
     /// background assertion so the persist + CKSyncEngine enqueue completes
     /// even if the scene is suspended immediately; whatever doesn't land is
     /// recovered by the next foreground's `enqueueUnconfirmedMoves`.
     func syncOnBackground() {
         ensureInBackground("moves-flush") { [weak self] in
             await self?.movesUpdater.flush()
         }
         ensureInBackground("event-log-flush") { [weak self] in
             await self?.eventLog.flush()
         }
     }
 
     /// Pull-to-refresh action for the library. Discovers any zones the
     /// device hasn't seen yet on both database scopes, then runs the normal
     /// engine fetch so any in-flight changes also catch up. Bypasses
     /// CKSyncEngine's database-scope change delivery, which can lag behind
     /// reality when the engine has been idle.
     func refreshLibrary() async {
         await freshenGameList(reason: .manual)
         guard await ensureICloudSyncStarted() else { return }
         await syncMonitor.run("library refresh: engine fetch") {
             try await syncEngine.fetchChanges(source: "library refresh")
         }
         await refreshSnapshot()
     }
 
     func freshenGameList(reason: FreshenReason) async {
         guard await ensureICloudSyncStarted() else { return }
         if let task = gameListFreshenTask {
             syncMonitor.note(
                 "freshen game list \(reason.diagnosticLabel): coalesced into in-flight freshen"
             )
             await task.value
             return
         }
 
         let task = Task { @MainActor in
             await self.runFreshenGameList(reason: reason)
         }
         gameListFreshenTask = task
         await task.value
         gameListFreshenTask = nil
     }
 
     private func runFreshenGameList(reason: FreshenReason) async {
         // The game list is a foreground-visible freshness path, not the live
         // collaboration path. Keep the two database scopes serialized so list
         // appearance and foreground transitions do not create a read burst.
         await freshenGameListScope(
             .private,
             label: "private",
             reason: reason
         )
         await freshenGameListScope(
             .shared,
             label: "shared",
             reason: reason
         )
         await refreshSnapshot()
         // Now that Core Data unread reflects server ground truth, prune any
         // badge-ledger entry no longer backed by unread state or a delivered
         // notification. Reconciling here (rather than once at startup, before
         // the freshen settles) clears orphans like a game whose push stamped
         // the ledger but was since opened — the divergence that otherwise pins
         // the badge above the count the library list shows.
         await badge.reconcileBadgeLedgerWithDeliveredNotifications()
         await badge.refreshAppBadge(reason: "game list freshen")
         await reconcilePendingJournalUploads()
         if shouldRunColdLaunchArchiveReconcile {
             shouldRunColdLaunchArchiveReconcile = false
             // Startup-only backstop for the private-DB archive: re-attempts any
             // completed participant game whose archive never landed, without
             // repeating the scan on every foreground/manual/remote refresh.
             await gameArchiver.reconcileUnarchived()
         }
     }
 
     /// Level-triggered backstop for replay journal uploads. The upload is
     /// normally fired edge-style — once, at local completion or when an inbound
     /// sync reveals the completion. But the local-completion enqueue is async
     /// (journal flush → prefs check → `enqueueJournalUpload`), so a solver who
     /// swipes the app away the instant they win can be suspended before the save
     /// reaches CKSyncEngine's durable state; nothing re-fires it, and replay's
     /// strict completeness then waits on that contributor forever. This sweep
     /// re-enqueues any completed game whose journal hasn't been confirmed
     /// uploaded. A re-send is a benign no-op, and `journalUploaded` (set on the
     /// confirmed save, here for games this device never contributed to) makes it
     /// converge to a no-op rather than re-enqueuing every freshen.
     private func reconcilePendingJournalUploads() async {
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let candidates: [UUID] = ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "completedAt != nil AND journalUploaded == NO")
             return ((try? ctx.fetch(req)) ?? []).compactMap(\.id)
         }
         guard !candidates.isEmpty else { return }
 
         var nothingToUpload: [UUID] = []
         for gameID in candidates {
             if store.localJournalEntries(for: gameID).isEmpty {
                 nothingToUpload.append(gameID)
             } else {
                 await syncEngine.enqueueJournalUpload(gameID: gameID, authorID: authorID)
             }
         }
         guard !nothingToUpload.isEmpty else { return }
 
         // No local journal for these — this device never played them, so there
         // is nothing to publish. Mark them done so the sweep stops reconsidering.
         let toMark = nothingToUpload
         ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id IN %@", toMark)
             for game in (try? ctx.fetch(req)) ?? [] {
                 game.journalUploaded = true
             }
             if ctx.hasChanges { try? ctx.save() }
         }
     }
 
     /// Edge-triggered, immediate companion to `reconcilePendingJournalUploads`:
     /// fired synchronously on completion (`GameStore.onJournalComplete`). Runs
     /// under a background assertion so the journal flush and the CKSyncEngine
     /// enqueue reach durable state even if the user backgrounds the app the
     /// instant they finish; CKSyncEngine then completes the send. The flush runs
     /// regardless of iCloud (it persists local journal entries that would
     /// otherwise be lost on termination); the enqueue is gated on sync being
     /// enabled. A force-quit before the work completes is the one case this
     /// can't cover — that falls to the foreground sweep.
     func beginCompletionJournalUpload(gameID: UUID, authorID: String) {
         ensureInBackground("journal-upload-\(gameID.uuidString)") { [weak self] in
             guard let self else { return }
             // Flush the cell buffer and journal queue first, so both the journal
             // upload and the archive snapshot see the finished grid and full log
             // (the winning move is still in flight when completion fires). The
             // flush persists local entries regardless of iCloud; the cloud-bound
             // steps below are gated on it.
             await self.store.flushCompletionWrites()
             guard self.preferences.isICloudSyncEnabled else { return }
             await self.shareController.closeTicketForCompletedGame(gameID: gameID)
             await self.syncEngine.enqueueJournalUpload(gameID: gameID, authorID: authorID)
             // Snapshot finished participant games to this user's private DB for
             // cross-device durability. A no-op for owned games (already durable)
             // and ones already archived; sequenced after the flush so it can't
             // capture a stale grid or miss the final journal rows.
             await self.gameArchiver.archiveIfNeeded(gameID: gameID)
         }
     }
 
     private func freshenGameList(
         scope: CKDatabase.Scope,
         reason: FreshenReason
     ) async {
         let label: String
         switch scope {
         case .private:
             label = "private"
         case .shared:
             label = "shared"
         case .public:
             return
         @unknown default:
             return
         }
         guard await ensureICloudSyncStarted() else { return }
         if let task = gameListFreshenTask {
             syncMonitor.note(
                 "freshen game list \(reason.diagnosticLabel): \(label) coalesced into in-flight freshen"
             )
             await task.value
             return
         }
         await freshenGameListScope(scope, label: label, reason: reason)
         await refreshSnapshot()
     }
 
     private func freshenGameListScope(
         _ scope: CKDatabase.Scope,
         label: String,
         reason: FreshenReason
     ) async {
         let reasonLabel = reason.diagnosticLabel
         if !shouldRunGameListFreshen(scope: scope, reason: reason, label: label) {
             return
         }
         guard beginGameListFreshen(scope: scope, label: label, reason: reasonLabel) else {
             return
         }
         defer { endGameListFreshen(scope: scope) }
 
         await syncMonitor.run("freshen game list \(reasonLabel): \(label) discovery") {
             _ = try await self.syncEngine.discoverNewZonesDirect(scope: scope)
         }
         let catchUpResult: Int? = await syncMonitor.run("freshen game list \(reasonLabel): \(label) game/moves") {
             try await self.syncEngine.fetchKnownGameMovesDirect(scope: scope)
         }
         let inviteResult: Int? = await syncMonitor.run("freshen game list \(reasonLabel): \(label) invites") {
             try await self.syncEngine.fetchFriendInvitesDirect(scope: scope)
         }
         if inviteResult != nil {
             await badge.refreshAppBadge(reason: "invite freshen")
         }
         if catchUpResult != nil {
             noteGameListFreshenCompleted(scope: scope)
         }
     }
 
     /// Decides whether a game-list freshen should run for this scope. The
     /// freshen polls each active zone for new records and enumerates
     /// database zones for newly-shared games; between inbound pushes it
     /// can't surface anything new, so we skip when the push signal hasn't
     /// moved since the last successful run and the staleness budget hasn't
     /// been exhausted. `.manual` (pull-to-refresh) always runs because the
     /// user explicitly asked.
     private func shouldRunGameListFreshen(
         scope: CKDatabase.Scope,
         reason: FreshenReason,
         label: String
     ) -> Bool {
         if reason == .manual {
             return true
         }
         guard let last = lastGameListFreshenAt(scope: scope) else {
             return true
         }
         if let pushAt = lastRemoteNotificationAt, pushAt > last {
             return true
         }
         let elapsed = Date().timeIntervalSince(last)
         if elapsed >= gameListFreshenCooldown {
             return true
         }
         let elapsedSeconds = Int(elapsed.rounded())
         syncMonitor.note(
             "freshen game list \(reason.diagnosticLabel): \(label) skipped (cooldown, last \(elapsedSeconds)s ago)"
         )
         return false
     }
 
     private func lastGameListFreshenAt(scope: CKDatabase.Scope) -> Date? {
         switch scope {
         case .private:
             return lastPrivateGameListFreshenAt
         case .shared:
             return lastSharedGameListFreshenAt
         case .public:
             return nil
         @unknown default:
             return nil
         }
     }
 
     private func noteGameListFreshenCompleted(scope: CKDatabase.Scope) {
         let now = Date()
         switch scope {
         case .private:
             lastPrivateGameListFreshenAt = now
         case .shared:
             lastSharedGameListFreshenAt = now
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     private func beginGameListFreshen(
         scope: CKDatabase.Scope,
         label: String,
         reason: String
     ) -> Bool {
         switch scope {
         case .private:
             guard !isFresheningPrivateGameList else {
                 syncMonitor.note("freshen game list \(reason): \(label) coalesced into in-flight freshen")
                 return false
             }
             isFresheningPrivateGameList = true
             return true
         case .shared:
             guard !isFresheningSharedGameList else {
                 syncMonitor.note("freshen game list \(reason): \(label) coalesced into in-flight freshen")
                 return false
             }
             isFresheningSharedGameList = true
             return true
         case .public:
             return false
         @unknown default:
             return false
         }
     }
 
     private func endGameListFreshen(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             isFresheningPrivateGameList = false
         case .shared:
             isFresheningSharedGameList = false
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     func freshenPuzzleGrid(
         gameID: UUID,
         scope: CKDatabase.Scope,
         reason: FreshenReason
     ) async {
         await movesUpdater.flush()
         guard await ensureICloudSyncStarted() else { return }
         let label = reason.diagnosticLabel
         if reason == .remote,
            shouldSkipRecentRemotePuzzleGridFreshen(
                gameID: gameID,
                scope: scope,
                label: label
            ) {
             return
         }
         guard beginPuzzleGridFreshen(gameID: gameID, scope: scope, reason: label) else {
             return
         }
         defer {
             endPuzzleGridFreshen(gameID: gameID, scope: scope)
             if reason == .remote {
                 noteRemotePuzzleGridFreshenCompleted(gameID: gameID, scope: scope)
             }
         }
 
         await syncMonitor.run("freshen puzzle grid \(label)") {
             let handled = try await syncEngine.fetchGameDirect(
                 scope: scope,
                 gameID: gameID
             )
             if !handled {
                 try await syncEngine.fetchChanges(source: "puzzle grid \(label)")
             }
         }
         await refreshSnapshot()
     }
 
     private func beginPuzzleGridFreshen(
         gameID: UUID,
         scope: CKDatabase.Scope,
         reason: String
     ) -> Bool {
         let key = puzzleGridFreshenKey(gameID: gameID, scope: scope)
         guard !fresheningPuzzleGridKeys.contains(key) else {
             syncMonitor.note(
                 "freshen puzzle grid \(reason): \(scopeLabel(scope)) \(gameID.uuidString.prefix(8)) coalesced into in-flight freshen"
             )
             return false
         }
         fresheningPuzzleGridKeys.insert(key)
         return true
     }
 
     private func endPuzzleGridFreshen(gameID: UUID, scope: CKDatabase.Scope) {
         fresheningPuzzleGridKeys.remove(puzzleGridFreshenKey(gameID: gameID, scope: scope))
     }
 
     private func shouldSkipRecentRemotePuzzleGridFreshen(
         gameID: UUID,
         scope: CKDatabase.Scope,
         label: String
     ) -> Bool {
         // The debounce only suppresses refreshes that the live channel already
         // covers. When the engagement websocket is live for this game, grid
         // deltas arrive over it and the push-driven fetch is redundant, so
         // collapsing a burst of pushes is harmless. When it is not live, the
         // CK-push path is the only thing converging the grid — never skip it,
         // or convergence stalls exactly when the live overlay is down.
         guard engagementStatus.isLive(gameID: gameID) else { return false }
         let key = puzzleGridFreshenKey(gameID: gameID, scope: scope)
         guard let last = lastRemotePuzzleGridFreshenAt[key] else { return false }
         let elapsed = Date().timeIntervalSince(last)
         guard elapsed < remotePuzzleGridFreshenDebounce else { return false }
         syncMonitor.note(
             "freshen puzzle grid \(label): \(scopeLabel(scope)) \(gameID.uuidString.prefix(8)) skipped (recent remote refresh \(Int(elapsed.rounded()))s ago)"
         )
         return true
     }
 
     private func noteRemotePuzzleGridFreshenCompleted(gameID: UUID, scope: CKDatabase.Scope) {
         lastRemotePuzzleGridFreshenAt[puzzleGridFreshenKey(gameID: gameID, scope: scope)] = Date()
     }
 
     private func puzzleGridFreshenKey(gameID: UUID, scope: CKDatabase.Scope) -> String {
         "\(scopeLabel(scope)):\(gameID.uuidString)"
     }
 
     private func scopeLabel(_ scope: CKDatabase.Scope) -> String {
         switch scope {
         case .private:
             return "private"
         case .shared:
             return "shared"
         case .public:
             return "public"
         @unknown default:
             return "unknown"
         }
     }
 
     func makePlayerRoster(for gameID: UUID, preferences: PlayerPreferences) -> PlayerRoster {
         PlayerRoster(
             gameID: gameID,
             authorIdentity: identity,
             preferences: preferences,
             persistence: persistence,
             container: ckContainer,
             engagementStore: engagementStore,
             tracer: { [syncMonitor] message in syncMonitor.note(message) }
         )
     }
 
     private func handleRemoteNotification(
         summary: String,
         scope: CKDatabase.Scope?,
         event: PushPayload.Event?,
         gameID: UUID?,
         kind: String?,
         senderDeviceID: String?,
         readAt: Date?,
         isBackground: Bool
     ) async {
         // Authoritative foreground correction. A content-available push is, by
         // definition, not the user looking at this app, so when the OS reports
         // we're backgrounded, pull the cached `isAppForeground` flag false now.
         // `scenePhase`'s `.onChange` — the flag's only other writer — never
         // fires for the *initial* phase of a process launched or woken straight
         // into the background, so the flag otherwise keeps its optimistic `true`
         // default and every background wake slips past the presence and
         // engagement foreground gates: re-arming a departed peer's read lease
         // (the ghost) and re-dialling the live socket it can't sustain. Only
         // ever downgrade here — a genuine foreground is restored by the
         // `.active` scenePhase transition, never by a push.
         if isBackground {
             noteAppForeground(false)
         }
         guard preferences.isICloudSyncEnabled else {
             syncMonitor.note("remote notification ignored while iCloud sync is disabled")
             return
         }
         guard await ensureICloudSyncStarted() else { return }
         lastRemoteNotificationAt = Date()
         syncMonitor.note("remote notification: \(summary)")
 
         if await handleAccountControlPush(
             kind: kind,
             gameID: gameID,
             senderDeviceID: senderDeviceID,
             readAt: readAt
         ) {
             return
         }
 
         if event == .replay {
             let label = gameID.map { String($0.uuidString.prefix(8)) } ?? "unknown"
             syncMonitor.note("push(replay): syncing game \(label)")
             await syncMonitor.run("replay push fetch") {
                 try await syncEngine.fetchChanges(source: "replay push")
             }
             await refreshSnapshot()
             await reconcilePendingJournalUploads()
             return
         }
 
         guard let scope, scope != .public else {
             await syncMonitor.run("remote-notification fetch") {
                 try await syncEngine.fetchChanges(source: "push")
             }
             await refreshSnapshot()
             return
         }
 
         guard beginRemoteNotificationHandling(scope: scope) else { return }
         defer { endRemoteNotificationHandling(scope: scope) }
 
         cancelBackgroundPushCatchUp(scope: scope)
 
         // A share accept is downloading the puzzle asset on the joining screen.
         // Don't fan out a session scan, zone discovery, or fetchChanges against
         // the shared database while it does — the deferred catch-up runs once
         // the burst (and the join) settle.
         if scope == .shared, isAcceptingSharedGame {
             syncMonitor.note("shared remote notification deferred during share acceptance")
             scheduleBackgroundPushCatchUp(scope: scope)
             await refreshSnapshot()
             return
         }
 
         if isBackground {
             scheduleBackgroundSessionScan(scope: scope)
             scheduleBackgroundPushCatchUp(scope: scope)
             await refreshSnapshot()
             return
         }
 
         if isGameListVisible {
             syncMonitor.note("remote notification: game list visible, refreshing list only")
             await freshenGameList(scope: scope, reason: .remote)
             scheduleBackgroundPushCatchUp(scope: scope)
             await refreshSnapshot()
             return
         }
 
         if let activeGameID = activeGameID(in: scope) {
             // Hot path: collaborator activity on the open puzzle. The Puzzle
             // Grid surface owns the direct Game/Moves/Player fetch so push
             // handling and open-puzzle polling coalesce instead of duplicating
             // the same active-zone query.
             syncMonitor.note("remote notification: active puzzle visible, refreshing game only")
             await freshenPuzzleGrid(
                 gameID: activeGameID,
                 scope: scope,
                 reason: .remote
             )
         } else {
             // Cold path: no puzzle open. Discover any zones this device
             // hasn't seen yet (e.g. a freshly-accepted share or a game
             // started on another device of the same iCloud user). The broader
             // game/moves catch-up is delayed below so a cold push doesn't fan
             // out multiple immediate CloudKit read paths.
             await syncMonitor.run("remote-notification zone discovery") {
                 _ = try await self.syncEngine.discoverNewZonesDirect(scope: scope)
             }
             scheduleBackgroundPushCatchUp(scope: scope)
         }
 
         await refreshSnapshot()
     }
 
     private func handleAccountControlPush(
         kind: String?,
         gameID: UUID?,
         senderDeviceID: String?,
         readAt: Date?
     ) async -> Bool {
         guard let kind,
               kind == AccountPushCoordinator.accountJoinedPushKind || kind == AccountPushCoordinator.accountSeenPushKind
         else { return false }
         if senderDeviceID == RecordSerializer.localDeviceID {
             syncMonitor.note("push(\(kind)): ignored self-send")
             return true
         }
         guard let gameID else {
             syncMonitor.note("push(\(kind)): ignored (no gameID)")
             return true
         }
 
         switch kind {
         case AccountPushCoordinator.accountJoinedPushKind:
             syncMonitor.note("push(accountJoined): sibling joined \(gameID.uuidString.prefix(8))")
             await syncMonitor.run("account-joined shared discovery") {
                 try await syncEngine.fetchChanges(source: "account joined")
             }
             await freshenGameList(scope: .shared, reason: .remote)
             await accountPush.reconcilePushRegistration()
             await refreshSnapshot()
         case AccountPushCoordinator.accountSeenPushKind:
             guard let readAt else {
                 syncMonitor.note("push(accountSeen): ignored (no readAt)")
                 return true
             }
             let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, readAt: readAt)
             syncMonitor.note(
                 "push(accountSeen): sibling saw \(gameID.uuidString.prefix(8)) " +
                 "readAt=\(readAt.ISO8601Format()) " +
                 "was=\(previous?.ISO8601Format() ?? "—")" +
                 (adopted ? "" : " (no-op)")
             )
             // The catch-up baseline is no longer recomputed here — it arrives,
             // accurate, on the sibling's `Player.sessionSnapshot` via the
             // record sync this push's companion DB change triggers. This fast
             // push is now only the cross-device notification-dismissal signal.
             // A forward-dated readAt is an active presence lease: the sibling is
             // in this game right now and has seen its events live, so retract
             // even the unread-marking notifications (win/resign/pause) from this
             // device — the "soon-swept" half of sending to every device. A past
             // readAt is a plain read watermark (the sibling left), where we still
             // preserve genuinely-unread alerts.
             let siblingPresent = readAt > Date()
             await badge.dismissDeliveredNotifications(
                 for: gameID,
                 seenAt: readAt,
                 publishAccountSeen: false,
                 preserveUnread: !siblingPresent
             )
         default:
             break
         }
         return true
     }
 
     private func activePuzzleGridTarget() -> (UUID, CKDatabase.Scope)? {
         guard let entity = store.currentEntity,
               let gameID = entity.id
         else { return nil }
         switch entity.databaseScope {
         case 0:
             return (gameID, .private)
         case 1:
             return (gameID, .shared)
         default:
             return nil
         }
     }
 
     private func beginRemoteNotificationHandling(scope: CKDatabase.Scope) -> Bool {
         switch scope {
         case .private:
             guard !isHandlingPrivateRemoteNotification else {
                 syncMonitor.note("private remote notification coalesced into in-flight handler")
                 return false
             }
             isHandlingPrivateRemoteNotification = true
             return true
         case .shared:
             guard !isHandlingSharedRemoteNotification else {
                 syncMonitor.note("shared remote notification coalesced into in-flight handler")
                 return false
             }
             isHandlingSharedRemoteNotification = true
             return true
         case .public:
             return false
         @unknown default:
             return false
         }
     }
 
     private func endRemoteNotificationHandling(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             isHandlingPrivateRemoteNotification = false
         case .shared:
             isHandlingSharedRemoteNotification = false
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     private func cancelBackgroundPushCatchUp(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             privatePushCatchUpTask?.cancel()
             privatePushCatchUpTask = nil
         case .shared:
             sharedPushCatchUpTask?.cancel()
             sharedPushCatchUpTask = nil
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     private func scheduleBackgroundPushCatchUp(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             privatePushCatchUpTask?.cancel()
             privatePushCatchUpTask = makeBackgroundPushCatchUpTask(scope: scope, label: "private")
         case .shared:
             sharedPushCatchUpTask?.cancel()
             sharedPushCatchUpTask = makeBackgroundPushCatchUpTask(scope: scope, label: "shared")
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     /// Trailing-edge window over which a burst of background pushes is collapsed
     /// into a single session scan. A collaborator playing live writes a record
     /// every second or two; running the full-zone scan per record turned a
     /// backgrounded join into minutes of back-to-back fetches.
     private static let backgroundSessionScanDebounce: UInt64 = 5_000_000_000
 
     /// Coalesces background-push session scans. Unlike the catch-up scheduler
     /// this does *not* cancel a pending scan — under sustained activity a
     /// cancel-and-reschedule would push the scan out indefinitely and starve
     /// presence. The first push arms a scan; later pushes within the window are
     /// no-ops; the task clears its own handle when it runs.
     private func scheduleBackgroundSessionScan(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             guard privateSessionScanTask == nil else { return }
             privateSessionScanTask = makeBackgroundSessionScanTask(scope: scope)
         case .shared:
             guard sharedSessionScanTask == nil else { return }
             sharedSessionScanTask = makeBackgroundSessionScanTask(scope: scope)
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     private func clearBackgroundSessionScanTask(scope: CKDatabase.Scope) {
         switch scope {
         case .private:
             privateSessionScanTask = nil
         case .shared:
             sharedSessionScanTask = nil
         case .public:
             return
         @unknown default:
             return
         }
     }
 
     private func makeBackgroundSessionScanTask(scope: CKDatabase.Scope) -> Task<Void, Never> {
         Task { @MainActor in
             defer { clearBackgroundSessionScanTask(scope: scope) }
             do {
                 try await Task.sleep(nanoseconds: Self.backgroundSessionScanDebounce)
             } catch {
                 return
             }
             guard !Task.isCancelled else { return }
             guard await ensureICloudSyncStarted() else { return }
             let result = await syncMonitor.run("remote-notification background session scan") {
                 try await syncEngine.fetchBackgroundSessionsDirect(scope: scope)
             }
             if let result {
                 // The receiver-side `presentBegins` path is no longer wired
                 // up. The catch-up banner that summarises peer adds/clears
                 // still consumes the SessionMonitor buckets via `consumeOnOpen`
                 // — see `handlePuzzleOpened`.
                 if result.isEmpty {
                     syncMonitor.note("remote-notification background session scan: no active sessions")
                 }
             }
             await refreshSnapshot()
         }
     }
 
     private func makeBackgroundPushCatchUpTask(
         scope: CKDatabase.Scope,
         label: String
     ) -> Task<Void, Never> {
         syncMonitor.note("\(label) game/moves catch-up scheduled")
         return Task { @MainActor in
             let shortMoveCount = await runBackgroundPushCatchUp(
                 scope: scope,
                 label: label,
                 delayNanoseconds: 5_000_000_000,
                 phaseSuffix: "short"
             )
             guard !Task.isCancelled else { return }
             guard shortMoveCount == 0 else {
                 syncMonitor.note(
                     "\(label) game/moves catch-up long skipped after short fetched \(shortMoveCount) move record(s)"
                 )
                 return
             }
             _ = await runBackgroundPushCatchUp(
                 scope: scope,
                 label: label,
                 delayNanoseconds: 15_000_000_000,
                 phaseSuffix: "long"
             )
         }
     }
 
     private func runBackgroundPushCatchUp(
         scope: CKDatabase.Scope,
         label: String,
         delayNanoseconds: UInt64,
         phaseSuffix: String
     ) async -> Int {
         do {
             try await Task.sleep(nanoseconds: delayNanoseconds)
         } catch {
             return 0
         }
         guard !Task.isCancelled else { return 0 }
         guard await ensureICloudSyncStarted() else { return 0 }
         guard beginGameListFreshen(
             scope: scope,
             label: label,
             reason: "remote \(phaseSuffix) catch-up"
         ) else {
             return 0
         }
         defer { endGameListFreshen(scope: scope) }
 
         let moveCount = await syncMonitor.run("remote-notification \(label) game/moves catch-up \(phaseSuffix)") {
             try await syncEngine.fetchKnownGameMovesDirect(scope: scope)
         }
         await refreshSnapshot()
         return moveCount ?? 0
     }
 
     private func activeGameID(in scope: CKDatabase.Scope) -> UUID? {
         guard let target = activePuzzleGridTarget() else { return nil }
         return target.1 == scope ? target.0 : nil
     }
 
     private func ensureICloudSyncStarted() async -> Bool {
         guard preferences.isICloudSyncEnabled else { return false }
         guard !syncStarted else { return true }
         if let inFlight = syncStartTask { return await inFlight.value }
 
         let task = Task { @MainActor in
             await identity.refresh(using: ckContainer)
             pushClient?.updateAuthorID(identity.currentID)
             await syncEngine.start()
             syncStarted = true
 
             let recoveredMoveCount = await syncEngine.enqueueUnconfirmedMoves()
             if recoveredMoveCount > 0 {
                 syncMonitor.note("recovered \(recoveredMoveCount) unconfirmed move(s) for CloudKit enqueue")
             }
             isReadyForShareAcceptance = true
             await processPendingShareAcceptances()
             // Only when this device has nothing cached to derive from is
             // `reconcilePushRegistration` about to *mint* a fresh secret/address
             // — and minting before a sibling's already-published value has been
             // fetched is what enqueues divergent per-game addresses that briefly
             // clobber the converged set. `start()` only constructs the engines,
             // so fetch the account zone first in exactly that case, letting the
             // inbound path (`onAccountPushSecret`) adopt and cache the winner so
             // reconcile derives from it instead of minting. On every later
             // launch the value is already cached, so this is skipped and startup
             // is unchanged. If the fetch throws, `run` swallows it and reconcile
             // still runs (no worse than before).
             if let authorID = identity.currentID, !authorID.isEmpty,
                !accountPush.hasCachedAccountPushCredentials(authorID: authorID) {
                 await syncMonitor.run("startup account sync") {
                     try await syncEngine.fetchChanges(source: "startup")
                 }
             }
             await accountPush.reconcilePushRegistration()
             return true
         }
         syncStartTask = task
         let result = await task.value
         syncStartTask = nil
         return result
     }
 
     /// Parses the silent-push payload into a short, human-readable summary
     /// (database scope, notification type, subscription ID, pruned flag).
     /// Used by the diagnostics log to confirm whether shared-DB pushes are
     /// actually being delivered to the device.
     static func describePush(userInfo: [AnyHashable: Any]) -> String {
         guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo) else {
             let kind = (userInfo["kind"] as? String) ?? "<nil>"
             let gameID = (userInfo["gameID"] as? String) ?? "<nil>"
             return "custom kind=\(kind) gameID=\(gameID)"
         }
         let kind: String
         let scope: CKDatabase.Scope?
         switch note {
         case let n as CKDatabaseNotification:
             kind = "database"
             scope = n.databaseScope
         case let n as CKRecordZoneNotification:
             kind = "recordZone"
             scope = n.databaseScope
         case let n as CKQueryNotification:
             kind = "query(\(n.queryNotificationReason.rawValue))"
             scope = n.databaseScope
         default:
             kind = "type(\(note.notificationType.rawValue))"
             scope = nil
         }
         let scopeLabel: String
         switch scope {
         case .private: scopeLabel = "private"
         case .shared: scopeLabel = "shared"
         case .public: scopeLabel = "public"
         case .none: scopeLabel = "n/a"
         case .some(let other): scopeLabel = "scope(\(other.rawValue))"
         }
         let sub = note.subscriptionID ?? "<nil>"
         return "scope=\(scopeLabel) kind=\(kind) sub=\(sub) pruned=\(note.isPruned)"
     }
 
     static func databaseScope(fromPush userInfo: [AnyHashable: Any]) -> CKDatabase.Scope? {
         guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo) else {
             return nil
         }
         switch note {
         case let n as CKDatabaseNotification:
             return n.databaseScope
         case let n as CKRecordZoneNotification:
             return n.databaseScope
         case let n as CKQueryNotification:
             return n.databaseScope
         default:
             return nil
         }
     }
 
     private func processPendingShareAcceptances() async {
         guard isReadyForShareAcceptance, !isProcessingShareAcceptanceQueue else { return }
         isProcessingShareAcceptanceQueue = true
         isAcceptingSharedGame = true
         defer {
             isProcessingShareAcceptanceQueue = false
             isAcceptingSharedGame = false
         }
 
         while !pendingShareMetadatas.isEmpty {
             let metadata = pendingShareMetadatas.removeFirst()
             do {
                 let outcome = try await cloudService.acceptShare(metadata: metadata)
                 // Accepted but the puzzle hasn't synced in yet — reassure the
                 // user it's coming, mirroring the link-tap path.
                 if case .pendingSync = outcome {
                     announcements.post(.puzzleStillSyncing())
                 }
             } catch {
                 // The CloudService already recorded the detailed CloudKit
                 // failure; OS-delivered share acceptances have no caller to
                 // surface the error to, so keep draining the queue.
             }
         }
     }
 
     private func refreshSnapshot() async {
         let snapshot = await syncEngine.diagnosticSnapshot()
         syncMonitor.updateSnapshot(snapshot)
     }
 
     /// Publishes this account's read horizon for other-author moves by
     /// updating `GameEntity.lastReadOtherMoveAt` and re-enqueuing its Player
     /// record. Active puzzle sessions write a future lease and refresh it
     /// only when less than `readLeaseRefreshFloor` remains; exits/background
     /// write the current time, which can intentionally close that lease.
     /// Records the app's foreground/active state. The one place the "user is
     /// actively using the app" fact is set; `publishReadCursor` reads it to
     /// decide whether a presence-lease renewal is legitimate.
     func noteAppForeground(_ foreground: Bool) {
         isAppForeground = foreground
     }
 
     func publishReadCursor(
         for gameID: UUID,
         mode: ReadCursorPublishMode = .activeLease,
         requireActivePuzzle: Bool = false
     ) async {
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         // A read lease asserts "the user is actively present on this puzzle," so
         // only a foregrounded app may advance it. A background CKSyncEngine wake
         // must never re-arm presence — that is what resurrected a departed
         // peer's cursor and held the engagement room open. The `.currentTime`
         // collapse is always allowed: we must be able to *end* the lease on the
         // way to the background.
         if case .activeLease = mode, !isAppForeground {
             syncMonitor.note("readCursor(activeLease) skipped for \(gameID.uuidString): backgrounded")
             return
         }
         // A re-assert triggered by an inbound sibling close (`requireActivePuzzle`)
         // is decided before an `await`, so the user may have left the puzzle in
         // the gap. Re-check here, synchronously in the write's critical section,
         // that this is still the puzzle on screen. The strict `activePuzzleID`
         // (no leave-grace tail) flips synchronously on `.onDisappear`/`.background`,
         // so a concurrent leave deterministically wins and we never strand a
         // future lease on a puzzle no device is actually viewing.
         if case .activeLease = mode,
            requireActivePuzzle,
            NotificationState.activePuzzleID() != gameID {
             syncMonitor.note("readCursor(activeLease) skipped for \(gameID.uuidString): not active puzzle")
             return
         }
         let now = Date()
         let didUpdate: Bool
         switch mode {
         case .activeLease:
             let readAt = now.addingTimeInterval(Self.readLeaseDuration)
             didUpdate = store.setReadCursor(
                 gameID: gameID,
                 readAt: readAt,
                 minimumExistingReadAt: now.addingTimeInterval(Self.readLeaseRefreshFloor)
             )
             if didUpdate {
                 // Ghost-peer probe: every active-session lease passes through
                 // here. `suppressed` is "is this device actually viewing this
                 // puzzle right now." A mint with suppressed=false is a presence
                 // lease asserted while the user isn't looking — the resurrection
                 // — and the foreground flag tells us which gate let it through.
                 syncMonitor.note(
                     "lease MINT[\(gameID.uuidString.prefix(8))] " +
                     "readAt=\(readAt.ISO8601Format()) foreground=\(isAppForeground) " +
                     "suppressed=\(NotificationState.isSuppressed(gameID: gameID))"
                 )
                 // Mirror the renewed lease into the badge ledger so an NSE
                 // push landing mid-session stays suppressed past the open's
                 // initial horizon (the open stamps one via
                 // `dismissDeliveredNotifications`; this covers the refreshes).
                 BadgeState.adoptReadHorizon(gameID: gameID, horizon: readAt)
                 await accountPush.publishAccountSeenPush(gameID: gameID, readAt: readAt)
             }
         case .currentTime:
             // Leaving / backgrounding: collapse the presence lease to now and,
             // in lockstep, advance the read watermark to now — the user was
             // looking right up to here, so they've seen everything through now.
             // The watermark write is what stops a peer re-summarising moves we
             // saw live just before leaving; it never reaches into the future.
             let collapsed = store.setReadCursor(gameID: gameID, readAt: now)
             let advanced = store.advanceReadThrough(gameID: gameID, through: now)
             // Collapse the badge ledger's suppression horizon in the same
             // lockstep. This write is local (App Group defaults), so it lands
             // even when the CloudKit lease collapse doesn't — an NSE push
             // arriving a minute after leave badges instead of being swallowed
             // for the rest of the lease window.
             BadgeState.markSeen(gameID: gameID, at: now)
             BadgeState.collapseSuppression(gameID: gameID, to: now)
             didUpdate = collapsed || advanced
         }
         guard didUpdate else { return }
         let reason: String
         let drain: Bool
         switch mode {
         case .activeLease:
             reason = "readCursor(activeLease)"
             drain = true
         case .currentTime:
             // Exit/background cursor: enqueue durably but don't force a send.
             // Live presence rides the engagement socket; CloudKit carries the
             // cursor on its own schedule, off the scarce suspension budget.
             reason = "readCursor(currentTime)"
             drain = false
         }
         await syncEngine.enqueuePlayer(
             gameID: gameID,
             authorID: authorID,
             reason: reason,
             drain: drain
         )
     }
 
     /// Diagnostic: logs each participant's `Player.readAt` lease for `gameID`
     /// at open, so a lingering peer cursor or engagement room can be reasoned
     /// about from the device log alone — the lease value is otherwise only
     /// visible server-side. One line per player: self/peer, author prefix,
     /// name, the raw `readAt` (UTC), and whether it currently reads as present
     /// (`+Ns` until expiry) or lapsed (`Ns ago`).
     func logPlayerLeaseSnapshot(gameID: UUID) async {
         let localAuthorID = identity.currentID
         let context = persistence.container.newBackgroundContext()
         let lines: [String] = await withCheckedContinuation { continuation in
             context.perform {
                 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 req.predicate = NSPredicate(format: "game.id == %@", gameID as CVarArg)
                 let now = Date()
                 let players = (try? context.fetch(req)) ?? []
                 let lines = players.map { player -> String in
                     let author = player.authorID ?? "?"
                     let isLocal = author == CKCurrentUserDefaultName
                         || (localAuthorID.map { author == $0 } ?? false)
                     let tag = isLocal ? "self" : "peer"
                     let name = (player.name?.isEmpty == false) ? player.name! : "—"
                     guard let readAt = player.readAt else {
                         return "\(tag) \(author.prefix(8)) [\(name)] readAt=nil"
                     }
                     let delta = Int(readAt.timeIntervalSince(now))
                     let state = delta > 0 ? "present, +\(delta)s" : "absent, \(-delta)s ago"
                     return "\(tag) \(author.prefix(8)) [\(name)] readAt=\(readAt.ISO8601Format()) (\(state))"
                 }
                 continuation.resume(returning: lines)
             }
         }
         syncMonitor.note("open lease snapshot \(gameID.uuidString.prefix(8)): \(lines.count) player(s)")
         for line in lines {
             syncMonitor.note("  \(line)")
         }
     }
 
     /// Builds the `GameStore.onGameDeleted` callback. Extracted so tests can
     /// drive the exact same closure that production wires up — keeps the
     /// cursor-cleanup branch from drifting silently. (Friend colours need no
     /// cleanup: they are derived on the fly, never persisted per game.)
     static func makeOnGameDeleted(
         syncEngine: SyncEngine,
         cursorStore: GameCursorStore? = nil,
         viewedStore: GameViewedStore? = nil
     ) -> (GameCloudDeletion) -> Void {
         { deletion in
             cursorStore?.clearCursor(forGame: deletion.gameID)
             viewedStore?.clearLastViewed(forGame: deletion.gameID)
             Task { await syncEngine.enqueueDeleteGame(deletion) }
         }
     }
 
     /// True iff some non-local participant in `gameID` currently holds a
     /// valid read lease (`readAt` in the future). The active-lease cursor —
     /// set ~10 minutes ahead while the puzzle is open and collapsed to `now`
     /// on leave — is the presence signal: it survives think-time without
     /// cursor movement and self-expires if a peer vanishes uncleanly, so a
     /// solo solver in a shared puzzle stops treating a departed peer as
     /// present within the lease window rather than on every paused minute.
     static func hasPresentPeer(
         persistence: PersistenceController,
         gameID: UUID,
         localAuthorID: String?
     ) async -> Bool {
         let context = persistence.container.newBackgroundContext()
         return await withCheckedContinuation { continuation in
             context.perform {
                 let now = Date()
                 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 req.predicate = NSPredicate(
                     format: "game.id == %@ AND readAt > %@",
                     gameID as CVarArg,
                     PeerPresence.presenceCutoff(asOf: now) as NSDate
                 )
                 let players = (try? context.fetch(req)) ?? []
                 let hasPeer = players.contains { player in
                     guard let authorID = player.authorID, !authorID.isEmpty else { return false }
                     if authorID == CKCurrentUserDefaultName { return false }
                     if let localAuthorID, !localAuthorID.isEmpty, authorID == localAuthorID { return false }
                     return PeerPresence.isPresent(readAt: player.readAt, asOf: now)
                 }
                 continuation.resume(returning: hasPeer)
             }
         }
     }
 
     /// The earliest future `readAt` among non-local participants in `gameID` —
     /// i.e. when the soonest peer lease lapses — or `nil` if no peer is
     /// present. `nil` is the same condition `hasPresentPeer` reports as absent,
     /// so callers can derive presence from this and also schedule against the
     /// expiry instant.
     static func soonestPeerLease(
         persistence: PersistenceController,
         gameID: UUID,
         localAuthorID: String?
     ) async -> Date? {
         let context = persistence.container.newBackgroundContext()
         return await withCheckedContinuation { continuation in
             context.perform {
                 let now = Date()
                 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 req.predicate = NSPredicate(
                     format: "game.id == %@ AND readAt > %@",
                     gameID as CVarArg,
                     PeerPresence.presenceCutoff(asOf: now) as NSDate
                 )
                 var soonest: Date?
                 for player in (try? context.fetch(req)) ?? [] {
                     guard let authorID = player.authorID, !authorID.isEmpty else { continue }
                     if authorID == CKCurrentUserDefaultName { continue }
                     if let localAuthorID, !localAuthorID.isEmpty, authorID == localAuthorID { continue }
                     guard let readAt = player.readAt,
                           PeerPresence.isPresent(readAt: readAt, asOf: now) else { continue }
                     if soonest == nil || readAt < soonest! { soonest = readAt }
                 }
                 continuation.resume(returning: soonest)
             }
         }
     }
 
     static func presentPeers(
         persistence: PersistenceController,
         gameIDs: Set<UUID>?,
         localAuthorID: String?
     ) async -> [UUID: [String]] {
         let context = persistence.container.newBackgroundContext()
         return await withCheckedContinuation { continuation in
             context.perform {
                 let now = Date()
                 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 var predicates = [
                     NSPredicate(format: "readAt > %@", PeerPresence.presenceCutoff(asOf: now) as NSDate)
                 ]
                 if let gameIDs, !gameIDs.isEmpty {
                     predicates.append(NSPredicate(format: "game.id IN %@", Array(gameIDs)))
                 }
                 if let localAuthorID, !localAuthorID.isEmpty {
                     predicates.append(NSPredicate(format: "authorID != %@", localAuthorID))
                 }
                 req.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: predicates)
 
                 var result: [UUID: Set<String>] = [:]
                 for player in (try? context.fetch(req)) ?? [] {
                     guard let gameID = player.game?.id,
                           let authorID = player.authorID,
                           !authorID.isEmpty,
                           authorID != CKCurrentUserDefaultName,
                           PeerPresence.isPresent(readAt: player.readAt, asOf: now) else { continue }
                     result[gameID, default: []].insert(authorID)
                 }
                 continuation.resume(returning: result.mapValues { Array($0) })
             }
         }
     }
 
 }