crossmate

GameMutator.swift (19392B)

---

 import Foundation
 
 /// Unified mutation processor that sits between `PlayerSession` and `Game`.
 /// Every mutation flows through here so that the in-memory `Game` stays
 /// up-to-date for immediate UI feedback, and a corresponding cell update is
 /// emitted to `MovesUpdater` for durable persistence and CloudKit sync.
 ///
 /// Remote changes no longer flow through here — they arrive via replay from
 /// the sync engine, which writes directly to `CellEntity` and notifies the
 /// store to refresh the in-memory game.
 ///
 /// All methods are `@MainActor` because `Game` is `@MainActor`.
 @MainActor
 @Observable
 final class GameMutator {
     private let game: Game
     let gameID: UUID
     private let movesUpdater: MovesUpdater?
     private let movesJournal: MovesJournal?
     private let authorIDProvider: (@MainActor () -> String?)?
     private let onLocalCellEdit: (@MainActor (RealtimeCellEdit) -> Void)?
     private let onLocalCellEditBatch: (@MainActor ([RealtimeCellEdit]) -> Void)?
     /// Observation token for undo/redo availability. The journal itself is not
     /// observable, so `canUndo`/`canRedo` read this value and journal mutations
     /// bump it to invalidate SwiftUI menu state.
     private var journalRevision = 0
 
     /// While non-nil, `emitMove` parks its live broadcast here instead of
     /// firing `onLocalCellEdit` per cell. A bulk gesture (check/clear/undo of a
     /// batch) thus ships one engagement message rather than one per cell, so
     /// the peer's grid lights up in a single frame instead of trickling.
     private var batchBroadcastBuffer: [RealtimeCellEdit]?
 
     /// `true` when the current user owns the CloudKit zone for this game.
     let isOwned: Bool
     /// `true` when the game is shared — either the owner has an active share
     /// or the current user joined via one. Mutable so the store can flip it
     /// when a share is created mid-session, which lets `PuzzleDisplayView`
     /// react and build a roster without requiring the user to re-open.
     var isShared: Bool
 
     /// Whether persisted cell authorship should be rendered with participant
     /// colours. A Chronicle can retain collaborative history after its live
     /// share has been retired, so this is deliberately separate from
     /// `isShared`, which continues to control network and share actions.
     var showsPlayerAttribution: Bool {
         isShared || hasArchivedPlayerAttribution
     }
     private let hasArchivedPlayerAttribution: Bool
 
     /// `true` for the local read-only projection of a Chronicle. It retains
     /// participant display and replay data, but must never enter live-game
     /// clock, presence, engagement, cursor, or CloudKit write paths.
     let isArchived: Bool
 
     /// Set to `true` when the owner has revoked the current user's access to
     /// a shared game. Revocation makes the game read-only: every mutating
     /// entry point below is a no-op (via `isEditable`) and `PuzzleView` shows
     /// a read-only banner.
     var isAccessRevoked: Bool
 
     /// Whether this app implements the sync protocol selected by the game.
     /// Unsupported games remain viewable but every mutation is blocked.
     var isSyncSupported: Bool
 
     /// Version 2 allocates a new Lamport tick for every emitted cell mutation.
     /// `logicalTick` tracks the largest value observed anywhere in the game,
     /// including timestamp-derived values from legacy clients.
     private var usesLogicalTicks: Bool
     private var logicalTick: Int64
 
     /// Set to `true` once the game is completed (won or resigned). A completed
     /// game is terminal and read-only: every mutating entry point below becomes
     /// a no-op, so the grid can't be edited or "re-solved" after the fact. Set
     /// at construction from `completedAt` and flipped live when completion
     /// latches mid-session. The gate keys off this latched fact, not the live
     /// `completionState`, so a grid that drifted after completion stays locked.
     var isCompleted: Bool
 
     /// The single read-only predicate: local mutations are accepted only while
     /// the game is not terminal, the local user still has access, and this app
     /// understands the game's sync protocol. Every mutating entry point below
     /// guards on this — blocking the in-memory mutation, not just the sync
     /// emit — and the editing UI (keyboard, toolbar menus, hardware keys,
     /// VoiceOver actions) disables itself from the same flag, so no surface
     /// can mutate a game the model would refuse.
     var isEditable: Bool { !isCompleted && !isAccessRevoked && isSyncSupported }
 
     init(
         game: Game,
         gameID: UUID,
         movesUpdater: MovesUpdater?,
         movesJournal: MovesJournal? = nil,
         authorIDProvider: (@MainActor () -> String?)? = nil,
         onLocalCellEdit: (@MainActor (RealtimeCellEdit) -> Void)? = nil,
         onLocalCellEditBatch: (@MainActor ([RealtimeCellEdit]) -> Void)? = nil,
         isOwned: Bool = true,
         isShared: Bool = false,
         showsPlayerAttribution: Bool? = nil,
         isArchived: Bool = false,
         isAccessRevoked: Bool = false,
         isSyncSupported: Bool = true,
         syncVersion: Int64 = GameSyncVersion.current,
         initialLogicalTick: Int64 = 0,
         isCompleted: Bool = false
     ) {
         self.game = game
         self.gameID = gameID
         self.movesUpdater = movesUpdater
         self.movesJournal = movesJournal
         self.authorIDProvider = authorIDProvider
         self.onLocalCellEdit = onLocalCellEdit
         self.onLocalCellEditBatch = onLocalCellEditBatch
         self.isOwned = isOwned
         self.isShared = isShared
         self.hasArchivedPlayerAttribution = showsPlayerAttribution ?? isShared
         self.isArchived = isArchived
         self.isAccessRevoked = isAccessRevoked
         self.isSyncSupported = isSyncSupported
         self.usesLogicalTicks = GameSyncVersion.normalized(syncVersion) >= GameSyncVersion.logicalTicks
         self.logicalTick = max(0, initialLogicalTick)
         self.isCompleted = isCompleted
         prefetchJournal()
     }
 
     /// Refreshes protocol state after an inbound Game/Moves record. A game can
     /// advance from legacy to logical ticks while it is open, and every remote
     /// revision must raise the local Lamport floor before the next edit.
     func updateSyncVersion(_ version: Int64, observedLogicalTick: Int64) {
         isSyncSupported = GameSyncVersion.supports(version)
         usesLogicalTicks = GameSyncVersion.normalized(version) >= GameSyncVersion.logicalTicks
         logicalTick = max(logicalTick, observedLogicalTick)
     }
 
     // MARK: - Single-cell mutations
 
     func setLetter(_ letter: String, atRow row: Int, atCol col: Int, pencil: Bool, direction: Puzzle.Direction? = nil) {
         guard isEditable else { return }
         let before = cellState(atRow: row, atCol: col)
         game.setLetter(letter, atRow: row, atCol: col, pencil: pencil, authorID: authorIDProvider?())
         emitMove(
             atRow: row,
             atCol: col,
             beforeState: before,
             journalKind: kind(.input, ifChangedFrom: before, atRow: row, atCol: col),
             direction: direction
         )
     }
 
     func clearLetter(atRow row: Int, atCol col: Int, direction: Puzzle.Direction? = nil) {
         guard isEditable else { return }
         let before = cellState(atRow: row, atCol: col)
         game.clearLetter(atRow: row, atCol: col)
         emitMove(
             atRow: row,
             atCol: col,
             beforeState: before,
             journalKind: kind(.input, ifChangedFrom: before, atRow: row, atCol: col),
             direction: direction
         )
     }
 
     // MARK: - Bulk mutations
 
     // Every gesture is journaled (so it can be replayed), but only `clear` is
     // undoable among these — `check` and `reveal` are help actions, recorded
     // but never offered as undo steps. Each bulk gesture is one undo/replay
     // step via a shared batch ID; cells that didn't actually change record no
     // entry.
 
     func checkCells(_ cells: [Puzzle.Cell]) {
         applyBulk(cells, kind: .check) { game.checkCells($0) }
     }
 
     func revealCells(_ cells: [Puzzle.Cell]) {
         applyBulk(cells, kind: .reveal) { game.revealCells($0) }
     }
 
     func clearCells(_ cells: [Puzzle.Cell]) {
         applyBulk(cells, kind: .clear) { game.clearCells($0) }
     }
 
     private func applyBulk(
         _ cells: [Puzzle.Cell],
         kind: JournalKind,
         _ mutate: ([Puzzle.Cell]) -> Void
     ) {
         // A completed or revoked game is read-only. `resignGame` reveals
         // through a freshly loaded mutator whose `isCompleted` is still false
         // (it sets `completedAt` only afterwards), so its reveal is unaffected.
         guard isEditable else { return }
         let applicable = cells.filter { !$0.isBlock }
         guard !applicable.isEmpty else { return }
         let before = applicable.map { cellState(atRow: $0.row, atCol: $0.col) }
         mutate(applicable)
         let batch = UUID()
         collectingBroadcast {
             for (cell, priorState) in zip(applicable, before) {
                 let journalKind = self.kind(kind, ifChangedFrom: priorState, atRow: cell.row, atCol: cell.col)
                 if journalKind == nil, kind != .reveal { continue }
                 emitMove(
                     atRow: cell.row,
                     atCol: cell.col,
                     beforeState: priorState,
                     journalKind: journalKind,
                     batchID: batch
                 )
             }
         }
     }
 
     // MARK: - Undo / redo
 
     /// Where the cursor should land after an undo/redo, and which way it should
     /// point. `direction` is the way the reversed letter was originally typed,
     /// or `nil` when that wasn't recorded (older entries) so the caller keeps
     /// its current orientation.
     struct CursorLanding {
         let position: GridPosition
         let direction: Puzzle.Direction?
     }
 
     /// `true` when there is a still-undoable move by this user. Reading these
     /// is cheap (a derivation pass over the in-memory journal) and drives the
     /// enabled state of the undo/redo controls.
     var canUndo: Bool {
         _ = journalRevision
         guard isEditable, let movesJournal else { return false }
         return movesJournal.canUndo(gameID: gameID)
     }
 
     var canRedo: Bool {
         _ = journalRevision
         guard isEditable, let movesJournal else { return false }
         return movesJournal.canRedo(gameID: gameID)
     }
 
     func prefetchJournal() {
         guard let movesJournal else { return }
         Task { @MainActor [weak self, movesJournal, gameID] in
             await movesJournal.preload(gameID: gameID)
             guard let self, self.gameID == gameID else { return }
             self.journalRevision += 1
         }
     }
 
     /// Reverts the most recent still-standing move. Each restored cell is
     /// applied as a fresh forward mutation (so it syncs like any edit) and
     /// recorded as an `undo` row. Cells a collaborator has changed since are
     /// skipped via the supersession guard; if a whole step was superseded it is
     /// passed over so undo lands on the next still-standing move.
     ///
     /// Returns where the cursor should follow to — the single cell of an
     /// `input` step, with the direction it was typed in — or `nil` for a bulk
     /// `clear` (no single target) or when nothing was undone.
     @discardableResult
     func undo() -> CursorLanding? {
         guard isEditable, let movesJournal else { return nil }
         while let plan = movesJournal.planUndo(gameID: gameID) {
             if applyRestores(plan.restores, kind: .undo) { return cursorTarget(for: plan) }
             movesJournal.markUndoConsumed(stepID: plan.stepID, gameID: gameID)
             journalRevision += 1
         }
         return nil
     }
 
     /// Re-applies the most recently undone move. Mirror of `undo()`.
     @discardableResult
     func redo() -> CursorLanding? {
         guard isEditable, let movesJournal else { return nil }
         while let plan = movesJournal.planRedo(gameID: gameID) {
             if applyRestores(plan.restores, kind: .redo) { return cursorTarget(for: plan) }
             movesJournal.markRedoConsumed(stepID: plan.stepID, gameID: gameID)
             journalRevision += 1
         }
         return nil
     }
 
     /// The cell the cursor should move to after applying `plan`: a single-cell
     /// `input` step focuses its cell (oriented to how it was typed), while a
     /// bulk `clear` leaves the cursor put.
     private func cursorTarget(for plan: JournalPlan) -> CursorLanding? {
         guard plan.kind == .input, let position = plan.restores.first?.position else { return nil }
         return CursorLanding(position: position, direction: plan.direction)
     }
 
     /// Applies the surviving cells of a plan under one batch, returning whether
     /// any cell was applied (a fully-superseded step applies nothing).
     private func applyRestores(_ restores: [JournalRestore], kind: JournalKind) -> Bool {
         let batch = UUID()
         var appliedAny = false
         collectingBroadcast {
             for restore in restores {
                 let row = restore.position.row
                 let col = restore.position.col
                 let square = game.squares[row][col]
                 let current = JournalCellState(
                     letter: square.entry,
                     mark: square.mark,
                     cellAuthorID: square.letterAuthorID
                 )
                 guard current.letterMatches(restore.expectedCurrent) else { continue }
                 game.applyCellState(
                     restore.restoreTo.letter,
                     mark: restore.restoreTo.mark,
                     authorID: restore.restoreTo.cellAuthorID,
                     atRow: row, atCol: col
                 )
                 emitMove(
                     atRow: row,
                     atCol: col,
                     beforeState: current,
                     journalKind: kind,
                     batchID: batch,
                     targetSeq: restore.targetSeq
                 )
                 appliedAny = true
             }
         }
         return appliedAny
     }
 
     /// The cell's current full state, for change detection and the
     /// supersession guard.
     private func cellState(atRow row: Int, atCol col: Int) -> JournalCellState {
         let square = game.squares[row][col]
         return JournalCellState(letter: square.entry, mark: square.mark, cellAuthorID: square.letterAuthorID)
     }
 
     /// Returns `kind` when the cell's state actually changed (letter or mark),
     /// `nil` otherwise — a same-letter rewrite, a no-op write to a revealed
     /// cell, or a check/clear that skipped a cell records nothing.
     private func kind(_ kind: JournalKind, ifChangedFrom before: JournalCellState, atRow row: Int, atCol col: Int) -> JournalKind? {
         let square = game.squares[row][col]
         let changed = square.entry != before.letter || square.mark != before.mark
         return changed ? kind : nil
     }
 
     // MARK: - Helpers
 
     /// Runs `body` with per-cell live broadcasts buffered, then flushes them as
     /// a single message. A one-cell result degrades to the legacy single-cell
     /// `onLocalCellEdit` path, so it stays wire-compatible with peers that
     /// don't understand batches; only genuinely multi-cell gestures send a
     /// batch. The durable Moves/journal writes in `emitMove` are unaffected —
     /// only the live overlay is coalesced.
     private func collectingBroadcast(_ body: () -> Void) {
         batchBroadcastBuffer = []
         body()
         let edits = batchBroadcastBuffer ?? []
         batchBroadcastBuffer = nil
         switch edits.count {
         case 0: break
         case 1: onLocalCellEdit?(edits[0])
         default: onLocalCellEditBatch?(edits)
         }
     }
 
     private func emitMove(
         atRow row: Int,
         atCol col: Int,
         beforeState: JournalCellState? = nil,
         journalKind: JournalKind? = nil,
         batchID: UUID? = nil,
         targetSeq: Int64? = nil,
         direction: Puzzle.Direction? = nil
     ) {
         guard !isAccessRevoked, isSyncSupported else { return }
         let square = game.squares[row][col]
         let mark = square.mark
         let id = gameID
         let letter = square.entry
         // The cell's `letterAuthorID` is the canonical author for the square —
         // it may differ from the acting user when a same-letter write or a
         // reveal-of-correct preserved the original author.
         let cellAuthorID = square.letterAuthorID
         let actingAuthorID = authorIDProvider?()
 
         // Only letter adds/deletes (and undo/redo of them) are journaled;
         // `journalKind == nil` means this move is not undoable (check/reveal,
         // or a no-op write). Recording is independent of whether sync is wired.
         if let journalKind {
             movesJournal?.record(
                 gameID: id,
                 position: GridPosition(row: row, col: col),
                 beforeState: beforeState,
                 state: JournalCellState(letter: letter, mark: square.mark, cellAuthorID: cellAuthorID),
                 actingAuthorID: actingAuthorID,
                 kind: journalKind,
                 targetSeq: targetSeq,
                 batchID: batchID,
                 direction: direction
             )
             journalRevision += 1
         }
 
         guard let movesUpdater else { return }
         // Stamp the flag on the MainActor *before* the Task hops to the
         // actor, atomically with the value the user just typed. While it's
         // set, `GameStore.restore` won't overwrite this square from a remote
         // refresh — closing the window where the buffered letter exists only
         // in the actor and a fetch could revert it. The same timestamp is
         // persisted as the cell's `updatedAt` on flush, which is how
         // `restore` later recognises the edit has landed and retires the flag.
         let enqueuedAt = Date()
         let tick = nextLogicalTick()
         game.squares[row][col].enqueuedAt = enqueuedAt
         if let actingAuthorID, !actingAuthorID.isEmpty {
             let edit = RealtimeCellEdit(
                 gameID: id,
                 authorID: actingAuthorID,
                 deviceID: RecordSerializer.localDeviceID,
                 row: row,
                 col: col,
                 letter: letter,
                 mark: mark,
                 updatedAt: enqueuedAt,
                 cellAuthorID: cellAuthorID,
                 tick: tick
             )
             if batchBroadcastBuffer != nil {
                 batchBroadcastBuffer?.append(edit)
             } else {
                 onLocalCellEdit?(edit)
             }
         }
         Task {
             await movesUpdater.enqueue(
                 gameID: id,
                 row: row, col: col,
                 letter: letter,
                 mark: mark,
                 authorID: cellAuthorID,
                 enqueuedAt: enqueuedAt,
                 tick: tick
             )
         }
     }
 
     private func nextLogicalTick() -> Int64? {
         guard usesLogicalTicks else { return nil }
         if logicalTick < Int64.max { logicalTick += 1 }
         return logicalTick
     }
 }