crossmate

NYTPuzzleUpgrader.swift (7679B)

---

 import Foundation
 
 /// Re-fetches a NYT puzzle and runs the current `NYTToXDConverter` over it.
 /// Used when `XD.currentConverterVersion` 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 it is structurally the
 /// same puzzle. The verifier guards puzzle identity, not fill validity:
 /// geometry and single-letter solution diffs refuse the upgrade, while rebus
 /// fills deliberately defer to the fresh conversion (see
 /// `structuralDivergence`).
 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 advance the kept source's converter-version
         /// header but keep the old grid 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 its converter version 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.currentConverterVersion`. 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.converterVersion != XD.currentConverterVersion,
               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` advances the kept source's converter-version header via
     /// `stampConverterVersion` so `plan` stops re-fetching a permanently
     /// diverged puzzle 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.stampConverterVersion(for: plan.gameID)
         case .failed:
             break
         }
         return outcome
     }
 
     /// Two puzzles are structurally equivalent when their grids have the same
     /// dimensions and block layout, and the same solution at every open cell
     /// that isn't a rebus. The comparison guards puzzle *identity*, not fill
     /// validity: dimension or block changes would corrupt persisted move
     /// coordinates, and a single-letter solution diff can't plausibly come
     /// from a converter fix (that conversion is trivial), so it signals a
     /// different or edited puzzle and refuses the upgrade. Rebus cells are
     /// the opposite case — see `isRebusFill`. Special markers, accepted
     /// variants, clues, and headers may all differ.
     static func structurallyEquivalent(_ a: XD, _ b: XD) -> Bool {
         structuralDivergence(a, b) == nil
     }
 
     /// A rebus fill occupies a single square with a multi-character solution.
     /// Rebus representation is exactly where converter fixes land, so a diff
     /// here is presumed to be such a fix and defers to the fresh conversion —
     /// treating it as divergence would keep the broken conversion in place
     /// forever, the worse failure. The accepted cost: a genuine NYT content
     /// edit at a rebus square is indistinguishable in this diff, so it also
     /// replaces the answer under any existing fill, and a checked-right mark
     /// on that square stays stale until re-checked (marks live in synced move
     /// state, which `replacePuzzleSource` doesn't touch).
     private static func isRebusFill(_ solution: String?) -> Bool {
         (solution?.count ?? 0) > 1
     }
 
     /// 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, _, _)):
                     // A rebus fill on either side is presumed to be a
                     // converter fix — exempt it (see `isRebusFill`). Compare
                     // only single-letter cells.
                     if isRebusFill(left) || isRebusFill(right) { continue }
                     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
     }
 }