crossmate

Journal.swift (25256B)

---

 import CoreData
 import Foundation
 
 /// Why a journal entry exists. Every grid-changing move is recorded so the
 /// whole game can be replayed (Phase 2). Letter `input` (adds/deletes) and
 /// `clear` (the bulk clear gesture) are undoable; `check`/`reveal` are recorded
 /// for replay but the undo/redo machine never offers them as steps — checking
 /// and revealing are "help" actions, not edits you rewind. `undo`/`redo` rows
 /// are the forward mutations produced by reversing or re-applying an undoable
 /// step; they are real grid changes (so they sync) but the stack machine treats
 /// them as stack operations.
 enum JournalKind: Int16, Sendable {
     case input = 0
     case check = 1
     case reveal = 2
     case clear = 3
     case undo = 4
     case redo = 5
 
     /// Whether this kind is an undoable step (as opposed to a recorded-only
     /// help gesture or a stack operation).
     var isUndoable: Bool { self == .input || self == .clear }
 }
 
 /// The after-state of a single cell touch — what the cell became, not what it
 /// was. The "before" value is never stored; it is recovered by following
 /// `JournalValue.prevSeqAtCell`.
 struct JournalCellState: Equatable, Sendable {
     var letter: String
     var mark: CellMark
     var cellAuthorID: String?
 
     static let empty = JournalCellState(letter: "", mark: .none, cellAuthorID: nil)
 
     /// Letter match for the supersession guard: undo only fires when the cell
     /// still holds the letter the move produced. Only the letter is compared —
     /// the journal logs letter adds/deletes, so a peer's check/reveal (a mark
     /// change) shouldn't block undoing one's own letter, while a peer changing
     /// the letter itself should.
     func letterMatches(_ other: JournalCellState) -> Bool {
         letter == other.letter
     }
 }
 
 /// One recorded cell touch. Append-only and immutable once written.
 /// `prevSeqAtCell` points at the previous entry for the same `(row, col)`
 /// (any kind), or `nil` when the cell was empty before — that pointer is how a
 /// before-state is recovered in O(1) without scanning the log.
 struct JournalValue: Equatable, Sendable {
     let seq: Int64
     let timestamp: Date
     let position: GridPosition
     /// The cell state observed immediately before this local touch. New local
     /// rows carry this so undo can restore a collaborator's pre-existing
     /// letter even though that letter is not in this device's local journal.
     /// Older rows and replay-upload rows may be nil and fall back to
     /// `prevSeqAtCell`.
     let beforeState: JournalCellState?
     let state: JournalCellState
     let actingAuthorID: String?
     let kind: JournalKind
     let targetSeq: Int64?
     let batchID: UUID?
     let prevSeqAtCell: Int64?
     /// The cursor direction at the moment of input, so undo/redo can land the
     /// cursor pointing the way the letter was originally typed. Only meaningful
     /// for `.input` entries; `nil` for clears, help gestures, and undo/redo
     /// rows (whose cursor direction comes from the input op they reverse).
     let direction: Puzzle.Direction?
 
     init(
         seq: Int64,
         timestamp: Date,
         position: GridPosition,
         beforeState: JournalCellState? = nil,
         state: JournalCellState,
         actingAuthorID: String?,
         kind: JournalKind,
         targetSeq: Int64?,
         batchID: UUID?,
         prevSeqAtCell: Int64?,
         direction: Puzzle.Direction? = nil
     ) {
         self.seq = seq
         self.timestamp = timestamp
         self.position = position
         self.beforeState = beforeState
         self.state = state
         self.actingAuthorID = actingAuthorID
         self.kind = kind
         self.targetSeq = targetSeq
         self.batchID = batchID
         self.prevSeqAtCell = prevSeqAtCell
         self.direction = direction
     }
 }
 
 /// One cell to rewrite as part of an undo or redo, with the guard value the
 /// caller checks against the live grid before applying.
 struct JournalRestore: Equatable, Sendable {
     let position: GridPosition
     /// The value to write into the cell.
     let restoreTo: JournalCellState
     /// Skip this cell if the live grid no longer shows this — it means a
     /// collaborator (or a later edit) changed it since.
     let expectedCurrent: JournalCellState
     /// The undoable entry being reversed / re-applied.
     let targetSeq: Int64
 }
 
 /// The cells to restore for one undo/redo step, plus the step's identity so the
 /// caller can mark it consumed if every cell turned out to be superseded.
 struct JournalPlan: Equatable, Sendable {
     let restores: [JournalRestore]
     let stepID: Int64
     /// The kind of the undoable step being reversed/re-applied (`.input` or
     /// `.clear`). Lets the caller decide where to put the cursor — onto a
     /// single-cell input, but not after a bulk clear.
     let kind: JournalKind
     /// The direction the reversed/re-applied input step was typed in, so the
     /// caller can orient the cursor to match. `nil` for `.clear` (no single
     /// direction) and for older entries recorded before direction was tracked.
     let direction: Puzzle.Direction?
 }
 
 /// Local, append-only log of every grid move, and the undo/redo derivation
 /// built on top of it. Local only — never synced in Phase 1. The current
 /// game's entries are held in memory (loaded lazily, so undo survives a
 /// relaunch) and each new entry is persisted on a background context; the
 /// in-memory list is authoritative for the session.
 @MainActor
 final class MovesJournal {
     private let persistence: PersistenceController
     private let backgroundContext: NSManagedObjectContext
 
     private var loadedGameID: UUID?
     private var entries: [JournalValue] = []
     private var bySeq: [Int64: JournalValue] = [:]
     private var lastSeqAtCell: [GridPosition: Int64] = [:]
     private var nextSeq: Int64 = 0
 
     /// Steps whose every cell was found superseded when the caller tried to
     /// apply them, so they should be passed over. Transient (session-only): a
     /// fully-superseded step has no grid effect to record, so without this the
     /// stack would keep re-offering it and undo would be stuck. Cleared on load.
     private var consumedUndoSteps: Set<Int64> = []
     private var consumedRedoSteps: Set<Int64> = []
 
     init(persistence: PersistenceController) {
         self.persistence = persistence
         self.backgroundContext = persistence.container.newBackgroundContext()
         // Each appended entry links its `GameEntity` (for cascade-delete),
         // which touches that row's inverse relationship. Meanwhile the grid
         // writer and summary backfills bump the same `GameEntity` constantly,
         // so this context's snapshot of it goes stale between saves. With the
         // default `NSErrorMergePolicy` that surfaces as a 133020 merge conflict
         // and the *entire* save — including the new journal row — is rolled
         // back, silently dropping the entry from disk while it lingers in the
         // in-memory list. Undo then works for the session but the row is gone
         // on relaunch, leaving the journal behind the grid. Store-trump keeps
         // the store's authoritative `GameEntity` and applies only our
         // relationship insert, so the journal write always lands.
         self.backgroundContext.mergePolicy = NSMergePolicy.mergeByPropertyStoreTrump
     }
 
     // MARK: - Recording
 
     /// Appends a cell touch and returns the recorded value. Assigns the next
     /// `seq`, links `prevSeqAtCell`, and persists asynchronously.
     @discardableResult
     func record(
         gameID: UUID,
         position: GridPosition,
         beforeState: JournalCellState? = nil,
         state: JournalCellState,
         actingAuthorID: String?,
         kind: JournalKind,
         targetSeq: Int64?,
         batchID: UUID?,
         direction: Puzzle.Direction? = nil
     ) -> JournalValue {
         ensureLoaded(gameID)
         let value = JournalValue(
             seq: nextSeq,
             timestamp: Date(),
             position: position,
             beforeState: beforeState,
             state: state,
             actingAuthorID: actingAuthorID,
             kind: kind,
             targetSeq: targetSeq,
             batchID: batchID,
             prevSeqAtCell: lastSeqAtCell[position],
             direction: direction
         )
         nextSeq += 1
         entries.append(value)
         bySeq[value.seq] = value
         lastSeqAtCell[position] = value.seq
         persist(value, gameID: gameID)
         return value
     }
 
     // MARK: - Replay
 
     /// Read-only snapshot of the recorded log for a game, in seq order —
     /// every move including checks and reveals. The basis for Phase 2 replay.
     func recordedEntries(gameID: UUID) -> [JournalValue] {
         ensureLoaded(gameID)
         return entries
     }
 
     // MARK: - Undo / redo queries
 
     func canUndo(gameID: UUID) -> Bool {
         ensureLoaded(gameID)
         return stacks().live.contains { !consumedUndoSteps.contains(stepID($0)) }
     }
 
     func canRedo(gameID: UUID) -> Bool {
         ensureLoaded(gameID)
         return stacks().redo.contains { !consumedRedoSteps.contains(stepID($0)) }
     }
 
     /// The cells to restore to undo the most recent still-undoable step, or
     /// `nil` when there is nothing to undo. Does not mutate journal state — the
     /// `undo` rows the caller records via `record` drive the stack forward.
     func planUndo(gameID: UUID) -> JournalPlan? {
         ensureLoaded(gameID)
         guard let op = stacks().live.last(where: { !consumedUndoSteps.contains(stepID($0)) })
         else { return nil }
         let restores = op.entries.map { entry in
             JournalRestore(
                 position: entry.position,
                 restoreTo: observedBeforeState(of: entry),
                 expectedCurrent: entry.state,
                 targetSeq: entry.seq
             )
         }
         return JournalPlan(restores: restores, stepID: stepID(op), kind: op.kind, direction: op.entries.first?.direction)
     }
 
     /// The cells to restore to redo the most recently undone step.
     func planRedo(gameID: UUID) -> JournalPlan? {
         ensureLoaded(gameID)
         guard let op = stacks().redo.last(where: { !consumedRedoSteps.contains(stepID($0)) })
         else { return nil }
         let restores = op.entries.map { entry in
             JournalRestore(
                 position: entry.position,
                 restoreTo: entry.state,
                 expectedCurrent: observedBeforeState(of: entry),
                 targetSeq: entry.seq
             )
         }
         return JournalPlan(restores: restores, stepID: stepID(op), kind: op.kind, direction: op.entries.first?.direction)
     }
 
     /// Records that a planned undo/redo step had no surviving cells (all
     /// superseded), so the next plan skips past it instead of re-offering it.
     func markUndoConsumed(stepID: Int64, gameID: UUID) {
         ensureLoaded(gameID)
         consumedUndoSteps.insert(stepID)
     }
 
     func markRedoConsumed(stepID: Int64, gameID: UUID) {
         ensureLoaded(gameID)
         consumedRedoSteps.insert(stepID)
     }
 
     // MARK: - Derivation
 
     private struct Operation {
         let kind: JournalKind
         let entries: [JournalValue]
     }
 
     /// Stable identity for an operation — the seq of its first entry, which is
     /// unique and immutable across re-derivations of the same log.
     private func stepID(_ op: Operation) -> Int64 {
         op.entries.first?.seq ?? -1
     }
 
     /// The before-state of an entry: the after-state of the previous touch at
     /// the same cell, or empty if there was none.
     private func beforeState(of entry: JournalValue) -> JournalCellState {
         guard let prev = entry.prevSeqAtCell, let value = bySeq[prev] else {
             return .empty
         }
         return value.state
     }
 
     private func observedBeforeState(of entry: JournalValue) -> JournalCellState {
         entry.beforeState ?? beforeState(of: entry)
     }
 
     /// Groups the log into operations (a bulk gesture or one undo/redo op is a
     /// single operation; each single-cell edit is its own), then runs the stack
     /// machine. `live` holds applied undoable operations newest-last; `redo`
     /// holds undone ones available to re-apply. `check`/`reveal` ops are
     /// recorded but inert here.
     ///
     /// `undo`/`redo` ops are matched to the undoable op they act on by
     /// `targetSeq`, not by stack position: the supersession guard can skip a
     /// superseded top step and undo an earlier one, so the op being reversed is
     /// not necessarily on top.
     private func stacks() -> (live: [Operation], redo: [Operation]) {
         var operations: [Operation] = []
         var i = 0
         while i < entries.count {
             let head = entries[i]
             var run = [head]
             var j = i + 1
             if let batch = head.batchID {
                 while j < entries.count,
                       entries[j].batchID == batch,
                       entries[j].kind == head.kind {
                     run.append(entries[j])
                     j += 1
                 }
             }
             operations.append(Operation(kind: head.kind, entries: run))
             i = j
         }
 
         // Each entry's seq maps to the op that owns it, so an undo/redo op can
         // find the exact undoable op its `targetSeq` refers to.
         var opIndexBySeq: [Int64: Int] = [:]
         for (index, op) in operations.enumerated() {
             for entry in op.entries { opIndexBySeq[entry.seq] = index }
         }
 
         var live: [Int] = []
         var redo: [Int] = []
         for (index, op) in operations.enumerated() {
             switch op.kind {
             case .undo:
                 guard let target = op.entries.first?.targetSeq,
                       let targetIndex = opIndexBySeq[target],
                       let pos = live.firstIndex(of: targetIndex) else { continue }
                 live.remove(at: pos)
                 redo.append(targetIndex)
             case .redo:
                 guard let target = op.entries.first?.targetSeq,
                       let targetIndex = opIndexBySeq[target],
                       let pos = redo.firstIndex(of: targetIndex) else { continue }
                 redo.remove(at: pos)
                 live.append(targetIndex)
             case .input, .clear:
                 redo.removeAll()       // a new undoable edit cuts the redo branch
                 live.append(index)
             case .check, .reveal:
                 break                  // recorded for replay, inert to undo/redo
             }
         }
         return (live.map { operations[$0] }, redo.map { operations[$0] })
     }
 
     // MARK: - Loading & persistence
 
     private func ensureLoaded(_ gameID: UUID) {
         guard loadedGameID != gameID else { return }
         load(gameID)
     }
 
     private func load(_ gameID: UUID) {
         entries.removeAll()
         bySeq.removeAll()
         lastSeqAtCell.removeAll()
         consumedUndoSteps.removeAll()
         consumedRedoSteps.removeAll()
         nextSeq = 0
         loadedGameID = gameID
 
         let ctx = backgroundContext
         let loaded: [JournalValue] = ctx.performAndWait {
             let req = NSFetchRequest<JournalEntity>(entityName: "JournalEntity")
             // `sourceDeviceID == nil` keeps this to *this device's* log: rows
             // cached from other devices for replay (see GameStore's replay
             // cache) carry a source key and must not enter the undo/redo model.
             req.predicate = NSPredicate(format: "gameID == %@ AND sourceDeviceID == nil", gameID as CVarArg)
             req.sortDescriptors = [NSSortDescriptor(key: "seq", ascending: true)]
             let rows = (try? ctx.fetch(req)) ?? []
             return rows.map(Self.value(from:))
         }
         for value in loaded {
             entries.append(value)
             bySeq[value.seq] = value
             lastSeqAtCell[value.position] = value.seq
             nextSeq = max(nextSeq, value.seq + 1)
         }
     }
 
     /// Awaits the background persistence queue so every recorded entry has
     /// landed in the store. `record(...)` persists asynchronously and the
     /// in-memory list is authoritative for play, but the Phase 2 upload
     /// reconstructs the asset from Core Data on a *separate* background
     /// context — call this first (e.g. at completion) so that context sees the
     /// final entries rather than racing the in-flight saves.
     func flush() async {
         await backgroundContext.perform { }
     }
 
     private func persist(_ value: JournalValue, gameID: UUID) {
         let ctx = backgroundContext
         ctx.perform {
             let entity = JournalEntity(context: ctx)
             // Local log: leave the source key nil (this device's own row).
             Self.assign(value, to: entity, gameID: gameID)
 
             let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             gameReq.fetchLimit = 1
             entity.game = try? ctx.fetch(gameReq).first
 
             do {
                 try ctx.save()
             } catch {
                 print("MovesJournal: failed to persist entry: \(error)")
                 ctx.rollback()
             }
         }
     }
 
     /// Writes a `JournalValue`'s fields onto a `JournalEntity`, leaving the
     /// `game` relationship and the `sourceAuthorID`/`sourceDeviceID` key to the
     /// caller. Shared by the local-log `persist` and the replay cache (which
     /// also stamps the source device), so the value→row mapping lives in one
     /// place. `nonisolated` so the cache can call it on its own context.
     nonisolated static func assign(_ value: JournalValue, to entity: JournalEntity, gameID: UUID) {
         entity.gameID = gameID
         entity.seq = value.seq
         entity.timestamp = value.timestamp
         entity.row = Int16(value.position.row)
         entity.col = Int16(value.position.col)
         entity.beforeLetter = value.beforeState?.letter
         entity.beforeMarkCode = value.beforeState.map { NSNumber(value: $0.mark.code) }
         entity.beforeCellAuthorID = value.beforeState?.cellAuthorID
         entity.letter = value.state.letter
         entity.markCode = value.state.mark.code
         entity.cellAuthorID = value.state.cellAuthorID
         entity.actingAuthorID = value.actingAuthorID
         entity.kind = value.kind.rawValue
         entity.targetSeq = value.targetSeq.map { NSNumber(value: $0) }
         entity.batchID = value.batchID
         entity.prevSeqAtCell = value.prevSeqAtCell.map { NSNumber(value: $0) }
         entity.dir = value.direction.map { NSNumber(value: $0 == .down ? 1 : 0) }
     }
 
     /// Maps a persisted row to its in-memory value. `internal` (not `private`)
     /// so `RecordBuilder` can reconstruct the upload asset straight from Core
     /// Data on its own background context.
     nonisolated static func value(from entity: JournalEntity) -> JournalValue {
         JournalValue(
             seq: entity.seq,
             timestamp: entity.timestamp ?? .distantPast,
             position: GridPosition(row: Int(entity.row), col: Int(entity.col)),
             beforeState: entity.beforeLetter.map {
                 JournalCellState(
                     letter: $0,
                     mark: CellMark(code: entity.beforeMarkCode?.int16Value ?? 0),
                     cellAuthorID: entity.beforeCellAuthorID
                 )
             },
             state: JournalCellState(
                 letter: entity.letter ?? "",
                 mark: CellMark(code: entity.markCode),
                 cellAuthorID: entity.cellAuthorID
             ),
             actingAuthorID: entity.actingAuthorID,
             kind: JournalKind(rawValue: entity.kind) ?? .input,
             targetSeq: entity.targetSeq?.int64Value,
             batchID: entity.batchID,
             prevSeqAtCell: entity.prevSeqAtCell?.int64Value,
             direction: entity.dir.map { $0.int16Value == 1 ? Puzzle.Direction.down : .across }
         )
     }
 }
 
 /// Wire format for a device's journal, encoded once at game completion and
 /// uploaded as the `Journal` record's `entries` asset (Phase 2). A faithful
 /// dump of `[JournalValue]` in `seq` order — merging every device's decoded
 /// dump by `timestamp` reconstructs the whole game for replay. The mark is
 /// carried as the single lossless `markCode` (`CellMark.code`).
 enum JournalCodec {
     struct Payload: Codable, Equatable {
         struct Entry: Codable, Equatable {
             let seq: Int64
             let timestamp: Date
             let row: Int
             let col: Int
             let letter: String
             let markCode: Int16
             let cellAuthorID: String?
             let actingAuthorID: String?
             let kind: Int16
             let targetSeq: Int64?
             let batchID: UUID?
             let prevSeqAtCell: Int64?
             let dir: Int?
 
             init(
                 seq: Int64,
                 timestamp: Date,
                 row: Int,
                 col: Int,
                 letter: String,
                 markCode: Int16,
                 cellAuthorID: String?,
                 actingAuthorID: String?,
                 kind: Int16,
                 targetSeq: Int64?,
                 batchID: UUID?,
                 prevSeqAtCell: Int64?,
                 dir: Int?
             ) {
                 self.seq = seq
                 self.timestamp = timestamp
                 self.row = row
                 self.col = col
                 self.letter = letter
                 self.markCode = markCode
                 self.cellAuthorID = cellAuthorID
                 self.actingAuthorID = actingAuthorID
                 self.kind = kind
                 self.targetSeq = targetSeq
                 self.batchID = batchID
                 self.prevSeqAtCell = prevSeqAtCell
                 self.dir = dir
             }
 
             // Optionals are decoded leniently so a record written by a newer
             // client that added fields still decodes cleanly on an older one
             // (same forward-compat stance as `MovesCodec.Payload.Entry`).
             init(from decoder: Decoder) throws {
                 let c = try decoder.container(keyedBy: CodingKeys.self)
                 seq = try c.decode(Int64.self, forKey: .seq)
                 timestamp = try c.decode(Date.self, forKey: .timestamp)
                 row = try c.decode(Int.self, forKey: .row)
                 col = try c.decode(Int.self, forKey: .col)
                 letter = try c.decode(String.self, forKey: .letter)
                 markCode = try c.decode(Int16.self, forKey: .markCode)
                 kind = try c.decode(Int16.self, forKey: .kind)
                 cellAuthorID = try? c.decode(String.self, forKey: .cellAuthorID)
                 actingAuthorID = try? c.decode(String.self, forKey: .actingAuthorID)
                 targetSeq = try? c.decode(Int64.self, forKey: .targetSeq)
                 batchID = try? c.decode(UUID.self, forKey: .batchID)
                 prevSeqAtCell = try? c.decode(Int64.self, forKey: .prevSeqAtCell)
                 dir = try? c.decode(Int.self, forKey: .dir)
             }
         }
         let entries: [Entry]
     }
 
     static func encode(_ values: [JournalValue]) throws -> Data {
         let entries = values
             .sorted { $0.seq < $1.seq }
             .map { value in
                 Payload.Entry(
                     seq: value.seq,
                     timestamp: value.timestamp,
                     row: value.position.row,
                     col: value.position.col,
                     letter: value.state.letter,
                     markCode: value.state.mark.code,
                     cellAuthorID: value.state.cellAuthorID,
                     actingAuthorID: value.actingAuthorID,
                     kind: value.kind.rawValue,
                     targetSeq: value.targetSeq,
                     batchID: value.batchID,
                     prevSeqAtCell: value.prevSeqAtCell,
                     dir: value.direction?.rawValue
                 )
             }
         return try JSONEncoder().encode(Payload(entries: entries))
     }
 
     static func decode(_ data: Data) throws -> [JournalValue] {
         let payload = try JSONDecoder().decode(Payload.self, from: data)
         return payload.entries.map { entry in
             JournalValue(
                 seq: entry.seq,
                 timestamp: entry.timestamp,
                 position: GridPosition(row: entry.row, col: entry.col),
                 beforeState: nil,
                 state: JournalCellState(
                     letter: entry.letter,
                     mark: CellMark(code: entry.markCode),
                     cellAuthorID: entry.cellAuthorID
                 ),
                 actingAuthorID: entry.actingAuthorID,
                 kind: JournalKind(rawValue: entry.kind) ?? .input,
                 targetSeq: entry.targetSeq,
                 batchID: entry.batchID,
                 prevSeqAtCell: entry.prevSeqAtCell,
                 direction: entry.dir.flatMap(Puzzle.Direction.init(rawValue:))
             )
         }
     }
 }