crossmate

GameStore.swift (29392B)

---

 import CloudKit
 import CoreData
 import Foundation
 import Observation
 
 /// 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 hasUnseenOtherMoves: Bool
 
     init?(entity: GameEntity) {
         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
         }
 
         let cellEntities = (entity.cells as? Set<CellEntity>) ?? []
         var filledSet: Set<Int> = []
         for ce in cellEntities where !(ce.letter ?? "").isEmpty {
             filledSet.insert(Int(ce.row) * width + Int(ce.col))
         }
 
         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 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.hasUnseenOtherMoves = Self.computeHasUnseen(
             isShared: self.isShared,
             latest: entity.latestOtherMoveAt,
             lastSeen: entity.lastSeenOtherMoveAt
         )
     }
 
     fileprivate static func computeHasUnseen(
         isShared: Bool,
         latest: Date?,
         lastSeen: Date?
     ) -> Bool {
         guard isShared, let latest else { return false }
         guard let lastSeen else { return true }
         return latest > lastSeen
     }
 }
 
 /// 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
 }
 
 /// 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 "thumbnail might have
 /// changed".
 @MainActor
 final class GameSummaryCache {
     private struct Key: Equatable {
         let updatedAt: Date?
         let completedAt: Date?
         let latestOther: Date?
         let lastSeenOther: Date?
         let scope: Int16
         let shareName: String?
         let revoked: Bool
     }
     private var entries: [NSManagedObjectID: (key: Key, summary: GameSummary)] = [:]
 
     func summary(for entity: GameEntity) -> GameSummary? {
         let key = Key(
             updatedAt: entity.updatedAt,
             completedAt: entity.completedAt,
             latestOther: entity.latestOtherMoveAt,
             lastSeenOther: entity.lastSeenOtherMoveAt,
             scope: entity.databaseScope,
             shareName: entity.ckShareRecordName,
             revoked: entity.isAccessRevoked
         )
         if let hit = entries[entity.objectID], hit.key == key {
             return hit.summary
         }
         guard let fresh = GameSummary(entity: entity) else { return nil }
         entries[entity.objectID] = (key, fresh)
         return fresh
     }
 }
 
 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
 
     /// 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
 
     init(
         persistence: PersistenceController,
         movesUpdater: MovesUpdater,
         authorIDProvider: @escaping @MainActor () -> String?,
         onGameCreated: @escaping (String) -> Void,
         onGameUpdated: @escaping (String) -> Void,
         onGameDeleted: @escaping (GameCloudDeletion) -> Void
     ) {
         self.persistence = persistence
         self.movesUpdater = movesUpdater
         self.authorIDProvider = authorIDProvider
         self.onGameCreated = onGameCreated
         self.onGameUpdated = onGameUpdated
         self.onGameDeleted = onGameDeleted
     }
 
     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()
             }
         }
     }
 
     /// 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, `lastSeenOtherMoveAt` 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
             }
             if currentEntity?.id == gameID {
                 entity.lastSeenOtherMoveAt = entity.latestOtherMoveAt
             }
         }
 
         if context.hasChanges {
             try? context.save()
         }
     }
 
     // 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
         markOtherMovesSeen(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 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
     }
 
     // MARK: - Delete a game
 
     func deleteGame(id: UUID) throws {
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
         request.fetchLimit = 1
 
         guard let entity = try context.fetch(request).first else { return }
 
         let deletion = GameCloudDeletion(
             gameID: id,
             databaseScope: entity.databaseScope,
             ckZoneName: entity.ckZoneName ?? "game-\(id.uuidString)",
             ckZoneOwnerName: entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
         )
 
         // 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)
     }
 
     // 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()
         try context.save()
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         Task { await movesUpdater.flush() }
 
         // Clean up current references
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
     }
 
     /// Marks a game as completed after a normal win. 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.
     func markCompleted(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,
               entity.completedAt == nil else { return }
         entity.completedAt = Date()
         try? context.save()
         if let ckName = entity.ckRecordName {
             onGameUpdated(ckName)
         }
         Task { await movesUpdater.flush() }
     }
 
     // MARK: - Reset
 
     /// Deletes every game (and its cascaded moves, snapshots, and cells) plus
     /// the sync-state row. Used by the diagnostics reset button.
     func resetAllData() {
         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)
         }
         try? context.save()
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
     }
 
     // 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
         markOtherMovesSeen(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
     }
 
     private func markOtherMovesSeen(for entity: GameEntity) {
         let isShared = entity.ckShareRecordName != nil || entity.databaseScope == 1
         guard isShared, let latest = entity.latestOtherMoveAt else { return }
         if (entity.lastSeenOtherMoveAt ?? .distantPast) < latest {
             entity.lastSeenOtherMoveAt = latest
             try? context.save()
         }
     }
 
     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?.source ?? 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))
     }
 
     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)
 
         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 }
             game.squares[r][c].entry = cell.letter
             game.squares[r][c].mark = decodeMark(kind: cell.markKind, checkedWrong: cell.checkedWrong)
             game.squares[r][c].letterAuthorID = cell.authorID
         }
         game.recomputeCompletionCache()
 
         if updateCache {
             updateCellCache(for: entity, from: grid)
         }
     }
 
     private func updateCellCache(for gameEntity: GameEntity, from grid: GridState) {
         Self.applyCellCache(to: gameEntity, from: grid, in: context)
         try? context.save()
     }
 
     /// 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
         )
     }
 
     /// 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.markKind = cell.markKind
             ce.checkedWrong = cell.checkedWrong
             ce.letterAuthorID = cell.authorID
         }
 
         for (position, ce) in existing where grid[position] == nil {
             ce.letter = ""
             ce.markKind = 0
             ce.checkedWrong = false
             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 only 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.
     func handleRemoteRemoval(gameID: UUID) {
         guard currentEntity?.id == gameID else { return }
         currentGame = nil
         currentMutator = nil
         currentEntity = nil
     }
 
     /// 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,
             authorIDProvider: authorIDProvider,
             isOwned: entity.databaseScope == 0,
             isShared: entity.ckShareRecordName != nil || entity.databaseScope == 1,
             isAccessRevoked: entity.isAccessRevoked
         )
     }
 
 
     // MARK: - CellMark coding
 
     private func decodeMark(kind: Int16, checkedWrong: Bool) -> CellMark {
         switch kind {
         case 1: return .pen(checkedWrong: checkedWrong)
         case 2: return .pencil(checkedWrong: checkedWrong)
         case 3: return .revealed
         default: return .none
         }
     }
 }