crossmate

NYTPuzzleUpgrader.swift (6011B)

---

 import Foundation
 
 /// Re-fetches a NYT puzzle and runs the current `NYTToXDConverter` over it.
 /// Used when `XD.currentCmVersion` advances and an existing game's stored
 /// XD source predates a converter fix; the upgrader produces an XD string
 /// that can replace the persisted source provided the puzzle's grid hasn't
 /// changed underneath us. Only clue text, accepted variants, specials, and
 /// metadata are allowed to differ — the structural verifier rejects anything
 /// that would invalidate the player's in-progress moves.
 enum NYTPuzzleUpgrader {
     typealias PuzzleFetch = @Sendable (Date) async throws -> String
 
     enum Outcome {
         /// The fetched + re-converted XD is structurally identical to the old
         /// one; the persisted source can be replaced.
         case upgraded(newSource: String)
         /// The new XD's grid differs from the persisted one. Per the upgrade
         /// policy, the caller should stamp the new CmVer but keep the old
         /// source so the player's moves stay valid. `reason` describes the
         /// first divergence found so diagnostics can pinpoint the cell.
         case mismatched(reason: String)
         /// The fetch or a parse step failed. Caller should leave both the
         /// source and the CmVer untouched so the upgrade is retried on the
         /// next launch.
         case failed(Error)
     }
 
     static func upgrade(
         date: Date,
         currentSource: String,
         fetch: PuzzleFetch
     ) async -> Outcome {
         let newSource: String
         do {
             newSource = try await fetch(date)
         } catch {
             return .failed(error)
         }
 
         let oldXD: XD
         let newXD: XD
         do {
             oldXD = try XD.parse(currentSource)
             newXD = try XD.parse(newSource)
         } catch {
             return .failed(error)
         }
 
         if let reason = structuralDivergence(oldXD, newXD) {
             return .mismatched(reason: reason)
         }
         return .upgraded(newSource: newSource)
     }
 
     /// Describes a deferred NYT re-conversion for an owned game whose stored
     /// `puzzleSource` predates `XD.currentCmVersion`. Built up-front (before
     /// `loadGame`) so the caller can show an "Updating puzzle…" state during
     /// the network round-trip. The bundled-catalog upgrade in
     /// `GameStore.preparePuzzleForLoad` runs synchronously and doesn't need
     /// this.
     struct Plan: Sendable {
         let gameID: UUID
         let date: Date
         fileprivate let currentSource: String
     }
 
     /// Returns a plan when an opened game would benefit from a NYT re-
     /// conversion: CmVer mismatch, the local user owns the zone (so this
     /// device's write will sync to participants), the persisted XD identifies
     /// a NYT puzzle, and a publication date is present. Bundled puzzles and
     /// participant-side rows are skipped — the bundled-catalog path already
     /// handles the former, and only the owner should rewrite the canonical
     /// source.
     @MainActor
     static func plan(for id: UUID, store: GameStore) -> Plan? {
         guard let info = store.puzzleInfo(for: id),
               info.isOwned,
               let xd = try? XD.parse(info.source),
               xd.cmVersion != XD.currentCmVersion,
               xd.publisher == "New York Times",
               let date = xd.date
         else { return nil }
         return Plan(gameID: info.gameID, date: date, currentSource: info.source)
     }
 
     /// Runs the upgrader and applies the result against `store`:
     /// `.upgraded` swaps in the new source via `replacePuzzleSource`;
     /// `.mismatched` stamps the new CmVer via `bumpPuzzleCmVersion` so we
     /// don't retry every launch; `.failed` writes nothing, so the upgrade
     /// is re-attempted next time the game is opened (covers transient
     /// network / auth failures).
     @MainActor
     @discardableResult
     static func apply(
         plan: Plan,
         store: GameStore,
         fetch: PuzzleFetch
     ) async -> Outcome {
         let outcome = await upgrade(
             date: plan.date,
             currentSource: plan.currentSource,
             fetch: fetch
         )
         switch outcome {
         case .upgraded(let newSource):
             store.replacePuzzleSource(id: plan.gameID, with: newSource)
         case .mismatched:
             store.bumpPuzzleCmVersion(for: plan.gameID)
         case .failed:
             break
         }
         return outcome
     }
 
     /// Two puzzles are structurally equivalent when their grids have the same
     /// dimensions, the same block layout, and the same solution at every open
     /// cell. Special markers, accepted variants, clues, and headers may all
     /// differ.
     static func structurallyEquivalent(_ a: XD, _ b: XD) -> Bool {
         structuralDivergence(a, b) == nil
     }
 
     /// Walks the grid in row-major order and returns a short description of
     /// the first cell that disagrees, or nil when the two are equivalent.
     /// Used to populate `.mismatched(reason:)` for diagnostic logging.
     static func structuralDivergence(_ a: XD, _ b: XD) -> String? {
         if a.width != b.width || a.height != b.height {
             return "dims old=\(a.width)x\(a.height) new=\(b.width)x\(b.height)"
         }
         for row in 0..<a.height {
             for col in 0..<a.width {
                 switch (a.cells[row][col], b.cells[row][col]) {
                 case (.block, .block):
                     continue
                 case let (.open(left, _, _), .open(right, _, _)):
                     if left != right {
                         return "cell(r=\(row),c=\(col)) old=\(left ?? "nil") new=\(right ?? "nil")"
                     }
                 case (.block, .open):
                     return "cell(r=\(row),c=\(col)) old=block new=open"
                 case (.open, .block):
                     return "cell(r=\(row),c=\(col)) old=open new=block"
                 }
             }
         }
         return nil
     }
 }