crossmate

GameStore.swift (152487B)

---

 import CloudKit
 import CoreData
 import Foundation
 import Observation
 import Security
 
 /// Fetches child rows explicitly instead of reading an already-realised
 /// inverse relationship. Background sync can insert a child in another
 /// context without refreshing a loaded GameEntity's to-many collection.
 private func playerEntities(for entity: GameEntity) -> [PlayerEntity] {
     guard let context = entity.managedObjectContext else { return [] }
     let request = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
     request.predicate = NSPredicate(format: "game == %@", entity)
     return (try? context.fetch(request)) ?? []
 }
 
 private func isMaterializedArchive(_ entity: GameEntity) -> Bool {
     entity.ckRecordName.flatMap(Archive.originalGameID(fromName:)) != nil
 }
 
 /// Contributor identities retained by a materialised Chronicle. The cached
 /// cells and journals are included so projections created by the first
 /// Chronicle build repair themselves without downloading the record again.
 private func archivedContributorAuthorIDs(_ entity: GameEntity) -> [String] {
     guard isMaterializedArchive(entity) else { return [] }
     var authorIDs = Set(playerEntities(for: entity).compactMap(\.authorID))
     authorIDs.formUnion(
         ((entity.cells as? Set<CellEntity>) ?? []).compactMap(\.letterAuthorID)
     )
     authorIDs.formUnion(
         ((entity.journal as? Set<JournalEntity>) ?? []).compactMap(\.sourceAuthorID)
     )
     if let completedBy = entity.completedBy {
         authorIDs.insert(completedBy)
     }
     authorIDs.remove("")
     authorIDs.remove(CKCurrentUserDefaultName)
     return authorIDs.sorted()
 }
 
 private func isArchivedSharedGame(_ entity: GameEntity) -> Bool {
     guard isMaterializedArchive(entity) else { return false }
     return entity.archiveParticipants != nil
         || archivedContributorAuthorIDs(entity).count > 1
 }
 
 /// The Chronicle's frozen grid. The first Chronicle build opened materialised
 /// rows through the live-Moves path and could consequently blank this cache.
 /// A complete replay journal still carries every after-state, so use its final
 /// frame only when no meaningful cached cell state remains.
 private func materializedArchiveGrid(_ entity: GameEntity) -> GridState? {
     guard isMaterializedArchive(entity) else { return nil }
     let cells = (entity.cells as? Set<CellEntity>) ?? []
     let cached = Dictionary(
         cells.map {
             (
                 GridPosition(row: Int($0.row), col: Int($0.col)),
                 GridCell(
                     letter: $0.letter ?? "",
                     mark: CellMark(code: $0.markCode),
                     authorID: $0.letterAuthorID
                 )
             )
         },
         uniquingKeysWith: { first, _ in first }
     )
     let hasMeaningfulCachedState = cached.values.contains {
         !$0.letter.isEmpty || $0.mark != .none || $0.authorID != nil
     }
     guard !hasMeaningfulCachedState else { return cached }
 
     let entries = ((entity.journal as? Set<JournalEntity>) ?? [])
         .map(MovesJournal.value(from:))
     guard !entries.isEmpty else { return cached }
     let timeline = ReplayTimeline(merging: [entries])
     return timeline.state(through: timeline.count).mapValues {
         GridCell(
             letter: $0.letter,
             mark: $0.mark,
             authorID: $0.cellAuthorID
         )
     }
 }
 
 /// Per-cell state for rendering a thumbnail. Plain value type so
 /// SwiftUI can diff it cheaply.
 enum GameThumbnailCell: Equatable {
     case block
     case empty
     case filled
 }
 
 /// Value type backing a library row. Built from a `GameEntity` so that
 /// SwiftUI's `@FetchRequest` can drive the list and still render through
 /// an immutable, diff-friendly model.
 struct GameSummary: Identifiable, Equatable {
     /// The persisted row to open. A Chronicle uses its derived archive UUID.
     let id: UUID
     /// Stable Game List identity across the live Game → Chronicle handoff.
     /// SwiftUI can therefore update the existing row instead of animating a
     /// removal and insertion when the visible representation changes.
     let listID: UUID
     let title: String
     let publisher: String?
     let puzzleDate: Date?
     let updatedAt: Date?
     let completedAt: Date?
     let gridWidth: Int
     let gridHeight: Int
     let thumbnailCells: [GameThumbnailCell]
     /// `true` when the current user owns this game (`databaseScope == 0`).
     let isOwned: Bool
     /// `true` when this game has an active share (owner) or is joined via
     /// a share (participant, `databaseScope == 1`).
     let isShared: Bool
     let isAccessRevoked: Bool
     let hasUnreadOtherMoves: Bool
     let allParticipants: [GameParticipantSummary]
 
     /// The participants ordered for the Game List strip: highest scorer at the
     /// leading edge. Derived from `allParticipants`, whose summaries already
     /// carry each player's score, so the ordering lives in one place.
     var stripParticipants: [GameParticipantSummary] {
         ParticipantSummaries.sortedByScore(
             allParticipants,
             score: \.score,
             name: \.name,
             id: \.authorID
         )
     }
 
     init?(
         entity: GameEntity,
         localAuthorID: String? = nil,
         localName: String = "Player",
         localColor: PlayerColor = .blue
     ) {
         guard let id = entity.id else { return nil }
 
         let width: Int
         let height: Int
         let publisher: String?
         let puzzleDate: Date?
         let blocks: [Bool]
 
         if entity.gridWidth > 0,
            entity.gridHeight > 0,
            let mask = entity.blockMask,
            mask.count == Int(entity.gridWidth) * Int(entity.gridHeight) {
             // Fast path: derived data is cached on the entity, so the list
             // can render without parsing XD on every keystroke-driven save.
             width = Int(entity.gridWidth)
             height = Int(entity.gridHeight)
             publisher = entity.cachedPublisher
             puzzleDate = entity.cachedPuzzleDate
             blocks = mask.map { $0 != 0 }
         } else {
             // Fallback for legacy rows that haven't been backfilled yet, or
             // test fixtures that bypass the creation helpers. The
             // PersistenceController backfill should make this rare.
             guard let source = entity.puzzleSource,
                   let xd = try? XD.parse(source) else {
                 return nil
             }
             let puzzle = Puzzle(xd: xd)
             width = puzzle.width
             height = puzzle.height
             publisher = puzzle.publisher
             puzzleDate = puzzle.date
             var bs: [Bool] = []
             bs.reserveCapacity(puzzle.width * puzzle.height)
             for r in 0..<puzzle.height {
                 for c in 0..<puzzle.width {
                     bs.append(puzzle.cells[r][c].isBlock)
                 }
             }
             blocks = bs
         }
 
         // A completed game is terminal and always renders solved (restore
         // seals it to the solution), but the CellEntity cache mirrors the raw
         // un-watermarked merge, which can permanently lack a winning letter —
         // a clear stamped after the completion latch beats it on LWW forever.
         // Derive the thumbnail from the latch, not the cache, so a finished
         // game's thumbnail is full regardless of merge drift.
         let isCompleted = entity.completedAt != nil
         var filledSet: Set<Int> = []
         var scoreByAuthorID: [String: Int] = [:]
         if !isCompleted {
             let cellEntities = (entity.cells as? Set<CellEntity>) ?? []
             for ce in cellEntities where !(ce.letter ?? "").isEmpty {
                 let index = Int(ce.row) * width + Int(ce.col)
                 filledSet.insert(index)
                 guard blocks.indices.contains(index), !blocks[index] else { continue }
                 guard !CellMark(code: ce.markCode).isRevealed,
                       let authorID = ce.letterAuthorID,
                       !authorID.isEmpty,
                       authorID != CKCurrentUserDefaultName else { continue }
                 scoreByAuthorID[authorID, default: 0] += 1
             }
         }
 
         var thumbCells: [GameThumbnailCell] = []
         thumbCells.reserveCapacity(width * height)
         for r in 0..<height {
             for c in 0..<width {
                 let idx = r * width + c
                 if blocks[idx] {
                     thumbCells.append(.block)
                 } else if isCompleted || filledSet.contains(idx) {
                     thumbCells.append(.filled)
                 } else {
                     thumbCells.append(.empty)
                 }
             }
         }
 
         self.id = id
         self.listID = entity.ckRecordName.flatMap(
             Archive.originalGameID(fromName:)
         ) ?? id
         self.title = entity.title ?? "Untitled"
         self.publisher = publisher
         self.puzzleDate = puzzleDate
         self.updatedAt = entity.updatedAt
         self.completedAt = entity.completedAt
         self.gridWidth = width
         self.gridHeight = height
         self.thumbnailCells = thumbCells
         self.isOwned = entity.databaseScope == 0
         self.isShared = entity.ckShareRecordName != nil
             || entity.databaseScope == 1
             || isArchivedSharedGame(entity)
         self.isAccessRevoked = entity.isAccessRevoked
         self.allParticipants = Self.computeParticipants(
             // A Chronicle's entity ID is deliberately distinct from the live
             // game's ID. Colours are game-seeded, so use the shared list
             // identity (the original ID for a Chronicle) to keep the same
             // collaborator colours across materialization.
             gameID: self.listID,
             entity: entity,
             localAuthorID: localAuthorID,
             localName: localName,
             localColor: localColor,
             scoreByAuthorID: scoreByAuthorID
         )
         self.hasUnreadOtherMoves = Self.computeHasUnread(
             isShared: self.isShared,
             latest: entity.latestOtherMoveAt,
             // The unread badge keys off the read *watermark*, not the presence
             // lease (`lastReadOtherMoveAt`).
             readThrough: entity.readThroughAt
         )
     }
 
     /// A game is unread when a peer's move is newer than this account's read
     /// watermark. Completed games count too: a co-player finishing or resigning
     /// is itself an unseen event (the badge ledger already flags it from the
     /// completion push), and opening the finished game to review it advances
     /// `readThroughAt` via `markOtherMovesRead`, clearing the dot like any other.
     fileprivate static func computeHasUnread(
         isShared: Bool,
         latest: Date?,
         readThrough: Date?
     ) -> Bool {
         guard isShared, let latest else { return false }
         guard let readThrough else { return true }
         return latest > readThrough
     }
 
     private static func computeParticipants(
         gameID: UUID,
         entity: GameEntity,
         localAuthorID: String?,
         localName: String,
         localColor: PlayerColor,
         scoreByAuthorID: [String: Int]
     ) -> [GameParticipantSummary] {
         guard entity.ckShareRecordName != nil
                 || entity.databaseScope == 1
                 || isArchivedSharedGame(entity)
         else {
             return []
         }
 
         var namesByAuthor: [String: String] = [:]
         var playerAuthorIDs: [String] = []
         for player in playerEntities(for: entity) {
             guard let authorID = player.authorID, !authorID.isEmpty else { continue }
             playerAuthorIDs.append(authorID)
             if let name = player.name?.trimmingCharacters(in: .whitespacesAndNewlines),
                !name.isEmpty {
                 namesByAuthor[authorID] = name
             }
         }
 
         let movesEntities = (entity.moves as? Set<MovesEntity>) ?? []
         var moveAuthorIDs: [String] = []
         for moves in movesEntities {
             guard let authorID = moves.authorID, !authorID.isEmpty else { continue }
             moveAuthorIDs.append(authorID)
         }
 
         let nicknames = friendNicknames(in: entity.managedObjectContext)
         return ParticipantSummaries.allParticipants(
             gameID: gameID,
             namesByAuthor: namesByAuthor,
             moveAuthorIDs: moveAuthorIDs,
             nicknamesByAuthor: nicknames,
             localAuthorID: localAuthorID,
             localName: localName,
             localColor: localColor,
             scoreByAuthorID: scoreByAuthorID,
             additionalAuthorIDs: playerAuthorIDs
                 + archivedContributorAuthorIDs(entity)
         )
     }
 
     private static func friendNicknames(in context: NSManagedObjectContext?) -> [String: String] {
         guard let context else { return [:] }
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(
             format: "isBlocked == NO AND nickname != nil AND nickname != %@", ""
         )
         let friends = (try? context.fetch(req)) ?? []
         var nicknames: [String: String] = [:]
         for friend in friends {
             guard let authorID = friend.authorID, !authorID.isEmpty,
                   let nickname = friend.nickname?.trimmingCharacters(in: .whitespacesAndNewlines),
                   !nickname.isEmpty
             else { continue }
             nicknames[authorID] = nickname
         }
         return nicknames
     }
 }
 
 /// CloudKit routing metadata captured before a game row is deleted locally.
 /// The sync layer cannot look this up after the Core Data cascade completes.
 struct GameCloudDeletion: Sendable, Equatable {
     let gameID: UUID
     let databaseScope: DatabaseScope
     let ckZoneName: String
     let ckZoneOwnerName: String
     /// False for a materialized archive: its ckZoneName is the account-wide
     /// archive zone, which must never be deleted as part of removing one game.
     let deletesLiveZone: Bool
     /// The one compact Archive record to delete from the common private zone.
     let archiveRecordName: String?
     /// Best-effort cleanup for archives written before v1.1.0.
     let legacyArchiveZoneName: String?
 }
 
 /// Per-entity memoisation of `GameSummary`. The library list re-runs on
 /// every Core Data save (i.e., every keystroke), but only the active
 /// entity's fields actually change. The cache key intentionally uses fast
 /// scalar/string fields so a hit never has to fault the `cells`
 /// relationship; `MovesUpdater` bumps `updatedAt` atomically with cell
 /// writes, so it acts as a faithful proxy for "the filled-cell thumbnail
 /// might have changed".
 ///
 /// The puzzle-structure fields (`title`, cached publisher/date, grid dims,
 /// block mask) are keyed directly because they are *not* proxied by
 /// `updatedAt`: `replacePuzzleSource` rewrites them during an NYT-style
 /// upgrade without bumping `updatedAt`, so the row would otherwise render
 /// the old title/grid until unrelated cell activity nudged the proxy.
 @MainActor
 final class GameSummaryCache {
     private struct Key: Equatable {
         let updatedAt: Date?
         let completedAt: Date?
         let latestOther: Date?
         let readThrough: Date?
         let scope: Int16
         let shareName: String?
         let revoked: Bool
         let title: String?
         let publisher: String?
         let puzzleDate: Date?
         let gridWidth: Int16
         let gridHeight: Int16
         let blockMask: Data?
         let localAuthorID: String?
         let localName: String
         let localColorID: String
         let playersSignature: [String]
         let movesAuthorIDs: [String]
         let nicknamesSignature: [String]
     }
     private var entries: [NSManagedObjectID: (key: Key, summary: GameSummary)] = [:]
 
     func summary(
         for entity: GameEntity,
         localAuthorID: String? = nil,
         localName: String = "Player",
         localColor: PlayerColor = .blue
     ) -> GameSummary? {
         let key = Key(
             updatedAt: entity.updatedAt,
             completedAt: entity.completedAt,
             latestOther: entity.latestOtherMoveAt,
             readThrough: entity.readThroughAt,
             scope: entity.databaseScope,
             shareName: entity.ckShareRecordName,
             revoked: entity.isAccessRevoked,
             title: entity.title,
             publisher: entity.cachedPublisher,
             puzzleDate: entity.cachedPuzzleDate,
             gridWidth: entity.gridWidth,
             gridHeight: entity.gridHeight,
             blockMask: entity.blockMask,
             localAuthorID: localAuthorID,
             localName: localName,
             localColorID: localColor.id,
             playersSignature: Self.playersSignature(for: entity),
             movesAuthorIDs: Self.movesAuthorIDs(for: entity),
             nicknamesSignature: Self.nicknamesSignature(in: entity.managedObjectContext)
         )
         if let hit = entries[entity.objectID], hit.key == key {
             return hit.summary
         }
         guard let fresh = GameSummary(
             entity: entity,
             localAuthorID: localAuthorID,
             localName: localName,
             localColor: localColor
         ) else { return nil }
         entries[entity.objectID] = (key, fresh)
         return fresh
     }
 
     private static func playersSignature(for entity: GameEntity) -> [String] {
         playerEntities(for: entity).map { player in
             "\(player.authorID ?? "")|\(player.name ?? "")|\(player.updatedAt?.timeIntervalSinceReferenceDate ?? 0)"
         }
         .sorted()
     }
 
     private static func movesAuthorIDs(for entity: GameEntity) -> [String] {
         let moves = (entity.moves as? Set<MovesEntity>) ?? []
         return Array(Set(moves.compactMap { $0.authorID })).sorted()
     }
 
     private static func nicknamesSignature(in context: NSManagedObjectContext?) -> [String] {
         guard let context else { return [] }
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(
             format: "isBlocked == NO AND nickname != nil AND nickname != %@", ""
         )
         let friends = (try? context.fetch(req)) ?? []
         return friends.compactMap { friend in
             guard let authorID = friend.authorID, !authorID.isEmpty else { return nil }
             return "\(authorID)|\(friend.nickname ?? "")"
         }
         .sorted()
     }
 }
 
 extension GameEntity {
     /// The Game List excludes both games hidden by the local block table and
     /// live games whose visible representation is a materialized Chronicle.
     static var visibleInGameListPredicate: NSPredicate {
         NSPredicate(format: "isHidden == NO AND isSupersededByChronicle == NO")
     }
 
     /// Writes the derived puzzle data that `GameSummary` (and the library
     /// list) needs into the entity, so the list path never has to call
     /// `XD.parse` on every Core Data save. Block layout is encoded as one
     /// byte per cell in row-major order.
     func populateCachedSummaryFields(from puzzle: Puzzle) {
         cachedPublisher = puzzle.publisher
         cachedPuzzleDate = puzzle.date
         gridWidth = Int16(puzzle.width)
         gridHeight = Int16(puzzle.height)
 
         var bytes = [UInt8]()
         bytes.reserveCapacity(puzzle.width * puzzle.height)
         for r in 0..<puzzle.height {
             for c in 0..<puzzle.width {
                 bytes.append(puzzle.cells[r][c].isBlock ? 1 : 0)
             }
         }
         blockMask = Data(bytes)
     }
 
     /// Re-derives local game-list hiding from the synced block table.
     ///
     /// `isHidden` is intentionally local-only: block/unblock owns the durable
     /// account-wide fact, and games are hidden when any known collaborator on
     /// that game is currently blocked. Chronicle replacement is tracked
     /// independently by `isSupersededByChronicle`.
     @discardableResult
     static func reconcileBlockedFriendHiddenGames(
         forAuthorIDs authorIDs: Set<String>,
         in ctx: NSManagedObjectContext
     ) -> Int {
         let authorIDs = authorIDs.filter { !$0.isEmpty }
         guard !authorIDs.isEmpty else { return 0 }
         return reconcileBlockedFriendHiddenGames(
             games: gamesFeaturingAnyAuthor(in: authorIDs, ctx: ctx),
             blockedAuthorIDs: blockedAuthorIDs(in: ctx)
         )
     }
 
     @discardableResult
     static func reconcileBlockedFriendHiddenGames(
         forGameIDs gameIDs: Set<UUID>,
         in ctx: NSManagedObjectContext
     ) -> Int {
         guard !gameIDs.isEmpty else { return 0 }
         let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         gameReq.predicate = NSPredicate(format: "id IN %@", Array(gameIDs))
         return reconcileBlockedFriendHiddenGames(
             games: (try? ctx.fetch(gameReq)) ?? [],
             blockedAuthorIDs: blockedAuthorIDs(in: ctx)
         )
     }
 
     private static func reconcileBlockedFriendHiddenGames(
         games: [GameEntity],
         blockedAuthorIDs: Set<String>
     ) -> Int {
         var changed = 0
         for game in games {
             var didChange = false
             // Builds that predate `isSupersededByChronicle` used `isHidden`
             // for Chronicle replacement too. Preserve that reason before
             // block reconciliation clears the legacy combined flag.
             if !game.isSupersededByChronicle,
                hasMaterializedChronicle(for: game) {
                 game.isSupersededByChronicle = true
                 didChange = true
             }
             let authors = collaboratorAuthorIDs(for: game)
             let shouldHide = !blockedAuthorIDs.isDisjoint(with: authors)
             if game.isHidden != shouldHide {
                 game.isHidden = shouldHide
                 didChange = true
             }
             if didChange { changed += 1 }
         }
         return changed
     }
 
     private static func hasMaterializedChronicle(for game: GameEntity) -> Bool {
         guard !isMaterializedArchive(game),
               let gameID = game.id,
               let ctx = game.managedObjectContext
         else { return false }
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "id == %@",
             Archive.archiveGameID(for: gameID) as CVarArg
         )
         request.fetchLimit = 1
         return (try? ctx.count(for: request)) == 1
     }
 
     static func blockedAuthorIDs(in ctx: NSManagedObjectContext) -> Set<String> {
         let blockedReq = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         blockedReq.predicate = NSPredicate(format: "isBlocked == YES")
         blockedReq.propertiesToFetch = ["authorID"]
         return Set(((try? ctx.fetch(blockedReq)) ?? []).compactMap(\.authorID))
     }
 
     private static func gamesFeaturingAnyAuthor(
         in authorIDs: Set<String>,
         ctx: NSManagedObjectContext
     ) -> [GameEntity] {
         let authors = Array(authorIDs)
         var games: [GameEntity] = []
         var seen = Set<NSManagedObjectID>()
 
         func append(_ game: GameEntity?) {
             guard let game, !seen.contains(game.objectID) else { return }
             seen.insert(game.objectID)
             games.append(game)
         }
 
         let ownedReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         ownedReq.predicate = NSPredicate(format: "ckZoneOwnerName IN %@", authors)
         for game in (try? ctx.fetch(ownedReq)) ?? [] {
             append(game)
         }
 
         let playerReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         playerReq.predicate = NSPredicate(format: "authorID IN %@", authors)
         for player in (try? ctx.fetch(playerReq)) ?? [] {
             append(player.game)
         }
 
         let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         movesReq.predicate = NSPredicate(format: "authorID IN %@", authors)
         for moves in (try? ctx.fetch(movesReq)) ?? [] {
             append(moves.game)
         }
 
         return games
     }
 
     private static func collaboratorAuthorIDs(for game: GameEntity) -> Set<String> {
         var authors = Set<String>()
         if let owner = game.ckZoneOwnerName, !owner.isEmpty {
             authors.insert(owner)
         }
         let moves = (game.moves as? Set<MovesEntity>) ?? []
         for move in moves {
             if let authorID = move.authorID, !authorID.isEmpty {
                 authors.insert(authorID)
             }
         }
         for player in playerEntities(for: game) {
             if let authorID = player.authorID, !authorID.isEmpty {
                 authors.insert(authorID)
             }
         }
         return authors
     }
 }
 
 /// Repository over the local Core Data store. Manages the lifecycle of
 /// games — loading a specific one, creating new ones from bundled puzzles,
 /// and deleting them. The library list itself is driven by `@FetchRequest`
 /// in `GameListView`, not this type. Persistence of individual cell
 /// mutations is handled by `GameMutator`.
 @MainActor
 @Observable
 final class GameStore {
     /// Upper bound on how far past now an incoming realtime cell edit's
     /// `updatedAt` is trusted. Matches the relay worker's auth skew; a genuine
     /// cross-device clock difference stays well under it, while a crafted
     /// far-future timestamp is clamped so it can't win per-cell LWW forever.
     static let realtimeCellEditMaxFutureSkew: TimeInterval = 120
 
     let persistence: PersistenceController
     private var context: NSManagedObjectContext { persistence.viewContext }
 
     private(set) var currentGame: Game?
     private(set) var currentMutator: GameMutator?
     private(set) var currentEntity: GameEntity?
 
     private let movesUpdater: MovesUpdater
     private let movesJournal: MovesJournal
 
     /// Returns the current iCloud author ID, or nil while the first
     /// `userRecordID()` lookup is still pending. The inner Optional reflects
     /// genuine "don't know yet" state on first install.
     private let authorIDProvider: @MainActor () -> String?
 
     /// Called when a new game's `ckRecordName` is ready to push.
     private let onGameCreated: (String) -> Void
 
     /// Called with CloudKit zone metadata after a game is removed locally.
     private let onGameDeleted: (GameCloudDeletion) -> Void
 
     /// Called when a mutable field on the `Game` record (e.g. `completedAt`)
     /// changes and needs to be re-pushed.
     private let onGameUpdated: (String) -> Void
 
     /// Called once a game completes (win or resign) with `(gameID, authorID)`,
     /// so this device's move journal can be uploaded for later replay (Phase
     /// 2). Separate from `onGameUpdated`: that re-pushes the Game record, this
     /// pushes the per-device Journal asset. Assigned post-init (like the other
     /// UI-facing callbacks below) so the handler can reference `AppServices`.
     @ObservationIgnored
     var onJournalComplete: (@MainActor (UUID, String, Bool, Bool) -> Void)?
 
     /// Fires when the count of shared games with unseen other-author moves
     /// may have changed (inbound moves merged, a game opened, a game
     /// deleted). Consumers refresh the app-icon badge from here.
     @ObservationIgnored
     var onUnreadOtherMovesChanged: (() -> Void)?
     @ObservationIgnored
     var onPushRegistrationMayNeedRefresh: (@MainActor () -> Void)?
     @ObservationIgnored
     var onLocalCellEdit: (@MainActor (RealtimeCellEdit) -> Void)?
     @ObservationIgnored
     var onLocalCellEditBatch: (@MainActor ([RealtimeCellEdit]) -> Void)?
 
     private let eventLog: EventLog?
 
     init(
         persistence: PersistenceController,
         movesUpdater: MovesUpdater,
         authorIDProvider: @escaping @MainActor () -> String?,
         onGameCreated: @escaping (String) -> Void,
         onGameUpdated: @escaping (String) -> Void,
         onGameDeleted: @escaping (GameCloudDeletion) -> Void,
         eventLog: EventLog? = nil
     ) {
         self.persistence = persistence
         self.movesUpdater = movesUpdater
         // The journal needs nothing but the local store, so the store owns it
         // rather than having callers thread it in (unlike MovesUpdater, which
         // depends on identity + the sync sink and so is built in AppServices).
         self.movesJournal = MovesJournal(persistence: persistence)
         self.authorIDProvider = authorIDProvider
         self.onGameCreated = onGameCreated
         self.onGameUpdated = onGameUpdated
         self.onGameDeleted = onGameDeleted
         self.eventLog = eventLog
     }
 
     /// Re-applies the block-derived visibility rule to games featuring authors
     /// whose block state just changed.
     @discardableResult
     func reconcileBlockedFriendHiddenGames(forAuthorIDs authorIDs: Set<String>) async -> Int {
         let ctx = persistence.container.newBackgroundContext()
         let result: (changed: Int, errorMessage: String?) = await ctx.perform {
             let changed = GameEntity.reconcileBlockedFriendHiddenGames(
                 forAuthorIDs: authorIDs,
                 in: ctx
             )
             if changed > 0 {
                 do {
                     try ctx.save()
                 } catch {
                     return (
                         changed: 0,
                         errorMessage: "GameStore: reconcileBlockedFriendHiddenGames save failed — \(error)"
                     )
                 }
             }
             return (changed: changed, errorMessage: nil)
         }
         if let errorMessage = result.errorMessage {
             eventLog?.note(errorMessage, level: "error")
         }
         return result.changed
     }
 
     /// Re-applies the block-derived visibility rule to games that just changed
     /// in sync. This catches games that arrive after their collaborator was
     /// already blocked without scanning the whole library.
     @discardableResult
     func reconcileBlockedFriendHiddenGames(forGameIDs gameIDs: Set<UUID>) async -> Int {
         let ctx = persistence.container.newBackgroundContext()
         let result: (changed: Int, errorMessage: String?) = await ctx.perform {
             let changed = GameEntity.reconcileBlockedFriendHiddenGames(
                 forGameIDs: gameIDs,
                 in: ctx
             )
             if changed > 0 {
                 do {
                     try ctx.save()
                 } catch {
                     return (
                         changed: 0,
                         errorMessage: "GameStore: reconcileBlockedFriendHiddenGames save failed — \(error)"
                     )
                 }
             }
             return (changed: changed, errorMessage: nil)
         }
         if let errorMessage = result.errorMessage {
             eventLog?.note(errorMessage, level: "error")
         }
         return result.changed
     }
 
     private func saveContext(_ label: String) {
         do {
             try context.save()
         } catch {
             eventLog?.note("GameStore: \(label) save failed — \(error)", level: "error")
         }
     }
 
     enum LoadError: Error {
         case sampleResourceMissing
         case persistedSourceMissing
         case gameNotFound
         /// A joined game was offered a zone the current user owns. Shared
         /// games live in somebody else's zone by definition, so this is a
         /// mis-routed zone identity, not a game we can seat locally.
         case sharedZoneOwnedByCurrentUser
     }
 
     // MARK: - Remote update
 
     /// Re-replays the current game from its move log after remote moves have
     /// been written into Core Data by the sync engine.
     func refreshCurrentGame() {
         guard let game = currentGame, let entity = currentEntity else { return }
         refreshCurrentSyncState()
         // On this path the SyncEngine's inbound fetch has already replayed
         // the CellEntity cache atomically with the inbound MovesEntity
         // (see SyncEngine.replayCellCache); rewriting it here would do the
         // same work against the main context, so we skip it to keep the
         // main thread free during co-solve bursts.
         restore(game: game, from: entity, updateCache: false)
     }
 
     /// Refreshes only the active mutator's protocol/counter state. Game record
     /// changes use this lightweight path so a participant whose puzzle is
     /// already open adopts an owner upgrade before either player types again.
     func refreshCurrentSyncState() {
         guard let entity = currentEntity else { return }
         currentMutator?.updateSyncVersion(
             entity.syncVersion,
             observedLogicalTick: maximumLogicalTick(for: entity)
         )
     }
 
     /// Merges every device's `MovesEntity` rows for each game ID and updates
     /// the `CellEntity` cache so that list thumbnails reflect local edits
     /// immediately after a `MovesUpdater` flush, without waiting for the next
     /// sync cycle. Runs on a background context to keep the main actor free.
     func replayCellCaches(for gameIDs: Set<UUID>) async {
         let bgCtx = persistence.container.newBackgroundContext()
         bgCtx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         await bgCtx.perform {
             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? bgCtx.fetch(req).first else { continue }
 
                 let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 movesReq.predicate = NSPredicate(format: "game == %@", entity)
                 let values: [MovesValue] = ((try? bgCtx.fetch(movesReq)) ?? [])
                     .compactMap { Self.movesValue(from: $0) }
                 let grid = GridStateMerger.merge(values)
                 Self.applyCellCache(to: entity, from: grid, in: bgCtx)
             }
             if bgCtx.hasChanges {
                 try? bgCtx.save()
             }
         }
     }
 
     /// Serial queue feeding the peer-change ledger writer. The continuation is
     /// the producer end; a single long-lived consumer (started lazily on first
     /// use) drains it one request at a time. One consumer is the whole safety
     /// argument: builds never overlap, so the upsert-by-position in
     /// `updatePeerChangeLedger` can't duplicate a row.
     private var ledgerRequests: AsyncStream<Set<UUID>>.Continuation?
     private var peerChangeLedgerBuildSerial = 0
 
     /// Establishes the silent starting snapshot for a shared game's peer-change
     /// ledger. The durable flag is separate from the rows because an empty grid
     /// is still a valid seed; without it, the first later peer fill would be
     /// mistaken for pre-existing content and stamped at `.distantPast`.
     func ensurePeerChangeLedgerSeeded(for gameID: UUID) {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let game = try? context.fetch(request).first,
               game.completedAt == nil,
               !game.hasSeededPeerChanges else { return }
         enqueuePeerChangeLedgerUpdate(for: [gameID])
     }
 
     /// Fire-and-forget request to refresh the peer-change ledger for `gameIDs`.
     /// Returns immediately — the inbound-moves hot path must never wait on this
     /// database write. The request is just buffered onto the serial queue; the
     /// single consumer applies it when it gets there.
     func enqueuePeerChangeLedgerUpdate(for gameIDs: Set<UUID>) {
         guard !gameIDs.isEmpty else { return }
         eventLog?.note(
             "peer ledger enqueue: games=[\(gameIDs.map { String($0.uuidString.prefix(8)) }.sorted().joined(separator: ","))]"
         )
         if ledgerRequests == nil {
             let (stream, continuation) = AsyncStream<Set<UUID>>.makeStream()
             ledgerRequests = continuation
             // The sole consumer: serial by construction, so no two builds run at
             // once. Inherits this `@MainActor`, hopping to a background context
             // only inside `updatePeerChangeLedger`.
             Task { [weak self] in
                 for await gameIDs in stream {
                     await self?.updatePeerChangeLedger(for: gameIDs)
                 }
             }
         }
         ledgerRequests?.yield(gameIDs)
     }
 
     /// Maintains the device-local per-cell letter-change ledger
     /// (`PeerChangeEntity`) for each game that just received inbound moves. For
     /// every cell whose letter differs from what the ledger holds, upserts a row
     /// stamped with the move's letter-change time; a check (a mark-only
     /// re-stamp) leaves the letter unchanged and so writes nothing. A completed
     /// game is terminal, so its rows are dropped and not rebuilt. Runs on a
     /// background context, off the main actor.
     ///
     /// The ledger is what the "changed while you were away" borders and catch-up
     /// banner read (`recentChanges(forGame:since:)`). Recording a letter-change
     /// time — rather than trusting the synced cell's `updatedAt`, which a check
     /// bumps — is what stops a peer's check sweep from flagging the whole board
     /// on rejoin. A game with neither the durable seed flag nor legacy ledger
     /// rows records every current cell at `.distantPast`, a silent baseline that
     /// surfaces nothing; the separate flag lets an empty grid count as seeded.
     ///
     /// In the app this is driven through `enqueuePeerChangeLedgerUpdate`, whose
     /// single serial consumer guarantees builds never overlap — so the
     /// upsert-by-position below can't duplicate a row. Tests call it directly
     /// and `await` it for determinism.
     func updatePeerChangeLedger(for gameIDs: Set<UUID>) async {
         guard !gameIDs.isEmpty else { return }
         peerChangeLedgerBuildSerial += 1
         let serial = peerChangeLedgerBuildSerial
         let startedAt = Date()
         eventLog?.note(
             "peer ledger build #\(serial) start: games=[\(gameIDs.map { String($0.uuidString.prefix(8)) }.sorted().joined(separator: ","))]"
         )
         let ctx = persistence.container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let result: (diagnostics: [String], errorMessage: String?) = await ctx.perform {
             var diagnostics: [String] = []
             var errorMessage: String?
             for gameID in gameIDs {
                 let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
                 gameReq.fetchLimit = 1
                 guard let game = try? ctx.fetch(gameReq).first else {
                     diagnostics.append("\(gameID.uuidString.prefix(8)) missing-game")
                     continue
                 }
 
                 let ledgerReq = NSFetchRequest<PeerChangeEntity>(entityName: "PeerChangeEntity")
                 ledgerReq.predicate = NSPredicate(format: "gameID == %@", gameID as CVarArg)
                 let existingRows = (try? ctx.fetch(ledgerReq)) ?? []
 
                 // A completed game is terminal: its grid is sealed and the
                 // "changed while you were away" surfaces never read this ledger
                 // again, so drop the rows and stop maintaining it. The cleanup
                 // lives here, not only at the completion call site, because a
                 // late peer move can still arrive for a finished game.
                 if game.completedAt != nil {
                     for row in existingRows { ctx.delete(row) }
                     diagnostics.append(
                         "\(gameID.uuidString.prefix(8)) completed existing=\(existingRows.count) deleted"
                     )
                     continue
                 }
 
                 let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 movesReq.predicate = NSPredicate(format: "game == %@", game)
                 let values: [MovesValue] = ((try? ctx.fetch(movesReq)) ?? [])
                     .compactMap { Self.movesValue(from: $0) }
                 let current = GridStateMerger.mergeWithProvenance(values)
                 // Rows written by an older app already prove that game was
                 // seeded; honour them when migrating the new durable flag.
                 let isSeeding = !game.hasSeededPeerChanges && existingRows.isEmpty
 
                 var rowByPosition: [GridPosition: PeerChangeEntity] = [:]
                 for row in existingRows {
                     rowByPosition[GridPosition(row: Int(row.row), col: Int(row.col))] = row
                 }
                 let recorded = rowByPosition.mapValues { Self.peerChange(from: $0) }
 
                 let upserts = PeerChangeLedger.upserts(
                     current: current,
                     recorded: recorded,
                     seeding: isSeeding
                 )
                 game.hasSeededPeerChanges = true
                 diagnostics.append(
                     "\(gameID.uuidString.prefix(8)) existing=\(existingRows.count) "
                     + "moves=\(values.count) current=\(current.count) "
                     + "seeding=\(isSeeding) upserts=\(upserts.count) "
                     + Self.peerChangeSampleSummary(upserts)
                 )
                 for change in upserts {
                     // Positions originate in peer-controlled Moves payloads;
                     // the codec guarantees Int16 representability, and this
                     // keeps out-of-grid leftovers from becoming ledger rows.
                     guard change.position.isPersistable(
                         gridWidth: game.gridWidth,
                         gridHeight: game.gridHeight
                     ) else { continue }
                     let row = rowByPosition[change.position] ?? PeerChangeEntity(context: ctx)
                     row.gameID = gameID
                     row.row = Int16(change.position.row)
                     row.col = Int16(change.position.col)
                     row.letter = change.letter
                     row.authorID = change.authorID
                     row.changedAt = change.changedAt
                     row.game = game
                 }
             }
             guard ctx.hasChanges else {
                 return (diagnostics: diagnostics, errorMessage: errorMessage)
             }
             do {
                 try ctx.save()
             } catch {
                 errorMessage = "GameStore: peer change ledger save failed — \(error)"
             }
             return (diagnostics: diagnostics, errorMessage: errorMessage)
         }
         if let errorMessage = result.errorMessage {
             eventLog?.note(errorMessage, level: "error")
         }
         let elapsed = Date().timeIntervalSince(startedAt)
         eventLog?.note(
             "peer ledger build #\(serial) end: elapsed=\(String(format: "%.3f", elapsed))s "
             + result.diagnostics.joined(separator: " | ")
         )
     }
 
     /// Updates `latestOtherMoveAt` for each game whose Moves record was just
     /// updated by another iCloud user, driving the unread-badge heuristic.
     /// `gameIDs` are the games that received an inbound `Moves` record in the
     /// most recent sync batch; for each, we scan the now-persisted
     /// `MovesEntity` rows and pick the latest `updatedAt` whose row is owned
     /// by a different `authorID` than the local user. If the game is currently
     /// open, `lastReadOtherMoveAt` is advanced in lockstep so the badge
     /// doesn't appear for activity the user is already watching.
     func noteIncomingMovesUpdate(gameIDs: Set<UUID>, currentAuthorID: String?) {
         guard let currentAuthorID, !gameIDs.isEmpty else { return }
 
         for gameID in gameIDs {
             let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameReq.fetchLimit = 1
             guard let entity = try? context.fetch(gameReq).first else { continue }
 
             let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
             movesReq.predicate = NSPredicate(
                 format: "game == %@ AND authorID != %@",
                 entity,
                 currentAuthorID
             )
             let rows = (try? context.fetch(movesReq)) ?? []
             guard let latest = rows.compactMap(\.updatedAt).max() else { continue }
 
             if (entity.latestOtherMoveAt ?? .distantPast) < latest {
                 entity.latestOtherMoveAt = latest
             }
             // Use the foreground-visible signal rather than `currentEntity` —
             // the latter stays set after a normal back-out from the puzzle,
             // and would otherwise advance lastReadOtherMoveAt in lockstep
             // even when the user is sitting on the library list, suppressing
             // the badge that should appear there.
             // Suppressed = viewing here (incl. the local leave-grace) — the
             // user has eyes on these moves, so advance the *read watermark*
             // (`readThroughAt`) to what they're looking at. This is monotonic
             // and never forward-dated, so it cannot claim moves that arrive
             // after the user backgrounds. Sibling devices learn about the read
             // via `Player.readThrough`; the forward-dated presence lease
             // (`lastReadOtherMoveAt`) is published separately by AppServices.
             if NotificationState.isSuppressed(gameID: gameID),
                (entity.readThroughAt ?? .distantPast) < latest {
                 entity.readThroughAt = latest
             }
             mirrorReadStateToChronicle(from: entity)
         }
 
         if context.hasChanges {
             saveContext("mergeRemoteMoves")
         }
         onUnreadOtherMovesChanged?()
     }
 
     @discardableResult
     func applyRealtimeCellEdit(_ edit: RealtimeCellEdit) -> Bool {
         applyRealtimeCellEdits([edit]) > 0
     }
 
     /// Applies a batch of live cell edits with a single Core Data save and a
     /// single UI refresh, regardless of cell count. Edits are grouped by their
     /// owning Moves record (author + device), so each record is decoded and
     /// re-encoded once even for a whole-grid gesture like "check puzzle".
     /// Per-cell last-writer-wins is preserved. Returns the number of cells that
     /// actually changed.
     @discardableResult
     func applyRealtimeCellEdits(_ edits: [RealtimeCellEdit]) -> Int {
         // A live edit's `updatedAt` is attacker-controlled over the relay
         // channel. Clamp it to a bounded skew past now so a crafted far-future
         // timestamp can't win per-cell LWW permanently (and can't poison the
         // persisted Moves/Game `updatedAt`, which would then sync to CloudKit).
         // A genuine later edit always reclaims the cell once this is bounded.
         let maxAcceptableUpdatedAt = Date().addingTimeInterval(Self.realtimeCellEditMaxFutureSkew)
         let groups = Dictionary(grouping: edits) { edit in
             RecordSerializer.recordName(
                 forMovesInGame: edit.gameID,
                 authorID: edit.authorID,
                 deviceID: edit.deviceID
             )
         }
 
         var applied = 0
         var rejected = 0
         var touchedGameIDs: Set<UUID> = []
         for (recordName, groupEdits) in groups {
             guard let sample = groupEdits.first,
                   !sample.authorID.isEmpty,
                   !sample.deviceID.isEmpty,
                   sample.deviceID != RecordSerializer.localDeviceID,
                   let entity = fetchGameEntity(id: sample.gameID)
             else { continue }
 
             // A live edit's coordinates are attacker-controlled over the
             // relay channel, like its `updatedAt` below. Reject anything
             // outside the grid before it reaches the persisted Moves state,
             // whose Int16 cache sinks trap on overflow — and before an
             // all-rejected batch can insert an empty MovesEntity stub.
             let validEdits = groupEdits.filter { edit in
                 GridPosition(row: edit.row, col: edit.col).isPersistable(
                     gridWidth: entity.gridWidth,
                     gridHeight: entity.gridHeight
                 )
             }
             rejected += groupEdits.count - validEdits.count
             guard !validEdits.isEmpty else { continue }
 
             let movesEntity = ensureMovesEntity(
                 recordName: recordName,
                 game: entity,
                 authorID: sample.authorID,
                 deviceID: sample.deviceID
             )
 
             var cells: [GridPosition: TimestampedCell] = [:]
             if let data = movesEntity.cells, !data.isEmpty {
                 cells = (try? MovesCodec.decode(data)) ?? [:]
             }
 
             var latest = movesEntity.updatedAt ?? .distantPast
             var changed = false
             for edit in validEdits {
                 let position = GridPosition(row: edit.row, col: edit.col)
                 let clampedUpdatedAt = min(edit.updatedAt, maxAcceptableUpdatedAt)
                 let incoming = TimestampedCell(
                     letter: edit.letter,
                     mark: edit.mark,
                     updatedAt: clampedUpdatedAt,
                     authorID: edit.cellAuthorID,
                     tick: edit.tick
                 )
                 if let current = cells[position],
                    current.compareRevision(to: incoming) == .orderedDescending {
                     continue
                 }
                 cells[position] = incoming
                 changed = true
                 applied += 1
                 if clampedUpdatedAt > latest { latest = clampedUpdatedAt }
             }
 
             guard changed else { continue }
             movesEntity.cells = (try? MovesCodec.encode(cells)) ?? Data()
             if (movesEntity.updatedAt ?? .distantPast) < latest {
                 movesEntity.updatedAt = latest
             }
             if (entity.updatedAt ?? .distantPast) < latest {
                 entity.updatedAt = latest
             }
             touchedGameIDs.insert(sample.gameID)
         }
 
         if rejected > 0 {
             eventLog?.note(
                 "GameStore: rejected \(rejected) out-of-grid realtime cell edit(s)",
                 level: "error"
             )
         }
         guard applied > 0 else { return 0 }
         saveContext("applyRealtimeCellEdits")
         if let openID = currentEntity?.id, touchedGameIDs.contains(openID) {
             refreshCurrentGame()
         }
         onUnreadOtherMovesChanged?()
         return applied
     }
 
     /// Number of shared games with unseen other-author moves — the same
     /// `hasUnreadOtherMoves` heuristic the library list uses, aggregated as
     /// a count for the app-icon badge.
     func unreadOtherMovesGameCount() -> Int {
         unreadOtherMovesGameTimes().count
     }
 
     /// The same heuristic as `unreadOtherMovesGameCount`, returning the
     /// individual game IDs so the App Group `BadgeState` set can be unioned
     /// with NSE-added entries.
     func unreadOtherMovesGameIDs() -> Set<UUID> {
         Set(unreadOtherMovesGameTimes().keys)
     }
 
     func hasUnreadOtherMoves(gameID: UUID) -> Bool {
         unreadOtherMovesGameIDs().contains(canonicalGameID(for: gameID))
     }
 
     /// The same heuristic as `unreadOtherMovesGameIDs`, but paired with each
     /// game's newest unseen other-author move time (`latestOtherMoveAt`, which
     /// the predicate guarantees is non-nil). The app seeds these into the App
     /// Group `BadgeState` ledger as `unreadAt` horizons so the Notification
     /// Service Extension — which can't reach Core Data — inherits this ground
     /// truth when it stamps the badge for a push that lands while the app is
     /// suspended. The timestamp is what keeps the seed safe: a game the user
     /// has since opened carries a newer `seenAt` and won't resurrect.
     func unreadOtherMovesGameTimes() -> [UUID: Date] {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = unreadOtherMovesPredicate
         request.propertiesToFetch = ["id", "latestOtherMoveAt"]
         let rows = (try? context.fetch(request)) ?? []
         var result: [UUID: Date] = [:]
         for row in rows {
             if let id = row.id, let at = row.latestOtherMoveAt {
                 let canonicalID = row.ckRecordName.flatMap(
                     Archive.originalGameID(fromName:)
                 ) ?? id
                 result[canonicalID] = max(result[canonicalID] ?? .distantPast, at)
             }
         }
         return result
     }
 
     /// Games this account has a pending (un-acted) invite to, excluding invites
     /// from blocked collaborators — the same set the library's "Invited" section
     /// shows (`GameListView` filters blocked inviters at display time). The app
     /// publishes these into `BadgeState` so a pending invite counts toward the
     /// app-icon badge. A pending `InviteEntity` is dropped once its `GameEntity`
     /// exists, so this set is disjoint from the unread-other-moves set.
     func pendingInviteGameIDs() -> Set<UUID> {
         let blockedRequest = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         blockedRequest.predicate = NSPredicate(format: "isBlocked == YES")
         blockedRequest.propertiesToFetch = ["authorID"]
         let blocked = Set(((try? context.fetch(blockedRequest)) ?? []).compactMap(\.authorID))
 
         let request = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         request.predicate = NSPredicate(format: "status == %@", "pending")
         request.propertiesToFetch = ["gameID", "inviterAuthorID"]
         let rows = (try? context.fetch(request)) ?? []
         return Set(rows.compactMap { invite in
             guard let id = invite.gameID else { return nil }
             if let inviter = invite.inviterAuthorID, blocked.contains(inviter) { return nil }
             return id
         })
     }
 
     private var unreadOtherMovesPredicate: NSPredicate {
         // Keyed off the read *watermark* (`readThroughAt`), not the forward-
         // dated presence lease (`lastReadOtherMoveAt`) — matches
         // `GameSummary.computeHasUnread`. A shared Chronicle is locally owned
         // (`databaseScope == 0`) but still participates after retirement
         // deletes its live row; `unreadOtherMovesGameTimes` canonicalizes the
         // overlapping rows to one original game ID before counting.
         NSPredicate(
             format: "(databaseScope == 1 OR ckShareRecordName != nil "
                 + "OR archiveParticipants != nil) "
                 + "AND latestOtherMoveAt != nil "
                 + "AND (readThroughAt == nil OR latestOtherMoveAt > readThroughAt)"
         )
     }
 
     // MARK: - Load a specific game
 
     /// Loads a game by its entity ID. Sets it as the current game.
     func loadGame(id: UUID) throws -> (Game, GameMutator) {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
 
         guard let entity = try context.fetch(request).first else {
             throw LoadError.gameNotFound
         }
         try upgradeOwnedGameSyncVersionIfNeeded(entity)
         let puzzle = try preparePuzzleForLoad(from: entity)
         let game = Game(puzzle: puzzle)
         restore(game: game, from: entity)
 
         let mutator = makeMutator(game: game, entity: entity)
 
         currentGame = game
         currentMutator = mutator
         currentEntity = entity
         markOtherMovesRead(for: entity)
 
         return (game, mutator)
     }
 
     /// The stable identity used by notifications and unread state. A
     /// materialized Chronicle has its own Core Data ID so it can coexist with
     /// the retained live row, but its record name preserves the original game
     /// ID that pushes and Player records use.
     func canonicalGameID(for storedGameID: UUID) -> UUID {
         guard let entity = fetchGameEntity(id: storedGameID),
               let recordName = entity.ckRecordName,
               let originalID = Archive.originalGameID(fromName: recordName)
         else { return storedGameID }
         return originalID
     }
 
     /// Whether either persisted representation in a live-game/Chronicle family
     /// is terminal. Used only for account-level read receipts: unlike an active
     /// puzzle, a completed game cannot gain a later move after a sibling says
     /// it has been opened, so the receiving device can safely advance its local
     /// Chronicle watermark immediately.
     func isCompletedGameFamily(gameID: UUID) -> Bool {
         let canonicalID = canonicalGameID(for: gameID)
         return readStateEntities(canonicalGameID: canonicalID).contains {
             $0.completedAt != nil
         }
     }
 
     // MARK: - Duplicate detection
 
     /// Returns the ID of an existing game for the same source. Exact source
     /// matches win, then catalog resource ID/title matches catch older stored
     /// copies of a packaged puzzle.
     func findGameID(matching source: String) -> UUID? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "puzzleSource == %@", source)
         request.fetchLimit = 1
         if let exact = try? context.fetch(request).first?.id {
             return exact
         }
 
         guard let xd = try? XD.parse(source) else { return nil }
         let resourceID = PuzzleCatalog.resourceID(matching: source)
         let fallback = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         if let resourceID {
             fallback.predicate = NSPredicate(format: "puzzleResourceID == %@", resourceID)
             fallback.fetchLimit = 1
             if let match = try? context.fetch(fallback).first?.id {
                 return match
             }
         }
 
         guard resourceID != nil, let title = xd.title else { return nil }
         fallback.predicate = NSPredicate(format: "title == %@", title)
         fallback.fetchLimit = 1
         return (try? context.fetch(fallback).first?.id)
     }
 
     /// Returns NYT publication dates already present in the local library.
     /// Games hidden by the block table are excluded — those aren't something
     /// the browser should report back as "you have this" — but a live row
     /// superseded by its Chronicle is *not*: the user still holds that puzzle,
     /// and whether the pair has been compacted yet is invisible to them. Both
     /// rows in a live/Chronicle family carry the same publication date, and
     /// the returned `Set` collapses the duplicate.
     ///
     /// Rows only cover what is currently local, which is live games plus the
     /// recently completed: everything older has been compacted into a Chronicle
     /// and evicted. `ChronicleLedgerEntity` carries those dates, so the two are
     /// unioned — each half derived from its own authority, and the `Set`
     /// collapses a date that both report.
     ///
     /// Fetched as dictionaries rather than managed objects: the only column
     /// wanted is a `Date`, and materialising `GameEntity` rows would drag the
     /// whole library's `puzzleSource` XD text through the row cache with it.
     /// Dictionary results read the store rather than the context, which is
     /// safe here because `createGame` saves before it returns.
     func nytPuzzleDatesInLibrary() -> Set<Date> {
         let request = NSFetchRequest<NSDictionary>(entityName: "GameEntity")
         request.resultType = .dictionaryResultType
         request.propertiesToFetch = ["cachedPuzzleDate"]
         request.returnsDistinctResults = true
         request.includesPendingChanges = false
         request.predicate = NSPredicate(
             format: "isHidden == NO AND cachedPublisher == %@ AND cachedPuzzleDate != nil",
             "New York Times"
         )
         let rows = (try? context.fetch(request)) ?? []
         var dates = rows.compactMap { $0["cachedPuzzleDate"] as? Date }
         dates.append(
             contentsOf: ChronicleLedgerEntity.puzzleDates(
                 publisher: "New York Times",
                 blockedAuthorIDs: GameEntity.blockedAuthorIDs(in: context),
                 in: context
             )
         )
 
         var calendar = Calendar(identifier: .gregorian)
         calendar.timeZone = TimeZone(identifier: "America/New_York") ?? .gmt
         return Set(dates.map { calendar.startOfDay(for: $0) })
     }
 
     /// Returns joined CloudKit-share games that have a usable puzzle payload.
     /// Placeholders created from shared-zone discovery are intentionally
     /// excluded until the root Game record has arrived.
     func joinedSharedGameIDs() -> Set<UUID> {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "databaseScope == 1 AND puzzleSource != nil AND puzzleSource != %@",
             ""
         )
         return Set(((try? context.fetch(request)) ?? []).compactMap(\.id))
     }
 
     // MARK: - Create a new game
 
     /// Creates a new game from XD source text. Returns the new game's UUID.
     func createGame(from source: String) throws -> UUID {
         let xd = try XD.parse(source)
         let puzzle = Puzzle(xd: xd)
 
         let now = Date()
         let gameID = UUID()
         let entity = GameEntity(context: context)
         entity.id = gameID
         entity.title = puzzle.title
         entity.puzzleSource = source
         entity.puzzleParserVersion = Int64(XD.currentParserVersion)
         entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source)
         entity.createdAt = now
         entity.updatedAt = now
         entity.ckRecordName = "game-\(gameID.uuidString)"
         entity.ckZoneName = "game-\(gameID.uuidString)"
         entity.databaseScope = 0
         entity.syncVersion = GameSyncVersion.current
         entity.populateCachedSummaryFields(from: puzzle)
 
         try context.save()
         onGameCreated("game-\(gameID.uuidString)")
         return gameID
     }
 
     /// Builds a complete participant game (`databaseScope == 1`) from an
     /// invite's serialised XD source, so a freshly-accepted shared game is
     /// immediately playable and fully listed without waiting on the shared-zone
     /// fetch. Everything derives from the source exactly as `createGame` does;
     /// only the zone identity comes from the share. Unlike `createGame` it
     /// enqueues no push — the participant doesn't own this zone — and it leaves
     /// `ckSystemFields` nil, so the first canonical Game-record sync adopts the
     /// server etag and updates this row in place (matched by `ckRecordName` in
     /// `RecordSerializer.fetchOrCreate`) rather than creating a duplicate.
     /// No-ops if a row for the game already exists — a sibling device or an
     /// earlier sync got there first.
     func constructJoinedGame(
         gameID: UUID,
         zoneID: CKRecordZone.ID,
         source: String,
         notification: String? = nil
     ) throws {
         // A share's zone always belongs to its owner, so an own-owner zone
         // here is a mis-routed identity. Refuse it rather than normalising the
         // owner to nil: that spelling means "private zone" everywhere else, and
         // a `databaseScope == 1` row carrying it can never be matched by either
         // scope's `gameIdentityPredicate` again. The caller falls back to the
         // ordinary shared-zone fetch.
         guard zoneID.ownerName != CKCurrentUserDefaultName else {
             throw LoadError.sharedZoneOwnedByCurrentUser
         }
         let recordName = "game-\(gameID.uuidString)"
         let existing = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         existing.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         existing.fetchLimit = 1
         if let existingEntity = try? context.fetch(existing).first {
             if existingEntity.notification == nil, let notification {
                 existingEntity.notification = notification
                 GameEntity.rebuildContentKeyDirectory(in: context)
                 try context.save()
             }
             return
         }
 
         let xd = try XD.parse(source)
         let puzzle = Puzzle(xd: xd)
         let now = Date()
         let entity = GameEntity(context: context)
         entity.id = gameID
         entity.title = puzzle.title
         entity.puzzleSource = source
         entity.puzzleParserVersion = Int64(XD.currentParserVersion)
         entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source)
         entity.createdAt = now
         entity.updatedAt = now
         entity.ckRecordName = recordName
         entity.ckZoneName = zoneID.zoneName
         entity.ckZoneOwnerName = zoneID.ownerName
         entity.databaseScope = 1
         entity.syncVersion = GameSyncVersion.legacy
         entity.notification = notification
         entity.populateCachedSummaryFields(from: puzzle)
         if notification != nil {
             GameEntity.rebuildContentKeyDirectory(in: context)
         }
 
         try context.save()
     }
 
     // MARK: - Delete a game
 
     func deleteGame(id: UUID) throws {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
 
         guard let entity = try context.fetch(request).first else { return }
 
         let materializedOriginalID = entity.ckRecordName.flatMap(
             Archive.originalGameID(fromName:)
         )
         let originalGameID = materializedOriginalID ?? id
         let isMaterializedArchive = materializedOriginalID != nil
         let hasArchive = isMaterializedArchive || entity.archivedAt != nil
         let deletion = GameCloudDeletion(
             gameID: id,
             databaseScope: DatabaseScope(entityValue: entity.databaseScope),
             ckZoneName: entity.ckZoneName ?? "game-\(id.uuidString)",
             ckZoneOwnerName: entity.ckZoneOwnerName ?? CKCurrentUserDefaultName,
             deletesLiveZone: !isMaterializedArchive,
             archiveRecordName: hasArchive
                 ? Archive.recordName(forOriginalGameID: originalGameID)
                 : nil,
             legacyArchiveZoneName: hasArchive
                 ? Archive.legacyZoneID(forOriginalGameID: originalGameID).zoneName
                 : nil
         )
 
         // Clear current references if this is the active game
         if currentEntity?.id == id {
             currentGame = nil
             currentMutator = nil
             currentEntity = nil
         }
 
         // The archive record goes with the game, so its index entry goes too.
         // Deletions made on another device are caught by the reconcile instead.
         if hasArchive {
             ChronicleLedgerEntity.remove(originalGameID: originalGameID, in: context)
         }
 
         context.delete(entity)
         try context.save()
         onGameDeleted(deletion)
         onPushRegistrationMayNeedRefresh?()
         onUnreadOtherMovesChanged?()
     }
 
     // MARK: - Resign a game
 
     /// Reveals all cells and marks the game as completed (resigned). A
     /// revoked participant cannot resign: that would turn the read-only
     /// revoked copy into a terminal completed game.
     func resignGame(id: UUID) throws {
         guard let existing = fetchGameEntity(id: id),
               !existing.isAccessRevoked,
               GameSyncVersion.supports(existing.syncVersion)
         else { return }
         let (game, mutator) = try loadGame(id: id)
         let allCells = game.puzzle.cells.flatMap { $0 }
         mutator.revealCells(allCells)
 
         guard let entity = currentEntity else { return }
         let completedAt = Date()
         entity.completedAt = completedAt
         markObservedCompletionRead(for: entity, at: completedAt)
         // Resignation: no solver, so `completedBy` stays nil — that's how a
         // resigned game is told apart from a win.
         entity.completedBy = nil
         entity.hasPendingSave = true
         try context.save()
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         Task { await movesUpdater.flush() }
         triggerJournalUpload(id: id, resigned: true, notifyPeers: true)
 
         // Clean up current references
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
     }
 
     /// Rewrites every local row authored under a device-local fallback identity
     /// to the resolved iCloud author id. Offline play stamps a `local-<UUID>`
     /// author so writes can persist without an account (the moves/cell layers
     /// refuse to flush without one); when the user signs in, this realigns that
     /// data — including the author-embedding CloudKit record names — before the
     /// sync engine ever pushes it. Safe precisely because fallback-authored rows
     /// were never synced: no account existed, so no server record predates them.
     func remapAuthorID(from oldID: String, to newID: String) {
         guard oldID != newID, !oldID.isEmpty, !newID.isEmpty else { return }
 
         func fetch<T: NSManagedObject>(_ entityName: String, where predicate: NSPredicate) -> [T] {
             let request = NSFetchRequest<T>(entityName: entityName)
             request.predicate = predicate
             return (try? context.fetch(request)) ?? []
         }
 
         let matchesOld = NSPredicate(format: "authorID == %@", oldID)
 
         // Plain author fields — no author in their record name.
         for game: GameEntity in fetch("GameEntity", where: NSPredicate(format: "completedBy == %@", oldID)) {
             game.completedBy = newID
         }
         for cell: CellEntity in fetch("CellEntity", where: NSPredicate(format: "letterAuthorID == %@", oldID)) {
             cell.letterAuthorID = newID
         }
         for entry: JournalEntity in fetch("JournalEntity", where: NSPredicate(
             format: "actingAuthorID == %@ OR cellAuthorID == %@ OR beforeCellAuthorID == %@ OR sourceAuthorID == %@",
             oldID, oldID, oldID, oldID
         )) {
             if entry.actingAuthorID == oldID { entry.actingAuthorID = newID }
             if entry.cellAuthorID == oldID { entry.cellAuthorID = newID }
             if entry.beforeCellAuthorID == oldID { entry.beforeCellAuthorID = newID }
             if entry.sourceAuthorID == oldID { entry.sourceAuthorID = newID }
         }
 
         // Author-embedded record names — rewrite the name and drop any cached
         // system fields so the row pushes fresh under the real id.
         for moves: MovesEntity in fetch("MovesEntity", where: matchesOld) {
             moves.authorID = newID
             if let gameID = moves.game?.id, let deviceID = moves.deviceID {
                 moves.ckRecordName = RecordSerializer.recordName(
                     forMovesInGame: gameID, authorID: newID, deviceID: deviceID
                 )
                 moves.ckSystemFields = nil
             }
         }
         for player: PlayerEntity in fetch("PlayerEntity", where: matchesOld) {
             player.authorID = newID
             if let gameID = player.game?.id {
                 player.ckRecordName = RecordSerializer.recordName(
                     forPlayerInGame: gameID, authorID: newID
                 )
                 player.ckSystemFields = nil
             }
         }
 
         saveContext("remapAuthorID")
     }
 
     /// Marks a game as completed after a normal win. Returns whether the
     /// entity changed; no-ops if already marked.
     /// Triggers a buffer flush so the completion snapshot is created promptly
     /// rather than waiting for the next keystroke or app-background event.
     @discardableResult
     func markCompleted(id: UUID) throws -> Bool {
         try persistCompletion(id: id, completedBy: authorIDProvider(), notifyPeers: true)
     }
 
     /// Marks a game completed after the visible grid became solved through
     /// observed state, e.g. a collaborator's realtime edit. Uses the writer of
     /// the latest winning cell as the solver when provenance is available.
     @discardableResult
     func markCompletedFromObservedSolvedState(id: UUID) throws -> Bool {
         let solver = inferredObservedCompletionAuthorID(for: id) ?? authorIDProvider()
         return try persistCompletion(id: id, completedBy: solver, notifyPeers: false)
     }
 
     @discardableResult
     private func persistCompletion(
         id: UUID,
         completedBy authorID: String?,
         notifyPeers: Bool
     ) throws -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
         guard let entity = try context.fetch(request).first,
               entity.completedAt == nil,
               // A revoked participant can't legitimately finish the game, so
               // never latch a revoked copy into a terminal completed state.
               !entity.isAccessRevoked,
               GameSyncVersion.supports(entity.syncVersion)
         else { return false }
         let completedAt = Date()
         entity.completedAt = completedAt
         markObservedCompletionRead(for: entity, at: completedAt)
         // A win: stamp the solver so the Game record can distinguish wins
         // from resignations and the completion APN body can name them.
         entity.completedBy = authorID
         entity.hasPendingSave = true
         try context.save()
         // The game is now terminal, so its peer-change ledger is dead weight.
         // The writer drops the rows once it sees completedAt — schedule it.
         enqueuePeerChangeLedgerUpdate(for: [id])
         // Lock the open session immediately so no further input lands on the
         // now-terminal game (the view also reflects this via `isSolved`).
         if currentEntity?.id == id {
             currentMutator?.isCompleted = true
         }
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         Task { await movesUpdater.flush() }
         triggerJournalUpload(id: id, resigned: false, notifyPeers: notifyPeers)
         return true
     }
 
     /// Seals the read watermark when this device observes a game becoming
     /// terminal. Every legitimate move in the finished grid precedes this
     /// instant, so a collaborator's final Moves snapshot may arrive after the
     /// user leaves without turning the game unread again. A device that learns
     /// about completion later through sync does not take this path and still
     /// surfaces the completed game as unread.
     private func markObservedCompletionRead(for entity: GameEntity, at completedAt: Date) {
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared else { return }
         if (entity.readThroughAt ?? .distantPast) < completedAt {
             entity.readThroughAt = completedAt
         }
         mirrorReadStateToChronicle(from: entity)
     }
 
     /// Signals that a just-completed game's move journal should be uploaded
     /// (Phase 2). Fired synchronously on the main actor at completion so the
     /// app layer can take a background-execution assertion *before* any
     /// suspension point — the flush and CKSyncEngine enqueue then run under it
     /// via `flushJournal()`. Attributed to the local user (not the solver) — a
     /// resigner still has a log to upload.
     private func triggerJournalUpload(id: UUID, resigned: Bool, notifyPeers: Bool) {
         guard let authorID = authorIDProvider(), !authorID.isEmpty else { return }
         onJournalComplete?(id, authorID, resigned, notifyPeers)
     }
 
     /// Drains the journal's async persistence queue so the upload's record
     /// builder, reading Core Data on its own context, sees every entry. Called
     /// by the app-layer upload path under its background assertion.
     func flushJournal() async {
         await movesJournal.flush()
     }
 
     /// Drains both the cell-write buffer and the journal queue so a reader on a
     /// fresh background context sees the *finished* grid and this device's full
     /// local log — rather than buffered-but-unpersisted state. The completion
     /// archive snapshots Core Data directly, so it must run after this; the
     /// winning move in particular is still in flight when `persistCompletion`
     /// returns.
     func flushCompletionWrites() async {
         await movesUpdater.flush()
         await movesJournal.flush()
     }
 
     /// This device's live journal for a game, tagged with its device key. The
     /// replay assembler overlays this over any uploaded copy of ourselves: the
     /// in-memory log is the session's authoritative copy and may be fresher than
     /// what's round-tripped to CloudKit. `nil` until the local author is known.
     func localReplaySource(gameID: UUID) -> DeviceJournal? {
         guard let authorID = authorIDProvider(), !authorID.isEmpty else { return nil }
         let key = JournalDeviceKey(authorID: authorID, deviceID: RecordSerializer.localDeviceID)
         return DeviceJournal(key: key, entries: movesJournal.recordedEntries(gameID: gameID))
     }
 
     /// This device's journal entries for a game, independent of iCloud identity.
     /// The journal is recorded locally as the player types, so it exists even
     /// with no signed-in account — the local replay path uses this directly
     /// rather than `localReplaySource`, which needs an authorID to form a key.
     func localJournalEntries(for gameID: UUID) -> [JournalValue] {
         movesJournal.recordedEntries(gameID: gameID)
     }
 
     /// A Chronicle with no embedded journals is either still waiting for its
     /// live zone to collect every device's history, or is the terminal fallback
     /// written when that retry window expires.
     func archivedReplayBlocker(forGameID gameID: UUID) async -> JournalReplayResult? {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             guard let game = try? ctx.fetch(req).first else { return nil }
             if game.replayUnavailable { return .unavailable }
             if let missing = game.replayMissingDeviceCount?.intValue, missing > 0 {
                 return .waiting(missing: missing)
             }
             return nil
         }
     }
 
     /// Other devices' journals cached locally for replay, grouped by source
     /// device — or `nil` if this game's cache isn't known-complete yet
     /// (`replayCacheComplete`), in which case the caller must fetch from
     /// CloudKit. These are stored as `JournalEntity` rows carrying a source key
     /// (`sourceDeviceID != nil`), kept out of this device's own log. A finished
     /// game's journals never change, so once cached they replay offline; the
     /// live local journal is overlaid separately by `localReplaySource`, so this
     /// deliberately excludes any cached copy of ourselves and may be empty (a
     /// solo game has no remote contributors but is still "complete").
     func cachedRemoteJournals(forGameID gameID: UUID) async -> [DeviceJournal]? {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameReq.fetchLimit = 1
             guard let game = try? ctx.fetch(gameReq).first, game.replayCacheComplete else {
                 return nil
             }
             let req = NSFetchRequest<JournalEntity>(entityName: "JournalEntity")
             req.predicate = NSPredicate(
                 format: "gameID == %@ AND sourceDeviceID != nil", gameID as CVarArg
             )
             req.sortDescriptors = [NSSortDescriptor(key: "seq", ascending: true)]
             let rows = (try? ctx.fetch(req)) ?? []
             var byDevice: [JournalDeviceKey: [JournalValue]] = [:]
             for row in rows {
                 let key = JournalDeviceKey(
                     authorID: row.sourceAuthorID ?? "",
                     deviceID: row.sourceDeviceID ?? ""
                 )
                 byDevice[key, default: []].append(MovesJournal.value(from: row))
             }
             return byDevice.map { DeviceJournal(key: $0.key, entries: $0.value) }
         }
     }
 
     /// Persists `journals` (other devices' logs) as this game's replay cache and
     /// marks it `replayCacheComplete`, so later opens replay from Core Data with
     /// no CloudKit round-trip. Safe because a completed game's journals are
     /// frozen by edit-lockout. Idempotent: replaces any existing cached rows for
     /// the game. Rows carry a source key so the local-log readers skip them.
     func cacheRemoteJournals(_ journals: [DeviceJournal], forGameID gameID: UUID) async {
         let ctx = persistence.container.newBackgroundContext()
         let eventLog = eventLog
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         await ctx.perform {
             let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameReq.fetchLimit = 1
             guard let game = try? ctx.fetch(gameReq).first else { return }
 
             let stale = NSFetchRequest<JournalEntity>(entityName: "JournalEntity")
             stale.predicate = NSPredicate(
                 format: "gameID == %@ AND sourceDeviceID != nil", gameID as CVarArg
             )
             for row in (try? ctx.fetch(stale)) ?? [] { ctx.delete(row) }
 
             // Remote journal entries are peer-controlled; the codec already
             // dropped Int16-unrepresentable coordinates, and this skips
             // anything outside the recorded grid before it becomes a cached
             // replay row.
             var skippedOutOfGrid = 0
             for journal in journals {
                 for value in journal.entries {
                     guard value.position.isPersistable(
                         gridWidth: game.gridWidth,
                         gridHeight: game.gridHeight
                     ) else {
                         skippedOutOfGrid += 1
                         continue
                     }
                     let row = JournalEntity(context: ctx)
                     MovesJournal.assign(value, to: row, gameID: gameID)
                     row.sourceAuthorID = journal.key.authorID
                     row.sourceDeviceID = journal.key.deviceID
                     row.game = game
                 }
             }
             if skippedOutOfGrid > 0 {
                 let message = "GameStore: replay cache skipped \(skippedOutOfGrid) "
                     + "out-of-grid remote journal entr(ies)"
                 Task { @MainActor in
                     eventLog?.note(message, level: "error")
                 }
             }
             game.replayCacheComplete = true
             do {
                 try ctx.save()
             } catch {
                 let message = "GameStore: replay cache save failed — \(error)"
                 Task { @MainActor in
                     eventLog?.note(message, level: "error")
                 }
             }
         }
     }
 
     // MARK: - Engagement room
 
     /// `true` once `gameID` has been completed (solved or resigned). A
     /// completed game is no longer a live collaborative session, so engagement
     /// is torn down and peer cursors are suppressed for it.
     func isCompleted(gameID: UUID) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         return (try? context.fetch(request).first)?.completedAt != nil
     }
 
     /// The shared live-engagement room creds for `gameID` (an encoded
     /// `EngagementRoomCredentials`), or nil if none has been minted yet.
     func engagement(for gameID: UUID) -> String? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         return (try? context.fetch(request).first)?.engagement
     }
 
     /// Writes the engagement room creds for `gameID` and enqueues a Game-record
     /// push. No-op (returns false) when unchanged or the game isn't shared.
     /// Sets `hasPendingSave` so an inbound Game record can't clobber freshly
     /// minted creds before the push lands; record-level LWW then converges any
     /// concurrent mint by another participant.
     @discardableResult
     func setEngagement(_ encoded: String?, for gameID: UUID) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first else { return false }
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared, entity.engagement != encoded else { return false }
         entity.engagement = encoded
         entity.hasPendingSave = true
         saveContext("setEngagement")
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         return true
     }
 
     /// The shared per-game push credential for `gameID` (an encoded
     /// `GamePushCredentials`), or nil if none has been minted yet.
     func notification(for gameID: UUID) -> String? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         return (try? context.fetch(request).first)?.notification
     }
 
     /// Writes the notification credentials for `gameID` and enqueues a
     /// Game-record push, mirroring `setEngagement`. On a real change also
     /// re-mirrors the App Group content-key directory the NSE reads (the blob
     /// carries the content key). No-op (false) when unchanged or not shared.
     @discardableResult
     func setNotification(_ encoded: String?, for gameID: UUID) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first else { return false }
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared, entity.notification != encoded else { return false }
         entity.notification = encoded
         entity.hasPendingSave = true
         saveContext("setNotification")
         GameEntity.rebuildContentKeyDirectory(in: context)
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         return true
     }
 
     /// Returns the shared notification credentials for `gameID`, minting and
     /// persisting a fresh one (and enqueuing the Game-record push, so
     /// participants converge) when the game is shared and none exists yet. A
     /// legacy credential minted before content keys existed is backfilled with a
     /// fresh one in place, preserving its `credID`/`secret` so worker
     /// registration stays valid. Any participant may mint; record-level LWW
     /// resolves concurrent mints. Returns nil for a non-shared or missing game,
     /// or if minting fails.
     @discardableResult
     func ensurePushCredentials(for gameID: UUID) -> GamePushCredentials? {
         if var existing = GamePushCredentials.decode(notification(for: gameID)) {
             if existing.contentKey != nil { return existing }
             // Backfill a content key onto a legacy credential, keeping its auth
             // material so the worker registration is unaffected.
             guard let key = try? GamePushCredentials.freshContentKey() else { return existing }
             existing.contentKey = key
             guard let encoded = try? existing.encoded(), setNotification(encoded, for: gameID)
             else { return existing }
             return existing
         }
         guard let fresh = try? GamePushCredentials.fresh(),
               let encoded = try? fresh.encoded(),
               setNotification(encoded, for: gameID)
         else { return nil }
         return fresh
     }
 
     /// Replaces the game's push credentials wholesale — new `credID`, worker
     /// secret, and content key at the next rotation generation — because a
     /// participant left or was removed. The departed device holds every field
     /// of the old credential, so only full replacement revokes its ability to
     /// receive, publish, or re-subscribe; the generation is what stops a stale
     /// device's Game-record re-push from resurrecting the old one. Any
     /// remaining device may rotate; record-level LWW converges concurrent
     /// rotations. No-op for a game with no credentials yet (nothing to revoke)
     /// — `ensurePushCredentials` will mint at the current roster on demand.
     @discardableResult
     func rotatePushCredentials(for gameID: UUID) -> GamePushCredentials? {
         guard let current = GamePushCredentials.decode(notification(for: gameID)),
               let fresh = try? GamePushCredentials.rotated(after: current),
               let encoded = try? fresh.encoded(),
               setNotification(encoded, for: gameID)
         else { return nil }
         return fresh
     }
 
     /// Whether any game rows remain in the local store — the cheap, offline
     /// signal that this build carried data over from a previous CloudKit
     /// generation (used by the v3→v4 transition ahead of any network probe).
     func hasAnyGames() -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         return ((try? context.count(for: request)) ?? 0) > 0
     }
 
     // MARK: - Reset
 
     /// Deletes every game (and its cascaded moves, snapshots, and cells) plus
     /// the sync-state row. Used by the diagnostics reset button and by the
     /// account-switch purge (`CloudService.purgeLocalData`).
     func resetAllData() throws {
         for entity in try context.fetch(NSFetchRequest<GameEntity>(entityName: "GameEntity")) {
             context.delete(entity)
         }
         for entity in try context.fetch(NSFetchRequest<SyncStateEntity>(entityName: "SyncStateEntity")) {
             context.delete(entity)
         }
         // Friend zones themselves are removed by CloudService.resetAllData's
         // wholesale private-zone delete / shared-zone leave; clear the local
         // friendship + invite rows so a reset is a clean slate.
         for entity in try context.fetch(NSFetchRequest<FriendEntity>(entityName: "FriendEntity")) {
             context.delete(entity)
         }
         for entity in try context.fetch(NSFetchRequest<InviteEntity>(entityName: "InviteEntity")) {
             context.delete(entity)
         }
         // Replay journals are keyed to games; once every game is gone they are
         // orphaned and (on an account switch) hold the previous account's solve
         // history, so clear them too.
         for entity in try context.fetch(NSFetchRequest<JournalEntity>(entityName: "JournalEntity")) {
             context.delete(entity)
         }
         try context.save()
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
         onUnreadOtherMovesChanged?()
     }
 
     // MARK: - Legacy convenience
 
     /// Returns the single current game and its mutator, creating from
     /// `sample.xd` on first launch. Subsequent launches rehydrate the
     /// in-memory `Game` from the stored `CellEntity` rows so any prior
     /// progress is restored.
     func loadOrCreateCurrentGame() throws -> (Game, GameMutator) {
         let entity: GameEntity
         let puzzle: Puzzle
 
         if let existing = try fetchCurrentEntity() {
             entity = existing
             try upgradeOwnedGameSyncVersionIfNeeded(existing)
             puzzle = try preparePuzzleForLoad(from: existing)
         } else {
             (entity, puzzle) = try seedFromSample()
         }
 
         let game = Game(puzzle: puzzle)
         restore(game: game, from: entity)
 
         let mutator = makeMutator(game: game, entity: entity)
 
         currentGame = game
         currentMutator = mutator
         currentEntity = entity
         markOtherMovesRead(for: entity)
 
         return (game, mutator)
     }
 
     // MARK: - Loading
 
     private func fetchCurrentEntity() throws -> GameEntity? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.sortDescriptors = [NSSortDescriptor(key: "updatedAt", ascending: false)]
         request.fetchLimit = 1
         return try context.fetch(request).first
     }
 
     /// Applies this account's `Player.presenceUntil` from a sibling device under
     /// last-writer-wins: SyncEngine has already accepted this record as the
     /// freshest server version, so adopt the value directly as the account's
     /// resolved read horizon. A leaving sibling can pull the horizon back below
     /// an active sibling's future lease, but that collapse is bounded and
     /// self-healing: the still-present device re-asserts its lease as soon as it
     /// processes the inbound close (`AppServices`'s incoming-cursor drain), and a
     /// foreground device marks inbound peer moves read on arrival regardless.
     /// Representing "A left while C is still here" without that collapse would
     /// require per-device Player rows, which do not exist (one row per author).
     /// Returns the cursor value that was in place before the write and whether
     /// the inbound value was actually adopted, so callers can log the
     /// adoption — cross-device cursor convergence is otherwise invisible in
     /// the device log.
     @discardableResult
     func noteIncomingReadCursor(gameID: UUID, presenceUntil: Date) -> (previous: Date?, adopted: Bool) {
         let previous = fetchGameEntity(id: gameID)?.lastReadOtherMoveAt
         let adopted = setReadCursor(gameID: gameID, presenceUntil: presenceUntil)
         return (previous, adopted)
     }
 
     /// Sets the per-account **presence lease** for `gameID` — the forward-dated
     /// "the user is actively present on this puzzle" horizon stored in
     /// `lastReadOtherMoveAt`. When `minimumExistingPresenceUntil` is provided, the
     /// write is skipped if the current lease already reaches that floor; active
     /// sessions use this to refresh a future lease only when it is close to
     /// expiry.
     ///
     /// This is *not* the read watermark — see `advanceReadThrough`. The two were
     /// historically the same field, which is why `lastReadOtherMoveAt` ships on
     /// the wire as the `presenceUntil` CKRecord field (renamed from `readAt` in
     /// the v4 schema).
     /// TODO: the local `lastReadOtherMoveAt` Core Data attribute still carries
     /// the misleading old name — an internal-only rename to match `presenceUntil`
     /// was deferred (it collides with unrelated identifiers and the store is
     /// wiped on the v4 transition anyway, so it has no external effect).
     @discardableResult
     func setReadCursor(
         gameID: UUID,
         presenceUntil: Date,
         minimumExistingPresenceUntil: Date? = nil
     ) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first else { return false }
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared else { return false }
         if let minimumExistingPresenceUntil,
            let current = entity.lastReadOtherMoveAt,
            current >= minimumExistingPresenceUntil {
             return false
         }
         guard entity.lastReadOtherMoveAt != presenceUntil else { return false }
         entity.lastReadOtherMoveAt = presenceUntil
         saveContext("updatePresenceUntil")
         onUnreadOtherMovesChanged?()
         return true
     }
 
     /// Advances the per-account **read watermark** (`readThroughAt`) to
     /// `through`, monotonically — the latest other-author move time this
     /// account has actually observed. Unlike the presence lease it is never
     /// forward-dated, so a peer computing what we've seen (and our own unread
     /// badge) never credits us with moves made after we stopped looking.
     /// Returns `true` if the watermark moved.
     @discardableResult
     func advanceReadThrough(gameID: UUID, through: Date) -> Bool {
         let canonicalID = canonicalGameID(for: gameID)
         let entities = readStateEntities(canonicalGameID: canonicalID)
         guard entities.contains(where: {
             $0.ckShareRecordName != nil
                 || $0.databaseScope == 1
                 || isArchivedSharedGame($0)
         }) else { return false }
         var changed = false
         for entity in entities where (entity.readThroughAt ?? .distantPast) < through {
             entity.readThroughAt = through
             changed = true
         }
         guard changed else { return false }
         saveContext("advanceReadThrough")
         onUnreadOtherMovesChanged?()
         return true
     }
 
     private func markOtherMovesRead(for entity: GameEntity) {
         guard let storedID = entity.id else { return }
         let canonicalID = canonicalGameID(for: storedID)
         let entities = readStateEntities(canonicalGameID: canonicalID)
         let isShared = entities.contains {
             $0.ckShareRecordName != nil
                 || $0.databaseScope == 1
                 || isArchivedSharedGame($0)
         }
         guard isShared,
               let latest = entities.compactMap(\.latestOtherMoveAt).max()
         else { return }
         // Advances the *read watermark* (`readThroughAt`), not the presence
         // lease (`lastReadOtherMoveAt`). Opening the game means the user has now
         // seen every other-author move up to `latest`; the lease is a separate,
         // forward-dated "actively present" horizon owned by `setReadCursor`.
         var changed = false
         for candidate in entities where (candidate.readThroughAt ?? .distantPast) < latest {
             candidate.readThroughAt = latest
             changed = true
         }
         guard changed else { return }
         saveContext("markOtherMovesRead")
         onUnreadOtherMovesChanged?()
     }
 
     private func readStateEntities(canonicalGameID: UUID) -> [GameEntity] {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "id IN %@",
             [
                 canonicalGameID,
                 Archive.archiveGameID(for: canonicalGameID)
             ]
         )
         return (try? context.fetch(request)) ?? []
     }
 
     private func mirrorReadStateToChronicle(from live: GameEntity) {
         guard let liveID = live.id else { return }
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "id == %@",
             Archive.archiveGameID(for: liveID) as CVarArg
         )
         request.fetchLimit = 1
         guard let chronicle = try? context.fetch(request).first else { return }
         Archive.mirrorReadState(from: live, to: chronicle)
     }
 
     private func seedFromSample() throws -> (GameEntity, Puzzle) {
         guard let url = Bundle.main.resourceURL?
             .appendingPathComponent("Puzzles/debug/sample.xd") else {
             throw LoadError.sampleResourceMissing
         }
         let source = try String(contentsOf: url, encoding: .utf8)
         let xd = try XD.parse(source)
         let puzzle = Puzzle(xd: xd)
 
         let now = Date()
         let gameID = UUID()
         let entity = GameEntity(context: context)
         entity.id = gameID
         entity.title = puzzle.title
         entity.puzzleSource = source
         entity.puzzleParserVersion = Int64(XD.currentParserVersion)
         entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source)
         entity.createdAt = now
         entity.updatedAt = now
         entity.ckRecordName = "game-\(gameID.uuidString)"
         entity.ckZoneName = "game-\(gameID.uuidString)"
         entity.databaseScope = 0
         entity.syncVersion = GameSyncVersion.current
         entity.populateCachedSummaryFields(from: puzzle)
 
         try context.save()
         onGameCreated("game-\(gameID.uuidString)")
         return (entity, puzzle)
     }
 
     private func preparePuzzleForLoad(from entity: GameEntity) throws -> Puzzle {
         guard let source = entity.puzzleSource else {
             throw LoadError.persistedSourceMissing
         }
 
         let currentVersion = Int64(XD.currentParserVersion)
         if entity.puzzleParserVersion != currentVersion {
             let catalogSource = PuzzleCatalog.source(
                 matchingResourceID: entity.puzzleResourceID,
                 title: try? XD.parse(source).title
             )
             let nextSource = (catalogSource.flatMap { try? $0.loadSource() }) ?? source
             let nextXD = try XD.parse(nextSource)
             let puzzle = Puzzle(xd: nextXD)
             entity.title = puzzle.title
             entity.puzzleSource = nextSource
             entity.puzzleParserVersion = currentVersion
             if let catalogSource {
                 entity.puzzleResourceID = catalogSource.id
             } else if entity.puzzleResourceID == nil {
                 entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: nextSource)
             }
             entity.populateCachedSummaryFields(from: puzzle)
             try context.save()
             return puzzle
         }
 
         if entity.puzzleResourceID == nil {
             entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source)
             if context.hasChanges { try context.save() }
         }
 
         return Puzzle(xd: try XD.parse(source))
     }
 
     /// Minimal read snapshot of a game's persisted puzzle metadata, sized for
     /// out-of-store decision logic (e.g. whether to run a converter upgrade)
     /// without exposing the underlying `GameEntity`.
     struct PuzzleInfo: Sendable {
         let gameID: UUID
         let source: String
         let isOwned: Bool
     }
 
     func puzzleInfo(for id: UUID) -> PuzzleInfo? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first,
               let source = entity.puzzleSource
         else { return nil }
         return PuzzleInfo(
             gameID: id,
             source: source,
             // Completed puzzles are immutable history. In particular, updating
             // a Chronicle's disposable local projection would be undone by its
             // next materialisation.
             isOwned: entity.databaseScope == 0
                 && entity.completedAt == nil
                 && !isMaterializedArchive(entity)
         )
     }
 
     /// Persists `viewedAt` onto this account's own `Player.viewedAt` for
     /// `gameID` — the "last viewed" cutoff, shipped on the Player record so
     /// sibling devices adopt it rather than recomputing from their own view.
     /// Creates a stub PlayerEntity if none exists yet, keyed by the
     /// deterministic `ckRecordName`. No-op if the GameEntity is missing.
     func setViewedAt(_ viewedAt: Date?, gameID: UUID, authorID: String) {
         let entity: PlayerEntity
         if let existing = fetchPlayerEntity(gameID: gameID, authorID: authorID) {
             entity = existing
         } else {
             let gameRequest = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameRequest.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameRequest.fetchLimit = 1
             guard let game = try? context.fetch(gameRequest).first else { return }
             entity = PlayerEntity(context: context)
             entity.game = game
             entity.authorID = authorID
             entity.ckRecordName = RecordSerializer.recordName(
                 forPlayerInGame: gameID,
                 authorID: authorID
             )
             entity.updatedAt = Date()
         }
         entity.viewedAt = viewedAt
         saveContext("setViewedAt")
     }
 
     // MARK: - Solve-time clock
 
     /// Opens a solve session for the local device on `gameID` (idempotent across
     /// resumes within one sitting). `reconcileStale` — set on the first open of
     /// this game since launch — banks a session left dangling by a previous
     /// run's crash rather than counting the dead gap. Returns `true` if the
     /// stored log changed, so the caller can decide whether to enqueue a sync.
     @discardableResult
     func openClockSession(
         gameID: UUID,
         authorID: String,
         reconcileStale: Bool = false,
         at now: Date = Date()
     ) -> Bool {
         mutateTimeLog(gameID: gameID, authorID: authorID) {
             $0.open(deviceID: RecordSerializer.localDeviceID, at: now, reconcileStale: reconcileStale)
         }
     }
 
     /// Seals the local device's open solve session into a sealed interval.
     @discardableResult
     func sealClockSession(gameID: UUID, authorID: String, at now: Date = Date()) -> Bool {
         mutateTimeLog(gameID: gameID, authorID: authorID) {
             $0.seal(deviceID: RecordSerializer.localDeviceID, at: now)
         }
     }
 
     /// Refreshes the local device's liveness heartbeat so a peer keeps
     /// extrapolating an open session toward now.
     @discardableResult
     func beatClockSession(gameID: UUID, authorID: String, at now: Date = Date()) -> Bool {
         mutateTimeLog(gameID: gameID, authorID: authorID) {
             $0.beat(deviceID: RecordSerializer.localDeviceID, at: now)
         }
     }
 
     /// The completion instant for `gameID` (win or resign), or `nil` while it is
     /// unfinished. Used to seal the clock at the moment of the finish.
     func completedAt(forGame gameID: UUID) -> Date? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         return (try? context.fetch(request).first)?.completedAt
     }
 
     /// Whether `gameID` is finished (won or resigned). The clock stops opening
     /// new sessions once this is true.
     func isGameCompleted(gameID: UUID) -> Bool {
         completedAt(forGame: gameID) != nil
     }
 
     /// Whether `gameID` is currently shared. Shared open-time Player writes are
     /// already batched by `PuzzleDisplayView.activateSharing`; solo games still
     /// need standalone Player enqueues so their clock syncs across this
     /// account's devices.
     func isGameShared(gameID: UUID) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first else { return false }
         return entity.ckShareRecordName != nil || entity.databaseScope == 1
     }
 
     /// Whether `gameID` is the local read-only projection of a Chronicle.
     ///
     /// This is also what routes replay: a materialised Chronicle carries its
     /// history as cached Journal rows regardless of whether the original game
     /// was shared, so it must use the merged replay loader rather than the live
     /// game's local-journal shortcut.
     func isGameArchived(gameID: UUID) -> Bool {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first else { return false }
         return isGameArchived(entity)
     }
 
     /// Entity-taking form, for callers that already hold the row and would
     /// otherwise re-fetch it by ID.
     func isGameArchived(_ entity: GameEntity) -> Bool {
         isMaterializedArchive(entity)
     }
 
     /// Reads, mutates, and re-persists the local author's `Player.timeLog`,
     /// creating a stub `PlayerEntity` if none exists (works for solo games — no
     /// `isShared` gate). `updatedAt` is left untouched on an existing row: the
     /// `timeLog` field is adopted on apply regardless of LWW freshness (see
     /// `RecordApplier`), so it need not win the selection's `updatedAt` race.
     /// Returns `true` when the encoded log actually changed.
     @discardableResult
     private func mutateTimeLog(
         gameID: UUID,
         authorID: String,
         _ change: (inout TimeLog) -> Void
     ) -> Bool {
         let entity: PlayerEntity
         if let existing = fetchPlayerEntity(gameID: gameID, authorID: authorID) {
             entity = existing
         } else {
             let gameRequest = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameRequest.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameRequest.fetchLimit = 1
             guard let game = try? context.fetch(gameRequest).first else { return false }
             entity = PlayerEntity(context: context)
             entity.game = game
             entity.authorID = authorID
             entity.ckRecordName = RecordSerializer.recordName(
                 forPlayerInGame: gameID,
                 authorID: authorID
             )
             entity.updatedAt = Date()
         }
         var log = TimeLog.decode(entity.timeLog)
         change(&log)
         // Nothing to record — e.g. a heartbeat with no open session. Avoid
         // writing (and shipping) an empty `{"devices":{}}` blob.
         guard !log.devices.isEmpty else { return false }
         let encoded = TimeLog.encode(log)
         guard entity.timeLog != encoded else { return false }
         entity.timeLog = encoded
         saveContext("updateTimeLog")
         return true
     }
 
     /// Stamps the local author's Player record for `gameID` with the address
     /// derived from `secret` (see `RecordSerializer.deriveGameAddress`), so it
     /// ships on the Player-record write the puzzle-open burst is already making.
     /// Returns the derived address, or `nil` if the GameEntity is missing.
     /// Creating the row here is safe because the open burst fills its `name` and
     /// `presenceUntil` before the send — unlike the standalone registration sweep
     /// (`reconcileLocalPushAddresses`), which must never fabricate a bare row.
     @discardableResult
     func setPushAddress(gameID: UUID, authorID: String, secret: String) -> String? {
         let entity: PlayerEntity
         if let existing = fetchPlayerEntity(gameID: gameID, authorID: authorID) {
             entity = existing
         } else {
             let gameRequest = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameRequest.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameRequest.fetchLimit = 1
             guard let game = try? context.fetch(gameRequest).first else { return nil }
             entity = PlayerEntity(context: context)
             entity.game = game
             entity.authorID = authorID
             entity.ckRecordName = RecordSerializer.recordName(
                 forPlayerInGame: gameID,
                 authorID: authorID
             )
             entity.updatedAt = Date()
         }
         let address = RecordSerializer.deriveGameAddress(secret: secret, gameID: gameID)
         guard entity.pushAddress != address else { return address }
         entity.pushAddress = address
         // Bump updatedAt so the derived address wins LWW and the outbound build
         // picks it up as a fresh write.
         entity.updatedAt = Date()
         saveContext("setPushAddress")
         return address
     }
 
     /// Derives the local author's push address for every shared game the account
     /// participates in (`HMAC(secret, gameID)`) and pairs each with that game's
     /// shared push credential, minting the credential when absent (any
     /// participant may mint; record-level LWW converges concurrent mints). The
     /// caller registers the bindings with the push worker, which keys each
     /// game address under its `credID`. Also returns the games whose existing
     /// Player row was updated to a new derived address, so the caller can
     /// republish those rows for peers. The address write-back never fabricates a
     /// bare Player row (which would clobber `name`/`presenceUntil` server-side); a game
     /// with no local row still contributes its binding to the registration set.
     func reconcileLocalPushAddresses(
         authorID: String,
         secret: String,
         republishPlayerRows: Bool = true
     ) -> (bindings: [PushAddressBinding], republishGameIDs: [UUID]) {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "databaseScope == 1 OR ckShareRecordName != nil"
         )
         let games = (try? context.fetch(request)) ?? []
         var bindings: [PushAddressBinding] = []
         var republishGameIDs: [UUID] = []
         var gameRecordUpdates: [String] = []
         var notificationCredentialsChanged = false
         var didChange = false
         for game in games {
             guard let gameID = game.id else { continue }
             // Mint the shared push credential in place when absent, so it ships
             // on the next Game-record push and peers converge on it.
             var creds = GamePushCredentials.decode(game.notification)
             if creds == nil,
                let fresh = try? GamePushCredentials.fresh(),
                let encoded = try? fresh.encoded() {
                 game.notification = encoded
                 game.hasPendingSave = true
                 creds = fresh
                 notificationCredentialsChanged = true
                 didChange = true
                 if let ckName = game.ckRecordName { gameRecordUpdates.append(ckName) }
             }
             guard let credentials = creds else { continue }
             let address = RecordSerializer.deriveGameAddress(secret: secret, gameID: gameID)
             bindings.append(
                 PushAddressBinding(gameID: gameID, address: address, credentials: credentials)
             )
             // Update an existing row in place; never create one here.
             guard republishPlayerRows,
                   let player = fetchPlayerEntity(gameID: gameID, authorID: authorID),
                   player.pushAddress != address
             else { continue }
             player.pushAddress = address
             player.updatedAt = Date()
             republishGameIDs.append(gameID)
             didChange = true
         }
         if didChange {
             saveContext("reconcileLocalPushAddresses")
             if notificationCredentialsChanged {
                 GameEntity.rebuildContentKeyDirectory(in: context)
             }
         }
         // Enqueue Game-record pushes for freshly-minted credentials after the
         // save, mirroring `setNotification`.
         for ckName in gameRecordUpdates {
             onGameUpdated(ckName)
         }
         return (bindings, republishGameIDs)
     }
 
     /// Player record `updatedAt` for `(gameID, authorID)` — `nil` if no row
     /// exists yet. Used as the peer-device liveness probe during the pause
     /// grace window: a value newer than `pauseStart` means a sibling device
     /// of the same author wrote to Player after we started pausing, i.e.
     /// that device is still active and will publish its own pause later.
     func playerUpdatedAt(for gameID: UUID, by authorID: String) -> Date? {
         fetchPlayerEntity(gameID: gameID, authorID: authorID)?.updatedAt
     }
 
     /// Sender-local "notified through" watermark for `(gameID, authorID)` —
     /// the latest authored move we've told this recipient about via a pause,
     /// or `nil` if we never have. Paired with `Player.presenceUntil` to window the
     /// next session-end diff (see `SessionPushPlanner.sessionEndAddressees`).
     func notifiedThrough(for gameID: UUID, by authorID: String) -> Date? {
         fetchPlayerEntity(gameID: gameID, authorID: authorID)?.notifiedThrough
     }
 
     /// Advances the notified-through watermark for each peer in `authorIDs` to
     /// `through`, the latest move the pause we just sent them covered. Purely
     /// local bookkeeping: it stamps no `updatedAt` and enqueues no push, so it
     /// never rides a CloudKit Player record — `RecordSerializer.playerRecord`
     /// deliberately omits the field. Monotonic; a backward `through` (clock
     /// wobble) is ignored. Rows are expected to exist already, since we only
     /// notify recipients read out of `pushPlan`.
     func recordNotified(gameID: UUID, authorIDs: [String], through: Date) {
         guard !authorIDs.isEmpty else { return }
         var didChange = false
         for authorID in authorIDs {
             guard let player = fetchPlayerEntity(gameID: gameID, authorID: authorID) else {
                 continue
             }
             if let current = player.notifiedThrough, current >= through { continue }
             player.notifiedThrough = through
             didChange = true
         }
         if didChange {
             saveContext("recordNotified")
         }
     }
 
     /// Merged-across-devices author cells for `(gameID, authorID)`. Returns
     /// each touched grid position's winning `TimestampedCell` after the
     /// usual LWW merge across the author's devices, including cleared cells
     /// (empty `letter` with a non-default `updatedAt`). The pause-push
     /// per-recipient diff iterates this list, counting cells whose
     /// `updatedAt` is newer than that recipient's last-known `Player.presenceUntil`.
     func mergedAuthorCells(for gameID: UUID, by authorID: String) -> [TimestampedCell] {
         let request = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         request.predicate = NSPredicate(
             format: "game.id == %@ AND authorID == %@",
             gameID as CVarArg,
             authorID
         )
         let entities = (try? context.fetch(request)) ?? []
         let values: [MovesValue] = entities.compactMap { Self.movesValue(from: $0) }
         guard !values.isEmpty else { return [] }
         return GridStateMerger.mergeWithProvenance(values).values.map(\.cell)
     }
 
     /// Grid cells a *peer* filled or cleared since `since`, each mapped to the
     /// author who wrote the change — the data behind the "changed while you were
     /// away" borders. Merges every contributor's moves (not just one author's),
     /// so a peer's clear is attributed to them even though it leaves no
     /// preserved cell author. The local player's own edits are excluded. Returns
     /// empty when the local author is unknown (nothing to compare against).
     func recentlyChangedCells(forGame gameID: UUID, since: Date) -> [GridPosition: String] {
         recentChanges(forGame: gameID, since: since).cells
     }
 
     /// The full `RecentChanges.Changes` for `gameID` since `since`: the cell
     /// map behind the borders *and* the per-author counts behind the catch-up
     /// banner, from one pass over the per-cell letter-change ledger so the two
     /// surfaces always agree. Empty when the local author is unknown, or when
     /// the ledger holds nothing newer than `since` (including a game whose
     /// ledger has not been seeded yet — a first open shows no banner).
     func recentChanges(forGame gameID: UUID, since: Date) -> RecentChanges.Changes {
         guard let localAuthorID = authorIDProvider() else { return .empty }
         let request = NSFetchRequest<PeerChangeEntity>(entityName: "PeerChangeEntity")
         request.predicate = NSPredicate(
             format: "gameID == %@ AND changedAt > %@",
             gameID as CVarArg,
             since as NSDate
         )
         let rows = (try? context.fetch(request)) ?? []
         guard !rows.isEmpty else { return .empty }
         let entries = rows.map { Self.peerChange(from: $0) }
         return RecentChanges.changes(in: entries, since: since, excludingAuthor: localAuthorID)
     }
 
     /// Diagnostic snapshot for the catch-up banner and border-highlight reads.
     /// This is intentionally read-only: it reports the ledger as it stands at
     /// the instant the UI asks for recent changes, so a stale/asynchronous build
     /// can be distinguished from a bad reduction.
     func recentChangesDiagnosticSummary(forGame gameID: UUID, since: Date) -> String {
         let localAuthorID = authorIDProvider()
         let allReq = NSFetchRequest<PeerChangeEntity>(entityName: "PeerChangeEntity")
         allReq.predicate = NSPredicate(format: "gameID == %@", gameID as CVarArg)
         let allRows = (try? context.fetch(allReq)) ?? []
 
         let newerRows = allRows.filter { ($0.changedAt ?? .distantPast) > since }
         let entries = newerRows.map { Self.peerChange(from: $0) }
         let changes = localAuthorID.map {
             RecentChanges.changes(in: entries, since: since, excludingAuthor: $0)
         } ?? .empty
         let counted = changes.counts.values.reduce(0) { $0 + $1.added + $1.cleared }
         let byAuthor = changes.counts.keys.sorted().map { authorID in
             let count = changes.counts[authorID] ?? RecentChanges.Count(added: 0, cleared: 0)
             return "\(authorID.prefix(8))=+\(count.added)/-\(count.cleared)"
         }.joined(separator: ",")
         let newest = allRows.compactMap(\.changedAt).max()
 
         return "since=\(since.ISO8601Format()) "
             + "local=\(Self.shortAuthorID(localAuthorID)) "
             + "ledgerRows=\(allRows.count) newer=\(newerRows.count) "
             + "counted=\(counted) cells=\(changes.cells.count) "
             + "byAuthor=[\(byAuthor)] "
             + "newest=\(newest?.ISO8601Format() ?? "nil") "
             + Self.peerChangeEntitySampleSummary(newerRows)
     }
 
     /// Sender-side measurements describing *why* the pause-push counts for
     /// `(gameID, authorID)` came out as they did. Mirrors the set the count
     /// path (`mergedAuthorCells`) iterates, then breaks it down against the
     /// current grid: how many merged positions fall inside the bounds and on
     /// playable squares, the coordinate range, the contributing device count,
     /// and the edit window. Diagnostic-only; never affects badge or body. The
     /// time-of-day and per-recipient fields are filled by the caller — only
     /// the store-derived measurements are populated here.
     func movesDiagnostics(for gameID: UUID, by authorID: String) -> PushPayload.Diagnostics? {
         let gReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         gReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         gReq.fetchLimit = 1
         guard let game = try? context.fetch(gReq).first else { return nil }
 
         let mReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         mReq.predicate = NSPredicate(
             format: "game.id == %@ AND authorID == %@",
             gameID as CVarArg,
             authorID
         )
         let entities = (try? context.fetch(mReq)) ?? []
         let values: [MovesValue] = entities.compactMap { Self.movesValue(from: $0) }
         let merged = GridStateMerger.mergeWithProvenance(values)
 
         let width = Int(game.gridWidth)
         let height = Int(game.gridHeight)
         let puzzle = game.puzzleSource
             .flatMap { try? XD.parse($0) }
             .map(Puzzle.init(xd:))
 
         var inBounds = 0
         var playable = 0
         var minRow = Int.max, maxRow = Int.min, minCol = Int.max, maxCol = Int.min
         var earliest: Date?
         var latest: Date?
         for (position, provenance) in merged {
             minRow = min(minRow, position.row); maxRow = max(maxRow, position.row)
             minCol = min(minCol, position.col); maxCol = max(maxCol, position.col)
             let updatedAt = provenance.cell.updatedAt
             if earliest == nil || updatedAt < earliest! { earliest = updatedAt }
             if latest == nil || updatedAt > latest! { latest = updatedAt }
             let within = position.row >= 0 && position.row < height
                 && position.col >= 0 && position.col < width
             guard within else { continue }
             inBounds += 1
             if let puzzle, !puzzle.cells[position.row][position.col].isBlock {
                 playable += 1
             }
         }
         let deviceCount = Set(entities.compactMap { $0.deviceID }).count
 
         return PushPayload.Diagnostics(
             gridWidth: width,
             gridHeight: height,
             parserVersion: Int(game.puzzleParserVersion),
             mergedCells: merged.count,
             inBounds: inBounds,
             playable: playable,
             minRow: merged.isEmpty ? nil : minRow,
             maxRow: merged.isEmpty ? nil : maxRow,
             minCol: merged.isEmpty ? nil : minCol,
             maxCol: merged.isEmpty ? nil : maxCol,
             deviceCount: deviceCount,
             earliestEdit: earliest,
             latestEdit: latest
         )
     }
 
     /// Every `(author, device)` that has written a `MovesEntity` for `gameID` —
     /// i.e. every device whose grid letters are present locally. Peers' and this
     /// account's *other* devices' Moves sync in as their own per-device rows, so
     /// this is the authoritative local answer to "did anyone else contribute"
     /// (the roster can't tell, being keyed by author alone). Replay needs a
     /// journal from each; when the set is just this device the local journal
     /// already explains the whole grid and no CloudKit fetch is needed.
     func contributingDevices(for gameID: UUID) -> Set<JournalDeviceKey> {
         let request = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         request.predicate = NSPredicate(format: "game.id == %@", gameID as CVarArg)
         let entities = (try? context.fetch(request)) ?? []
         var devices: Set<JournalDeviceKey> = []
         for entity in entities {
             guard let authorID = entity.authorID, !authorID.isEmpty,
                   let deviceID = entity.deviceID, !deviceID.isEmpty else { continue }
             devices.insert(JournalDeviceKey(authorID: authorID, deviceID: deviceID))
         }
         return devices
     }
 
     /// Distinct authorIDs that have written a `MovesEntity` for `gameID`,
     /// with `excluding` filtered out. The session-summary banner uses this
     /// to enumerate peers whose activity it should diff.
     func peerAuthorIDs(for gameID: UUID, excluding localAuthorID: String?) -> [String] {
         let request = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         request.predicate = NSPredicate(format: "game.id == %@", gameID as CVarArg)
         let entities = (try? context.fetch(request)) ?? []
         var unique: Set<String> = []
         for entity in entities {
             guard let authorID = entity.authorID, !authorID.isEmpty else { continue }
             if let localAuthorID, authorID == localAuthorID { continue }
             unique.insert(authorID)
         }
         return Array(unique)
     }
 
     /// Formatted title used by notifications and the in-app session banner
     /// for `gameID`. Returns an empty string when the game can't be found.
     func puzzleTitleForNotification(for gameID: UUID) -> String {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         let entity = try? context.fetch(request).first
         return PuzzleNotificationText.title(for: entity)
     }
 
     /// Display name persisted on the PlayerEntity for `(gameID, authorID)`,
     /// or an empty string when no row exists. The session banner falls back
     /// to "A player" via `SessionMonitor.bodyText` when empty.
     func playerName(for gameID: UUID, by authorID: String) -> String {
         return fetchPlayerEntity(gameID: gameID, authorID: authorID)?.name ?? ""
     }
 
     /// The user's private nickname for `authorID` (`FriendEntity.nickname`),
     /// or `nil` when none is set. The same override `resolvedDisplayName`
     /// applies, exposed here for surfaces hydrated through `GameStore`
     /// rather than from a `FriendEntity` row — currently the catch-up
     /// banner's `SessionMonitor.summaries`.
     func friendNickname(for authorID: String) -> String? {
         guard !authorID.isEmpty else { return nil }
         let request = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         request.predicate = NSPredicate(format: "authorID == %@", authorID)
         request.fetchLimit = 1
         guard let nickname = (try? context.fetch(request).first)?.nickname?
             .trimmingCharacters(in: .whitespacesAndNewlines),
             !nickname.isEmpty
         else { return nil }
         return nickname
     }
 
     /// The read cursor persisted for `(gameID, authorID)`, or `nil` when no row
     /// exists or none has been stamped. Used by the local pause-diagnostics
     /// mirror to compare this device's actual cursor against the value a peer's
     /// pushed diagnostics claim it saw.
     func presenceUntil(for gameID: UUID, by authorID: String) -> Date? {
         return fetchPlayerEntity(gameID: gameID, authorID: authorID)?.presenceUntil
     }
 
     /// The local author's own derived push address for `gameID`, read off the
     /// local Player row, or nil if one hasn't been stamped yet. Used to keep a
     /// room broadcast from notifying the sender's own other devices.
     func localPushAddress(gameID: UUID, authorID: String) -> String? {
         fetchPlayerEntity(gameID: gameID, authorID: authorID)?.pushAddress
     }
 
     /// The authorIDs of every participant in `gameID` — the game's known
     /// roster, reused from the same summary the library renders. Used to
     /// address per-recipient authentication tags on outbound live engagement
     /// frames.
     func participantAuthorIDs(gameID: UUID) -> [String] {
         guard let entity = fetchGameEntity(id: gameID),
               let summary = GameSummary(entity: entity, localAuthorID: authorIDProvider())
         else { return [] }
         return summary.allParticipants.map(\.authorID).filter { !$0.isEmpty }
     }
 
     private func fetchPlayerEntity(gameID: UUID, authorID: String) -> PlayerEntity? {
         let request = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         request.predicate = NSPredicate(
             format: "game.id == %@ AND authorID == %@",
             gameID as CVarArg,
             authorID
         )
         request.fetchLimit = 1
         return try? context.fetch(request).first
     }
 
     /// Replaces a game's persisted XD source with a re-converted equivalent,
     /// stamps the current CmVer, raises `hasPushPending` so the next outbound
     /// Game record re-includes the `puzzleSource` asset, and enqueues the push
     /// via `onGameUpdated`. Callers (currently the NYT upgrade flow) are
     /// responsible for verifying that `newSource` is structurally compatible
     /// with the player's in-progress moves before invoking this.
     func replacePuzzleSource(id: UUID, with newSource: String) {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first,
               let parsed = try? XD.parse(newSource) else { return }
         let puzzle = Puzzle(xd: parsed)
         entity.puzzleSource = newSource
         entity.title = puzzle.title
         entity.puzzleParserVersion = Int64(XD.currentParserVersion)
         entity.hasPushPending = true
         entity.hasPendingSave = true
         entity.populateCachedSummaryFields(from: puzzle)
         saveContext("upgradePuzzleSource")
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
     }
 
     /// Records that a game's source has been evaluated at the current converter
     /// version by rewriting its `ConVer:` header in place, leaving the grid (and
     /// the player's moves) untouched. Used when an attempted NYT upgrade found a
     /// structural divergence and kept the old source: advancing the header stops
     /// `NYTPuzzleUpgrader.plan` from re-fetching the game on every open. The
     /// parser version is deliberately left alone so `preparePuzzleForLoad` still
     /// refreshes the cache if the parser has advanced. Local-only — only the
     /// owning device acts on the converter version, so there is nothing to push.
     func stampConverterVersion(for id: UUID) {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first,
               let source = entity.puzzleSource else { return }
         entity.puzzleSource = XD.settingConverterVersionHeader(
             in: source, to: XD.currentConverterVersion
         )
         saveContext("stampConverterVersion")
     }
 
     private func restore(game: Game, from entity: GameEntity, updateCache: Bool = true) {
         let movesRequest = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         movesRequest.predicate = NSPredicate(format: "game == %@", entity)
         let movesEntities = (try? context.fetch(movesRequest)) ?? []
         let values: [MovesValue] = movesEntities.compactMap { Self.movesValue(from: $0) }
         // A materialised Chronicle deliberately has no live Moves rows. Its
         // final cells are the authoritative frozen grid, including the author
         // attribution needed for participant colours.
         let archiveGrid = materializedArchiveGrid(entity)
         let grid = archiveGrid ?? GridStateMerger.merge(values)
 
         // A completed game (won or resigned) is terminal; its grid is, by
         // definition, the solution. The merge is watermarked at `completedAt`:
         // a collaborator's letter typed just before the win still merges in
         // when it reaches us afterward (carrying its author), but anything
         // stamped after the latch is ignored — nothing re-opens or rewrites a
         // finished puzzle. Whatever's still empty at the cutoff is sealed to
         // the solution so a completed game always renders solved, independent
         // of merge drift (a late clear, an edit that reached a peer over
         // engagement but never synced — see the realtime/durable decoupling).
         // Input is separately locked (`GameMutator.isCompleted`); the
         // CellEntity cache still mirrors the raw (un-watermarked) merge.
         if let completedAt = entity.completedAt {
             let sealedGrid = archiveGrid
                 ?? GridStateMerger.merge(values, notAfter: completedAt)
             sealToSolution(game: game, mergedGrid: sealedGrid)
             if updateCache {
                 updateCellCache(for: entity, from: grid)
             }
             return
         }
 
         // The local device's own row. Used to decide whether a buffered edit
         // (flagged by `Square.enqueuedAt`) has landed durably yet: once the
         // flush writes it, this row carries the cell with `updatedAt` equal
         // to the flag's timestamp (`MovesUpdater` persists `enqueuedAt` as the
         // cell's `updatedAt`).
         let localDeviceID = RecordSerializer.localDeviceID
         let localAuthorID = authorIDProvider()
         let localCells: [GridPosition: TimestampedCell] = values.first {
             $0.deviceID == localDeviceID
                 && (localAuthorID == nil || $0.authorID == localAuthorID)
         }?.cells ?? [:]
 
         // Apply the merge as a diff: an inbound catch-up usually carries one
         // peer keystroke, yet the merged grid spans the whole board. Writing
         // every square unconditionally fires the `@Observable squares`
         // hundreds of times per catch-up — invalidating the grid view and
         // re-running the completion scan — even when the merged result is
         // identical to what's already on screen. Touch only the cells whose
         // value actually changed, and rebuild the completion cache only if at
         // least one did, so a redundant catch-up becomes a true no-op on the
         // main actor (the co-solve hot path).
         var changed = false
         for (position, cell) in grid {
             let r = position.row
             let c = position.col
             guard r >= 0, r < game.puzzle.height, c >= 0, c < game.puzzle.width else { continue }
             let current = game.squares[r][c]
             // A non-nil `enqueuedAt` means the user typed here and the edit
             // may still be buffered in `MovesUpdater`. Retire the flag only
             // once the local row shows this cell at a timestamp >= the flag
             // (the edit, or a newer one, has landed); until then leave the
             // value fields alone so the just-typed letter stays on screen.
             var clearEnqueued = false
             if let stamp = current.enqueuedAt {
                 guard let landed = localCells[position],
                       landed.updatedAt >= stamp
                 else { continue }
                 clearEnqueued = true
             }
             guard clearEnqueued
                 || current.entry != cell.letter
                 || current.mark != cell.mark
                 || current.letterAuthorID != cell.authorID
             else { continue }
             // Build the new square locally and assign once, so the cell fires
             // a single `squares` mutation rather than one per field.
             var updated = current
             updated.enqueuedAt = clearEnqueued ? nil : current.enqueuedAt
             updated.entry = cell.letter
             updated.mark = cell.mark
             updated.letterAuthorID = cell.authorID
             game.squares[r][c] = updated
             changed = true
         }
         if changed {
             game.recomputeCompletionCache()
         }
 
         if updateCache {
             updateCellCache(for: entity, from: grid)
         }
     }
 
     /// Populates `game.squares` from the puzzle solution for a completed
     /// (terminal) game. A cell the merge already resolved to an accepted answer
     /// keeps that entry, its author, and its mark; a hole or a stray
     /// post-completion letter is overwritten with the canonical solution and a
     /// clean mark. Cells with no known solution fall back to the merged value.
     /// The result is always `.solved`, so the finish presentation is shown.
     private func sealToSolution(game: Game, mergedGrid: GridState) {
         for r in 0..<game.puzzle.height {
             for c in 0..<game.puzzle.width {
                 let cell = game.puzzle.cells[r][c]
                 guard !cell.isBlock else { continue }
                 game.squares[r][c].enqueuedAt = nil
                 let merged = mergedGrid[GridPosition(row: r, col: c)]
                 if let merged, cell.accepts(merged.letter) {
                     // Correctly filled — preserve who filled it and its mark
                     // (a stale wrong-mark on a correct letter is contradictory,
                     // so force it off).
                     game.squares[r][c].entry = merged.letter
                     game.squares[r][c].mark = merged.mark.withoutWrongCheck
                     game.squares[r][c].letterAuthorID = merged.authorID
                 } else if let solution = cell.solution {
                     // Hole or stray post-completion letter — seal to solution.
                     game.squares[r][c].entry = solution
                     game.squares[r][c].mark = .none
                     game.squares[r][c].letterAuthorID = merged?.authorID
                 } else if let merged {
                     // No known solution — show whatever the merge resolved.
                     game.squares[r][c].entry = merged.letter
                     game.squares[r][c].mark = merged.mark
                     game.squares[r][c].letterAuthorID = merged.authorID
                 }
             }
         }
         game.recomputeCompletionCache()
     }
 
     private func updateCellCache(for gameEntity: GameEntity, from grid: GridState) {
         Self.applyCellCache(to: gameEntity, from: grid, in: context)
         saveContext("updateCellCache")
     }
 
     /// Hydrates a `MovesValue` from a `MovesEntity`. Returns `nil` if the row
     /// is missing required fields.
     fileprivate nonisolated static func movesValue(from entity: MovesEntity) -> MovesValue? {
         guard let gameID = entity.game?.id,
               let authorID = entity.authorID,
               let deviceID = entity.deviceID,
               let updatedAt = entity.updatedAt
         else { return nil }
         let cells = (entity.cells.flatMap { try? MovesCodec.decode($0) }) ?? [:]
         return MovesValue(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             cells: cells,
             updatedAt: updatedAt
         )
     }
 
     fileprivate nonisolated static func peerChange(from entity: PeerChangeEntity) -> PeerChange {
         PeerChange(
             position: GridPosition(row: Int(entity.row), col: Int(entity.col)),
             letter: entity.letter ?? "",
             authorID: entity.authorID,
             changedAt: entity.changedAt ?? .distantPast
         )
     }
 
     private nonisolated static func peerChangeSampleSummary(_ changes: [PeerChange]) -> String {
         guard !changes.isEmpty else { return "sample=[]" }
         let sample = changes
             .sorted { lhs, rhs in
                 if lhs.changedAt != rhs.changedAt { return lhs.changedAt < rhs.changedAt }
                 if lhs.position.row != rhs.position.row { return lhs.position.row < rhs.position.row }
                 return lhs.position.col < rhs.position.col
             }
             .prefix(5)
             .map {
                 "r\($0.position.row)c\($0.position.col):"
                 + "\($0.letter.isEmpty ? "-" : $0.letter)"
                 + "@\($0.changedAt.ISO8601Format())"
                 + "#\(Self.shortAuthorID($0.authorID))"
             }
             .joined(separator: ",")
         return "sample=[\(sample)]"
     }
 
     private nonisolated static func peerChangeEntitySampleSummary(_ rows: [PeerChangeEntity]) -> String {
         peerChangeSampleSummary(rows.map { peerChange(from: $0) })
     }
 
     private nonisolated static func shortAuthorID(_ authorID: String?) -> String {
         guard let authorID else { return "nil" }
         return String(authorID.prefix(8))
     }
 
     private func inferredObservedCompletionAuthorID(for id: UUID) -> String? {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? context.fetch(request).first,
               let source = entity.puzzleSource,
               let xd = try? XD.parse(source)
         else { return nil }
 
         let puzzle = Puzzle(xd: xd)
         let movesRequest = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         movesRequest.predicate = NSPredicate(format: "game == %@", entity)
         let movesEntities = (try? context.fetch(movesRequest)) ?? []
         let values: [MovesValue] = movesEntities.compactMap { Self.movesValue(from: $0) }
         let provenance = GridStateMerger.mergeWithProvenance(values)
 
         var latest: (date: Date, authorID: String)?
         for row in puzzle.cells {
             for cell in row {
                 guard !cell.isBlock, cell.solution != nil else { continue }
                 let position = GridPosition(row: cell.row, col: cell.col)
                 guard let winner = provenance[position],
                       !winner.cell.letter.isEmpty,
                       cell.accepts(winner.cell.letter)
                 else { return nil }
 
                 if latest.map({ winner.cell.updatedAt > $0.date }) ?? true {
                     latest = (winner.cell.updatedAt, winner.writerAuthorID)
                 }
             }
         }
         return latest?.authorID
     }
 
     /// Reconciles a `GameEntity`'s `CellEntity` cache against `grid` inside
     /// `ctx`. Caller is responsible for saving `ctx`. Used from both the
     /// main-context `updateCellCache` and the background-context
     /// `replayCellCaches`.
     fileprivate nonisolated static func applyCellCache(
         to gameEntity: GameEntity,
         from grid: GridState,
         in ctx: NSManagedObjectContext
     ) {
         let cellEntities = (gameEntity.cells as? Set<CellEntity>) ?? []
         var existing: [GridPosition: CellEntity] = [:]
         for ce in cellEntities {
             existing[GridPosition(row: Int(ce.row), col: Int(ce.col))] = ce
         }
 
         for (position, cell) in grid {
             // The merged grid can include peer-controlled positions; the codec
             // guarantees Int16 representability, and this keeps out-of-grid
             // leftovers from materializing as CellEntity rows.
             guard position.isPersistable(
                 gridWidth: gameEntity.gridWidth,
                 gridHeight: gameEntity.gridHeight
             ) else { continue }
             let ce: CellEntity
             if let found = existing[position] {
                 ce = found
             } else {
                 ce = CellEntity(context: ctx)
                 ce.row = Int16(position.row)
                 ce.col = Int16(position.col)
                 ce.game = gameEntity
             }
             ce.letter = cell.letter
             ce.markCode = cell.mark.code
             ce.letterAuthorID = cell.authorID
         }
 
         for (position, ce) in existing where grid[position] == nil {
             ce.letter = ""
             ce.markCode = 0
             ce.letterAuthorID = nil
         }
     }
 
     /// Marks the active game read-only when the sync engine sees its shared
     /// zone disappear from the shared database (owner revoked access).
     func markAccessRevoked(gameID: UUID) {
         guard currentEntity?.id == gameID else { return }
         currentMutator?.isAccessRevoked = true
     }
 
     /// Called after the sync engine deletes a `GameEntity` in response to a
     /// remote private-DB zone deletion (the user removed this game on another
     /// device). The deletion itself has already been merged into the view
     /// context; this method's job is to drop the active references if the
     /// open puzzle is the one that just disappeared, so the UI doesn't
     /// dereference a deleted managed object. Returns whether the removed game
     /// was the one currently open, so the caller can surface an in-puzzle
     /// notice only when there is a puzzle on screen to host it.
     @discardableResult
     func handleRemoteRemoval(gameID: UUID) -> Bool {
         let wasOpen = currentEntity?.id == gameID
         if wasOpen {
             currentGame = nil
             currentMutator = nil
             currentEntity = nil
         }
         onUnreadOtherMovesChanged?()
         return wasOpen
     }
 
     /// Flips the active game's mutator to shared after `ShareController`
     /// saves a `CKShare`, so an open `PuzzleView` reacts (builds the roster,
     /// starts publishing the local selection) without requiring the user to re-open.
     func markShared(gameID: UUID) {
         guard currentEntity?.id == gameID else { return }
         currentMutator?.isShared = true
     }
 
     private func makeMutator(game: Game, entity: GameEntity) -> GameMutator {
         guard let gameID = entity.id else {
             fatalError("GameEntity missing id — data model invariant violated")
         }
         return GameMutator(
             game: game,
             gameID: gameID,
             movesUpdater: movesUpdater,
             movesJournal: movesJournal,
             authorIDProvider: authorIDProvider,
             onLocalCellEdit: { [weak self] edit in
                 self?.onLocalCellEdit?(edit)
             },
             onLocalCellEditBatch: { [weak self] edits in
                 self?.onLocalCellEditBatch?(edits)
             },
             isOwned: entity.databaseScope == 0,
             isShared: entity.ckShareRecordName != nil || entity.databaseScope == 1,
             showsPlayerAttribution: entity.ckShareRecordName != nil
                 || entity.databaseScope == 1
                 || isArchivedSharedGame(entity),
             isArchived: isMaterializedArchive(entity),
             isAccessRevoked: entity.isAccessRevoked,
             isSyncSupported: GameSyncVersion.supports(entity.syncVersion),
             syncVersion: entity.syncVersion,
             initialLogicalTick: maximumLogicalTick(for: entity),
             isCompleted: entity.completedAt != nil
         )
     }
 
     /// Advances an owned legacy game when its owner opens it. Participants
     /// adopt the owner's Game record and never select a protocol themselves.
     /// Marking the row pending protects the chosen version from a stale fetch
     /// until SyncEngine confirms the owner-authoritative save.
     private func upgradeOwnedGameSyncVersionIfNeeded(_ entity: GameEntity) throws {
         let version = GameSyncVersion.normalized(entity.syncVersion)
         guard entity.databaseScope == DatabaseScope.private.rawValue,
               version < GameSyncVersion.current,
               GameSyncVersion.supports(version)
         else { return }
 
         entity.syncVersion = GameSyncVersion.current
         entity.hasPendingSave = true
         try context.save()
         if let recordName = entity.ckRecordName {
             onGameUpdated(recordName)
         }
     }
 
     /// Highest modern tick or timestamp-derived legacy value currently known
     /// for the game. This is the Lamport floor used by the next local edit.
     private func maximumLogicalTick(for entity: GameEntity) -> Int64 {
         let moves = (entity.moves as? Set<MovesEntity>) ?? []
         var maximum: Int64 = 0
         for row in moves {
             guard let data = row.cells,
                   let cells = try? MovesCodec.decode(data)
             else { continue }
             for cell in cells.values {
                 maximum = max(maximum, cell.logicalValue)
             }
         }
         return maximum
     }
 
     private func fetchGameEntity(id gameID: UUID) -> GameEntity? {
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         req.fetchLimit = 1
         return try? context.fetch(req).first
     }
 
     private func ensureMovesEntity(
         recordName: String,
         game: GameEntity,
         authorID: String,
         deviceID: String
     ) -> MovesEntity {
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         req.fetchLimit = 1
         if let existing = try? context.fetch(req).first {
             return existing
         }
 
         let entity = MovesEntity(context: context)
         entity.game = game
         entity.ckRecordName = recordName
         entity.authorID = authorID
         entity.deviceID = deviceID
         entity.cells = Data()
         entity.updatedAt = Date()
         return entity
     }
 
 }