crossmate

GameStore.swift (118760B)

---

 import CloudKit
 import CoreData
 import Foundation
 import Observation
 import Security
 
 /// 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 {
     let id: 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.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
         self.isAccessRevoked = entity.isAccessRevoked
         self.allParticipants = Self.computeParticipants(
             gameID: id,
             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. Rows created before the watermark existed only have the
             // older cursor, so use a non-future legacy value as a migration
             // fallback until the first real readThroughAt write lands.
             readThrough: entity.readThroughAt,
             legacyReadAt: entity.lastReadOtherMoveAt
         )
     }
 
     /// 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?,
         legacyReadAt: Date?
     ) -> Bool {
         guard isShared, let latest else { return false }
         if let readThrough {
             return latest > readThrough
         }
         guard let legacyReadAt, legacyReadAt <= Date() else { return true }
         return latest > legacyReadAt
     }
 
     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 else {
             return []
         }
 
         var namesByAuthor: [String: String] = [:]
         let playerEntities = (entity.players as? Set<PlayerEntity>) ?? []
         for player in playerEntities {
             guard let authorID = player.authorID, !authorID.isEmpty else { continue }
             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
         )
     }
 
     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: Int16
     let ckZoneName: String
     let ckZoneOwnerName: String
     /// The private-DB archive backup zone (archive-<id>) to tear down alongside
     /// the game, set only for a finished participant game whose backup lives in
     /// a zone separate from its live (shared) one. nil otherwise — an unarchived
     /// game, or a materialized archive whose own zone already is the archive and
     /// is covered by ckZoneName.
     let archiveZoneName: 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] {
         let players = (entity.players as? Set<PlayerEntity>) ?? []
         return players.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 {
     /// 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)
     }
 }
 
 /// 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 {
     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) -> 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 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
     }
 
     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
     }
 
     // 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 }
         // 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)
     }
 
     /// 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
 
     /// 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 first build for a game (no rows yet) seeds every current
     /// cell at `.distantPast`, a silent baseline that surfaces nothing.
     ///
     /// 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
         var diagnostics: [String] = []
         await ctx.perform {
             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)
 
                 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: recorded.isEmpty
                 )
                 diagnostics.append(
                     "\(gameID.uuidString.prefix(8)) existing=\(existingRows.count) "
                     + "moves=\(values.count) current=\(current.count) "
                     + "seeding=\(recorded.isEmpty) upserts=\(upserts.count) "
                     + Self.peerChangeSampleSummary(upserts)
                 )
                 for change in upserts {
                     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 }
             do {
                 try ctx.save()
             } catch {
                 let message = "GameStore: peer change ledger save failed — \(error)"
                 Task { @MainActor [weak self] in
                     self?.eventLog?.note(message, level: "error")
                 }
             }
         }
         let elapsed = Date().timeIntervalSince(startedAt)
         eventLog?.note(
             "peer ledger build #\(serial) end: elapsed=\(String(format: "%.3f", elapsed))s "
             + 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
             }
         }
 
         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 {
         let groups = Dictionary(grouping: edits) { edit in
             RecordSerializer.recordName(
                 forMovesInGame: edit.gameID,
                 authorID: edit.authorID,
                 deviceID: edit.deviceID
             )
         }
 
         var applied = 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 }
 
             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 groupEdits {
                 let position = GridPosition(row: edit.row, col: edit.col)
                 let incoming = TimestampedCell(
                     letter: edit.letter,
                     mark: edit.mark,
                     updatedAt: edit.updatedAt,
                     authorID: edit.cellAuthorID
                 )
                 if let current = cells[position], current.updatedAt > incoming.updatedAt {
                     continue
                 }
                 cells[position] = incoming
                 changed = true
                 applied += 1
                 if edit.updatedAt > latest { latest = edit.updatedAt }
             }
 
             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)
         }
 
         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 {
         let request = NSFetchRequest<NSNumber>(entityName: "GameEntity")
         request.resultType = .countResultType
         request.predicate = unreadOtherMovesPredicate
         return (try? context.count(for: request)) ?? 0
     }
 
     /// 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> {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = unreadOtherMovesPredicate
         request.propertiesToFetch = ["id"]
         let rows = (try? context.fetch(request)) ?? []
         return Set(rows.compactMap(\.id))
     }
 
     func hasUnreadOtherMoves(gameID: UUID) -> Bool {
         let request = NSFetchRequest<NSNumber>(entityName: "GameEntity")
         request.resultType = .countResultType
         request.fetchLimit = 1
         request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: [
             NSPredicate(format: "id == %@", gameID as CVarArg),
             unreadOtherMovesPredicate
         ])
         return ((try? context.count(for: request)) ?? 0) > 0
     }
 
     /// 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 {
                 result[id] = 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
         })
     }
 
     /// One-shot upgrade heal for the read-watermark split. Older installs only
     /// had `lastReadOtherMoveAt`, which has since become a presence lease; rows
     /// with missing or stale `readThroughAt` can therefore look unread after
     /// upgrading. Backfill them to their current latest peer move unless a
     /// delivered unread notification still represents that game.
     @discardableResult
     func backfillLegacyReadThrough(excluding excludedGameIDs: Set<UUID>) -> Int {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "(databaseScope == 1 OR ckShareRecordName != nil) "
                 + "AND latestOtherMoveAt != nil "
                 + "AND (readThroughAt == nil OR latestOtherMoveAt > readThroughAt)"
         )
         request.propertiesToFetch = ["id", "latestOtherMoveAt", "readThroughAt"]
         let rows = (try? context.fetch(request)) ?? []
         var changed = 0
         for entity in rows {
             guard let id = entity.id,
                   !excludedGameIDs.contains(id),
                   let latest = entity.latestOtherMoveAt
             else { continue }
             entity.readThroughAt = latest
             changed += 1
         }
         guard changed > 0 else { return 0 }
         saveContext("backfillLegacyReadThrough")
         onUnreadOtherMovesChanged?()
         return changed
     }
 
     private var unreadOtherMovesPredicate: NSPredicate {
         // Keyed off the read *watermark* (`readThroughAt`), not the forward-
         // dated presence lease (`lastReadOtherMoveAt`) — matches
         // `GameSummary.computeHasUnread`. For pre-watermark rows, fall back to
         // a non-future legacy cursor so an upgrade doesn't badge every
         // already-seen shared puzzle whose readThroughAt starts nil. Future
         // legacy values are active-session leases, not durable read watermarks.
         NSPredicate(
             format: "(databaseScope == 1 OR ckShareRecordName != nil) "
                 + "AND latestOtherMoveAt != nil "
                 + "AND ("
                 + "  (readThroughAt != nil AND latestOtherMoveAt > readThroughAt) "
                 + "  OR (readThroughAt == nil AND "
                 + "      (lastReadOtherMoveAt == nil "
                 + "       OR lastReadOtherMoveAt > %@ "
                 + "       OR latestOtherMoveAt > lastReadOtherMoveAt))"
                 + ")",
             Date() as NSDate
         )
     }
 
     // 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
         }
         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)
     }
 
     // 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.
     func nytPuzzleDatesInLibrary() -> Set<Date> {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(
             format: "cachedPublisher == %@ AND cachedPuzzleDate != nil",
             "New York Times"
         )
         let dates = ((try? context.fetch(request)) ?? []).compactMap(\.cachedPuzzleDate)
 
         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.puzzleCmVersion = Int64(XD.currentCmVersion)
         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.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) throws {
         let recordName = "game-\(gameID.uuidString)"
         let existing = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         existing.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         existing.fetchLimit = 1
         if ((try? context.count(for: existing)) ?? 0) > 0 { 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.puzzleCmVersion = Int64(XD.currentCmVersion)
         entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source)
         entity.createdAt = now
         entity.updatedAt = now
         entity.ckRecordName = recordName
         entity.ckZoneName = zoneID.zoneName
         entity.ckZoneOwnerName =
             zoneID.ownerName == CKCurrentUserDefaultName ? nil : zoneID.ownerName
         entity.databaseScope = 1
         entity.populateCachedSummaryFields(from: puzzle)
 
         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 }
 
         // A finished participant game (scope 1, archived, still a participant)
         // carries a separate private-DB archive backup under archive-<id>;
         // deleting the game outright should drop that backup too. A materialized
         // or revoked archive is excluded — its own zone already is the archive,
         // covered by ckZoneName above, so it needs no second teardown.
         let hasSeparateArchive = entity.databaseScope == 1
             && entity.archivedAt != nil
             && !entity.isAccessRevoked
         let deletion = GameCloudDeletion(
             gameID: id,
             databaseScope: entity.databaseScope,
             ckZoneName: entity.ckZoneName ?? "game-\(id.uuidString)",
             ckZoneOwnerName: entity.ckZoneOwnerName ?? CKCurrentUserDefaultName,
             archiveZoneName: hasSeparateArchive
                 ? Archive.zoneID(forOriginalGameID: id).zoneName
                 : nil
         )
 
         // Clear current references if this is the active game
         if currentEntity?.id == id {
             currentGame = nil
             currentMutator = nil
             currentEntity = nil
         }
 
         context.delete(entity)
         try context.save()
         onGameDeleted(deletion)
         onUnreadOtherMovesChanged?()
     }
 
     // MARK: - Resign a game
 
     /// Reveals all cells and marks the game as completed (resigned).
     func resignGame(id: UUID) throws {
         let (game, mutator) = try loadGame(id: id)
         let allCells = game.puzzle.cells.flatMap { $0 }
         mutator.revealCells(allCells)
 
         guard let entity = currentEntity else { return }
         entity.completedAt = Date()
         // 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)
 
         // Clean up current references
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
     }
 
     /// 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())
     }
 
     /// 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)
     }
 
     @discardableResult
     private func persistCompletion(id: UUID, completedBy authorID: String?) 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 else { return false }
         entity.completedAt = Date()
         // 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)
         return true
     }
 
     /// 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) {
         guard let authorID = authorIDProvider(), !authorID.isEmpty else { return }
         onJournalComplete?(id, authorID)
     }
 
     /// 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)
     }
 
     /// 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()
         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) }
 
             for journal in journals {
                 for value in journal.entries {
                     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
                 }
             }
             game.replayCacheComplete = true
             do {
                 try ctx.save()
             } catch {
                 let message = "GameStore: replay cache save failed — \(error)"
                 Task { @MainActor [weak self] in
                     self?.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
     }
 
     // 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
             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.readAt` 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, readAt: Date) -> (previous: Date?, adopted: Bool) {
         let previous = fetchGameEntity(id: gameID)?.lastReadOtherMoveAt
         let adopted = setReadCursor(gameID: gameID, readAt: readAt)
         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 `minimumExistingReadAt` 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 `Player.readAt`.
     /// TODO(v4): rename the `readAt` CloudKit field (and `lastReadOtherMoveAt`)
     /// to something like `presenceLeaseUntil` — it is a presence horizon, not a
     /// read position, now that `readThrough` carries the latter.
     @discardableResult
     func setReadCursor(
         gameID: UUID,
         readAt: Date,
         minimumExistingReadAt: 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 minimumExistingReadAt,
            let current = entity.lastReadOtherMoveAt,
            current >= minimumExistingReadAt {
             return false
         }
         guard entity.lastReadOtherMoveAt != readAt else { return false }
         entity.lastReadOtherMoveAt = readAt
         saveContext("updateReadAt")
         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 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 }
         guard (entity.readThroughAt ?? .distantPast) < through else { return false }
         entity.readThroughAt = through
         saveContext("advanceReadThrough")
         onUnreadOtherMovesChanged?()
         return true
     }
 
     private func markOtherMovesRead(for entity: GameEntity) {
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared, let latest = entity.latestOtherMoveAt 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`.
         if (entity.readThroughAt ?? .distantPast) < latest {
             entity.readThroughAt = latest
             saveContext("markOtherMovesRead")
             onUnreadOtherMovesChanged?()
         }
     }
 
     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.puzzleCmVersion = Int64(XD.currentCmVersion)
         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.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.currentCmVersion)
         if entity.puzzleCmVersion != 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.puzzleCmVersion = 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,
             isOwned: entity.databaseScope == 0
         )
     }
 
     /// Persists `data` (an encoded `SeenBaseline`) onto this account's own
     /// `Player.sessionSnapshot` 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 setSessionSnapshot(_ data: Data?, 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.sessionSnapshot = data
         saveContext("setSessionSnapshot")
     }
 
     // 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
     }
 
     /// 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
     /// `readAt` 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`/`readAt` server-side); a game
     /// with no local row still contributes its binding to the registration set.
     func reconcileLocalPushAddresses(
         authorID: String,
         secret: String
     ) -> (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 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
                 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 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")
         }
         // 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.readAt` 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.readAt`.
     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,
             cmVersion: Int(game.puzzleCmVersion),
             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 readAt(for gameID: UUID, by authorID: String) -> Date? {
         return fetchPlayerEntity(gameID: gameID, authorID: authorID)?.readAt
     }
 
     /// 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
     }
 
     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.puzzleCmVersion = Int64(XD.currentCmVersion)
         entity.hasPushPending = true
         entity.hasPendingSave = true
         entity.populateCachedSummaryFields(from: puzzle)
         saveContext("upgradePuzzleSource")
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
     }
 
     /// Stamps the current CmVer onto a game without other changes. Used when
     /// an attempted upgrade decided not to replace the source (e.g. structural
     /// mismatch) but the caller still wants to retire the stale version so the
     /// upgrade isn't reattempted every launch.
     func bumpPuzzleCmVersion(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 else { return }
         entity.puzzleCmVersion = Int64(XD.currentCmVersion)
         saveContext("bumpPuzzleCmVersion")
     }
 
     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) }
         let grid = 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 = 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 {
             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,
             isAccessRevoked: entity.isAccessRevoked,
             isCompleted: entity.completedAt != nil
         )
     }
 
     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
     }
 
 }