crossmate

AppServices.swift (133903B)

---

 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 friends 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 friend 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 {
     /// Which library to seed. The two differ only in the collaborative
     /// showcase game's roster: development wants four players (you + three
     /// friends) so all four attribution tints can be eyeballed at once, while
     /// marketing must never depict more than three players.
     enum Profile {
         case development
         case marketing
     }
 
     /// The local user's authorID in demo mode, injected into `AuthorIdentity`
     /// so the seeded friends classify as remote players. Kept distinct from
     /// every friend id below.
     static let localAuthorID = "_demo-you"
 
     private static let alice = "_demo-alice"
     private static let bob = "_demo-bob"
     private static let carol = "_demo-carol"
 
     private static let friends: [(id: String, name: String)] = [
         (alice, "Alice"),
         (bob, "Bob"),
         (carol, "Carol"),
     ]
 
     /// One seeded game backed by a real bundled 15×15 starter. `fillAuthors`
     /// are the authors given filled cells (drives the desaturated attribution
     /// tints and, together with `participants`, the Game List colour strip);
     /// empty leaves the grid blank (or fully solved, when `completed`).
     private struct GameSpec {
         let title: String
         let resourceID: String
         let participants: [String]
         let fillAuthors: [String]
         let completed: Bool
     }
 
     /// The demo library for `profile`, backed by real bundled 15×15 starters so
     /// the Game List shows full grids rather than toy puzzles. Each game draws a
     /// distinct puzzle so the row thumbnails differ; the mix spans shared/solo
     /// and in-progress/completed to exercise every card state.
     private static func games(for profile: Profile) -> [GameSpec] {
         // The only per-profile difference: how many players share (and have
         // filled cells in) the in-progress showcase game.
         let showcase: GameSpec = switch profile {
         case .development:
             GameSpec(
                 title: "Tuesday Crossword",
                 resourceID: "cm-starter-0001",
                 participants: [alice, bob, carol],
                 fillAuthors: [localAuthorID, alice, bob, carol],
                 completed: false
             )
         case .marketing:
             GameSpec(
                 title: "Tuesday Crossword",
                 resourceID: "cm-starter-0001",
                 participants: [alice, bob],
                 fillAuthors: [localAuthorID, alice, bob],
                 completed: false
             )
         }
         return [
             showcase,
             GameSpec(
                 title: "Sunday Special",
                 resourceID: "cm-starter-0002",
                 participants: [alice, bob],
                 fillAuthors: [localAuthorID, alice, bob],
                 completed: false
             ),
             GameSpec(
                 title: "Coffee Break",
                 resourceID: "cm-starter-0003",
                 participants: [],
                 fillAuthors: [],
                 completed: true
             ),
             GameSpec(
                 title: "Weekend Challenge",
                 resourceID: "cm-starter-0004",
                 participants: [alice, carol],
                 fillAuthors: [],
                 completed: true
             ),
         ]
     }
 
     @MainActor
     static func populate(
         persistence: PersistenceController,
         preferences: PlayerPreferences,
         profile: Profile
     ) {
         let ctx = persistence.viewContext
 
         // Keep the Game List out of its "set your profile name" empty state.
         if !preferences.hasName {
             preferences.name = "You"
         }
 
         for friend in friends {
             seedFriend(friend, in: ctx)
         }
 
         // Reuse the catalog the new-game picker uses; it resolves each bundled
         // `.xd` for us and reads its source on demand.
         for spec in games(for: profile) {
             guard let entry = PuzzleCatalog.source(matchingResourceID: spec.resourceID, title: nil),
                   let source = try? entry.loadSource(),
                   let xd = try? XD.parse(source) else { continue }
             let puzzle = Puzzle(xd: xd)
             let game = seedGame(
                 title: spec.title,
                 resourceID: spec.resourceID,
                 participants: spec.participants,
                 puzzle: puzzle,
                 source: source,
                 completed: spec.completed,
                 in: ctx
             )
             if !spec.fillAuthors.isEmpty {
                 seedFilledLetters(in: game, puzzle: puzzle, authors: spec.fillAuthors, in: ctx)
             }
         }
 
         try? ctx.save()
     }
 
     private static func seedFriend(
         _ seed: (id: String, name: String),
         in ctx: NSManagedObjectContext
     ) {
         let friend = FriendEntity(context: ctx)
         friend.authorID = seed.id
         friend.createdAt = Date()
         friend.displayName = seed.name
         friend.displayNameVersion = 0
         friend.isBlocked = false
         friend.nickname = ""
         friend.nicknameVersion = 0
         friend.pairKey = "demo-pair-\(seed.id)"
     }
 
     @discardableResult
     private static func seedGame(
         title: String,
         resourceID: String,
         participants: [String],
         puzzle: Puzzle,
         source: String,
         completed: Bool,
         in ctx: NSManagedObjectContext
     ) -> GameEntity {
         let now = Date()
         let game = GameEntity(context: ctx)
         game.id = UUID()
         game.title = title
         game.puzzleSource = source
         game.puzzleParserVersion = Int64(XD.currentParserVersion)
         game.puzzleResourceID = resourceID
         game.createdAt = now
         game.updatedAt = now
         game.syncVersion = GameSyncVersion.current
         // A non-nil share record name is what marks the game as shared, which is
         // the gate for the Game List participant colour strip; a solo game (no
         // participants) leaves it nil.
         if !participants.isEmpty {
             game.ckShareRecordName = "demo-share-\(title)"
         }
         // A completed game is terminal: the Game List files it under "Completed"
         // and renders it as a fully-solved board.
         if completed {
             game.completedAt = now
             game.completedBy = participants.first ?? localAuthorID
         }
         game.populateCachedSummaryFields(from: puzzle)
 
         for authorID in participants {
             let player = PlayerEntity(context: ctx)
             player.game = game
             player.authorID = authorID
             player.name = friends.first { $0.id == authorID }?.name
             player.ckRecordName = "demo-player-\(title)-\(authorID)"
             player.updatedAt = now
         }
         return game
     }
 
     /// Fills a realistic share of `game`'s grid with correct letters, handing
     /// each cell to one of `authors` 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. The author set also caps
     /// how many colours the Game List strip shows for this game.
     private static func seedFilledLetters(
         in game: GameEntity,
         puzzle: Puzzle,
         authors: [String],
         in ctx: NSManagedObjectContext
     ) {
         guard !authors.isEmpty else { return }
         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 {
     /// The process's one services instance, installed by `CrossmateApp.init`
     /// and owned by the App's `@State`. Exists for the app delegate's push
     /// path: on a background-only launch no scene ever activates, so the root
     /// view's startup task never calls `start` — the delegate drives startup
     /// through this reference instead. Weak because the App owns the
     /// instance's lifetime; this is a lookup, not a retain.
     static weak var current: 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 most-recently-used ordering for direct friend invites.
     let friendInviteRecency: FriendInviteRecencyStore
     /// 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()
     let inviteDeliveries = InviteDeliveryStore()
     private(set) lazy var appActions = AppActions(services: self)
     /// 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, presenceUntil in
             await self?.accountPush.publishAccountSeenPush(gameID: gameID, presenceUntil: presenceUntil)
         }
     )
     /// 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,
         store: store,
         syncEngine: syncEngine,
         announcements: announcements,
         shareController: shareController,
         friendController: friendController,
         cloudService: cloudService,
         refreshAppBadge: { [weak self] reason in
             await self?.badge.refreshAppBadge(reason: reason)
         },
         publishInvitePush: { [weak self] friendAuthorID, gameID, title, inviterName in
             await self?.accountPush.publishInvitePush(
                 to: friendAuthorID,
                 gameID: gameID,
                 puzzleTitle: title,
                 inviterName: inviterName
             )
         }
     )
 
     let preferences: PlayerPreferences
 
     private let ckContainer = CloudContainer.container
     /// The process-wide startup operation. Retaining the task makes `start`
     /// both one-shot and awaitable: a caller that arrives while startup is in
     /// progress waits for the same readiness boundary instead of treating
     /// "startup entered" as "startup complete."
     private var startupTask: Task<Void, Never>?
     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>?
     /// Serialises Chronicle/Game metadata paging. Main-actor methods are
     /// reentrant across CloudKit awaits, so notification and pull-to-refresh
     /// requests must not reset the shared cursor during a Load More operation.
     private var completedPageTask: Task<GameArchiver.CompletedPage, Never>?
     private var completedPageTaskID: UUID?
     private var hasStartedRemoteCompletedMigration = false
     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
     /// Puzzle destinations currently mounted by SwiftUI. Unlike
     /// `GameStore.currentEntity`, this is cleared synchronously on disappearance,
     /// so Chronicle cleanup can distinguish a visible or transitioning puzzle
     /// from a stale last-loaded entity.
     private var mountedPuzzleCounts: [UUID: Int] = [:]
     /// 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 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 friends, 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. `--crossmate-seed-
         // marketing` seeds the same way but caps every game at three players,
         // for the import marketing screenshot's backdrop.
         let arguments = ProcessInfo.processInfo.arguments
         let seedProfile: DemoSeed.Profile? =
             if arguments.contains("--crossmate-seed-marketing") {
                 .marketing
             } else if arguments.contains("--crossmate-seed-demo") {
                 .development
             } else {
                 nil
             }
         let isDemoSeed = seedProfile != nil
         // The demo seed writes a scratch profile name; give it a throwaway
         // preferences store so that write can't sync into a real launch via the
         // shared iCloud key-value store.
         let preferences = isDemoSeed ? PlayerPreferences.ephemeral() : PlayerPreferences()
         self.preferences = preferences
         let persistence = PersistenceController(inMemory: isDemoSeed, eventLog: eventLog)
         self.persistence = persistence
         if let seedProfile {
             DemoSeed.populate(persistence: persistence, preferences: preferences, profile: seedProfile)
             // Preview the one-time v4 reset notice on demand
             // (`run-demo.sh --v4-notice`); set explicitly so a normal demo run
             // clears any leftover flag on the reused demo simulator.
             UserDefaults.standard.set(
                 ProcessInfo.processInfo.arguments.contains("--crossmate-show-v4-notice"),
                 forKey: Self.showV4NoticeDefaultsKey
             )
         }
         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
         self.friendInviteRecency = FriendInviteRecencyStore()
         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
         // When an iCloud id first resolves after offline play, realign every
         // row authored under the device-local fallback to the real id — before
         // `ensureICloudSyncStarted` lets the sync engine push them.
         identity.onIdentityResolved = { [weak store] fallbackID, realID in
             store?.remapAuthorID(from: fallbackID, to: realID)
         }
         // 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
         )
 
         let accountPush = AccountPushCoordinator(
             identity: identity,
             preferences: preferences,
             persistence: persistence,
             store: store,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             pushClient: self.pushClient
         )
         self.accountPush = accountPush
         store.onPushRegistrationMayNeedRefresh = { [weak accountPush] in
             guard let accountPush else { return }
             Task { @MainActor in
                 await accountPush.reconcilePushRegistration()
             }
         }
 
         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,
             publishFriendInvitationKey: { [accountPush] pairKey, zoneID, scope in
                 await accountPush.ensureFriendInvitationKeyPublished(
                     pairKey: pairKey,
                     friendZoneID: zoneID,
                     friendZoneScope: scope
                 )
             }
         )
         self.gameArchiver = GameArchiver(
             container: self.ckContainer,
             persistence: persistence,
             syncEngine: syncEngine,
             syncMonitor: self.syncMonitor,
             eventLog: eventLog,
             localIdentity: { [identity, preferences] in
                 guard let authorID = identity.currentID, !authorID.isEmpty else { return nil }
                 return (authorID, preferences.name)
             }
         )
         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, resigned, notifyPeers in
             if notifyPeers {
                 self?.sessions.stageCompletionDelivery(gameID: gameID, resigned: resigned)
             }
             self?.beginCompletionJournalUpload(gameID: gameID, authorID: authorID)
         }
     }
 
     private static let cloudGenerationKey = "cloudGeneration"
     private static let currentCloudGeneration = 4
     /// UserDefaults flag that drives the one-time v4 reset notice; read by
     /// `GameListView` via `@AppStorage`. See `NoticeView`.
     static let showV4NoticeDefaultsKey = "showV4Notice"
 
     /// Detects a device carrying data from the pre-v4 CloudKit container, wipes
     /// the local cache of it, and flags the one-time explanatory notice.
     /// Idempotent via a stored generation marker, so it runs at most once per
     /// device across the v3→v4 boundary. The wipe is *local only*
     /// (`purgeLocalData`): the v3 container is abandoned, not deleted — we can't
     /// reach co-owners' shared zones anyway, and dormant v3 data is harmless.
     private func migrateOffLegacyContainerIfNeeded() async {
         // The demo seed brings up a throwaway in-memory store that is not a real
         // v3→v4 transition — never purge it. (The notice can still be previewed
         // via the flag set at seed time.)
         guard !ProcessInfo.processInfo.arguments.contains("--crossmate-seed-demo")
         else { return }
         let defaults = UserDefaults.standard
         guard defaults.integer(forKey: Self.cloudGenerationKey) < Self.currentCloudGeneration
         else { return }
 
         if await deviceHasLegacyData() {
             do {
                 try await cloudService.purgeLocalData()
             } catch {
                 syncMonitor.note("v4 transition purge failed — \(error)")
             }
             defaults.set(true, forKey: Self.showV4NoticeDefaultsKey)
             syncMonitor.note("Migrated device off legacy CloudKit container — local cache cleared for v4")
         }
         defaults.set(Self.currentCloudGeneration, forKey: Self.cloudGenerationKey)
     }
 
     /// UserDefaults marker for the one-time v3 reclamation. Set only after a
     /// clean sweep, so a run that was offline, signed out, or partially
     /// rejected is retried on the next launch instead of being written off.
     private static let legacyCloudReclaimedKey = "legacyCloudDataReclaimed"
 
     /// Deletes this account's remaining v3 records, once, in the background.
     /// Silent by design: the v4 notice already explained that pre-v4 games are
     /// gone, so there is nothing further to tell the user — the work only
     /// returns storage that is already unreachable.
     private func reclaimLegacyCloudStorageIfNeeded() {
         // The demo seed runs against a throwaway store and must never touch a
         // real account's cloud data.
         guard !ProcessInfo.processInfo.arguments.contains("--crossmate-seed-demo")
         else { return }
         let defaults = UserDefaults.standard
         guard !defaults.bool(forKey: Self.legacyCloudReclaimedKey) else { return }
 
         Task { [syncEngine, syncMonitor] in
             let swept = await syncEngine.deleteLegacyCloudData { message in
                 syncMonitor.note(message)
             }
             guard swept else { return }
             UserDefaults.standard.set(true, forKey: Self.legacyCloudReclaimedKey)
         }
     }
 
     /// Pre-v4 data signal: the local store first (offline, instant), then — for
     /// a reinstalled device with an empty store — a probe of the legacy v3
     /// container for any custom zone (an `account` or per-game zone). A probe
     /// failure (signed out / offline) reports `false`, so no spurious notice
     /// shows.
     private func deviceHasLegacyData() async -> Bool {
         if store.hasAnyGames() { return true }
         do {
             let zones = try await CloudContainer.v3Container
                 .privateCloudDatabase.allRecordZones()
             let defaultZoneName = CKRecordZone.default().zoneID.zoneName
             return zones.contains { $0.zoneID.zoneName != defaultZoneName }
         } catch {
             return false
         }
     }
 
     func start(appDelegate: AppDelegate) async {
         if let startupTask {
             await startupTask.value
             return
         }
 
         let task = Task { @MainActor in
             await self.performStartup(appDelegate: appDelegate)
         }
         startupTask = task
         await task.value
     }
 
     private func performStartup(appDelegate: AppDelegate) async {
         // One-time transition off the pre-v4 CloudKit container. The v4 build
         // points at a brand-new, empty container, so any games this device
         // cached under v3 are orphans that can never sync again — wipe them and
         // flag the explanatory notice. Runs before sync starts so the library
         // never shows the stale rows.
         await migrateOffLegacyContainerIfNeeded()
 
         // Reclaim the iCloud quota the abandoned v3 container still holds. The
         // v4 cutover pointed the app at a fresh container and left every zone
         // the account had written to v3 in place, where it consumes quota
         // indefinitely for data nothing can reach. Detached so a slow sweep
         // never delays launch, and it touches no container the sync engine
         // uses, so it cannot interfere with v4 syncing.
         reclaimLegacyCloudStorageIfNeeded()
 
         // 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. The launch note
         // holds tips off for a new user's first couple of visits to the Game
         // List (see TipStore.launchesBeforeTips), so it must run before the tip
         // is read.
         tips.noteColdLaunch()
         // Keep onboarding tips out of marketing screenshots — the import scene
         // shows the Game List, and a tip banner is chrome that doesn't belong in
         // the captured image.
         #if DEBUG
         let suppressTips = MarketingLaunch.isScreenshot
         #else
         let suppressTips = false
         #endif
         if !suppressTips, 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()
         await nicknameCtx.perform {
             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.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()
                 // `presenceUntil` 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 previously accepted participant vanished from a game's zone-wide
         // share — they left or were removed. Rotate the game's push
         // credentials (they hold every field of the old ones) and re-register
         // so this device binds under the new credID and drops the old binding.
         await syncEngine.setOnPushCredentialRotationNeeded { [weak self] gameIDs in
             guard let self else { return }
             var rotated = false
             for gameID in gameIDs where self.store.rotatePushCredentials(for: gameID) != nil {
                 self.syncMonitor.note("push credentials rotated for \(gameID.uuidString) after roster shrink")
                 rotated = true
             }
             if rotated {
                 await self.accountPush.reconcilePushRegistration()
             }
         }
 
         // A peer minted or rotated a game's push credential and this device
         // just adopted it. Re-run registration so the device binds under the
         // new credID (and unregisters the old binding) now, rather than on the
         // next launch or APNs token delivery — until then, publishes signed
         // with the new credential could not reach it.
         await syncEngine.setOnRemoteCredentialsChanged { [weak self] _ in
             await self?.accountPush.reconcilePushRegistration()
         }
 
         await syncEngine.setOnBlockedFriendsChanged { [weak self] authorIDs in
             let hiddenChanges = await self?.store.reconcileBlockedFriendHiddenGames(
                 forAuthorIDs: authorIDs
             ) ?? 0
             if hiddenChanges > 0 {
                 self?.syncMonitor.note("block visibility reconcile: updated \(hiddenChanges) game(s)")
             }
             await self?.refreshSnapshot()
         }
 
         await syncEngine.setOnGameVisibilityCandidates { [weak self] gameIDs in
             if let currentID = self?.store.currentEntity?.id,
                gameIDs.contains(currentID) {
                 self?.store.refreshCurrentSyncState()
             }
             let hiddenChanges = await self?.store.reconcileBlockedFriendHiddenGames(
                 forGameIDs: gameIDs
             ) ?? 0
             if hiddenChanges > 0 {
                 self?.syncMonitor.note("block visibility reconcile: updated \(hiddenChanges) game(s)")
                 await self?.refreshSnapshot()
             }
         }
 
         // 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 presenceUntil 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 presenceUntil 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, presenceUntil, viewedAt) in pairs {
                 let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, presenceUntil: presenceUntil)
                 self?.syncMonitor.note(
                     "lease ADOPT[\(gameID.uuidString.prefix(8))] src=sync " +
                     "presenceUntil=\(presenceUntil.ISO8601Format()) " +
                     "was=\(previous?.ISO8601Format() ?? "—")" +
                     (adopted ? "" : " (no-op)")
                 )
                 // A sibling device shipped its "last viewed" cutoff on its own
                 // `Player.viewedAt`; 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.
                 if let viewedAt {
                     gameViewedStore.advance(viewedAt, forGame: gameID)
                 }
                 if presenceUntil > now {
                     await self?.badge.dismissDeliveredNotifications(
                         for: gameID,
                         seenAt: presenceUntil,
                         publishAccountSeen: false,
                         preserveUnread: true
                     )
                 } else if NotificationState.activePuzzleID() == gameID {
                     self?.syncMonitor.note(
                         "lease ADOPT[\(gameID.uuidString.prefix(8))] past while active; reasserting"
                     )
                     // A past-dated presenceUntil 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 `presenceUntil`. 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: presenceUntil)
                     BadgeState.collapseSuppression(gameID: gameID, to: presenceUntil)
                 }
             }
         }
 
         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.onParticipantRemoved = { [weak self] gameID in
             guard let self else { return }
             guard self.store.rotatePushCredentials(for: gameID) != nil else { return }
             self.syncMonitor.note(
                 "push credentials rotated for \(gameID.uuidString) after participant removal"
             )
             Task { @MainActor [weak self] in
                 await self?.accountPush.reconcilePushRegistration()
             }
         }
 
         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.setOnPingDeliveryUpdate { [weak self] update in
             guard let self else { return }
             switch update.state {
             case .queued:
                 self.inviteDeliveries.markQueued(
                     recordName: update.recordName,
                     gameID: update.gameID,
                     friendAuthorID: update.addressee
                 )
                 self.dismissInviteFailureAnnouncement(
                     gameID: update.gameID,
                     friendAuthorID: update.addressee
                 )
             case .sent:
                 self.inviteDeliveries.markSent(
                     recordName: update.recordName,
                     gameID: update.gameID,
                     friendAuthorID: update.addressee
                 )
                 self.dismissInviteFailureAnnouncement(
                     gameID: update.gameID,
                     friendAuthorID: update.addressee
                 )
             case .failed:
                 let failure = update.failure ?? .other
                 self.inviteDeliveries.markFailed(
                     recordName: update.recordName,
                     gameID: update.gameID,
                     friendAuthorID: update.addressee,
                     failure: failure
                 )
                 // Always post, even with an invite sheet open. The sheet shows
                 // the same failure inline but only for the send it issued
                 // itself, so gating on "a sheet is presented" could swallow a
                 // failure entirely — including the one that arrives after a
                 // confirmed-send wait has already timed out. The banner is
                 // scoped to the Game List behind the sheet, and the `.queued`
                 // and `.sent` cases above retract it, so a retry that succeeds
                 // never leaves a stale one behind.
                 self.announcements.post(Announcement(
                     id: InviteDeliveryStore.failureAnnouncementID(
                         gameID: update.gameID,
                         friendAuthorID: update.addressee
                     ),
                     scope: .global,
                     severity: .error,
                     title: String(localized: failure.title),
                     body: String(localized: failure.body),
                     dismissal: .manual
                 ))
                 if update.rollbackParticipantOnFailure {
                     Task { @MainActor [weak self] in
                         await self?.invites.rollbackUndeliveredInvite(
                             gameID: update.gameID,
                             friendAuthorID: update.addressee
                         )
                     }
                 }
             }
         }
 
         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 { [weak self, 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)
             // 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; in-progress games are left as revoked rows.
             //
             // With that puzzle on screen the live row is kept (and hidden) rather
             // than deleted, so the mounted view isn't left on a dead
             // `GameEntity`; the open puzzle is then handed over to the Chronicle,
             // which shows its own load rather than a banner over a dead game.
             let chronicleID = await gameArchiver.promoteRevoked(gameID: gameID)
             if let chronicleID {
                 if self?.isPuzzleOnScreen(gameID: gameID) == true {
                     NotificationNavigationBroker.shared.replaceOpenGame(
                         gameID,
                         with: chronicleID
                     )
                 } else {
                     await gameArchiver.retireSupersededLiveRow(gameID: 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.
             //
             // A completed handover earns no banner: the zone is retired by design
             // once every participant has chronicled the game, so a finished puzzle
             // passing to a complete Chronicle is not news. Everything else is —
             // an unfinished game, or one whose Chronicle never completed before
             // the owner hit the retention deadline, which leaves a revoked row
             // the user can still open and `OpenPuzzleBanner` re-banners.
             if chronicleID == nil {
                 announcements.post(.accessRevoked(gameID: gameID))
             }
             await self?.accountPush.reconcilePushRegistration()
         }
 
         await syncEngine.setOnGameRemoved { [weak self, store, gameViewedStore, announcements, gameArchiver] gameID in
             let wasOpen = store.handleRemoteRemoval(gameID: gameID)
             // Another owner device may have retired this completed live zone.
             // Its compact private Archive is account-wide, but the Archive
             // record was intentionally inert while the live row existed; apply
             // it now that the zone deletion removed that row.
             let chronicleID = await gameArchiver.restoreRetired(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 retirement is not a deletion the user needs told about: a
             // sibling device retires the zone once the game is chronicled, so an
             // open puzzle is handed over to the Chronicle that replaced it —
             // the same substitution `onGameAccessRevoked` makes for a
             // participant whose shared zone went.
             //
             // The banner is what remains for a genuine hard delete (a solo
             // puzzle deleted on another device, a shared game left elsewhere) or
             // for a retirement whose Chronicle could not be read: sticky and
             // input-blocking, it freezes the now-orphaned puzzle on screen until
             // the user backs out. Off-screen removals just drop from the list.
             if let chronicleID {
                 if self?.isPuzzleOnScreen(gameID: gameID) == true {
                     NotificationNavigationBroker.shared.replaceOpenGame(
                         gameID,
                         with: chronicleID
                     )
                 }
             } else if wasOpen {
                 announcements.post(.gameRemoved(gameID: gameID))
             }
             await self?.accountPush.reconcilePushRegistration()
         }
 
         await syncEngine.setOnGameCompleted { [weak self, gameArchiver] 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 gameArchiver.archiveIfNeeded(gameID: gameID)
         }
 
         await syncEngine.setOnReplayJournalsSynced { [gameArchiver] gameIDs in
             for gameID in gameIDs {
                 await gameArchiver.archiveIfNeeded(gameID: gameID)
             }
         }
 
         await syncEngine.setOnCompletionRecordsSaved { [weak self] records in
             await self?.sessions.noteCompletionRecordsSaved(records)
         }
         await sessions.resumePendingCompletionDeliveries()
 
         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)
             }
             // Joining can complete without presenting PuzzleDisplayView (for
             // example when the app backgrounds during acceptance). Publish the
             // profile-name snapshot here as part of the join itself rather than
             // relying on a later puzzle open to fill the Player record.
             await self.playerNamePublisher?.publishName(for: gameID)
             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
                 )
             }
         )
 
         // Install this only after every SyncEngine callback above is ready.
         // Assignment starts the delegate's buffered-notification drain; doing
         // it earlier could let that drain start SyncEngine and advance its
         // change token while one-shot callbacks were still absent. Keep the
         // installation above the sync-enablement guard so buffered wakes are
         // also drained (and diagnosed as ignored) when iCloud sync is off.
         appDelegate.onRemoteNotification = {
             summary, scope, event, gameID, kind, senderDeviceID, presenceUntil, isBackground in
             await self.handleRemoteNotification(
                 summary: summary,
                 scope: scope,
                 event: event,
                 gameID: gameID,
                 kind: kind,
                 senderDeviceID: senderDeviceID,
                 presenceUntil: presenceUntil,
                 isBackground: isBackground
             )
         }
 
         guard await ensureICloudSyncStarted() else {
             syncMonitor.note("iCloud sync disabled — engine startup skipped")
             return
         }
         // Re-announce any inbox share a friend has still not accepted. The
         // bootstrap Ping is otherwise one-shot: a friend whose accept failed at
         // delivery is stuck at `friendshipNotReady` with no other retry path.
         // Runs only once the engine is up (it enqueues a share and a bootstrap
         // ping) and only with sync enabled. Detached so it never delays the
         // foreground sync below.
         if let localAuthorID = identity.currentID, !localAuthorID.isEmpty {
             Task { [friendController, preferences] in
                 await friendController.healPendingBootstraps(
                     localAuthorID: localAuthorID,
                     localDisplayName: preferences.name
                 )
             }
         }
         // 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))
         }
     }
 
     /// Whether `gameID` still has a mounted puzzle destination. This stays true
     /// while backgrounded and through a pop transition, until `onDisappear`
     /// confirms that deleting its live Core Data row is safe.
     private func isPuzzleOnScreen(gameID: UUID) -> Bool {
         mountedPuzzleCounts[gameID, default: 0] > 0
     }
 
     func gameListAppeared() async {
         isGameListVisible = true
         // Land any Chronicle swap that was deferred while its puzzle was on
         // screen, before the list renders, so the row goes straight from live
         // game to Chronicle without a revoked state in between. Also the
         // cold-launch backstop for a revocation that arrived while terminated.
         let retirable = await gameArchiver.sweepSupersededLiveGames()
         for gameID in retirable where !isPuzzleOnScreen(gameID: gameID) {
             await gameArchiver.retireSupersededLiveRow(gameID: gameID)
         }
         await freshenGameList(reason: .appeared)
     }
 
     func gameListDisappeared() {
         isGameListVisible = false
     }
 
     func puzzleAppeared(gameID: UUID) {
         mountedPuzzleCounts[gameID, default: 0] += 1
     }
 
     /// Clears the mounted destination before starting Chronicle cleanup. If
     /// promotion is still fetching, the archiver joins that work before
     /// deciding whether a complete Chronicle exists.
     ///
     /// The retirement attempt is driven by persisted state rather than by what
     /// the closing puzzle believed about itself: a revocation flips the mutator
     /// the open view holds, but an owner-side retirement replaces the row from
     /// underneath without the view ever hearing about it. The archiver deletes
     /// nothing that a Chronicle has not already replaced, so asking on every
     /// close is safe.
     func puzzleDisappeared(gameID: UUID) {
         let remaining = max(0, mountedPuzzleCounts[gameID, default: 0] - 1)
         if remaining == 0 {
             mountedPuzzleCounts[gameID] = nil
         } else {
             mountedPuzzleCounts[gameID] = remaining
         }
         guard remaining == 0 else { return }
         Task { await gameArchiver.retireSupersededLiveRow(gameID: gameID) }
     }
 
     func loadRecentCompleted(since cutoff: Date) async -> GameArchiver.CompletedPage {
         guard await ensureICloudSyncStarted() else {
             return .init(oldestCompletedAt: nil, hasMore: false)
         }
         let predecessor = completedPageTask
         let task = Task { @MainActor in
             if let predecessor { _ = await predecessor.value }
             return await gameArchiver.loadRecentCompleted(since: cutoff)
         }
         let taskID = UUID()
         completedPageTask = task
         completedPageTaskID = taskID
         let page = await task.value
         if completedPageTaskID == taskID {
             completedPageTask = nil
             completedPageTaskID = nil
         }
         beginRemoteCompletedMigrationIfNeeded()
         return page
     }
 
     func loadMoreCompleted() async -> GameArchiver.CompletedPage {
         guard await ensureICloudSyncStarted() else {
             return .init(oldestCompletedAt: nil, hasMore: false)
         }
         let predecessor = completedPageTask
         let task = Task { @MainActor in
             if let predecessor { _ = await predecessor.value }
             return await gameArchiver.loadMoreCompleted()
         }
         let taskID = UUID()
         completedPageTask = task
         completedPageTaskID = taskID
         let page = await task.value
         if completedPageTaskID == taskID {
             completedPageTask = nil
             completedPageTaskID = nil
         }
         return page
     }
 
     private func beginRemoteCompletedMigrationIfNeeded() {
         guard !hasStartedRemoteCompletedMigration else { return }
         hasStartedRemoteCompletedMigration = true
         Task { @MainActor [weak self] in
             await self?.gameArchiver.migrateMissingCompletedGames()
             // After the migration, so an archive it compacts this launch is
             // already in the ledger and needs no payload read of its own.
             await self?.gameArchiver.reconcileChronicleLedger()
         }
     }
 
     /// 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] = await ctx.perform {
             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
         await ctx.perform {
             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?,
         presenceUntil: 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,
             presenceUntil: presenceUntil
         ) {
             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?,
         presenceUntil: 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 presenceUntil else {
                 syncMonitor.note("push(accountSeen): ignored (no presenceUntil)")
                 return true
             }
             let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, presenceUntil: presenceUntil)
             if store.isCompletedGameFamily(gameID: gameID) {
                 // A completed game is immutable. Treat the sibling's explicit
                 // open as a read receipt immediately, including when retirement
                 // has already removed the live row and only the Chronicle
                 // projection remains. The Player.readThrough echo is still the
                 // durable convergence path while the live zone exists.
                 store.advanceReadThrough(
                     gameID: gameID,
                     through: min(presenceUntil, Date())
                 )
             }
             syncMonitor.note(
                 "push(accountSeen): sibling saw \(gameID.uuidString.prefix(8)) " +
                 "presenceUntil=\(presenceUntil.ISO8601Format()) " +
                 "was=\(previous?.ISO8601Format() ?? "—")" +
                 (adopted ? "" : " (no-op)")
             )
             // The catch-up baseline is no longer recomputed here — it arrives,
             // accurate, on the sibling's `Player.viewedAt` 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 presenceUntil 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
             // presenceUntil is a plain read watermark (the sibling left), where we still
             // preserve genuinely-unread alerts.
             let siblingPresent = presenceUntil > Date()
             await badge.dismissDeliveredNotifications(
                 for: gameID,
                 seenAt: presenceUntil,
                 publishAccountSeen: false,
                 preserveUnread: !siblingPresent
             )
         default:
             break
         }
         return true
     }
 
     /// Retracts a friend's invite-failure banner once that invitation is back
     /// in flight, so a successful retry never leaves the old failure standing.
     private func dismissInviteFailureAnnouncement(gameID: UUID, friendAuthorID: String) {
         announcements.dismiss(
             id: InviteDeliveryStore.failureAnnouncementID(
                 gameID: gameID,
                 friendAuthorID: friendAuthorID
             )
         )
     }
 
     private func activePuzzleGridTarget() -> (UUID, CKDatabase.Scope)? {
         guard let entity = store.currentEntity,
               let gameID = entity.id,
               !store.isGameArchived(entity)
         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. The OS route has no caller to present it, so surface
                 // the accepted-but-unavailable distinction here and keep
                 // draining the queue.
                 if error is AcceptedShareError {
                     let copy = CloudFailureCopy.joinFailure(for: error)
                     announcements.post(Announcement(
                         id: "os-share-joined-unavailable",
                         scope: .global,
                         severity: .error,
                         title: copy.title,
                         body: copy.body,
                         dismissal: .manual
                     ))
                 }
             }
         }
     }
 
     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("lease(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("lease(activeLease) skipped for \(gameID.uuidString): not active puzzle")
             return
         }
         let now = Date()
         let didUpdate: Bool
         switch mode {
         case .activeLease:
             let presenceUntil = now.addingTimeInterval(Self.readLeaseDuration)
             didUpdate = store.setReadCursor(
                 gameID: gameID,
                 presenceUntil: presenceUntil,
                 minimumExistingPresenceUntil: 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))] " +
                     "presenceUntil=\(presenceUntil.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: presenceUntil)
                 await accountPush.publishAccountSeenPush(gameID: gameID, presenceUntil: presenceUntil)
             }
         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, presenceUntil: 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 = "lease(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 = "lease(currentTime)"
             drain = false
         }
         await syncEngine.enqueuePlayer(
             gameID: gameID,
             authorID: authorID,
             reason: reason,
             drain: drain
         )
     }
 
     /// Diagnostic: logs each participant's effective `Player.presenceUntil` lease
     /// for `gameID` at open, so a lingering peer cursor or engagement room can be
     /// reasoned about from the device log alone. Peer leases come from their
     /// received Player rows; the local lease comes from `GameEntity`, matching the
     /// source `RecordBuilder` writes into the outgoing Player record. One line per
     /// player: self/peer, author prefix, name, the raw `presenceUntil` (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! : "—"
                     let presenceUntil = isLocal
                         ? player.game?.lastReadOtherMoveAt
                         : player.presenceUntil
                     guard let presenceUntil else {
                         return "\(tag) \(author.prefix(8)) [\(name)] presenceUntil=nil"
                     }
                     let delta = Int(presenceUntil.timeIntervalSince(now))
                     let state = delta > 0 ? "present, +\(delta)s" : "absent, \(-delta)s ago"
                     return "\(tag) \(author.prefix(8)) [\(name)] presenceUntil=\(presenceUntil.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 (`presenceUntil` 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 presenceUntil > %@",
                     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(presenceUntil: player.presenceUntil, asOf: now)
                 }
                 continuation.resume(returning: hasPeer)
             }
         }
     }
 
     /// The earliest future `presenceUntil` 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 presenceUntil > %@",
                     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 presenceUntil = player.presenceUntil,
                           PeerPresence.isPresent(presenceUntil: presenceUntil, asOf: now) else { continue }
                     if soonest == nil || presenceUntil < soonest! { soonest = presenceUntil }
                 }
                 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: "presenceUntil > %@", 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(presenceUntil: player.presenceUntil, asOf: now) else { continue }
                     result[gameID, default: []].insert(authorID)
                 }
                 continuation.resume(returning: result.mapValues { Array($0) })
             }
         }
     }
 
 }