crossmate

MovesUpdater.swift (12124B)

---

 import CoreData
 import Foundation
 
 /// In-memory staging area for cell edits. Coalesces rapid same-cell edits down
 /// to one per-cell entry, on flush merges them into the local device's
 /// `MovesEntity` row (per-cell wall-clock LWW), updates the local `CellEntity`
 /// cache, and hands the affected `gameIDs` to the injected sink so SyncEngine
 /// can enqueue Moves records for upload.
 ///
 /// Flush triggers:
 /// - trailing-edge debounce (the user has stopped typing);
 /// - cell change (focus moves to a different cell);
 /// - explicit `flush()` (view exit, app background, game completion, tests).
 actor MovesUpdater {
     private struct Key: Hashable {
         let gameID: UUID
         let row: Int
         let col: Int
     }
 
     private struct Pending {
         var letter: String
         var markKind: Int16
         var checkedWrong: Bool
         var authorID: String?
         var enqueuedAt: Date
     }
 
     private let debounceInterval: Duration
     private let sessionPingStaleInterval: TimeInterval
     private let persistence: PersistenceController
     private let writerAuthorIDProvider: @Sendable () async -> String?
     private let sink: @Sendable (Set<UUID>) async -> Void
     private let sessionPingSink: (@Sendable (UUID, String) async -> Void)?
     /// Sleep primitive used by the debounce timer. Injected so tests can
     /// drive flushes deterministically instead of racing against wall-clock
     /// `Task.sleep` from the actor's own task queue.
     private let sleep: @Sendable (Duration) async throws -> Void
 
     private var buffer: [Key: Pending] = [:]
     /// Cell most recently enqueued. A subsequent enqueue targeting a different
     /// cell flushes first so `updatedAt` ordering in the merged grid matches
     /// editing order for cells whose wall clocks are within the same tick.
     private var lastCell: Key?
     private var debounceTask: Task<Void, Never>?
     /// Per-game timestamp of the last session ping fired. The first `enqueue`
     /// for a game with no entry — or one stale beyond
     /// `sessionPingStaleInterval` — counts as a new session and fires a ping.
     private var lastSessionPingAt: [UUID: Date] = [:]
 
     init(
         debounceInterval: Duration = .milliseconds(500),
         sessionPingStaleInterval: TimeInterval = 20 * 60,
         persistence: PersistenceController,
         writerAuthorIDProvider: @escaping @Sendable () async -> String?,
         sink: @escaping @Sendable (Set<UUID>) async -> Void,
         sessionPingSink: (@Sendable (UUID, String) async -> Void)? = nil,
         sleep: @escaping @Sendable (Duration) async throws -> Void = { try await Task.sleep(for: $0) }
     ) {
         self.debounceInterval = debounceInterval
         self.sessionPingStaleInterval = sessionPingStaleInterval
         self.persistence = persistence
         self.writerAuthorIDProvider = writerAuthorIDProvider
         self.sink = sink
         self.sessionPingSink = sessionPingSink
         self.sleep = sleep
     }
 
     /// Registers a cell edit. `authorID` is the cell-effective author that
     /// gets persisted into the merged grid — it may differ from the acting
     /// (writer) user when a same-letter rewrite or a reveal-of-correct
     /// preserves the original author. The acting user is still passed
     /// separately so session pings fire on the typist.
     func enqueue(
         gameID: UUID,
         row: Int,
         col: Int,
         letter: String,
         markKind: Int16,
         checkedWrong: Bool,
         authorID: String?,
         actingAuthorID: String? = nil
     ) async {
         let key = Key(gameID: gameID, row: row, col: col)
 
         if let lastCell, lastCell != key {
             await performFlush()
         }
 
         buffer[key] = Pending(
             letter: letter,
             markKind: markKind,
             checkedWrong: checkedWrong,
             authorID: authorID,
             enqueuedAt: Date()
         )
         lastCell = key
         scheduleDebounce()
 
         let pingAuthorID = actingAuthorID ?? authorID
         if let pingAuthorID, !pingAuthorID.isEmpty {
             await maybeFireSessionPing(gameID: gameID, authorID: pingAuthorID)
         }
     }
 
     /// Resets session-ping tracking for `gameID`. Called from the puzzle
     /// view's teardown so re-entry counts as a fresh session.
     func noteSessionEnded(gameID: UUID) {
         lastSessionPingAt.removeValue(forKey: gameID)
     }
 
     /// Flushes any pending edits immediately and cancels the debounce. Safe
     /// to call when the buffer is empty.
     func flush() async {
         debounceTask?.cancel()
         debounceTask = nil
         await performFlush()
     }
 
     private func maybeFireSessionPing(gameID: UUID, authorID: String) async {
         let now = Date()
         if let last = lastSessionPingAt[gameID],
            now.timeIntervalSince(last) < sessionPingStaleInterval {
             return
         }
         lastSessionPingAt[gameID] = now
         if let sessionPingSink {
             await sessionPingSink(gameID, authorID)
         }
     }
 
     private func scheduleDebounce() {
         debounceTask?.cancel()
         let interval = debounceInterval
         let sleep = self.sleep
         debounceTask = Task { [weak self] in
             try? await sleep(interval)
             if Task.isCancelled { return }
             await self?.debouncedFlush()
         }
     }
 
     private func debouncedFlush() async {
         debounceTask = nil
         await performFlush()
     }
 
     private func performFlush() async {
         guard !buffer.isEmpty else { return }
         // The parent record name embeds the writer's authorID; without it we
         // can't address the row yet. Keep the buffer intact and retry rather
         // than losing live in-memory edits that have not reached Core Data.
         guard let writerAuthorID = await writerAuthorIDProvider(),
               !writerAuthorID.isEmpty
         else {
             scheduleDebounce()
             return
         }
 
         let snapshot = buffer
         buffer.removeAll(keepingCapacity: true)
         lastCell = nil
 
         guard let affected = persistAndMerge(
             snapshot: snapshot,
             writerAuthorID: writerAuthorID
         ) else {
             buffer.merge(snapshot) { current, _ in current }
             scheduleDebounce()
             return
         }
         guard !affected.isEmpty else { return }
         await sink(affected)
     }
 
     /// Merges buffered edits into the local device's `MovesEntity` row per
     /// game. Idempotent: existing per-cell entries are kept if they have a
     /// later `updatedAt` than the new edit (defensive against wall-clock
     /// regressions).
     private func persistAndMerge(
         snapshot: [Key: Pending],
         writerAuthorID: String
     ) -> Set<UUID>? {
         let context = persistence.container.newBackgroundContext()
         return context.performAndWait {
             var byGame: [UUID: [(Key, Pending)]] = [:]
             for (key, pending) in snapshot {
                 byGame[key.gameID, default: []].append((key, pending))
             }
 
             var affected = Set<UUID>()
             for (gameID, edits) in byGame {
                 guard let game = Self.fetchGame(gameID: gameID, in: context) else { continue }
 
                 let movesEntity = Self.ensureMovesEntity(
                     for: gameID,
                     writerAuthorID: writerAuthorID,
                     game: game,
                     in: context
                 )
 
                 var existing: [GridPosition: TimestampedCell] = [:]
                 if let data = movesEntity.cells, !data.isEmpty {
                     existing = (try? MovesCodec.decode(data)) ?? [:]
                 }
 
                 var maxUpdatedAt = movesEntity.updatedAt ?? .distantPast
                 var cellCacheMap = Self.cellCacheMap(for: game)
 
                 for (key, pending) in edits {
                     let position = GridPosition(row: key.row, col: key.col)
                     let newCell = TimestampedCell(
                         letter: pending.letter,
                         markKind: pending.markKind,
                         checkedWrong: pending.checkedWrong,
                         updatedAt: pending.enqueuedAt,
                         authorID: pending.authorID
                     )
                     if let current = existing[position],
                        current.updatedAt > newCell.updatedAt {
                         continue
                     }
                     existing[position] = newCell
                     if newCell.updatedAt > maxUpdatedAt {
                         maxUpdatedAt = newCell.updatedAt
                     }
 
                     Self.updateCellCache(
                         for: game,
                         key: key,
                         pending: pending,
                         cells: &cellCacheMap,
                         in: context
                     )
                 }
 
                 movesEntity.cells = (try? MovesCodec.encode(existing)) ?? Data()
                 movesEntity.updatedAt = maxUpdatedAt
                 if game.updatedAt.map({ $0 < maxUpdatedAt }) ?? true {
                     game.updatedAt = maxUpdatedAt
                 }
                 affected.insert(gameID)
             }
 
             if context.hasChanges {
                 do {
                     try context.save()
                 } catch {
                     print("MovesUpdater: failed to save context: \(error)")
                     return nil
                 }
             }
             return affected
         }
     }
 
     private nonisolated static func fetchGame(
         gameID: UUID,
         in ctx: NSManagedObjectContext
     ) -> GameEntity? {
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         req.fetchLimit = 1
         return try? ctx.fetch(req).first
     }
 
     private nonisolated static func ensureMovesEntity(
         for gameID: UUID,
         writerAuthorID: String,
         game: GameEntity,
         in ctx: NSManagedObjectContext
     ) -> MovesEntity {
         let deviceID = RecordSerializer.localDeviceID
         let recordName = RecordSerializer.recordName(
             forMovesInGame: gameID,
             authorID: writerAuthorID,
             deviceID: deviceID
         )
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         req.fetchLimit = 1
         if let existing = try? ctx.fetch(req).first {
             return existing
         }
         let entity = MovesEntity(context: ctx)
         entity.game = game
         entity.ckRecordName = recordName
         entity.authorID = writerAuthorID
         entity.deviceID = deviceID
         entity.cells = Data()
         entity.updatedAt = Date()
         return entity
     }
 
     private nonisolated static func cellCacheMap(
         for game: GameEntity
     ) -> [GridPosition: CellEntity] {
         let cellEntities = (game.cells as? Set<CellEntity>) ?? []
         var cells: [GridPosition: CellEntity] = [:]
         cells.reserveCapacity(cellEntities.count)
         for cell in cellEntities {
             cells[GridPosition(row: Int(cell.row), col: Int(cell.col))] = cell
         }
         return cells
     }
 
     private nonisolated static func updateCellCache(
         for game: GameEntity,
         key: Key,
         pending: Pending,
         cells: inout [GridPosition: CellEntity],
         in context: NSManagedObjectContext
     ) {
         let position = GridPosition(row: key.row, col: key.col)
         let cell: CellEntity
         if let existing = cells[position] {
             cell = existing
         } else {
             cell = CellEntity(context: context)
             cell.game = game
             cell.row = Int16(key.row)
             cell.col = Int16(key.col)
             cells[position] = cell
         }
         cell.letter = pending.letter
         cell.markKind = pending.markKind
         cell.checkedWrong = pending.checkedWrong
         cell.letterAuthorID = pending.authorID
     }
 }