crossmate

ReplayLoader.swift (6204B)

---

 import Foundation
 
 /// Loads finished-game replays and caches their assembled timelines for the
 /// session, extracted from `AppServices`. A finished game's journals are
 /// frozen, so a fully-merged timeline never changes once built.
 @MainActor
 final class ReplayLoader {
     private let store: GameStore
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor
 
     init(store: GameStore, syncEngine: SyncEngine, syncMonitor: SyncMonitor) {
         self.store = store
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
     }
 
     /// Assembled replay timelines, keyed by game. A finished game's journals are
     /// frozen (edit-lockout), so its timeline never changes once built — caching
     /// it here lets a `ReplayControls` instance recreated by rapid
     /// finish-banner nav re-entry skip re-running `ReplayAssembler.assemble`.
     /// Only `.ready` results land here; `.waiting`/`.unavailable` stay retryable.
     private var replayTimelineCache: [UUID: ReplayTimeline] = [:]
 
     /// A previously assembled timeline for `gameID`, if one was cached this
     /// session.
     func cachedReplayTimeline(gameID: UUID) -> ReplayTimeline? {
         replayTimelineCache[gameID]
     }
 
     /// Caches a fully assembled timeline so re-entry skips the re-merge. Safe
     /// because the caller only ever passes a finished game's `.ready` result,
     /// whose journals are frozen.
     func cacheReplayTimeline(_ timeline: ReplayTimeline, gameID: UUID) {
         replayTimelineCache[gameID] = timeline
     }
 
     /// Loads a finished game's replay: fetches every device's journal from
     /// CloudKit, overlays this device's live log, and gates on strict
     /// completeness. `.ready` carries a merged timeline; `.waiting(missing:)`
     /// means some contributing device hasn't uploaded its journal yet (the
     /// scrubber stays disabled until it does); `.unavailable` means the game's
     /// zone can't be reached. The fetch is a plain CKQuery, so it's safe to call
     /// from the UI when the finish banner appears.
     func loadReplay(gameID: UUID) async -> JournalReplayResult {
         let short = gameID.uuidString.prefix(8)
         func describe(_ result: JournalReplayResult) -> String {
             switch result {
             case .ready(let timeline): return "ready(steps=\(timeline.count))"
             case .waiting(let missing): return "waiting(missing=\(missing))"
             case .unavailable: return "unavailable"
             }
         }
         if let blocker = await store.archivedReplayBlocker(forGameID: gameID) {
             switch blocker {
             case .waiting(let missing):
                 syncMonitor.note(
                     "replay[\(short)]: Chronicle waiting for \(missing) device journal(s)"
                 )
             case .unavailable:
                 syncMonitor.note("replay[\(short)]: unavailable by archive retention policy")
             case .ready:
                 assertionFailure("A ready replay is not a blocker")
             }
             return blocker
         }
         // This device's live journal is always overlaid (fresher than any
         // uploaded copy of itself), whether the contributors' journals come
         // from the local cache or a fresh CloudKit fetch.
         let local = store.localReplaySource(gameID: gameID)
         let localKey = local?.key ?? JournalDeviceKey(authorID: "", deviceID: "")
         let localEntries = local?.entries ?? []
 
         // Completed-game journals are frozen (edit-lockout), so once every
         // contributor's journal has been fetched in full we cache the remote
         // ones locally and re-merge from Core Data — no CloudKit round-trip on
         // re-entry. The cache is `nil` until that first complete fetch lands.
         if let cachedRemotes = await store.cachedRemoteJournals(forGameID: gameID) {
             let result = ReplayAssembler.assemble(
                 fetch: JournalReplayFetch(
                     journals: cachedRemotes,
                     expectedDevices: Set(cachedRemotes.map(\.key))
                 ),
                 localKey: localKey,
                 localEntries: localEntries
             )
             syncMonitor.note(
                 "replay[\(short)]: served from cache — remoteDevices=\(cachedRemotes.count), " +
                 "localEntries=\(localEntries.count) → \(describe(result))"
             )
             return result
         }
 
         // A nil return means zone unknown / access revoked; a throw means the
         // on-demand CKQuery itself failed. Both flatten to `.unavailable`, but
         // log which one (and the error) so the diagnostics stream can tell them
         // apart — the replay fetch is otherwise invisible to the event log.
         let fetch: JournalReplayFetch?
         do {
             fetch = try await syncEngine.fetchReplay(forGameID: gameID)
         } catch {
             let ns = error as NSError
             syncMonitor.note(
                 "replay[\(short)]: fetch threw — domain=\(ns.domain) " +
                 "code=\(ns.code) \(ns.localizedDescription)"
             )
             return .unavailable
         }
         guard let fetch else {
             syncMonitor.note("replay[\(short)]: fetch unavailable (zone unknown / access revoked)")
             return .unavailable
         }
         let result = ReplayAssembler.assemble(
             fetch: fetch,
             localKey: localKey,
             localEntries: localEntries
         )
         // A complete merge will never change (the game is finished), so cache
         // the *remote* journals for offline re-entry. Our own copy is excluded:
         // the live local journal is overlaid fresh on every load.
         if case .ready = result {
             await store.cacheRemoteJournals(
                 fetch.journals.filter { $0.key != localKey },
                 forGameID: gameID
             )
         }
         syncMonitor.note(
             "replay[\(short)]: merged — expected=\(fetch.expectedDevices.count), " +
             "journals=\(fetch.journals.count), localEntries=\(localEntries.count) " +
             "→ \(describe(result))"
         )
         return result
     }
 }