crossmate

GameArchiver.swift (53790B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Shares one asynchronous operation among overlapping callers for the same
 /// key. Main-actor isolation makes the lookup-and-install atomic even though
 /// the operation itself can suspend.
 @MainActor
 final class AsyncTaskCoalescer<Key: Hashable, Value: Sendable> {
     private var tasks: [Key: Task<Value, Never>] = [:]
 
     func run(
         for key: Key,
         operation: @MainActor @Sendable @escaping () async -> Value
     ) async -> Value {
         if let task = tasks[key] {
             return await task.value
         }
 
         let task = Task { @MainActor in
             await operation()
         }
         tasks[key] = task
         let value = await task.value
         tasks[key] = nil
         return value
     }
 
     /// Waits only when work for `key` is already under way. Used by cleanup
     /// that must not race the materialization it follows.
     func waitForCurrentTask(for key: Key) async {
         guard let task = tasks[key] else { return }
         _ = await task.value
     }
 }
 
 enum CompletedMetadataPageWalker {
     struct Result<Item, Cursor> {
         let selected: [Item]
         let buffered: [Item]
         let cursor: Cursor?
     }
 
     /// Walks ordered metadata pages until the first item outside the initial
     /// date window. Passing the returned cursor into every subsequent fetch is
     /// the invariant that prevents page one from being re-read indefinitely.
     @MainActor
     static func recent<Item, Cursor>(
         cutoff: Date,
         completedAt: (Item) -> Date,
         fetch: @MainActor (Cursor?) async throws -> (
             records: [Item],
             cursor: Cursor?
         )
     ) async rethrows -> Result<Item, Cursor> {
         var cursor: Cursor?
         var selected: [Item] = []
         var buffered: [Item] = []
         repeat {
             let page = try await fetch(cursor)
             cursor = page.cursor
             if let firstOlder = page.records.firstIndex(where: {
                 completedAt($0) < cutoff
             }) {
                 selected.append(contentsOf: page.records[..<firstOlder])
                 buffered.append(contentsOf: page.records[firstOlder...])
                 break
             }
             selected.append(contentsOf: page.records)
         } while cursor != nil
         return Result(selected: selected, buffered: buffered, cursor: cursor)
     }
 }
 
 /// Compacts completed games into the account's private archive zone and retires
 /// their multi-record live zones once every participant has archived, or once
 /// the hard retention deadline expires.
 @MainActor
 final class GameArchiver {
     nonisolated static let archiveRetryWindow: TimeInterval = 14 * 24 * 60 * 60
     nonisolated static let completedPageSize = 7
 
     /// Payload reads allowed per ledger backfill run. A typical Chronicle is
     /// tens of kilobytes, so this is a modest download for a library that has
     /// never been indexed, and a long history simply converges over a few
     /// launches instead of one long run.
     nonisolated static let chronicleLedgerBackfillLimit = 50
 
     struct CompletedPage: Sendable {
         let oldestCompletedAt: Date?
         let hasMore: Bool
     }
 
     private enum CompletedSource {
         case chronicle(CKRecord.ID)
         case game(
             gameID: UUID,
             zoneID: CKRecordZone.ID,
             scope: DatabaseScope
         )
     }
 
     private struct CompletedMetadata {
         let originalGameID: UUID
         let completedAt: Date
         let source: CompletedSource
 
         var isLiveGame: Bool {
             if case .game = source { return true }
             return false
         }
     }
 
     private struct LocalGame {
         let snapshot: Archive.Snapshot
         let databaseScope: DatabaseScope
         let liveZoneID: CKRecordZone.ID
         let isShared: Bool
         /// nil means the owner has not received an authoritative CKShare roster
         /// yet. An empty set is a known solo/no-participant game.
         let acceptedParticipants: Set<String>?
         let archiveAcknowledgedAt: Date?
     }
 
     private struct StoredArchive {
         let payload: Archive.Payload
         let isLegacy: Bool
     }
 
     private let container: CKContainer
     private let persistence: PersistenceController
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor?
     private let eventLog: EventLog?
     private let localIdentity: () -> (authorID: String, playerName: String)?
     private let localDefaults: UserDefaults
     private let ubiquitousStore: NSUbiquitousKeyValueStore?
     private var ensuredArchiveZone = false
     private var chronicleCursor: CKQueryOperation.Cursor?
     private var bufferedCompleted: [CompletedMetadata] = []
     private let revokedPromotionCoalescer = AsyncTaskCoalescer<UUID, UUID?>()
     private let revokedRetirementCoalescer = AsyncTaskCoalescer<UUID, Bool>()
 
     init(
         container: CKContainer,
         persistence: PersistenceController,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor? = nil,
         eventLog: EventLog? = nil,
         localIdentity: @escaping () -> (authorID: String, playerName: String)? = { nil },
         localDefaults: UserDefaults = .standard,
         ubiquitousStore: NSUbiquitousKeyValueStore? = .default
     ) {
         self.container = container
         self.persistence = persistence
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.eventLog = eventLog
         self.localIdentity = localIdentity
         self.localDefaults = localDefaults
         self.ubiquitousStore = ubiquitousStore
     }
 
     // MARK: - Reconciliation
 
     /// Immediate completion path. It writes/refreshes the archive and emits a
     /// participant acknowledgement, but leaves zone retirement to the cold-
     /// launch reconciliation path so an open Success Panel is never replaced
     /// underneath the user.
     func archiveIfNeeded(gameID: UUID) async {
         guard let graceStart = await accountGraceStart() else { return }
         _ = await reconcileArchive(gameID: gameID, graceStart: graceStart)
     }
 
     /// Cold-launch backstop for new completions, migrations, acknowledgements,
     /// and owner-side zone retirement.
     func reconcileUnarchived() async {
         guard let graceStart = await accountGraceStart() else { return }
         await migrateMaterializedLegacyArchives()
 
         let ctx = persistence.container.newBackgroundContext()
         let ids: [UUID] = await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "completedAt != nil AND isAccessRevoked == NO " +
                     "AND isSupersededByChronicle == NO AND ckRecordName BEGINSWITH %@",
                 "game-"
             )
             return ((try? ctx.fetch(req)) ?? []).compactMap(\.id)
         }
         for id in ids {
             guard let result = await reconcileArchive(gameID: id, graceStart: graceStart),
                   result.local.databaseScope == .private
             else { continue }
             await retireOwnedGameIfEligible(
                 result.local,
                 snapshot: result.snapshot,
                 archiveComplete: result.complete,
                 graceStart: graceStart
             )
         }
     }
 
     /// Whether the Chronicle in CloudKit still says what this pass concluded.
     ///
     /// The journal comparison is deliberately limited to `.available`: only a
     /// complete Chronicle embeds journals, so a provisional one is always
     /// stored with an empty journal. Comparing that against the merged local
     /// history would report "missing" on every pass and re-upload the whole
     /// payload — a fetch, a replay query, and a compressed asset — for the
     /// entire multi-day waiting window, without ever changing what's stored.
     nonisolated static func chronicleNeedsWrite(
         stored: (
             isLegacy: Bool,
             formatVersion: Int,
             replayState: Archive.ReplayState,
             journalKeys: Set<JournalDeviceKey>
         )?,
         replayState: Archive.ReplayState,
         presentJournalKeys: Set<JournalDeviceKey>
     ) -> Bool {
         guard let stored else { return true }
         if stored.isLegacy { return true }
         if stored.formatVersion != Archive.currentPayloadFormatVersion { return true }
         if stored.replayState != replayState { return true }
         return replayState == .available
             && !presentJournalKeys.isSubset(of: stored.journalKeys)
     }
 
     nonisolated static func hasArchiveRetryExpired(
         completedAt: Date,
         graceStart: Date = .distantPast,
         now: Date = Date()
     ) -> Bool {
         now >= max(completedAt, graceStart).addingTimeInterval(archiveRetryWindow)
     }
 
     private func localGame(gameID: UUID) async -> LocalGame? {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first,
                   entity.completedAt != nil,
                   !entity.isAccessRevoked,
                   // A row its Chronicle already stands for has finished with
                   // this path: the archive is written, the zone retirement is
                   // enqueued, and all that remains is deleting the row once no
                   // `PuzzleView` still holds it.
                   !entity.isSupersededByChronicle,
                   entity.ckRecordName?.hasPrefix("game-") == true,
                   let snapshot = Archive.snapshot(forGameID: gameID, in: ctx)
             else { return nil }
 
             let scope = DatabaseScope(entityValue: entity.databaseScope)
             let isShared = entity.ckShareRecordName != nil || scope == .shared
             let participants: Set<String>?
             if !isShared {
                 participants = []
                 if entity.archiveParticipants == nil { entity.archiveParticipants = "" }
             } else if let encoded = entity.archiveParticipants {
                 participants = Set(encoded.split(separator: ",").map(String.init))
             } else if let encoded = entity.shareParticipants {
                 entity.archiveParticipants = encoded
                 participants = Set(encoded.split(separator: ",").map(String.init))
             } else {
                 participants = nil
             }
             if ctx.hasChanges { try? ctx.save() }
             return LocalGame(
                 snapshot: snapshot,
                 databaseScope: scope,
                 liveZoneID: CKRecordZone.ID(
                     zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)",
                     ownerName: entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
                 ),
                 isShared: isShared,
                 acceptedParticipants: participants,
                 archiveAcknowledgedAt: entity.archiveAcknowledgedAt
             )
         }
     }
 
     private func reconcileArchive(
         gameID: UUID,
         graceStart: Date
     ) async -> (local: LocalGame, snapshot: Archive.Snapshot, complete: Bool)? {
         guard let local = await localGame(gameID: gameID) else { return nil }
 
         let stored = await fetchArchive(originalGameID: gameID)
         // A complete compact Chronicle is authoritative: it was written only
         // after every expected device journal was present. Re-reading the live
         // replay cannot improve it and makes overlapping migration backstops
         // download the same Moves and Journal assets repeatedly.
         let storedComplete = stored.map {
             !$0.isLegacy && $0.payload.replayAvailable
         } ?? false
         let canSkipReplayFetch = storedComplete
             && stored?.payload.formatVersion == Archive.currentPayloadFormatVersion
         let fetch = canSkipReplayFetch
             ? nil
             : try? await syncEngine.fetchReplay(forGameID: gameID)
         var snapshot = local.snapshot
         if let stored { snapshot = Archive.merging(snapshot, peerJournals: stored.payload.journal) }
         if let fetch { snapshot = Archive.merging(snapshot, peerJournals: fetch.journals) }
 
         let present = Set(snapshot.journal.map(\.key))
         let fetchedMissing = fetch.map {
             $0.expectedDevices.subtracting(present).count
         }
         let fetchedComplete = fetchedMissing == 0
         // Only a compact payload's explicit flag is authoritative. Legacy
         // archives used archivedAt for both completeness and a timed best-effort
         // fallback, so they must be checked against the still-live zone again.
         let complete = storedComplete || fetchedComplete
         let replayState: Archive.ReplayState
         if complete {
             replayState = .available
         } else if case .waiting(let storedMissing) = stored?.payload.replayState {
             replayState = .waiting(missing: fetchedMissing ?? storedMissing)
         } else {
             // A failed first fetch cannot determine the exact count yet, but it
             // is still retryable rather than a retention fallback.
             replayState = .waiting(missing: fetchedMissing ?? 1)
         }
 
         let needsWrite = Self.chronicleNeedsWrite(
             stored: stored.map {
                 (
                     isLegacy: $0.isLegacy,
                     formatVersion: $0.payload.formatVersion,
                     replayState: $0.payload.replayState,
                     journalKeys: Set($0.payload.journal.map(\.key))
                 )
             },
             replayState: replayState,
             presentJournalKeys: present
         )
         if needsWrite {
             guard await write(snapshot, replayState: replayState) else { return nil }
         }
 
         if stored?.isLegacy == true {
             await syncEngine.enqueueDeleteLegacyArchiveZone(
                 Archive.legacyZoneID(forOriginalGameID: gameID)
             )
         }
 
         if complete {
             await markArchived(originalGameID: gameID)
             if local.databaseScope == .shared, local.archiveAcknowledgedAt == nil {
                 await acknowledgeChronicle(gameID: gameID)
             }
         }
         return (local, snapshot, complete)
     }
 
     // MARK: - Retirement
 
     private func retireOwnedGameIfEligible(
         _ local: LocalGame,
         snapshot: Archive.Snapshot,
         archiveComplete: Bool,
         graceStart: Date
     ) async {
         let expired = Self.hasArchiveRetryExpired(
             completedAt: snapshot.completedAt,
             graceStart: graceStart
         )
 
         var quorum = false
         if archiveComplete, let expected = local.acceptedParticipants {
             if expected.isEmpty {
                 quorum = true
             } else if let acknowledged = try? await syncEngine.fetchChronicleAcknowledgements(
                 forGameID: snapshot.originalGameID
             ) {
                 quorum = expected.isSubset(of: acknowledged)
             }
         }
         guard quorum || expired else { return }
 
         let keepReplay = quorum && archiveComplete
         if !keepReplay {
             syncMonitor?.note(
                 "archive \(snapshot.originalGameID.uuidString.prefix(8)): " +
                 "retention deadline reached; retiring without replay"
             )
             guard await write(snapshot, replayState: .unavailable) else { return }
         }
         guard let chronicleID = await promoteOwnedBeforeRetirement(
             snapshot,
             replayState: keepReplay ? .available : .unavailable
         ) else {
             return
         }
         // The puzzle may be open on this device — retirement is decided by a
         // cold-launch reconciliation pass that has no idea what is on screen.
         // Hand it over rather than letting the row vanish underneath: the
         // Chronicle is the same puzzle, so it takes the live game's place at
         // the top of the stack. A no-op when no stack is showing it.
         NotificationNavigationBroker.shared.replaceOpenGame(
             snapshot.originalGameID,
             with: chronicleID
         )
         await syncEngine.enqueueRetireOwnedGameZone(local.liveZoneID)
     }
 
     /// Materializes the Chronicle that replaces an owned game about to have its
     /// zone retired, returning the Chronicle's game id.
     ///
     /// The live row is taken out of the library but *not* deleted: deleting it
     /// under a mounted `PuzzleView` would strand that view on a dead
     /// `GameEntity`. `retireSupersededLiveRow` deletes it once no view can
     /// still hold it, exactly as the participant-side handover does.
     private func promoteOwnedBeforeRetirement(
         _ snapshot: Archive.Snapshot,
         replayState: Archive.ReplayState
     ) async -> UUID? {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let payload = Archive.payload(from: snapshot, replayState: replayState)
             guard let chronicle = Archive.materialize(payload, in: ctx),
                   let chronicleID = chronicle.id
             else { return nil }
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "id == %@", snapshot.originalGameID as CVarArg
             )
             req.fetchLimit = 1
             if let original = try? ctx.fetch(req).first {
                 original.isSupersededByChronicle = true
             }
             do {
                 if ctx.hasChanges { try ctx.save() }
                 return chronicleID
             } catch {
                 return nil
             }
         }
     }
 
     // MARK: - Acknowledgement
 
     private func acknowledgeChronicle(gameID: UUID) async {
         guard let identity = localIdentity() else { return }
         let enqueued = await syncEngine.enqueuePing(
             kind: .chronicled,
             gameID: gameID,
             authorID: identity.authorID,
             playerName: identity.playerName
         )
         guard enqueued else { return }
         let ctx = persistence.container.newBackgroundContext()
         await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first else { return }
             entity.archiveAcknowledgedAt = Date()
             try? ctx.save()
         }
     }
 
     private func markArchived(originalGameID: UUID) async {
         let ctx = persistence.container.newBackgroundContext()
         await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", originalGameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first else { return }
             if entity.archivedAt == nil { entity.archivedAt = Date() }
             entity.archiveGameID = Archive.archiveGameID(for: originalGameID)
             try? ctx.save()
         }
     }
 
     // MARK: - Restore / legacy migration
 
     /// Rebuilds a completed game after another owner device retired its live
     /// zone and the sync applier removed the local live row first, returning the
     /// Chronicle's game id so an open puzzle can be handed over to it.
     ///
     /// Unlike `promoteRevoked` this does not insist on a complete replay. That
     /// guard exists to keep a half-filled grid from being frozen while the user
     /// still has a revoked row to look at; here the live row is already gone, so
     /// whatever the account chronicled is the only representation left.
     @discardableResult
     func restoreRetired(gameID: UUID) async -> UUID? {
         guard let stored = await fetchArchive(originalGameID: gameID) else { return nil }
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             guard let chronicle = Archive.materialize(stored.payload, in: ctx),
                   let chronicleID = chronicle.id
             else { return nil }
             do {
                 if ctx.hasChanges { try ctx.save() }
                 return chronicleID
             } catch {
                 return nil
             }
         }
     }
 
     /// Sweeps every finished game whose live zone has gone, promoting a newly
     /// revoked one to its Chronicle, and returns every live row a Chronicle now
     /// stands for — the ones just promoted and any earlier handover still
     /// waiting on the puzzle that held it. Catches up a revocation the app never
     /// got to act on because it was terminated, one whose Chronicle could not be
     /// read at the time, and an owner-side retirement whose row outlived the
     /// puzzle it was handed over from.
     func sweepSupersededLiveGames() async -> [UUID] {
         let ctx = persistence.container.newBackgroundContext()
         let (revoked, superseded): ([UUID], [UUID]) = await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "completedAt != nil AND ckRecordName BEGINSWITH %@ " +
                     "AND (isAccessRevoked == YES OR isSupersededByChronicle == YES)",
                 "game-"
             )
             let rows = (try? ctx.fetch(req)) ?? []
             return (
                 rows.filter { !$0.isSupersededByChronicle }.compactMap(\.id),
                 rows.filter(\.isSupersededByChronicle).compactMap(\.id)
             )
         }
         // Already-superseded rows skip promotion: they have their Chronicle,
         // and re-materializing it would cost a CloudKit read per list opening.
         var retirable = superseded
         for id in revoked {
             if await promoteRevoked(gameID: id) != nil {
                 retirable.append(id)
             }
         }
         return retirable
     }
 
     /// Promotes a participant's private archive when the owner retires the live
     /// shared zone, returning the Chronicle's game id when the handover lands.
     ///
     /// Only a *complete* history earns the handover. The owner normally retires
     /// the zone on quorum — every participant having chronicled the game, which
     /// each only does once its own Chronicle saved complete — but it also retires
     /// unconditionally once `archiveRetryWindow` has passed since completion. A
     /// device that was away for that whole stretch can reach here holding a grid
     /// that never caught up, and `Archive.merging` fills a Chronicle's frozen
     /// cells from the local rows alone: peer journals extend the replay, never
     /// the board. Freezing that would present a half-filled grid as a finished
     /// puzzle, with the zone gone and no way back. Those stay revoked rows, a
     /// state the user is actually shown.
     ///
     /// Overlapping callers share one promotion. This matters when the revocation
     /// callback is suspended in CloudKit and the user returns to the Game List,
     /// whose catch-up sweep asks for the same promotion.
     ///
     /// Promotion never deletes the live row. It is hidden behind the Chronicle
     /// here, then retired separately once no mounted `PuzzleView` can still hold
     /// its `GameEntity`.
     @discardableResult
     func promoteRevoked(gameID: UUID) async -> UUID? {
         await revokedPromotionCoalescer.run(for: gameID) { [weak self] in
             guard let self else { return nil }
             return await self.performPromoteRevoked(gameID: gameID)
         }
     }
 
     private func performPromoteRevoked(gameID: UUID) async -> UUID? {
         // A game this device never saw finish is a genuine mid-play revocation,
         // whatever the account's Chronicle says; leave it as a revoked row.
         let ctx = persistence.container.newBackgroundContext()
         let isCompleted = await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             return (try? ctx.fetch(req).first)?.completedAt != nil
         }
         guard isCompleted else { return nil }
 
         // The stored Chronicle is the only witness worth trusting. An
         // acknowledgement would seem to be a second one, but a device that read
         // a *sibling* device's complete Chronicle acknowledges too, without its
         // own cells ever catching up — so it attests to the account's history,
         // not this row's. And an acknowledgement implies a complete Chronicle
         // was written (`reconcileArchive` bails before acking if the write
         // fails), so reading it back costs nothing but a retry when offline.
         guard let payload = await fetchArchive(originalGameID: gameID)?.payload,
               payload.replayState == .available
         else {
             syncMonitor?.note(
                 "archive \(gameID.uuidString.prefix(8)): no complete Chronicle to " +
                 "hand over to; staying revoked"
             )
             return nil
         }
 
         let promoteCtx = persistence.container.newBackgroundContext()
         return await promoteCtx.perform {
             guard let chronicle = Archive.materialize(payload, in: promoteCtx),
                   let chronicleID = chronicle.id
             else { return nil }
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             if let original = try? promoteCtx.fetch(req).first {
                 // Keep the row for any mounted view to finish with, but take it
                 // out of the library now: the Chronicle is already the visible
                 // representation, and they share a list identity.
                 original.isSupersededByChronicle = true
             }
             if promoteCtx.hasChanges {
                 do {
                     try promoteCtx.save()
                 } catch {
                     return nil
                 }
             }
             return chronicleID
         }
     }
 
     /// Deletes a live row its Chronicle has replaced — whether by a participant
     /// revocation or an owner-side zone retirement — once that Chronicle is
     /// durable and any in-flight promotion has finished. Calling this from
     /// `PuzzleView`'s disappearance is what makes deletion safe for an
     /// open-puzzle handover; off-screen callers can invoke it immediately after
     /// promotion.
     @discardableResult
     func retireSupersededLiveRow(gameID: UUID) async -> Bool {
         await revokedPromotionCoalescer.waitForCurrentTask(for: gameID)
         return await revokedRetirementCoalescer.run(for: gameID) { [weak self] in
             guard let self else { return false }
             return await self.performRetireSupersededLiveRow(gameID: gameID)
         }
     }
 
     private func performRetireSupersededLiveRow(gameID: UUID) async -> Bool {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let chronicleReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             chronicleReq.predicate = NSPredicate(
                 format: "id == %@ AND replayCacheComplete == YES",
                 Archive.archiveGameID(for: gameID) as CVarArg
             )
             chronicleReq.fetchLimit = 1
             guard (try? ctx.fetch(chronicleReq).first) != nil else { return false }
 
             let liveReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             liveReq.predicate = NSPredicate(
                 format: "id == %@ AND ckRecordName BEGINSWITH %@ " +
                     "AND (isAccessRevoked == YES OR isSupersededByChronicle == YES)",
                 gameID as CVarArg,
                 "game-"
             )
             liveReq.fetchLimit = 1
             guard let live = try? ctx.fetch(liveReq).first else { return true }
             ctx.delete(live)
             do {
                 try ctx.save()
                 return true
             } catch {
                 return false
             }
         }
     }
 
     private func migrateMaterializedLegacyArchives() async {
         let ctx = persistence.container.newBackgroundContext()
         let candidates: [(localID: UUID, originalID: UUID)] = await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "ckRecordName BEGINSWITH %@", "archive-")
             return ((try? ctx.fetch(req)) ?? []).compactMap { entity in
                 guard let localID = entity.id,
                       entity.ckZoneName?.hasPrefix("archive-") == true,
                       let name = entity.ckRecordName,
                       let originalID = Archive.originalGameID(fromName: name)
                 else { return nil }
                 return (localID, originalID)
             }
         }
         for candidate in candidates {
             let snapshot: Archive.Snapshot? = await ctx.perform {
                 Archive.snapshot(
                     forGameID: candidate.localID,
                     originalGameID: candidate.originalID,
                     in: ctx
                 )
             }
             guard let snapshot,
                   await write(snapshot, replayState: .available)
             else { continue }
             await ctx.perform {
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(format: "id == %@", candidate.localID as CVarArg)
                 req.fetchLimit = 1
                 if let entity = try? ctx.fetch(req).first {
                     entity.ckRecordName = Archive.recordName(
                         forOriginalGameID: candidate.originalID
                     )
                     entity.ckZoneName = Archive.zoneName
                     try? ctx.save()
                 }
             }
             await syncEngine.enqueueDeleteLegacyArchiveZone(
                 Archive.legacyZoneID(forOriginalGameID: candidate.originalID)
             )
         }
     }
 
     // MARK: - CloudKit archive I/O
 
     /// Starts a fresh descending scan across Chronicle and completed Game
     /// records. Only scalar metadata is read while locating the initial
     /// seven-day window; full zones/assets are fetched for visible records.
     func loadRecentCompleted(since cutoff: Date) async -> CompletedPage {
         chronicleCursor = nil
         bufferedCompleted = []
 
         do {
             let walk = try await CompletedMetadataPageWalker.recent(
                 cutoff: cutoff,
                 completedAt: \.completedAt,
                 fetch: fetchChronicleMetadataPage(continuing:)
             )
             chronicleCursor = walk.cursor
             bufferedCompleted.append(contentsOf: walk.buffered)
 
             let gameMetadata = try await fetchCompletedGameMetadata()
             let recentGames = gameMetadata.filter { $0.completedAt >= cutoff }
             bufferedCompleted.append(
                 contentsOf: gameMetadata.filter { $0.completedAt < cutoff }
             )
             bufferedCompleted = mergedMetadata(bufferedCompleted)
 
             let selected = mergedMetadata(walk.selected + recentGames)
             await hydrateCompleted(selected)
             await trimMaterializedChronicles(before: cutoff)
             return CompletedPage(
                 oldestCompletedAt: selected.last?.completedAt,
                 hasMore: !bufferedCompleted.isEmpty || chronicleCursor != nil
             )
         } catch {
             syncMonitor?.recordError("load recent completed games", error)
             return CompletedPage(
                 oldestCompletedAt: nil,
                 hasMore: !bufferedCompleted.isEmpty || chronicleCursor != nil
             )
         }
     }
 
     /// Continues the metadata scan and hydrates the next available records,
     /// crossing arbitrarily large date gaps in one request.
     func loadMoreCompleted() async -> CompletedPage {
         do {
             while uniqueGameCount(in: bufferedCompleted) < Self.completedPageSize,
                   let cursor = chronicleCursor {
                 let page = try await fetchChronicleMetadataPage(
                     continuing: cursor
                 )
                 chronicleCursor = page.cursor
                 bufferedCompleted.append(contentsOf: page.records)
                 bufferedCompleted = mergedMetadata(bufferedCompleted)
             }
 
             let selected = Array(bufferedCompleted.prefix(Self.completedPageSize))
             let selectedIDs = Set(selected.map(\.originalGameID))
             bufferedCompleted.removeAll {
                 selectedIDs.contains($0.originalGameID)
             }
             await hydrateCompleted(selected)
             return CompletedPage(
                 oldestCompletedAt: selected.last?.completedAt,
                 hasMore: !bufferedCompleted.isEmpty || chronicleCursor != nil
             )
         } catch {
             syncMonitor?.recordError("load more completed games", error)
             return CompletedPage(
                 oldestCompletedAt: nil,
                 hasMore: !bufferedCompleted.isEmpty || chronicleCursor != nil
             )
         }
     }
 
     /// Brings `ChronicleLedgerEntity` into line with the archive zone, which is
     /// authoritative: rows whose Chronicle is gone are dropped, and archives
     /// this device has never decoded are read once so the browser's calendar
     /// can mark them.
     ///
     /// The walk is metadata only — record IDs and `completedAt`, 50 to a page —
     /// so reconciliation costs one query for a typical library. Only the
     /// backfill reads payloads, and it is capped per run: what it doesn't reach
     /// stays unknown and is picked up on the next launch, since each run
     /// re-derives the outstanding set rather than tracking a cursor.
     ///
     /// Deliberately walks its own cursor rather than the Game List's paging
     /// state: `chronicleCursor` and `bufferedCompleted` belong to Load More,
     /// and resetting them here would make the list re-read pages it has shown.
     func reconcileChronicleLedger() async {
         let identified: [(originalGameID: UUID, recordID: CKRecord.ID)]
         do {
             identified = try await allChronicleRecordIdentities()
         } catch {
             syncMonitor?.recordError("scan chronicle ledger", error)
             return
         }
 
         let present = Set(identified.map(\.originalGameID))
         let ctx = persistence.container.newBackgroundContext()
         let (known, removed): (Set<UUID>, Int) = await ctx.perform {
             let removed = ChronicleLedgerEntity.retainOnly(present, in: ctx)
             if ctx.hasChanges { try? ctx.save() }
             return (ChronicleLedgerEntity.knownOriginalGameIDs(in: ctx), removed)
         }
         if removed > 0 {
             eventLog?.note(
                 "GameArchiver: chronicle ledger dropped \(removed) stale entr" +
                 (removed == 1 ? "y" : "ies")
             )
         }
 
         let outstanding = identified.filter { !known.contains($0.originalGameID) }
         guard !outstanding.isEmpty else { return }
         let batch = Array(outstanding.prefix(Self.chronicleLedgerBackfillLimit))
         let written = await backfillChronicleLedger(batch.map(\.recordID))
         // Reported whether or not anything was written: a run that reads
         // payloads and records none is the signature of a decode that is
         // failing silently, and is otherwise invisible from the device.
         eventLog?.note(
             "GameArchiver: chronicle ledger backfilled \(written) of " +
             "\(batch.count) fetched; \(outstanding.count - batch.count) " +
             "remaining for a later launch",
             level: written < batch.count ? "error" : "info"
         )
     }
 
     /// Every Chronicle in the archive zone, metadata only.
     private func allChronicleRecordIdentities() async throws
         -> [(originalGameID: UUID, recordID: CKRecord.ID)] {
         var identities: [(originalGameID: UUID, recordID: CKRecord.ID)] = []
         var cursor: CKQueryOperation.Cursor?
         repeat {
             let page = try await fetchChronicleMetadataPage(continuing: cursor)
             cursor = page.cursor
             for item in page.records {
                 guard case .chronicle(let recordID) = item.source else { continue }
                 identities.append((item.originalGameID, recordID))
             }
         } while cursor != nil
         return identities
     }
 
     /// Reads payloads purely to learn which puzzle each archive holds. No
     /// `GameEntity` row is created: a Chronicle that isn't in the Game List's
     /// window has no business appearing in the library, and materialising it
     /// would only be undone by the next trim.
     @discardableResult
     private func backfillChronicleLedger(_ recordIDs: [CKRecord.ID]) async -> Int {
         guard !recordIDs.isEmpty else { return 0 }
         let database = container.privateCloudDatabase
         let result = try? await database.records(
             for: recordIDs,
             desiredKeys: Archive.payloadDesiredKeys
         )
         guard let result else { return 0 }
         let payloads = result.values.compactMap { item -> Archive.Payload? in
             guard let record = try? item.get() else { return nil }
             return Archive.payload(from: record)
         }
         guard !payloads.isEmpty else { return 0 }
 
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             for payload in payloads {
                 // An unparseable archive still earns its row: the decode has
                 // been paid for once, and without a row the backfill would
                 // fetch it again on every launch.
                 let puzzle = (try? XD.parse(payload.puzzleSource)).map(Puzzle.init(xd:))
                 ChronicleLedgerEntity.upsert(
                     originalGameID: payload.originalGameID,
                     publisher: puzzle?.publisher,
                     puzzleDate: puzzle?.date,
                     participants: payload.wasShared
                         ? payload.participants.map(\.authorID).sorted().joined(separator: ",")
                         : nil,
                     in: ctx
                 )
             }
             if ctx.hasChanges { try? ctx.save() }
             return payloads.count
         }
     }
 
     /// One-launch migration backstop for completed live zones that this device
     /// has never materialised. It begins only after the bounded Game List load
     /// has returned, so old payloads cannot delay or expand the initial list.
     /// Each fetched game is immediately compacted; later launches skip it
     /// because the retained live row is already local while retirement settles.
     func migrateMissingCompletedGames() async {
         do {
             let metadata = try await fetchCompletedGameMetadata()
             let ctx = persistence.container.newBackgroundContext()
             var localLiveIDs: Set<UUID> = await ctx.perform {
                 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 req.predicate = NSPredicate(
                     format: "completedAt != nil AND isAccessRevoked == NO " +
                         "AND ckRecordName BEGINSWITH %@",
                     "game-"
                 )
                 return Set(((try? ctx.fetch(req)) ?? []).compactMap(\.id))
             }
 
             for item in mergedMetadata(metadata) {
                 guard !localLiveIDs.contains(item.originalGameID),
                       case .game(let gameID, let zoneID, let scope) = item.source
                 else { continue }
                 do {
                     guard try await syncEngine.fetchCompletedGameDirect(
                         gameID: gameID,
                         zoneID: zoneID,
                         scope: scope
                     ) else { continue }
                     localLiveIDs.insert(gameID)
                     await archiveIfNeeded(gameID: gameID)
                 } catch {
                     syncMonitor?.recordError("migrate completed game", error)
                 }
             }
             await reconcileUnarchived()
         } catch {
             syncMonitor?.recordError("scan completed-game migration", error)
         }
     }
 
     private func fetchChronicleMetadataPage(
         continuing cursor: CKQueryOperation.Cursor? = nil
     ) async throws -> (records: [CompletedMetadata], cursor: CKQueryOperation.Cursor?) {
         let database = container.privateCloudDatabase
         let result: (matchResults: [(CKRecord.ID, Result<CKRecord, any Error>)], queryCursor: CKQueryOperation.Cursor?)
         if let cursor {
             result = try await database.records(
                 continuingMatchFrom: cursor,
                 desiredKeys: ["completedAt"],
                 resultsLimit: 50
             )
         } else {
             let query = CKQuery(recordType: Archive.recordType, predicate: NSPredicate(value: true))
             query.sortDescriptors = [NSSortDescriptor(key: "completedAt", ascending: false)]
             result = try await database.records(
                 matching: query,
                 inZoneWith: Archive.zoneID,
                 desiredKeys: ["completedAt"],
                 resultsLimit: 50
             )
         }
         let records = result.matchResults.compactMap { _, item -> CompletedMetadata? in
             guard let record = try? item.get(),
                   let originalGameID = Archive.originalGameID(
                     fromName: record.recordID.recordName
                   ),
                   let completedAt = record["completedAt"] as? Date
             else { return nil }
             return CompletedMetadata(
                 originalGameID: originalGameID,
                 completedAt: completedAt,
                 source: .chronicle(record.recordID)
             )
         }
         return (records, result.queryCursor)
     }
 
     private func fetchCompletedGameMetadata() async throws -> [CompletedMetadata] {
         async let privateMetadata = fetchCompletedGameMetadata(
             database: container.privateCloudDatabase,
             scope: .private
         )
         async let sharedMetadata = fetchCompletedGameMetadata(
             database: container.sharedCloudDatabase,
             scope: .shared
         )
         return try await privateMetadata + sharedMetadata
     }
 
     private func fetchCompletedGameMetadata(
         database: CKDatabase,
         scope: DatabaseScope
     ) async throws -> [CompletedMetadata] {
         let zoneIDs = try await database.allRecordZones()
             .map(\.zoneID)
             .filter { RecordSerializer.gameID(fromGameRecordName: $0.zoneName) != nil }
         let recordIDs = zoneIDs.map {
             CKRecord.ID(recordName: $0.zoneName, zoneID: $0)
         }
 
         var metadata: [CompletedMetadata] = []
         for start in stride(from: 0, to: recordIDs.count, by: 200) {
             let end = min(start + 200, recordIDs.count)
             let batch = Array(recordIDs[start..<end])
             let results = try await database.records(
                 for: batch,
                 desiredKeys: ["completedAt"]
             )
             for (recordID, result) in results {
                 guard let record = try? result.get(),
                       let gameID = RecordSerializer.gameID(
                         fromGameRecordName: recordID.recordName
                       ),
                       let completedAt = record["completedAt"] as? Date
                 else { continue }
                 metadata.append(CompletedMetadata(
                     originalGameID: gameID,
                     completedAt: completedAt,
                     source: .game(
                         gameID: gameID,
                         zoneID: recordID.zoneID,
                         scope: scope
                     )
                 ))
             }
         }
         return metadata
     }
 
     /// Collapses a live Game and Chronicle for the same original puzzle into
     /// one candidate. Chronicle is the canonical completed representation;
     /// the live row remains only for acknowledgement and zone retirement.
     private func mergedMetadata(
         _ metadata: [CompletedMetadata]
     ) -> [CompletedMetadata] {
         var byGameID: [UUID: CompletedMetadata] = [:]
         for item in metadata {
             if let existing = byGameID[item.originalGameID] {
                 if !item.isLiveGame && existing.isLiveGame {
                     byGameID[item.originalGameID] = item
                 }
             } else {
                 byGameID[item.originalGameID] = item
             }
         }
         return byGameID.values.sorted { lhs, rhs in
             if lhs.completedAt != rhs.completedAt {
                 return lhs.completedAt > rhs.completedAt
             }
             return lhs.originalGameID.uuidString < rhs.originalGameID.uuidString
         }
     }
 
     private func uniqueGameCount(in metadata: [CompletedMetadata]) -> Int {
         Set(metadata.map(\.originalGameID)).count
     }
 
     private func hydrateCompleted(_ metadata: [CompletedMetadata]) async {
         let chronicles = metadata.compactMap { item -> CKRecord.ID? in
             if case .chronicle(let recordID) = item.source { return recordID }
             return nil
         }
         await materializeChronicles(chronicles)
 
         for item in metadata {
             guard case .game(let gameID, let zoneID, let scope) = item.source
             else { continue }
             do {
                 _ = try await syncEngine.fetchCompletedGameDirect(
                     gameID: gameID,
                     zoneID: zoneID,
                     scope: scope
                 )
             } catch {
                 syncMonitor?.recordError("load completed game", error)
             }
         }
     }
 
     private func materializeChronicles(_ recordIDs: [CKRecord.ID]) async {
         guard !recordIDs.isEmpty else { return }
         let database = container.privateCloudDatabase
         let result = try? await database.records(
             for: recordIDs,
             desiredKeys: Archive.payloadDesiredKeys
         )
         guard let result else { return }
         let records = result.compactMap { _, item in try? item.get() }
         let ctx = persistence.container.newBackgroundContext()
         await ctx.perform {
             for record in records {
                 _ = self.syncEngine.applyPreferredArchiveRecord(record, in: ctx)
             }
             if ctx.hasChanges { try? ctx.save() }
         }
     }
 
     /// Evicts only rows materialized from Chronicle. Live completed games stay
     /// local until their archive/acknowledgement/retirement work has converged.
     private func trimMaterializedChronicles(before cutoff: Date) async {
         let ctx = persistence.container.newBackgroundContext()
         await ctx.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "completedAt < %@ AND ckRecordName BEGINSWITH %@",
                 cutoff as NSDate,
                 "chronicle-"
             )
             for game in (try? ctx.fetch(req)) ?? [] {
                 if let name = game.ckRecordName,
                    let originalID = Archive.originalGameID(fromName: name) {
                     let liveReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                     liveReq.predicate = NSPredicate(
                         format: "id == %@",
                         originalID as CVarArg
                     )
                     liveReq.fetchLimit = 1
                     (try? ctx.fetch(liveReq).first)?
                         .isSupersededByChronicle = false
                 }
                 ctx.delete(game)
             }
             if ctx.hasChanges { try? ctx.save() }
         }
     }
 
     private func fetchArchive(originalGameID: UUID) async -> StoredArchive? {
         let name = Archive.recordName(forOriginalGameID: originalGameID)
         let commonID = CKRecord.ID(recordName: name, zoneID: Archive.zoneID)
         if let record = try? await container.privateCloudDatabase.record(for: commonID),
            let payload = Archive.payload(from: record) {
             return StoredArchive(payload: payload, isLegacy: false)
         }
         let legacyID = CKRecord.ID(
             recordName: Archive.legacyRecordName(forOriginalGameID: originalGameID),
             zoneID: Archive.legacyZoneID(forOriginalGameID: originalGameID)
         )
         if let record = try? await container.privateCloudDatabase.record(for: legacyID),
            let payload = Archive.payload(from: record) {
             return StoredArchive(payload: payload, isLegacy: true)
         }
         return nil
     }
 
     @discardableResult
     private func write(
         _ snapshot: Archive.Snapshot,
         replayState: Archive.ReplayState
     ) async -> Bool {
         do {
             try await ensureArchiveZone()
             let package = try Archive.recordPackage(
                 from: snapshot,
                 replayState: replayState
             )
             defer { removeTemporaryArchiveFiles(package.temporaryAssetFileURLs) }
             try await save(package.record)
             return true
         } catch {
             syncMonitor?.recordError("archive game", error)
             eventLog?.note(
                 "GameArchiver: write deferred for \(snapshot.originalGameID.uuidString); " +
                 "will retry on cold launch — \(error)",
                 level: "error"
             )
             return false
         }
     }
 
     private func ensureArchiveZone() async throws {
         guard !ensuredArchiveZone else { return }
         do {
             try await createArchiveZone(Archive.zoneID)
         } catch {
             guard Self.isZoneAlreadyExists(error) else { throw error }
         }
         ensuredArchiveZone = true
     }
 
     private func createArchiveZone(_ zoneID: CKRecordZone.ID) async throws {
         try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
             let operation = CKModifyRecordZonesOperation(
                 recordZonesToSave: [CKRecordZone(zoneID: zoneID)],
                 recordZoneIDsToDelete: nil
             )
             operation.qualityOfService = .utility
             operation.modifyRecordZonesResultBlock = { continuation.resume(with: $0) }
             container.privateCloudDatabase.add(operation)
         }
     }
 
     private func save(_ record: CKRecord) async throws {
         try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
             let operation = CKModifyRecordsOperation(recordsToSave: [record], recordIDsToDelete: nil)
             operation.savePolicy = .allKeys
             operation.qualityOfService = .utility
             operation.modifyRecordsResultBlock = { continuation.resume(with: $0) }
             container.privateCloudDatabase.add(operation)
         }
     }
 
     private nonisolated static func isZoneAlreadyExists(_ error: Error) -> Bool {
         guard let ckError = error as? CKError else { return false }
         if ckError.code == .serverRejectedRequest {
             return ckError.localizedDescription.lowercased().contains("already exist")
         }
         if ckError.code == .partialFailure {
             return ckError.partialErrorsByItemID?.values.contains {
                 isZoneAlreadyExists($0)
             } ?? false
         }
         return false
     }
 
     private func removeTemporaryArchiveFiles(_ urls: [URL]) {
         for url in urls {
             do {
                 try FileManager.default.removeItem(at: url)
             } catch {
                 eventLog?.note(
                     "GameArchiver: failed to remove temporary archive asset " +
                     "\(url.lastPathComponent) — \(error)",
                     level: "error"
                 )
             }
         }
     }
 
     // MARK: - Account-wide migration grace
 
     private static let graceKey = "archiveGraceStart.v1.1.0"
 
     /// Uses ubiquitous key-value storage as an account-wide shared default,
     /// with an author-keyed local fallback for immediate reads and account
     /// switches. Devices continually publish the earliest value they have seen,
     /// so a delayed KVS update can postpone retirement but can never make the
     /// grace period shorter than the first v1.1.0 launch observed by a device.
     private func accountGraceStart() async -> Date? {
         guard let authorID = localIdentity()?.authorID, !authorID.isEmpty else { return nil }
         let localKey = "\(Self.graceKey).\(authorID)"
         ubiquitousStore?.synchronize()
         let localValue = localDefaults.object(forKey: localKey) as? Double
         let cloudValue = ubiquitousStore?.object(forKey: Self.graceKey) as? Double
         let earliest = [localValue, cloudValue].compactMap { $0 }.min()
             ?? Date().timeIntervalSince1970
         localDefaults.set(earliest, forKey: localKey)
         if cloudValue == nil || earliest < cloudValue! {
             ubiquitousStore?.set(earliest, forKey: Self.graceKey)
             ubiquitousStore?.synchronize()
         }
         return Date(timeIntervalSince1970: earliest)
     }
 }