crossmate

PersistenceController.swift (18144B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Wraps the app's `NSPersistentContainer`. Plain Core Data with no
 /// CloudKit mirroring — sync (single-user iPhone↔iPad and CKShare
 /// collaboration alike) is the job of a separate sync engine that will
 /// drive CloudKit directly on top of this same store. See PLAN.md for the
 /// layered design.
 @MainActor
 final class PersistenceController {
     let container: NSPersistentContainer
 
     var viewContext: NSManagedObjectContext { container.viewContext }
 
     let eventLog: EventLog?
 
     init(inMemory: Bool = false, storeURL: URL? = nil, eventLog: EventLog? = nil) {
         self.eventLog = eventLog
         container = NSPersistentContainer(
             name: "CrossmateModel",
             managedObjectModel: Self.sharedModel
         )
 
         if inMemory {
             // NSInMemoryStoreType keeps each store fully isolated in process
             // memory with no file involvement, which prevents concurrent test
             // runs from colliding through shared SQLite WAL files at /dev/null.
             let description = NSPersistentStoreDescription()
             description.type = NSInMemoryStoreType
             container.persistentStoreDescriptions = [description]
         } else {
             // The app always uses the container's default location; tests
             // point the store at a throwaway URL to exercise the on-disk
             // load/recovery path without touching real data.
             if let storeURL {
                 container.persistentStoreDescriptions = [
                     NSPersistentStoreDescription(url: storeURL)
                 ]
             }
             // Enable lightweight migration so additive schema changes — and
             // attribute renames carrying a `renamingIdentifier` in the model
             // — apply on launch without a hand-written mapping. A non-additive
             // change made in place (no prior model version kept as a migration
             // source) can't be inferred; `recreateStore(after:)` handles that
             // by discarding and rebuilding the store.
             for description in container.persistentStoreDescriptions {
                 description.shouldMigrateStoreAutomatically = true
                 description.shouldInferMappingModelAutomatically = true
             }
         }
 
         container.loadPersistentStores { [self] _, error in
             guard let error else { return }
             if inMemory {
                 fatalError("Failed to load in-memory Core Data store: \(error)")
             }
             recreateStore(after: error)
         }
 
         container.viewContext.automaticallyMergesChangesFromParent = true
         container.viewContext.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
 
         if !inMemory {
             // Synchronous, unlike the backfill below: a stranded row shadows
             // the real game in every `id`-keyed lookup, so leaving a window
             // where the library is live but the heal hasn't landed means the
             // user can still open the broken row on this launch.
             healStrandedSharedGameRows_v1()
             backfillZoneIdentityFields()
             backfillCachedSummaryFields()
         }
     }
 
     /// Rebuilds the store empty when an existing one can't be opened against
     /// the current model — e.g. after an in-place schema change with no
     /// migration source. The store is *usually* a rebuildable cache of CloudKit
     /// (the sync engine refetches every record on the next sync), but not
     /// always: iCloud sync is user-toggleable, making the local store the only
     /// copy of that user's games, and even with sync on, offline edits may not
     /// have uploaded yet. The failing files are therefore moved aside under a
     /// `.broken-<timestamp>` suffix rather than destroyed, so the data stays
     /// inspectable and recoverable, and the recovery is surfaced through
     /// diagnostics.
     private func recreateStore(after originalError: Error) {
         let coordinator = container.persistentStoreCoordinator
         var preserved: [String] = []
         for description in container.persistentStoreDescriptions {
             guard let url = description.url else { continue }
             preserved.append(contentsOf: preserveBrokenStore(at: url))
             do {
                 try coordinator.destroyPersistentStore(
                     at: url,
                     ofType: description.type,
                     options: description.options
                 )
             } catch {
                 // Best effort — fall through and let the reload attempt report
                 // the real failure if the store truly can't be replaced.
             }
         }
         container.loadPersistentStores { _, retryError in
             if let retryError {
                 fatalError(
                     "Failed to load Core Data store after reset: \(retryError) "
                     + "(original open error: \(originalError))"
                 )
             }
         }
         eventLog?.note(
             "PersistenceController: store load failed; rebuilt empty"
             + (preserved.isEmpty
                 ? " (no files to preserve)"
                 : " (broken store preserved as \(preserved.joined(separator: ", ")))")
             + " — \(originalError)",
             level: "error"
         )
     }
 
     /// Moves the failing store's files (including the `-wal`/`-shm` sidecars)
     /// aside before destructive recovery, returning the names of the files it
     /// preserved. Best effort: a file that can't be moved is left in place for
     /// `destroyPersistentStore` to clear, so recovery always proceeds.
     private func preserveBrokenStore(at url: URL) -> [String] {
         let fileManager = FileManager.default
         let formatter = DateFormatter()
         formatter.dateFormat = "yyyyMMdd-HHmmss"
         formatter.timeZone = TimeZone(secondsFromGMT: 0)
         let timestamp = formatter.string(from: Date())
         var preserved: [String] = []
         for suffix in ["", "-wal", "-shm"] {
             let source = URL(fileURLWithPath: url.path + suffix)
             guard fileManager.fileExists(atPath: source.path) else { continue }
             let destination = URL(fileURLWithPath: source.path + ".broken-\(timestamp)")
             do {
                 try fileManager.moveItem(at: source, to: destination)
                 preserved.append(destination.lastPathComponent)
             } catch {
                 // Leave the file for destroyPersistentStore.
             }
         }
         return preserved
     }
 
     // MARK: - TEMPORARY v1.1 MIGRATION
 
     /// Repairs `GameEntity` rows stranded by the sync-engine scope bug: while
     /// `SyncEngine.handleEvent` resolved an engine's database by instance
     /// identity, a fetch still in flight from an engine that `resetSyncState`
     /// had just replaced (the account-switch and v4-container purges both
     /// replace both engines) resolved to *shared*. The private database's zone
     /// changes then ran the shared branch, which seats a "Joining…" placeholder
     /// for every newly-visible zone — so every game the user owned got a
     /// `databaseScope == 1` row carrying the owner placeholder.
     ///
     /// Neither scope's `gameIdentityPredicate` can match that row again
     /// (private wants `ckZoneOwnerName == NIL`, shared wants a concrete owner),
     /// so the arriving Game record forked a second row instead of filling this
     /// one in. Two rows then answered to one `id`, and the `fetchLimit = 1`
     /// lookups in `GameStore.loadGame(id:)` and `movesDiagnostics(for:by:)`
     /// picked between them unpredictably — an empty row reads as
     /// `.missingGrid`, surfacing as "Couldn't load puzzle".
     ///
     /// Only empty placeholders are touched: a stranded row that carries a
     /// puzzle is not this bug's work and is left alone. A row with a sibling is
     /// merged into it and deleted; a row without one is repaired to private
     /// scope, which is always right here — the branch that produced these rows
     /// only ever ran over zones the user owns — so the ordinary private sync
     /// path adopts and fills it.
     ///
     /// Gated on a stored flag rather than left to its predicate: unlike the
     /// non-destructive backfills below this one deletes rows, and a standing
     /// destructive sweep would be a hazard if some later change ever made this
     /// row shape legitimate. Remove as one block with
     /// `strandedSharedRowHealKey`, its call site, and
     /// `PersistenceControllerHealTests`.
     private static let strandedSharedRowHealKey = "healStrandedSharedGameRows_v1"
 
     func healStrandedSharedGameRows_v1(force: Bool = false) {
         let defaults = UserDefaults.standard
         if !force, defaults.bool(forKey: Self.strandedSharedRowHealKey) { return }
 
         let ctx = container.newBackgroundContext()
         ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
         let summary: String? = ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             // `CKCurrentUserDefaultName` is the spelling the placeholder branch
             // copied off the private zone; nil covers the same shape from
             // `constructJoinedGame`'s former owner-normalising ternary.
             req.predicate = NSPredicate(
                 format: "databaseScope == 1"
                     + " AND (ckZoneOwnerName == nil OR ckZoneOwnerName == %@)"
                     + " AND (puzzleSource == nil OR puzzleSource == %@)",
                 CKCurrentUserDefaultName,
                 ""
             )
             guard let stranded = try? ctx.fetch(req), !stranded.isEmpty else { return nil }
 
             var merged = 0
             var repaired = 0
             for row in stranded {
                 guard let id = row.id else {
                     // No domain identity, no puzzle, unmatchable by sync: inert.
                     ctx.delete(row)
                     merged += 1
                     continue
                 }
                 let siblings = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 siblings.predicate = NSPredicate(
                     format: "id == %@ AND SELF != %@", id as CVarArg, row
                 )
                 siblings.fetchLimit = 1
                 if let survivor = try? ctx.fetch(siblings).first {
                     Self.adoptChildren(of: row, into: survivor, in: ctx)
                     ctx.delete(row)
                     merged += 1
                 } else {
                     row.databaseScope = 0
                     row.ckZoneOwnerName = nil
                     repaired += 1
                 }
             }
 
             guard ctx.hasChanges else { return nil }
             do {
                 try ctx.save()
                 return "PersistenceController: healed \(stranded.count) stranded shared "
                     + "game row(s) — \(merged) merged, \(repaired) repaired to private"
             } catch {
                 return "PersistenceController: stranded-row heal save failed — \(error)"
             }
         }
 
         // `force` is the test affordance for driving the pass repeatedly; it
         // deliberately leaves the shared flag untouched so tests stay hermetic.
         if !force { defaults.set(true, forKey: Self.strandedSharedRowHealKey) }
         if let summary { eventLog?.note(summary) }
     }
 
     /// Moves a stranded row's irreplaceable children onto the surviving row.
     ///
     /// `moves` and `journal` are the synced/durable payload and `players`
     /// carries local read state, so they are reparented — skipping any whose
     /// counterpart the survivor already holds, since both rows may have been
     /// written from the same records. `cells` and `peerChanges` are derived
     /// caches (replay rebuilds one, the next ledger build the other), so they
     /// are left to cascade with the deleted row.
     private nonisolated static func adoptChildren(
         of row: GameEntity,
         into survivor: GameEntity,
         in ctx: NSManagedObjectContext
     ) {
         let existingMoves = Set(
             ((survivor.moves as? Set<MovesEntity>) ?? []).compactMap(\.ckRecordName)
         )
         for child in (row.moves as? Set<MovesEntity>) ?? [] {
             guard let name = child.ckRecordName, !existingMoves.contains(name) else {
                 ctx.delete(child)
                 continue
             }
             child.game = survivor
         }
 
         let existingPlayers = Set(
             ((survivor.players as? Set<PlayerEntity>) ?? []).compactMap(\.ckRecordName)
         )
         for child in (row.players as? Set<PlayerEntity>) ?? [] {
             guard let name = child.ckRecordName, !existingPlayers.contains(name) else {
                 ctx.delete(child)
                 continue
             }
             child.game = survivor
         }
 
         // Journal rows have no record name; a device's log is keyed by its
         // source device and sequence number.
         let existingJournal = Set(
             ((survivor.journal as? Set<JournalEntity>) ?? []).map {
                 "\($0.sourceDeviceID ?? "")|\($0.seq)"
             }
         )
         for child in (row.journal as? Set<JournalEntity>) ?? [] {
             let key = "\(child.sourceDeviceID ?? "")|\(child.seq)"
             guard !existingJournal.contains(key) else {
                 ctx.delete(child)
                 continue
             }
             child.game = survivor
         }
     }
 
     // MARK: - Backfill
 
     /// Populates the derived summary columns on rows that never got them.
     ///
     /// Chronicles materialized before `Archive.materialize` populated these
     /// are the population that matters: `GameSummary` papers over the gap by
     /// reparsing `puzzleSource`, but anything that queries the columns
     /// directly — the browser's "already in your library" lookup — simply
     /// can't see those rows.
     ///
     /// Self-limiting rather than flag-gated: a populated row no longer matches
     /// `gridWidth == 0`. A row whose source won't parse stays unmatched and is
     /// retried on later launches, which is the right outcome for the handful
     /// of rows that could be in that state.
     private func backfillCachedSummaryFields() {
         let bg = container.newBackgroundContext()
         let eventLog = eventLog
         bg.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "gridWidth == 0 AND puzzleSource != nil AND puzzleSource != %@",
                 ""
             )
             guard let rows = try? bg.fetch(req), !rows.isEmpty else { return }
             for entity in rows {
                 guard let source = entity.puzzleSource,
                       let xd = try? XD.parse(source) else { continue }
                 entity.populateCachedSummaryFields(from: Puzzle(xd: xd))
             }
             guard bg.hasChanges else { return }
             do {
                 try bg.save()
             } catch {
                 Task { @MainActor in
                     eventLog?.note(
                         "PersistenceController: backfillCachedSummaryFields save failed — \(error)",
                         level: "error"
                     )
                 }
             }
         }
     }
 
     /// One-shot pass for `GameEntity` rows written before inbound lookups
     /// matched on full zone identity (`RecordSerializer.gameIdentityPredicate`).
     /// Without it, a legacy row is invisible to the new predicate and the next
     /// fetched record silently spawns a duplicate. Two normalizations:
     /// a missing `ckZoneName` is derived from `ckRecordName` (game zone and
     /// record share the `game-<UUID>` spelling), and `ckZoneOwnerName` is
     /// cleared on private-scope rows — private zones always belong to the
     /// current user and are matched as `ckZoneOwnerName == NIL`, but rows
     /// written before that invariant could hold a concrete user-record ID
     /// when CloudKit round-tripped one instead of the owner placeholder.
     /// No-ops on every subsequent launch.
     private func backfillZoneIdentityFields() {
         let bg = container.newBackgroundContext()
         let eventLog = eventLog
         bg.perform {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "(ckRecordName != nil AND ckZoneName == nil) "
                     + "OR (databaseScope == 0 AND ckZoneOwnerName != nil)"
             )
             guard let rows = try? bg.fetch(req), !rows.isEmpty else { return }
             for entity in rows {
                 if entity.ckZoneName == nil {
                     entity.ckZoneName = entity.ckRecordName
                 }
                 if entity.databaseScope == 0 {
                     entity.ckZoneOwnerName = nil
                 }
             }
             if bg.hasChanges {
                 do {
                     try bg.save()
                 } catch {
                     Task { @MainActor in
                         eventLog?.note(
                             "PersistenceController: backfillZoneIdentityFields save failed — \(error)",
                             level: "error"
                         )
                     }
                 }
             }
         }
     }
 
     // Loaded once and shared across all container instances so that entity
     // descriptions are identical objects, which is required for CoreData
     // relationship type-checking to pass when tests create multiple containers
     // concurrently.
     private static let sharedModel: NSManagedObjectModel = {
         for bundle in Bundle.allBundles + Bundle.allFrameworks {
             if let url = bundle.url(forResource: "CrossmateModel", withExtension: "momd"),
                let model = NSManagedObjectModel(contentsOf: url) {
                 return model
             }
         }
         fatalError("CrossmateModel.momd not found in any loaded bundle")
     }()
 }