crossmate

PlayerRoster.swift (26008B)

---

 import CloudKit
 import CoreData
 import Foundation
 import Observation
 
 /// Observable view-model that represents all participants (local + remote)
 /// in a single shared game. Drives the "Players" menu in `PuzzleView`.
 @Observable
 @MainActor
 final class PlayerRoster {
 
     struct Entry: Equatable, Identifiable {
         let authorID: String
         let name: String
         let color: PlayerColor
         let isLocal: Bool
         var id: String { authorID }
     }
 
     struct RemoteSelection: Equatable {
         let authorID: String
         let row: Int
         let col: Int
         let direction: Puzzle.Direction
         let color: PlayerColor
         let updatedAt: Date
     }
 
     private struct RawSelection {
         let authorID: String
         let row: Int
         let col: Int
         let direction: Puzzle.Direction
         let updatedAt: Date
     }
 
     /// The Core Data snapshot read off the background context in `refresh()`.
     /// A struct rather than a tuple so the empty-game path, the populated
     /// return, and the consumers stay in sync by name rather than position.
     private struct FetchedRoster {
         /// The stable game identity used to seed collaborator colours. A
         /// materialized Chronicle has its own derived entity ID, but must keep
         /// using the original live game's ID or its palette changes at the
         /// live-game → Chronicle boundary.
         var colorGameID: UUID?
         var databaseScope: Int16 = 0
         var ckShareRecordName: String?
         var ckZoneName: String?
         var ckZoneOwnerName: String?
         var namesMap: [String: String] = [:]
         var playerAuthorIDs: [String] = []
         /// The user's private nicknames (`FriendEntity.nickname`), keyed by
         /// authorID. A nickname overrides the peer's own published name
         /// everywhere the roster surfaces it (players menu, cursor chips,
         /// presence traces).
         var nicknamesByAuthor: [String: String] = [:]
         var moveAuthorIDs: [String] = []
         var rawSelections: [RawSelection] = []
         var presenceUntilByAuthor: [String: Date] = [:]
         var finalSolveSeconds: Int64?
         var completedAt: Date?
         var timeLogs: [TimeLog] = []
     }
 
     /// Last-known peer cursor tracks keyed by `authorID`, from the synced
     /// Player record. Held unconditionally; visibility is decided at read time
     /// by the presence gate in `remoteSelections`. The local player is never
     /// present in this map.
     private var persistedRemoteSelections: [String: RemoteSelection] = [:]
 
     /// Each non-local peer's active-session lease (`Player.presenceUntil`). A cursor
     /// is shown only while its peer is present (`PeerPresence.isPresent`), so a
     /// peer who pauses keeps their cursor and a departed peer's cursor clears
     /// when the lease lapses — the same heuristic that gates engagement.
     private var remotePresenceUntil: [String: Date] = [:]
     private var finalSolveSeconds: Int64?
     private var completedAt: Date?
     private var timeLogs: [TimeLog] = []
 
     /// The non-local authorIDs whose lease last read as present, so each
     /// present↔absent edge is logged once rather than on every refresh. This
     /// is the same gate that shows/hides a peer's cursor, so the log records
     /// *when* a remote player actually left — the one thing a co-solve log was
     /// previously blind to.
     private var lastPresentAuthors: Set<String> = []
 
     var remoteSelections: [String: RemoteSelection] {
         var merged = persistedRemoteSelections
         let colorByAuthor = Dictionary(
             uniqueKeysWithValues: entries.filter { !$0.isLocal }.map { ($0.authorID, $0.color) }
         )
         for (authorID, engagement) in engagementStore.selections(for: gameID) {
             guard let color = colorByAuthor[authorID] else { continue }
             let selection = RemoteSelection(
                 authorID: authorID,
                 row: engagement.row,
                 col: engagement.col,
                 direction: engagement.direction,
                 color: color,
                 updatedAt: engagement.updatedAt
             )
             if merged[authorID].map({ $0.updatedAt <= selection.updatedAt }) ?? true {
                 merged[authorID] = selection
             }
         }
         let now = Date()
         return merged.filter { PeerPresence.isPresent(presenceUntil: remotePresenceUntil[$0.key], asOf: now) }
     }
 
     private(set) var entries: [Entry] = []
     private(set) var localAuthorID: String?
 
     /// Active solve time across every player in this game as of `now` — the
     /// length of the union of all devices' play intervals, so simultaneous
     /// co-solving counts once and disjoint play sums. In-progress sessions are
     /// extrapolated to `now`, so the puzzle clock ticks between syncs simply by
     /// re-reading this with a fresh date. Once the game is finished the union is
     /// bounded at `completedAt`, freezing the displayed value at the win.
     func solveTime(asOf now: Date = Date()) -> TimeInterval {
         guard !isStaticPreview else { return 0 }
         // A materialised archive has no `timeLog` rows to union — it carries the
         // frozen final time (whole seconds) the live clock reached.
         if let finalSolveSeconds {
             return TimeInterval(finalSolveSeconds)
         }
         let asOf = completedAt.map { min(now, $0) } ?? now
         return TimeLog.accumulatedSeconds(
             forLogs: timeLogs,
             localDeviceID: RecordSerializer.localDeviceID,
             asOf: asOf
         )
     }
 
     private let gameID: UUID
     private let authorIdentity: AuthorIdentity
     private let preferences: PlayerPreferences
     private let persistence: PersistenceController
     private let container: CKContainer
     private let engagementStore: EngagementStore
     private let tracer: (@MainActor @Sendable (String) -> Void)?
     private let isStaticPreview: Bool
 
     private var cachedShare: CKShare?
     private var observationTasks: [Task<Void, Never>] = []
     private var lastTracedSignature: String?
     private var refreshGeneration = 0
     /// One-shot recompute scheduled for the soonest peer lease expiry, so a
     /// departed peer's ghost cursor clears precisely when its lease lapses
     /// rather than waiting for an unrelated record to nudge a refresh.
     private var leaseExpiryTask: Task<Void, Never>?
 
     init(
         gameID: UUID,
         authorIdentity: AuthorIdentity,
         preferences: PlayerPreferences,
         persistence: PersistenceController,
         container: CKContainer,
         engagementStore: EngagementStore = EngagementStore(),
         tracer: (@MainActor @Sendable (String) -> Void)? = nil
     ) {
         self.gameID = gameID
         self.authorIdentity = authorIdentity
         self.preferences = preferences
         self.persistence = persistence
         self.container = container
         self.engagementStore = engagementStore
         self.tracer = tracer
         self.isStaticPreview = false
         startObserving()
     }
 
     #if DEBUG
     init(
         previewGameID gameID: UUID,
         localName: String,
         localColor: PlayerColor,
         remoteSelection: RemoteSelection?
     ) {
         self.gameID = gameID
         self.authorIdentity = AuthorIdentity(testing: "marketing-local")
         self.preferences = PlayerPreferences()
         self.persistence = PersistenceController(inMemory: true)
         self.container = CloudContainer.container
         self.engagementStore = EngagementStore()
         self.tracer = nil
         self.isStaticPreview = true
         self.localAuthorID = "marketing-local"
         var entries = [
             Entry(authorID: "marketing-local", name: localName, color: localColor, isLocal: true),
         ]
         if let remoteSelection {
             entries.append(Entry(
                 authorID: remoteSelection.authorID,
                 name: "Teammate",
                 color: remoteSelection.color,
                 isLocal: false
             ))
             self.persistedRemoteSelections = [remoteSelection.authorID: remoteSelection]
             self.remotePresenceUntil = [remoteSelection.authorID: Date().addingTimeInterval(600)]
         } else {
             self.persistedRemoteSelections = [:]
             self.remotePresenceUntil = [:]
         }
         self.entries = entries
     }
     #endif
 
     isolated deinit {
         for task in observationTasks {
             task.cancel()
         }
         leaseExpiryTask?.cancel()
     }
 
     // MARK: - Observation
 
     private func startObserving() {
         let gameID = self.gameID
 
         // Roster-relevant remote changes for this game — a peer's Player
         // record (name / cursor), a Game record, a deletion, or a new
         // contributor's first Moves row (see `BatchEffects.rosterRelevant`).
         // `refresh()` discovers participants from PlayerEntity, the CKShare,
         // and Moves authorIDs, so a brand-new collaborator surfaces here even
         // before their Player record arrives; repeat moves from a known author
         // don't post, since they add nothing to the roster. Invalidate the
         // cached share so the next refresh re-fetches it; participant lists
         // may have moved.
         observationTasks.append(
             Task { [weak self] in
                 for await note in NotificationCenter.default.notifications(
                     named: .playerRosterShouldRefresh
                 ) {
                     guard let self else { return }
                     guard let ids = note.userInfo?["gameIDs"] as? Set<UUID>,
                           ids.contains(gameID) else { continue }
                     self.cachedShare = nil
                     await self.refresh()
                 }
             }
         )
     }
 
     // MARK: - Refresh
 
     /// Loads the durable local roster without waiting on CKShare. Used before
     /// presenting a puzzle so returning to a game never briefly renders an
     /// empty Players list while CloudKit metadata is fetched.
     func preload() async {
         await refresh(includingShare: false)
     }
 
     func refresh() async {
         await refresh(includingShare: true)
     }
 
     private func refresh(includingShare: Bool) async {
         guard !isStaticPreview else { return }
         refreshGeneration += 1
         let generation = refreshGeneration
         // Without a known local authorID we can't classify any participant as
         // self vs. remote, so the only safe answer is an empty roster. The
         // next refresh (after AuthorIdentity populates) will do the real work.
         guard let localAuthorID = authorIdentity.currentID else {
             self.localAuthorID = nil
             entries = []
             persistedRemoteSelections = [:]
             remotePresenceUntil = [:]
             finalSolveSeconds = nil
             completedAt = nil
             timeLogs = []
             leaseExpiryTask?.cancel()
             leaseExpiryTask = nil
             return
         }
         self.localAuthorID = localAuthorID
 
         // Pull Core Data fields off a background context without blocking the
         // main actor: `await perform` hops to the context's queue and suspends
         // (vs. `performAndWait`, which stalls main until the fetch returns).
         let ctx = persistence.container.newBackgroundContext()
         let fetched = await ctx.perform { [gameID] () -> FetchedRoster in
             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 FetchedRoster()
             }
             let nameReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
             nameReq.predicate = NSPredicate(format: "game == %@", entity)
             let nameEntities = (try? ctx.fetch(nameReq)) ?? []
             var namesMap: [String: String] = [:]
             var playerAuthorIDs: [String] = []
             var selections: [RawSelection] = []
             var presenceUntilByAuthor: [String: Date] = [:]
             var timeLogs: [TimeLog] = []
             for nr in nameEntities {
                 timeLogs.append(TimeLog.decode(nr.timeLog))
                 guard let aid = nr.authorID, !aid.isEmpty else { continue }
                 playerAuthorIDs.append(aid)
                 if let name = nr.name, !name.isEmpty {
                     namesMap[aid] = name
                 }
                 if aid == localAuthorID { continue }
                 if let presenceUntil = nr.presenceUntil {
                     presenceUntilByAuthor[aid] = presenceUntil
                 }
                 if let row = nr.selRow,
                    let col = nr.selCol,
                    let dir = nr.selDir,
                    let direction = Puzzle.Direction(rawValue: dir.intValue),
                    let updatedAt = nr.updatedAt {
                     selections.append(RawSelection(
                         authorID: aid,
                         row: row.intValue,
                         col: col.intValue,
                         direction: direction,
                         updatedAt: updatedAt
                     ))
                 }
             }
             let movesReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
             movesReq.predicate = NSPredicate(format: "game == %@", entity)
             let movesEntities = (try? ctx.fetch(movesReq)) ?? []
             var contributorAuthorIDs = Set(movesEntities.compactMap(\.authorID))
             // Chronicles retain authorship in cached final cells and replay
             // journals rather than live Moves rows. Reading all three sources
             // also repairs projections materialised by the first Chronicle
             // build, which did not create Player rows.
             contributorAuthorIDs.formUnion(
                 ((entity.cells as? Set<CellEntity>) ?? [])
                     .compactMap(\.letterAuthorID)
             )
             contributorAuthorIDs.formUnion(
                 ((entity.journal as? Set<JournalEntity>) ?? [])
                     .compactMap(\.sourceAuthorID)
             )
             let authorIDs = Array(
                 contributorAuthorIDs
                     .subtracting([localAuthorID, CKCurrentUserDefaultName, ""])
             )
             let nicknameReq = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             nicknameReq.predicate = NSPredicate(
                 format: "isBlocked == NO AND nickname != nil AND nickname != %@", ""
             )
             var nicknamesByAuthor: [String: String] = [:]
             for friend in (try? ctx.fetch(nicknameReq)) ?? [] {
                 guard let aid = friend.authorID, !aid.isEmpty,
                       let nickname = friend.nickname, !nickname.isEmpty
                 else { continue }
                 nicknamesByAuthor[aid] = nickname
             }
             return FetchedRoster(
                 colorGameID: entity.ckRecordName.flatMap(
                     Archive.originalGameID(fromName:)
                 ) ?? entity.id,
                 databaseScope: entity.databaseScope,
                 ckShareRecordName: entity.ckShareRecordName,
                 ckZoneName: entity.ckZoneName,
                 ckZoneOwnerName: entity.ckZoneOwnerName,
                 namesMap: namesMap,
                 playerAuthorIDs: playerAuthorIDs,
                 nicknamesByAuthor: nicknamesByAuthor,
                 moveAuthorIDs: authorIDs,
                 rawSelections: selections,
                 presenceUntilByAuthor: presenceUntilByAuthor,
                 finalSolveSeconds: entity.finalSolveSeconds?.int64Value,
                 completedAt: entity.completedAt,
                 timeLogs: timeLogs
             )
         }
 
         guard generation == refreshGeneration else { return }
         applyRoster(localAuthorID: localAuthorID, fetched: fetched, share: nil)
         scheduleLeaseExpiryRecompute()
 
         guard includingShare else { return }
 
         // Fetch the CKShare if not already cached. This can be noticeably
         // slower on device, so publish the local Core Data roster first and
         // then refine names/participants if share metadata arrives.
         let share = await fetchShare(
             databaseScope: fetched.databaseScope,
             ckShareRecordName: fetched.ckShareRecordName,
             ckZoneName: fetched.ckZoneName,
             ckZoneOwnerName: fetched.ckZoneOwnerName,
             generation: generation
         )
         guard generation == refreshGeneration else { return }
         applyRoster(localAuthorID: localAuthorID, fetched: fetched, share: share)
         scheduleLeaseExpiryRecompute()
         // Trace only the post-fetch roster. The interim publish above always
         // has `share: nil` and would otherwise emit a second signature on
         // every refresh, defeating the dedup and producing the
         // `share=[]` ↔ `share=[…]` flicker seen in the logs.
         traceRoster(
             localAuthorID: localAuthorID,
             namesMap: fetched.namesMap,
             moveAuthorIDs: fetched.moveAuthorIDs,
             share: share
         )
     }
 
     private func applyRoster(
         localAuthorID: String,
         fetched: FetchedRoster,
         share: CKShare?
     ) {
         var shareAuthorIDs: [String] = []
         if let share {
             for participant in share.participants {
                 guard participant.acceptanceStatus == .accepted,
                       let recordName = participant.userIdentity.userRecordID?.recordName
                 else { continue }
                 shareAuthorIDs.append(recordName)
             }
         }
 
         // Assign each collaborator a colour for this game. Colours are derived
         // from (authorID, gameID) and de-conflicted against each other and the
         // local user's stable colour, so they are distinct within the game but
         // deliberately vary from game to game — see
         // `ParticipantSummaries.remoteParticipants`.
         let remoteEntries = ParticipantSummaries.remoteParticipants(
             gameID: fetched.colorGameID ?? gameID,
             namesByAuthor: fetched.namesMap,
             moveAuthorIDs: fetched.moveAuthorIDs,
             nicknamesByAuthor: fetched.nicknamesByAuthor,
             localAuthorID: localAuthorID,
             localColor: preferences.color,
             additionalAuthorIDs: fetched.playerAuthorIDs + shareAuthorIDs
         ).map { participant in
             Entry(
                 authorID: participant.authorID,
                 name: participant.name,
                 color: participant.color,
                 isLocal: false
             )
         }
 
         let localEntry = Entry(
             authorID: localAuthorID,
             name: preferences.name,
             color: preferences.color,
             isLocal: true
         )
         let updatedEntries = [localEntry] + remoteEntries
         if entries != updatedEntries {
             entries = updatedEntries
         }
 
         // Map raw cursor tracks to the resolved colour from the entry list,
         // dropping anything with no matching entry. Visibility (the presence
         // gate) is applied lazily in `remoteSelections`, so the last-known
         // track is retained here regardless of age.
         let colorByAuthor = Dictionary(
             uniqueKeysWithValues: remoteEntries.map { ($0.authorID, $0.color) }
         )
         var tracks: [String: RemoteSelection] = [:]
         for raw in fetched.rawSelections {
             guard let color = colorByAuthor[raw.authorID] else { continue }
             tracks[raw.authorID] = RemoteSelection(
                 authorID: raw.authorID,
                 row: raw.row,
                 col: raw.col,
                 direction: raw.direction,
                 color: color,
                 updatedAt: raw.updatedAt
             )
         }
         persistedRemoteSelections = tracks
         remotePresenceUntil = fetched.presenceUntilByAuthor
         finalSolveSeconds = fetched.finalSolveSeconds
         completedAt = fetched.completedAt
         timeLogs = fetched.timeLogs
         logPresenceTransitions()
     }
 
     /// Emits a tracer line on each non-local peer's present↔absent edge — the
     /// same `presenceUntil`-lease gate that drives their cursor (`remoteSelections`)
     /// and the `leaseExpiryTask` recompute. Deduped via `lastPresentAuthors`,
     /// so the interim and post-share `applyRoster` of one refresh, plus the
     /// lease-expiry refresh, log a transition only once. A departure prints the
     /// lapsed lease and how long ago it expired, so the log can answer "when
     /// did the peer leave?" instead of leaving it to inference.
     private func logPresenceTransitions() {
         guard let tracer else { return }
         let now = Date()
         let present = Set(remotePresenceUntil.keys.filter {
             PeerPresence.isPresent(presenceUntil: remotePresenceUntil[$0], asOf: now)
         })
         guard present != lastPresentAuthors else { return }
         let nameByAuthor = Dictionary(
             uniqueKeysWithValues: entries.filter { !$0.isLocal }.map { ($0.authorID, $0.name) }
         )
         let prefix = "PlayerRoster[\(gameID.uuidString.prefix(8))]"
         func describe(_ authorID: String) -> String {
             "\(authorID.prefix(8)) (\(nameByAuthor[authorID] ?? "?"))"
         }
         func iso(_ date: Date) -> String {
             ISO8601DateFormatter().string(from: date)
         }
         for authorID in present.subtracting(lastPresentAuthors).sorted() {
             let lease = remotePresenceUntil[authorID]
             let until = lease.map(iso) ?? "—"
             let secs = lease.map { Int($0.timeIntervalSince(now)) } ?? 0
             tracer("\(prefix): peer \(describe(authorID)) present (lease until \(until), +\(secs)s)")
         }
         for authorID in lastPresentAuthors.subtracting(present).sorted() {
             let lease = remotePresenceUntil[authorID]
             let lapsed = lease.map(iso) ?? "—"
             let ago = lease.map { Int(now.timeIntervalSince($0)) } ?? 0
             tracer("\(prefix): peer \(describe(authorID)) no longer present (lease \(lapsed) lapsed \(ago)s ago)")
         }
         lastPresentAuthors = present
     }
 
     /// Schedules a single recompute at the soonest moment a present peer drops
     /// out of presence — its `presenceUntil` plus the presence grace, since a lapsed
     /// lease still counts as present through the grace. When it fires,
     /// `refresh()` re-reads `presenceUntil` (reassigning `remotePresenceUntil`, which triggers
     /// observation so the cursor and engagement icon re-evaluate) and
     /// reschedules for the next-soonest. No-op when no peer is present.
     private func scheduleLeaseExpiryRecompute() {
         leaseExpiryTask?.cancel()
         leaseExpiryTask = nil
         let now = Date()
         guard let soonest = remotePresenceUntil.values
             .filter({ PeerPresence.isPresent(presenceUntil: $0, asOf: now) })
             .min() else { return }
         let interval = max(0, soonest.addingTimeInterval(PeerPresence.presenceGrace).timeIntervalSince(now))
         leaseExpiryTask = Task { [weak self] in
             try? await Task.sleep(for: .seconds(interval))
             guard !Task.isCancelled, let self else { return }
             await self.refresh()
         }
     }
 
     // MARK: - Private helpers
 
     /// Diagnostic — surfaces the inputs that drive the entries list so we
     /// can tell whether a "ghost" authorID came from a stale `PlayerEntity`,
     /// a stray `MovesEntity`, or the share's participant list. Called once
     /// per refresh after the final `applyRoster` so the interim `share: nil`
     /// publish doesn't push a second signature through and defeat the dedup.
     private func traceRoster(
         localAuthorID: String,
         namesMap: [String: String],
         moveAuthorIDs: [String],
         share: CKShare?
     ) {
         guard let tracer else { return }
         let participantIDs: [String] = share?.participants.compactMap {
             $0.userIdentity.userRecordID?.recordName
         } ?? []
         let signature = "local=\(localAuthorID) | names=\(namesMap.keys.sorted()) | moves=\(moveAuthorIDs.sorted()) | share=\(participantIDs.sorted())"
         guard signature != lastTracedSignature else { return }
         lastTracedSignature = signature
         tracer("PlayerRoster[\(gameID.uuidString.prefix(8))]: \(signature)")
     }
 
     private func fetchShare(
         databaseScope: Int16,
         ckShareRecordName: String?,
         ckZoneName: String?,
         ckZoneOwnerName: String?,
         generation: Int
     ) async -> CKShare? {
         if let cached = cachedShare { return cached }
         guard let zoneName = ckZoneName else { return nil }
         let ownerName = ckZoneOwnerName ?? CKCurrentUserDefaultName
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
         do {
             if databaseScope == 0, let shareRecordName = ckShareRecordName {
                 let shareID = CKRecord.ID(recordName: shareRecordName, zoneID: zoneID)
                 let share = try await container.privateCloudDatabase.record(for: shareID) as? CKShare
                 if generation == refreshGeneration {
                     cachedShare = share
                 }
                 return share
             } else if databaseScope == 1 {
                 let shareID = CKRecord.ID(recordName: CKRecordNameZoneWideShare, zoneID: zoneID)
                 let share = try await container.sharedCloudDatabase.record(for: shareID) as? CKShare
                 if generation == refreshGeneration {
                     cachedShare = share
                 }
                 return share
             }
         } catch {
             // Best effort — proceed without share metadata.
         }
         return nil
     }
 
 }