crossmate

SessionCoordinator.swift (41780B)

---

 import CoreData
 import CloudKit
 import Foundation
 import UIKit
 
 struct CompletionDeliveryProgress: Codable, Equatable {
     let resigned: Bool
     var durableRecords: Set<CompletionDurableRecordKind> = []
     var completionDelivered = false
     var replayDelivered = false
 
     var canDeliverCompletion: Bool {
         !completionDelivered && durableRecords.isSuperset(of: [.game, .moves])
     }
 
     var canDeliverReplay: Bool {
         completionDelivered && !replayDelivered && durableRecords.contains(.journal)
     }
 
     mutating func acknowledge(_ kinds: Set<CompletionDurableRecordKind>) {
         let gameWasDurable = durableRecords.contains(.game)
         if kinds.contains(.game) {
             durableRecords.insert(.game)
         }
         // Ignore data acknowledgements that can belong to requests already in
         // flight before completion was staged. Once the completed Game is
         // durable (or accompanies them in this event), subsequent saves come
         // from completion's flush/enqueue path.
         if gameWasDurable || kinds.contains(.game) {
             if kinds.contains(.moves) { durableRecords.insert(.moves) }
             if kinds.contains(.journal) { durableRecords.insert(.journal) }
         }
     }
 }
 
 /// Owns the play-session lifecycle: the sender-side session pushes
 /// (pause / win / resign / replay), the manual `nudge` push, and the
 /// receiver-side catch-up banner, driven by three lifecycle events —
 /// `notePuzzleActive`, `notePuzzleBackgrounded`, `notePuzzleClosed` — that
 /// `CrossmateApp`'s scene-phase and `onDisappear` handlers forward. The
 /// per-game timer lives in one `PuzzleSession` state machine per open game, so
 /// the leave/resume/grace interleavings are decided (and testable) in one
 /// place. `AppServices` composes one instance.
 @MainActor
 final class SessionCoordinator {
     /// Grace window before a backgrounded session is treated as ended. A
     /// briefly-backgrounded puzzle (phone sleep, app switcher peek, taking a
     /// call) should not fan out a pause ping to peers on every flicker —
     /// only a sustained absence does.
     static let sessionEndGrace: TimeInterval = 30
     /// Minimum gap between nudges for a given game, enforced per device. A
     /// nudge is a deliberate manual ping from the players menu, so the
     /// cooldown only guards against the button being spammed.
     static let nudgeCooldown: TimeInterval = 60
     /// Settle delay before the catch-up banner is computed on open. Lets the
     /// `.appeared` grid freshen land peer moves first, so the diff reflects the
     /// settled grid rather than a half-synced snapshot; cancelled if the user
     /// leaves before it elapses.
     static let sessionSummaryBannerDelay: TimeInterval = 3
     /// Cadence of the solve-clock liveness heartbeat for a shared game on screen.
     /// Kept well under `TimeLog.openGrace` so a co-solver's continuous sitting
     /// is never briefly capped on peers' clocks; only fires for shared games, so
     /// solo play makes no extra Player writes.
     static let clockHeartbeatInterval: TimeInterval = 90
 
     private let persistence: PersistenceController
     private let store: GameStore
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor
     private let sessionMonitor: SessionMonitor
     private let gameViewedStore: GameViewedStore
     private let announcements: AnnouncementCenter
     private let identity: AuthorIdentity
     private let preferences: PlayerPreferences
     private let pushClient: PushClient?
     private let completionDefaults: UserDefaults
     private static let pendingCompletionsKey = "pendingCompletionDeliveries.v1"
 
     /// Per-open-game session state machines — each owns its game's grace
     /// timers, background assertion, banner timer, and announced state.
     /// Created on the first event for a game and pruned once idle; see
     /// `PuzzleSession`.
     private var sessions: [UUID: PuzzleSession] = [:]
 
     /// When this device last sent a nudge for each game, used to enforce
     /// `nudgeCooldown`. Device-local and ephemeral — a relaunch clears it,
     /// which at worst allows one extra nudge.
     private var lastNudge: [UUID: Date] = [:]
 
     /// Games whose solve clock has been opened at least once this app run. The
     /// first open of a game reconciles any session left dangling by a previous
     /// run's crash; later opens (resumes) continue the same sitting. Cleared by a
     /// relaunch, which is exactly when the next first-open should reconcile again.
     private var clockSessionsOpenedThisLaunch: Set<UUID> = []
 
     init(
         persistence: PersistenceController,
         store: GameStore,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor,
         sessionMonitor: SessionMonitor,
         gameViewedStore: GameViewedStore,
         announcements: AnnouncementCenter,
         identity: AuthorIdentity,
         preferences: PlayerPreferences,
         pushClient: PushClient?,
         completionDefaults: UserDefaults = .standard
     ) {
         self.persistence = persistence
         self.store = store
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.sessionMonitor = sessionMonitor
         self.gameViewedStore = gameViewedStore
         self.announcements = announcements
         self.identity = identity
         self.preferences = preferences
         self.pushClient = pushClient
         self.completionDefaults = completionDefaults
     }
 
     // MARK: Per-game sessions
 
     /// The session state machine for `gameID`, created on demand with its
     /// effects wired back into this coordinator's push and banner paths.
     private func session(for gameID: UUID) -> PuzzleSession {
         if let existing = sessions[gameID] { return existing }
         let session = PuzzleSession(
             gameID: gameID,
             effects: PuzzleSession.Effects(
                 publishEnd: { [weak self] pauseStart in
                     await self?.publishSessionEndPush(gameID: gameID, pauseStart: pauseStart)
                 },
                 postSummaryBanner: { [weak self] in
                     self?.postSessionSummaryBanner(gameID: gameID, reason: "open")
                 },
                 note: { [weak self] message in
                     self?.syncMonitor.note(message)
                 },
                 beginBackgroundAssertion: { name, onExpiration in
                     UIApplication.shared.beginBackgroundTask(
                         withName: name,
                         expirationHandler: onExpiration
                     )
                 },
                 endBackgroundAssertion: { id in
                     UIApplication.shared.endBackgroundTask(id)
                 }
             )
         )
         sessions[gameID] = session
         return session
     }
 
     /// Drops `gameID`'s session once nothing keeps it alive (no pending
     /// timer, no assertion held, no announced play session awaiting its
     /// pause). Run after each lifecycle event and after a pause publish, so
     /// the map only holds games with live session state.
     private func pruneIfIdle(_ gameID: UUID) {
         guard let session = sessions[gameID], session.isIdle else { return }
         sessions[gameID] = nil
     }
 
     // MARK: Puzzle lifecycle events
 
     /// The puzzle is on screen and the scene is active (open or resume).
     /// Stamps the active-puzzle ID for notification suppression. If a pause
     /// was queued in the grace window and the user returned before it fired,
     /// drops it — peers should see one continuous session, not a stray pause,
     /// for a brief absence (phone sleep, a call, an app-switcher peek that
     /// escalated to background). Either way, schedules the catch-up banner
     /// after a short settle; the matching baseline commit happens on leave.
     func notePuzzleActive(gameID: UUID) {
         NotificationState.setActivePuzzleID(gameID)
         session(for: gameID).cancelPendingEndPush()
         handlePuzzleOpened(gameID: gameID)
     }
 
     /// The app backgrounded while the puzzle is open. Clears the
     /// active-puzzle ID and commits the catch-up baseline (the user has seen
     /// what's on screen), then defers the pause by the end grace under a
     /// background assertion. The pause self-gates on content when it fires, so
     /// a brief visit that changed no letters reaches no one regardless.
     func notePuzzleBackgrounded(gameID: UUID) {
         NotificationState.clearActivePuzzleID(if: gameID)
         handlePuzzleLeft(gameID: gameID)
         session(for: gameID).scheduleEndPush(after: Self.sessionEndGrace)
     }
 
     /// The user navigated away from the puzzle (`onDisappear`). Same commit as
     /// backgrounding. The caller sequences `publishSessionEndPush` after the
     /// moves flush: the pause counts read the journal, so the buffered cell
     /// edits must land first. The pause self-gates on content, so a visit that
     /// changed no letters reaches no one.
     func notePuzzleClosed(gameID: UUID) {
         NotificationState.clearActivePuzzleID(if: gameID)
         handlePuzzleLeft(gameID: gameID)
         pruneIfIdle(gameID)
     }
 
     /// Persists the intent to notify peers before completion's asynchronous
     /// CloudKit work begins. The visible completion alert waits until both the
     /// Game marker and this device's final Moves snapshot are durable; replay
     /// waits for the journal too.
     func stageCompletionDelivery(gameID: UUID, resigned: Bool) {
         var pending = pendingCompletions()
         pending[gameID] = CompletionDeliveryProgress(resigned: resigned)
         savePendingCompletions(pending)
         syncMonitor.note("push(completion): staged pending durable Game+Moves for \(gameID.uuidString.prefix(8))…")
     }
 
     func noteCompletionRecordsSaved(
         _ records: [UUID: Set<CompletionDurableRecordKind>]
     ) async {
         var pending = pendingCompletions()
         for (gameID, kinds) in records where pending[gameID] != nil {
             pending[gameID]?.acknowledge(kinds)
         }
         savePendingCompletions(pending)
         for gameID in records.keys where pending[gameID] != nil {
             await deliverPendingCompletion(gameID: gameID)
         }
     }
 
     /// Retries a worker publish that was interrupted after CloudKit durability
     /// had already been established. Called during service wiring on launch.
     func resumePendingCompletionDeliveries() async {
         for gameID in pendingCompletions().keys {
             await deliverPendingCompletion(gameID: gameID)
         }
     }
 
     private func deliverPendingCompletion(gameID: UUID) async {
         var all = pendingCompletions()
         guard var pending = all[gameID] else { return }
         if pending.canDeliverCompletion {
             guard await publishCompletionPush(gameID: gameID, resigned: pending.resigned) else { return }
             pending.completionDelivered = true
             all[gameID] = pending
             savePendingCompletions(all)
         }
         if pending.canDeliverReplay {
             guard await publishReplayPush(gameID: gameID) else { return }
             pending.replayDelivered = true
         }
         if pending.completionDelivered && pending.replayDelivered {
             all.removeValue(forKey: gameID)
         } else {
             all[gameID] = pending
         }
         savePendingCompletions(all)
     }
 
     private func pendingCompletions() -> [UUID: CompletionDeliveryProgress] {
         guard let data = completionDefaults.data(forKey: Self.pendingCompletionsKey),
               let stored = try? JSONDecoder().decode([String: CompletionDeliveryProgress].self, from: data)
         else { return [:] }
         return Dictionary(uniqueKeysWithValues: stored.compactMap { key, value in
             UUID(uuidString: key).map { ($0, value) }
         })
     }
 
     private func savePendingCompletions(_ pending: [UUID: CompletionDeliveryProgress]) {
         let stored = Dictionary(uniqueKeysWithValues: pending.map { ($0.key.uuidString, $0.value) })
         completionDefaults.set(try? JSONEncoder().encode(stored), forKey: Self.pendingCompletionsKey)
     }
 
     // MARK: Nudge
 
     /// Whether a nudge for `gameID` is allowed right now — i.e. the cooldown
     /// since the last one this device sent has elapsed. The players menu reads
     /// this (rebuilt each time it opens) to disable the button. It does not
     /// consult the roster or push capability; an empty fan-out is a silent
     /// no-op inside `nudge`.
     func canNudge(gameID: UUID, asOf now: Date = Date()) -> Bool {
         guard let last = lastNudge[gameID] else { return true }
         return now.timeIntervalSince(last) >= Self.nudgeCooldown
     }
 
     /// When the next nudge for `gameID` becomes allowed, or `nil` if one is
     /// allowed right now. The nudge button reads this so it can re-enable itself
     /// exactly when the cooldown lapses, rather than polling `canNudge`.
     func nudgeReadyAt(gameID: UUID, asOf now: Date = Date()) -> Date? {
         guard let last = lastNudge[gameID] else { return nil }
         let ready = last.addingTimeInterval(Self.nudgeCooldown)
         return ready > now ? ready : nil
     }
 
     /// Sends a manual nudge for `gameID` to every other player who isn't
     /// currently present in the puzzle, rousing them through an APNs alert. A
     /// deliberate action from the players menu, so unlike the session pushes it
     /// carries no grid summary — just "Alice nudged you to play X". Gated by
     /// `nudgeCooldown` (the button is also disabled via `canNudge`, but the
     /// guard here closes the double-tap race), and skipped on a finished or
     /// access-revoked game where there's nothing to rouse anyone into.
     func nudge(gameID: UUID) async {
         guard canNudge(gameID: gameID) else {
             syncMonitor.note("push(nudge): skipped (cooldown)")
             return
         }
         guard let localAuthorID = identity.currentID, !localAuthorID.isEmpty else {
             syncMonitor.note("push(nudge): skipped (no authorID)")
             return
         }
         // Arm the cooldown the moment we accept the gesture, not after a publish
         // that happens to find recipients. The button flashes "Nudge Sent" and
         // dims on every tap regardless of how many devices we actually reach (a
         // present-only or push-incapable peer reaches none), so the cooldown that
         // drives the dimming has to track the gesture — otherwise the button
         // snaps back to ready the instant the confirmation clears. Also closes
         // the double-tap race before this publish returns.
         lastNudge[gameID] = Date()
         guard let pushClient else {
             syncMonitor.note("push(nudge): skipped (no pushClient)")
             return
         }
         let plan = await pushPlan(for: gameID, excluding: localAuthorID)
         guard plan.completedAt == nil else {
             syncMonitor.note("push(nudge): skipped (game completed)")
             return
         }
         guard !plan.isAccessRevoked else {
             syncMonitor.note("push(nudge): skipped (access revoked)")
             return
         }
         // Broadcast to the whole room rather than an enumerated recipient list:
         // every participant registered under the game credential is reached even
         // if their Player record hasn't synced to us. A recipient who is
         // actually present suppresses the banner on the device they're using
         // (foreground `isSuppressed`) and sweeps it from their other devices
         // once their present device's read cursor syncs; `excludeAddress` keeps
         // the nudge off our own other devices.
         await pushClient.publish(
             kind: "nudge",
             gameID: gameID,
             addressees: [],
             title: "Crossmate",
             puzzleTitle: plan.title,
             broadcast: true,
             excludeAddress: store.localPushAddress(gameID: gameID, authorID: localAuthorID),
             broadcastPayload: PushPayload(event: .nudge, playerName: preferences.name),
             collapseID: PushClient.gameCollapseID(gameID),
             body: PuzzleNotificationText.nudgeBody(
                 playerName: preferences.name,
                 puzzleTitle: plan.title
             )
         )
     }
 
     /// Announces to everyone already in the room that this account has accepted
     /// an invitation and joined `gameID`. Broadcast like `nudge` — the joiner
     /// can't enumerate the other participants because their Player records are
     /// only just syncing in — and carries no grid summary, just "Alice joined
     /// 'X'". `excludeAddress` (passed by the join hook, which derives it as part
     /// of stamping the local push address) keeps the joiner's own other devices
     /// from being notified. Skipped on a finished or access-revoked game, which
     /// can't be meaningfully joined.
     func publishJoinPush(gameID: UUID, excludeAddress: String?) async {
         guard let localAuthorID = identity.currentID, !localAuthorID.isEmpty else {
             syncMonitor.note("push(join): skipped (no authorID)")
             return
         }
         guard let pushClient else {
             syncMonitor.note("push(join): skipped (no pushClient)")
             return
         }
         let plan = await pushPlan(for: gameID, excluding: localAuthorID)
         guard plan.completedAt == nil else {
             syncMonitor.note("push(join): skipped (game completed)")
             return
         }
         guard !plan.isAccessRevoked else {
             syncMonitor.note("push(join): skipped (access revoked)")
             return
         }
         await pushClient.publish(
             kind: "join",
             gameID: gameID,
             addressees: [],
             title: "Crossmate",
             puzzleTitle: plan.title,
             broadcast: true,
             excludeAddress: excludeAddress,
             broadcastPayload: PushPayload(event: .join, playerName: preferences.name),
             collapseID: PushClient.gameCollapseID(gameID),
             body: PuzzleNotificationText.joinBody(
                 playerName: preferences.name,
                 puzzleTitle: plan.title
             )
         )
     }
 
     /// Sender-side session-end push. For each recipient, tallies this
     /// device's journal entries newer than that recipient's read watermark
     /// (`Player.readThrough`), and ships a body describing only what *that*
     /// recipient hasn't seen. Caught-up recipients still get a presence-only
     /// "stopped solving"; recipients whose presence lease shows them in the
     /// game right now are dropped entirely — they watched the session live,
     /// and the push would banner their other devices.
     ///
     /// Suppresses the push when a peer device of this author wrote to
     /// Player during the grace window — that device is still playing and
     /// will publish its own pause when it stops.
     func publishSessionEndPush(gameID: UUID, pauseStart: Date = Date()) async {
         // A direct call (e.g. from `.onDisappear`) supersedes any pending
         // grace-window timer for this game — drop it so we don't fire a
         // second pause once the timer elapses.
         sessions[gameID]?.supersedePendingEndPush()
         guard let localAuthorID = identity.currentID, !localAuthorID.isEmpty else {
             syncMonitor.note("push(pause): skipped (no authorID)")
             return
         }
         // During the grace window this device wrote nothing to Player
         // (any local activity would have reset the timer via
         // `cancelPendingEndPush`). A Player `updatedAt` newer than
         // pauseStart therefore came from another device of this author —
         // that device is still active, so let its eventual pause cover
         // the session.
         if let updatedAt = store.playerUpdatedAt(for: gameID, by: localAuthorID),
            updatedAt > pauseStart {
             syncMonitor.note("push(pause): skipped (peer device active)")
             return
         }
         guard let pushClient else {
             syncMonitor.note("push(pause): skipped (no pushClient)")
             return
         }
         let plan = await pushPlan(for: gameID, excluding: localAuthorID)
         guard !plan.recipients.isEmpty else {
             syncMonitor.note("push(pause): skipped (no recipients)")
             return
         }
         // A finished or revoked game has no live play session, so a pause
         // summary is meaningless.
         guard plan.completedAt == nil else {
             syncMonitor.note("push(pause): skipped (game completed)")
             return
         }
         guard !plan.isAccessRevoked else {
             syncMonitor.note("push(pause): skipped (access revoked)")
             return
         }
         // Send to every participant: presence is no longer guessed here. A
         // present recipient suppresses the banner on the device they're using
         // and sweeps it from their others once their read cursor syncs. The
         // per-recipient tally below still drops recipients with nothing unseen,
         // so a session that changed no letters still reaches no one.
         let recipients = plan.recipients
         // The pause counts are derived from this device's own journal (gesture
         // history), not the merged grid, so the summary can name fills/clears/
         // checks/reveals. The merged-grid measurements still ride the
         // diagnostics block below for context.
         let journalEntries = store.localJournalEntries(for: gameID)
         // Sender-side diagnostics: store-derived measurements plus this
         // device's clock and the session-start it announced. Rides the
         // per-recipient payload (the planner stamps each recipient's presenceUntil)
         // so the receiver can log why the counts came out as they did.
         var diagnostics = store.movesDiagnostics(for: gameID, by: localAuthorID)
             ?? PushPayload.Diagnostics()
         diagnostics.senderNow = Date()
         // Each recipient is addressed only when this session changed letters
         // they haven't seen; cursor-only and check-only recipients are dropped
         // (see `SessionPushPlanner.sessionEndAddressees`).
         let addressees = SessionPushPlanner.sessionEndAddressees(
             recipients: recipients,
             journalEntries: journalEntries,
             selfAuthorID: localAuthorID,
             playerName: preferences.name,
             puzzleTitle: plan.title,
             diagnostics: diagnostics
         )
         guard !addressees.isEmpty else {
             // No recipient had unseen letter changes (cursor-only or
             // check-only session), or none could be addressed. Nothing to
             // report — the session still closed, so release the state machine.
             syncMonitor.note("push(pause): skipped (no letter changes to report)")
             pruneIfIdle(gameID)
             return
         }
         // Top-level broadcast body is the worker's fallback if an addressee
         // carries no per-recipient body. Under the new contract every
         // addressee has one, but the field is still required.
         let fallbackBody = PuzzleNotificationText.pauseBody(
             playerName: preferences.name,
             puzzleTitle: plan.title,
             fills: 0,
             clears: 0,
             checks: 0,
             reveals: 0
         )
         await pushClient.publish(
             kind: "pause",
             gameID: gameID,
             addressees: addressees,
             title: "Crossmate",
             puzzleTitle: plan.title,
             collapseID: PushClient.gameCollapseID(gameID),
             body: fallbackBody
         )
         // Advance each addressed recipient's notified-through watermark to the
         // latest move this pause reported. A later pause windows its counts to
         // the later of this and the recipient's presenceUntil, so a bounce that adds
         // no new move re-tallies to zero and reaches no one instead of
         // repeating the same summary. Only recipients we actually pushed to
         // advance: a recipient dropped for no letter changes (or no push
         // capability) keeps their old watermark and catches up when there's
         // genuinely new content. The addressee list carries only push
         // addresses, so map those back to author IDs.
         if let notifiedThrough = journalEntries.map(\.timestamp).max() {
             let addressedAddresses = Set(addressees.map(\.address))
             let addressed = recipients
                 .filter { $0.pushAddress.map(addressedAddresses.contains) ?? false }
                 .map(\.authorID)
             store.recordNotified(gameID: gameID, authorIDs: addressed, through: notifiedThrough)
         }
         // The pause closed the session; if no timer or assertion is live
         // either, the per-game state machine has nothing left to hold.
         pruneIfIdle(gameID)
     }
 
     private func publishCompletionPush(gameID: UUID, resigned: Bool) async -> Bool {
         let kindLabel = resigned ? "resign" : "win"
         guard let pushClient else {
             syncMonitor.note("push(\(kindLabel)): skipped (no pushClient)")
             return false
         }
         guard let localAuthorID = identity.currentID, !localAuthorID.isEmpty else {
             syncMonitor.note("push(\(kindLabel)): skipped (no authorID)")
             return false
         }
         let plan = await pushPlan(for: gameID, excluding: localAuthorID)
         guard !plan.recipients.isEmpty else {
             syncMonitor.note("push(\(kindLabel)): skipped (no recipients)")
             return true
         }
         // Send to every participant: presence is no longer guessed here. A
         // present recipient suppresses the banner where they're playing and
         // sweeps it from their other devices once their read cursor syncs.
         let event: PushPayload.Event = resigned ? .resign : .win
         let addressees = plan.recipients.compactMap { recipient in
             recipient.pushAddress.map {
                 PushClient.Addressee(
                     address: $0,
                     payload: PushPayload(
                         event: event,
                         playerName: preferences.name,
                         occurredAt: plan.completedAt
                     )
                 )
             }
         }
         guard !addressees.isEmpty else {
             syncMonitor.note("push(\(kindLabel)): skipped (no addressable recipients)")
             return true
         }
         let kind = resigned ? "resign" : "win"
         let body = PuzzleNotificationText.completionBody(
             playerName: preferences.name,
             puzzleTitle: plan.title,
             resigned: resigned
         )
         return await pushClient.publish(
             kind: kind,
             gameID: gameID,
             addressees: addressees,
             title: "Crossmate",
             puzzleTitle: plan.title,
             collapseID: PushClient.gameCollapseID(gameID),
             body: body
         )
     }
 
     private func publishReplayPush(gameID: UUID) async -> Bool {
         guard let pushClient else {
             syncMonitor.note("push(replay): skipped (no pushClient)")
             return false
         }
         let plan = await pushPlan(for: gameID)
         guard !plan.recipients.isEmpty else {
             syncMonitor.note("push(replay): skipped (no recipients)")
             return true
         }
         let addressees = plan.recipients.compactMap { recipient in
             recipient.pushAddress.map {
                 PushClient.Addressee(address: $0, payload: PushPayload(event: .replay))
             }
         }
         guard !addressees.isEmpty else {
             syncMonitor.note("push(replay): skipped (no addressable recipients)")
             return true
         }
         return await pushClient.publish(
             kind: "replay",
             gameID: gameID,
             addressees: addressees,
             title: "",
             background: true,
             body: ""
         )
     }
 
     private struct PushPlan {
         let recipients: [PushRecipient]
         let title: String
         let completedAt: Date?
         let isAccessRevoked: Bool
 
         static let empty = PushPlan(
             recipients: [],
             title: "",
             completedAt: nil,
             isAccessRevoked: false
         )
     }
 
     private func pushPlan(
         for gameID: UUID,
         excluding authorID: String? = nil
     ) async -> PushPlan {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let gReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gReq.fetchLimit = 1
             guard let game = try? ctx.fetch(gReq).first else { return .empty }
             var byAuthor: [String: (readThrough: Date?, notifiedThrough: Date?, pushAddress: String?)] = [:]
             let pReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
             pReq.predicate = NSPredicate(format: "game == %@", game)
             for p in (try? ctx.fetch(pReq)) ?? [] {
                 guard let a = p.authorID,
                       a != CKCurrentUserDefaultName,
                       !a.isEmpty
                 else { continue }
                 if let authorID, a == authorID { continue }
                 byAuthor[a] = (p.readThrough, p.notifiedThrough, p.pushAddress)
             }
             let recipients = byAuthor.map {
                 PushRecipient(
                     authorID: $0.key,
                     readThrough: $0.value.readThrough,
                     notifiedThrough: $0.value.notifiedThrough,
                     pushAddress: $0.value.pushAddress
                 )
             }
             return PushPlan(
                 recipients: recipients,
                 title: PuzzleNotificationText.title(for: game),
                 completedAt: game.completedAt,
                 isAccessRevoked: game.isAccessRevoked
             )
         }
     }
 
     /// Hand-off called when the puzzle becomes active. Pulls any pending
     /// session-end tallies out of SessionMonitor and posts them as a
     /// transient announcement on the puzzle header, in lieu of the
     /// local notification that would otherwise have fired in a few
     /// minutes' time. No-op if nothing was accumulated.
     private func handlePuzzleOpened(gameID: UUID) {
         logLocalPauseDiagnostics(for: gameID)
         openClockSession(gameID: gameID)
         // Defer the banner so the open's `.appeared` grid freshen can land peer
         // moves first; otherwise it would diff against a half-synced grid and
         // under-report. The baseline is not touched here — it advances only on
         // leave (`handlePuzzleLeft`) — so this is a pure read and re-running it
         // on a later foreground is harmless.
         session(for: gameID).scheduleSummaryBanner(after: Self.sessionSummaryBannerDelay)
     }
 
     /// Called when the user leaves the puzzle (backgrounded or navigated away).
     /// Drops a still-pending banner timer and advances the local "last viewed"
     /// baseline — the user has now seen what's on screen, so the next open diffs
     /// against this moment — then ships that baseline to sibling devices on this
     /// account's own `Player.viewedAt`, so they converge on the latest
     /// view time rather than recomputing from their own view. The advance is
     /// monotonic, so it is harmless that `CrossmateApp`'s leave handler also
     /// stamps the baseline.
     private func handlePuzzleLeft(gameID: UUID) {
         sessions[gameID]?.cancelPendingSummaryBanner()
         sealClockSession(gameID: gameID)
         gameViewedStore.advance(Date(), forGame: gameID)
         guard let authorID = identity.currentID, !authorID.isEmpty,
               let viewedAt = gameViewedStore.lastViewed(forGame: gameID)
         else { return }
         // Write it onto our own Player record and enqueue the send. This also
         // rides the leave's read-cursor Player write, but enqueuing directly
         // guarantees it ships even when that write is a no-op.
         store.setViewedAt(viewedAt, gameID: gameID, authorID: authorID)
         let syncEngine = self.syncEngine
         // Leave-path Player write: enqueue durably but don't force a drain that
         // would race the suspension budget — siblings adopt the baseline on the
         // next CKSyncEngine sync.
         Task { await syncEngine.enqueuePlayer(gameID: gameID, authorID: authorID, reason: "viewedAt", drain: false) }
     }
 
     /// Opens (or, on resume, refreshes the heartbeat of) the local device's
     /// solve-time session and ships it on the Player record. Skipped once the
     /// game is finished — a solved puzzle's clock is frozen, so revisiting it
     /// must not start accruing again. Runs for solo games too: the Player record
     /// rides the same private-zone sync that already carries solo Moves across
     /// the owner's devices.
     private func openClockSession(gameID: UUID) {
         guard !store.isGameCompleted(gameID: gameID) else { return }
         // The first open of a game since launch reconciles a session left
         // dangling by a previous run's force-quit/crash; a resume within this run
         // continues the same sitting. `open` also refreshes the heartbeat, so a
         // resume re-arms liveness without a separate beat.
         let firstOpenThisLaunch = clockSessionsOpenedThisLaunch.insert(gameID).inserted
         guard store.openClockSession(
             gameID: gameID,
             authorID: localClockAuthorID,
             reconcileStale: firstOpenThisLaunch
         ) else { return }
         // Shared puzzle opens immediately run `activateSharing`, whose
         // Player-record burst sends the same row with read cursor, name,
         // selection, push address, and this freshly-written time log. Avoid a
         // separate clock enqueue that CKSyncEngine can ship as its own Player
         // save just before or after the burst.
         guard !store.isGameShared(gameID: gameID) else { return }
         enqueueClockIfSynced(gameID: gameID, reason: "clockOpen")
     }
 
     /// Periodic liveness heartbeat for the open solve session, ticked by the
     /// puzzle host while a *shared* game is on screen. Refreshes `beatAt` and
     /// ships it so a co-solver keeps extrapolating this still-open session toward
     /// now — without it, a continuous sitting longer than `TimeLog.openGrace`
     /// would be capped on peers' clocks and only catch up when this device leaves.
     /// A no-op once finished or when no session is open.
     func noteClockHeartbeat(gameID: UUID) {
         guard !store.isGameCompleted(gameID: gameID) else { return }
         guard store.beatClockSession(gameID: gameID, authorID: localClockAuthorID) else { return }
         enqueueClockIfSynced(gameID: gameID, reason: "clockBeat")
     }
 
     /// The author key for the local player's clock writes. Falls back to the
     /// CloudKit owner placeholder when no iCloud identity has resolved yet — a
     /// solo game on a device not signed into iCloud (or before the async
     /// `userRecordID` fetch lands) — so the clock still accumulates locally. The
     /// placeholder is the same value the roster and push planner already exclude
     /// from peer logic, and such writes are never enqueued for sync (see
     /// `enqueueClockIfSynced`).
     private var localClockAuthorID: String {
         identity.currentID ?? CKCurrentUserDefaultName
     }
 
     /// Enqueues the local player's Player record for sync, but only once a real
     /// iCloud identity is resolved — the placeholder-author local row must never
     /// be uploaded. When `currentID` is set, the clock wrote under it, so this
     /// ships the same record the write touched.
     private func enqueueClockIfSynced(gameID: UUID, reason: String) {
         guard let authorID = identity.currentID else { return }
         let syncEngine = self.syncEngine
         Task { await syncEngine.enqueuePlayer(gameID: gameID, authorID: authorID, reason: reason, drain: false) }
     }
 
     /// Seals the local device's open solve-time session on leave and ships it.
     /// Allowed even after completion so an in-progress session at the moment of
     /// the win is made durable (the display still freezes it at `completedAt`).
     private func sealClockSession(gameID: UUID) {
         guard store.sealClockSession(gameID: gameID, authorID: localClockAuthorID) else { return }
         enqueueClockIfSynced(gameID: gameID, reason: "clockSeal")
     }
 
     /// Seals the local solve session at the instant the game finished — win,
     /// observed solve, or resign — and ships it, so peers and sibling devices
     /// converge on the final time straight away rather than only when this device
     /// next leaves the puzzle. Sealing at the game's own completedAt keeps the
     /// final interval identical to what the display already freezes to. A no-op
     /// when no session is open.
     func noteClockCompleted(gameID: UUID) {
         let finishedAt = store.completedAt(forGame: gameID) ?? Date()
         guard store.sealClockSession(
             gameID: gameID,
             authorID: localClockAuthorID,
             at: finishedAt
         ) else { return }
         enqueueClockIfSynced(gameID: gameID, reason: "clockComplete")
     }
 
     /// Computes the receiver-side catch-up summary for `gameID` and, when a peer
     /// has unseen activity, posts (or replaces, by stable id) the "Puzzle
     /// Updated" banner. Read-only — the baseline advances on leave, not here —
     /// so it is safe to recompute on every foreground. Logs the per-peer counts
     /// it surfaces so a missing or wrong banner is diagnosable after the fact.
     private func postSessionSummaryBanner(gameID: UUID, reason: String) {
         // No baseline means a first-ever open: stay silent rather than flag the
         // whole grid, exactly as the border highlights do — the two surfaces
         // read this one cutoff so they always agree.
         guard let since = gameViewedStore.lastViewed(forGame: gameID) else {
             syncMonitor.note("session summary[\(gameID.uuidString.prefix(8))] \(reason): skipped (no baseline)")
             return
         }
         syncMonitor.note(
             "session summary[\(gameID.uuidString.prefix(8))] \(reason) diag: "
             + store.recentChangesDiagnosticSummary(forGame: gameID, since: since)
         )
         let summaries = sessionMonitor.summaries(for: gameID, since: since)
         guard !summaries.isEmpty else {
             syncMonitor.note("session summary[\(gameID.uuidString.prefix(8))] \(reason): skipped (no changes)")
             return
         }
         let detail = summaries.map { summary -> String in
             let who = summary.playerName.isEmpty
                 ? String(summary.authorID.prefix(8))
                 : summary.playerName
             return "\(who) +\(summary.added)/-\(summary.cleared)"
         }.joined(separator: ", ")
         syncMonitor.note(
             "session summary[\(gameID.uuidString.prefix(8))] \(reason): \(detail)"
         )
         announcements.post(Announcement(
             id: "session-summary-\(gameID.uuidString)",
             scope: .game(gameID),
             severity: .info,
             title: "Puzzle Updated",
             body: Self.formatSummaryBanner(summaries),
             dismissal: .transient(after: 6)
         ))
     }
 
     /// Logs this device's own view of each peer's Moves for `gameID`, using the
     /// same `movesDiagnostics` computation the sender embeds in a pause push.
     /// Pairs with the `pause-diagnostics` receipt the NSE records: a suspicious
     /// pushed count can be diffed field-for-field against local ground truth.
     /// Phantom cells that actually synced surface here too; ones that stayed
     /// local to the sender (un-uploaded churn) won't — which is itself the
     /// answer. `recipientPresenceUntil` carries this device's *actual* cursor, to
     /// compare against the value the peer's pushed diagnostics claimed it saw.
     private func logLocalPauseDiagnostics(for gameID: UUID) {
         let localAuthorID = identity.currentID
         let selfPresenceUntil = localAuthorID.flatMap { store.presenceUntil(for: gameID, by: $0) }
         for peerAuthorID in store.peerAuthorIDs(for: gameID, excluding: localAuthorID) {
             guard var diagnostics = store.movesDiagnostics(for: gameID, by: peerAuthorID)
             else { continue }
             diagnostics.senderNow = Date()
             diagnostics.recipientPresenceUntil = selfPresenceUntil
             syncMonitor.note(
                 "local pause diag peer=\(peerAuthorID.prefix(8)): \(diagnostics.summaryLine)"
             )
         }
     }
 
     nonisolated static func formatSummaryBanner(_ summaries: [SessionMonitor.SessionSummary]) -> String {
         guard !summaries.isEmpty else { return "" }
         let phrases: [String] = summaries.map { summary in
             let name = summary.playerName.isEmpty ? "A player" : summary.playerName
             var parts: [String] = []
             if summary.added > 0 {
                 parts.append("added \(summary.added) \(summary.added == 1 ? "letter" : "letters")")
             }
             if summary.cleared > 0 {
                 parts.append("cleared \(summary.cleared) \(summary.cleared == 1 ? "letter" : "letters")")
             }
             let action = parts.isEmpty ? "made changes" : parts.joined(separator: " and ")
             return "\(name) \(action)"
         }
         return "\(phrases.joined(separator: "; "))."
     }
 }