crossmate

InviteCoordinator.swift (38084B)

---

 import CloudKit
 import CoreData
 import Foundation
 import UserNotifications
 
 /// Owns the friend-zone traffic that used to live in `AppServices`: outbound
 /// game invites, inbound `Ping` handling (claim/dedup, staleness GC, local
 /// notification presentation, friendship-bootstrap dispatch), the durable
 /// `InviteEntity` rows behind the library's "Invited" section, and friend
 /// blocking. `AppServices` composes one instance and forwards the
 /// `SyncEngine` ping callbacks into it; the accept/decline/block entry
 /// points are surfaced to the UI through environment closures.
 @MainActor
 final class InviteCoordinator {
     enum InviteAcceptanceError: LocalizedError {
         case unavailable
 
         var errorDescription: String? {
             switch self {
             case .unavailable:
                 return "This invite is no longer available. Ask the sender to invite you again."
             }
         }
     }
 
     private let persistence: PersistenceController
     private let identity: AuthorIdentity
     private let preferences: PlayerPreferences
     private let syncMonitor: SyncMonitor
     private let eventLog: EventLog
     private let syncEngine: SyncEngine
     private let announcements: AnnouncementCenter
     private let shareController: ShareController
     private let friendController: FriendController
     private let cloudService: CloudService
     /// Refreshes the app-icon badge — `BadgeCoordinator.refreshAppBadge` —
     /// whenever invite rows change (pending invites count toward the badge).
     private let refreshAppBadge: (String) async -> Void
 
     private var claimedPingRecordNames: Set<String> = []
     private var claimedPingRecordNameOrder: [String] = []
     private let claimedPingRecordNameCap = 200
 
     init(
         persistence: PersistenceController,
         identity: AuthorIdentity,
         preferences: PlayerPreferences,
         syncMonitor: SyncMonitor,
         eventLog: EventLog,
         syncEngine: SyncEngine,
         announcements: AnnouncementCenter,
         shareController: ShareController,
         friendController: FriendController,
         cloudService: CloudService,
         refreshAppBadge: @escaping (String) async -> Void
     ) {
         self.persistence = persistence
         self.identity = identity
         self.preferences = preferences
         self.syncMonitor = syncMonitor
         self.eventLog = eventLog
         self.syncEngine = syncEngine
         self.announcements = announcements
         self.shareController = shareController
         self.friendController = friendController
         self.cloudService = cloudService
         self.refreshAppBadge = refreshAppBadge
     }
 
     /// Re-invites an existing friend to a game: adds them as a participant on
     /// the game's `CKShare` and writes an `.invite` Ping into the friend zone.
     /// Surfaced to the UI via the `\.inviteFriend` environment closure.
     func inviteFriend(gameID: UUID, friendAuthorID: String) async throws {
         guard let localAuthorID = identity.currentID, !localAuthorID.isEmpty else {
             throw FriendController.FriendError.friendNotFound
         }
         let ctx = persistence.viewContext
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         req.fetchLimit = 1
         let game = try? ctx.fetch(req).first
         let title = game?.title ?? ""
 
         // Encode the grid silhouette the same way share links do, so the
         // recipient can preview the puzzle in their "Invited" row. `nil` when
         // the layout cache is unpopulated, which simply gets no preview.
         let shape = shareController.gridSilhouette(for: gameID)
         let silhouette = shape.flatMap {
             GridSilhouette.encode(width: $0.width, height: $0.height, blocks: $0.blocks)
         }
 
         // Carry the puzzle's XD source in the invite. The recipient already
         // syncs the friend zone, so they receive it with the Ping — letting
         // the accept path build a playable game without waiting on the shared
         // zone fetch. Everything the recipient's GameEntity needs derives from
         // this source (as in `GameStore.createGame`); the canonical Game record
         // then merges in as a background update.
         let puzzleSource = game?.puzzleSource
 
         let url = try await shareController.addFriendParticipant(
             toGameID: gameID,
             userRecordName: friendAuthorID
         )
         try await friendController.sendInvite(
             toFriendAuthorID: friendAuthorID,
             gameID: gameID,
             gameTitle: title,
             inviterAuthorID: localAuthorID,
             inviterName: preferences.name,
             gameShareURL: url,
             gridSilhouette: silhouette,
             puzzleSource: puzzleSource
         )
     }
 
     /// For each collaborative game with newly-known remote authors, asks the
     /// `FriendController` to bootstrap a friendship. `establishIfOwner` is a
     /// no-op for the non-owner and for already-established pairs (a defensive
     /// backstop — the caller already fires this only on a Player record's
     /// first sighting, so it runs about once per new collaborator).
     func reconcileFriendships(forGameIDs gameIDs: Set<UUID>) async {
         guard preferences.isICloudSyncEnabled,
               let localAuthorID = identity.currentID,
               !localAuthorID.isEmpty
         else { return }
 
         let ctx = persistence.container.newBackgroundContext()
         let candidates: [(gameID: UUID, remoteAuthorID: String)] = ctx.performAndWait {
             var result: [(UUID, String)] = []
             for gameID in gameIDs {
                 let gReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 gReq.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
                 gReq.fetchLimit = 1
                 guard let game = try? ctx.fetch(gReq).first else { continue }
                 // Only collaborative games carry other authors.
                 guard game.databaseScope == 1 || game.ckShareRecordName != nil else { continue }
 
                 // Identity comes only from Player records — this feature is
                 // deliberately uninterested in Moves (the bootstrap trigger is
                 // the first sighting of a remote Player record). Display names
                 // are not gathered here: they ride `name` Decisions in the
                 // friend zone itself.
                 var remoteAuthorIDs = Set<String>()
                 let pReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 pReq.predicate = NSPredicate(format: "game == %@", game)
                 for p in (try? ctx.fetch(pReq)) ?? [] {
                     guard let authorID = p.authorID else { continue }
                     remoteAuthorIDs.insert(authorID)
                 }
                 remoteAuthorIDs.remove(localAuthorID)
                 remoteAuthorIDs.remove(CKCurrentUserDefaultName)
                 remoteAuthorIDs.remove("")
                 for authorID in remoteAuthorIDs {
                     result.append((gameID, authorID))
                 }
             }
             return result
         }
 
         for (gameID, remoteAuthorID) in candidates {
             await friendController.establishIfOwner(
                 localAuthorID: localAuthorID,
                 remoteAuthorID: remoteAuthorID,
                 localDisplayName: preferences.name,
                 viaGameID: gameID
             )
         }
     }
 
     /// Upserts a durable `InviteEntity` for each inbound `.invite` Ping so the
     /// Game List's "Invited" section survives the Ping being GC'd. Skips
     /// self-authored invites, invites not directed to this author, invites
     /// from blocked friends, games already joined, and any `pingRecordName`
     /// already seen (a declined row is a tombstone that prevents
     /// resurrection).
     /// Returns the `pingRecordName`s of invites whose durable row was created
     /// for the first time by this call — i.e. invites that have just synced
     /// from the server. The caller uses this to notify exactly once: a pending
     /// invite's Ping is re-fetched on every cold start, but its row already
     /// exists by then, so it is absent from this set and isn't re-surfaced.
     @discardableResult
     private func applyInvitePings(_ pings: [Ping]) -> Set<String> {
         let invites = pings.filter {
             $0.kind == .invite &&
             $0.authorID != identity.currentID &&
             $0.addressee == identity.currentID
         }
         guard !invites.isEmpty else { return [] }
 
         let ctx = persistence.container.newBackgroundContext()
         return ctx.performAndWait {
             var insertedPingRecordNames: Set<String> = []
             for ping in invites {
                 guard let payload = FriendZone.InvitePayload.decode(ping.payload) else { continue }
 
                 let dupReq = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
                 dupReq.predicate = NSPredicate(format: "pingRecordName == %@", ping.recordName)
                 dupReq.fetchLimit = 1
                 if ((try? ctx.count(for: dupReq)) ?? 0) > 0 { continue }
 
                 let invite = InviteEntity(context: ctx)
                 invite.gameID = ping.gameID
                 invite.gameTitle = ping.puzzleTitle
                 invite.inviterAuthorID = ping.authorID
                 invite.inviterName = ping.playerName
                 invite.shareURL = payload.gameShareURL
                 invite.gridSilhouette = payload.gridSilhouette
                 invite.puzzleSource = payload.puzzleSource
                 invite.pingRecordName = ping.recordName
                 invite.status = "pending"
                 invite.createdAt = Date()
                 insertedPingRecordNames.insert(ping.recordName)
             }
 
             // GC: a pending invite whose game now exists locally was joined by
             // some other path (a link, or accepted on another device), so the
             // "Invited" row is stale — drop it.
             let pendingReq = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
             pendingReq.predicate = NSPredicate(format: "status == %@", "pending")
             for invite in (try? ctx.fetch(pendingReq)) ?? [] {
                 guard let gid = invite.gameID else { continue }
                 let gReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
                 gReq.predicate = NSPredicate(format: "id == %@", gid as CVarArg)
                 gReq.fetchLimit = 1
                 if ((try? ctx.count(for: gReq)) ?? 0) > 0 { ctx.delete(invite) }
             }
 
             if ctx.hasChanges {
                 do {
                     try ctx.save()
                 } catch {
                     // The rows didn't persist, so treat none as "freshly
                     // recorded" — a later fetch will re-create and notify.
                     insertedPingRecordNames.removeAll()
                     Task { @MainActor [weak self] in
                         self?.eventLog.note("InviteCoordinator: applyInvitePings save failed — \(error)", level: "error")
                     }
                 }
             }
             return insertedPingRecordNames
         }
     }
 
     /// Drops the pending invite row(s) for `gameID`. Called when the game's
     /// shared zone appears locally (joined here or on a sibling device): the
     /// "Invited" row is now redundant. `applyInvitePings` runs the same
     /// garbage-collection over every pending invite, but only when a ping is
     /// fetched — hooking zone arrival closes the window where a just-synced
     /// game and its stale invite show side by side in the library.
     func removePendingInvite(forGameID gameID: UUID) throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(
             format: "gameID == %@ AND status == %@", gameID as CVarArg, "pending"
         )
         let invites = try ctx.fetch(req)
         guard !invites.isEmpty else { return }
         for invite in invites { ctx.delete(invite) }
         if ctx.hasChanges {
             try ctx.save()
         }
     }
 
     /// Drops pending invite rows whose source Ping was consumed elsewhere on
     /// this account. Matching by record name avoids conflating invite Pings
     /// with other Ping kinds for the same game.
     func removePendingInvites(forPingRecordNames recordNames: Set<String>) throws {
         guard !recordNames.isEmpty else { return }
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(
             format: "pingRecordName IN %@ AND status == %@",
             Array(recordNames),
             "pending"
         )
         let invites = try ctx.fetch(req)
         guard !invites.isEmpty else { return }
         for invite in invites { ctx.delete(invite) }
         if ctx.hasChanges {
             try ctx.save()
         }
     }
 
     /// Accepts a pending game invite: fetches the share metadata, joins via
     /// the existing share-accept path, then drops the local `InviteEntity`
     /// (the game now represents it). If CloudKit says the share URL no longer
     /// exists, the durable invite row is stale, so it is removed as well.
     /// Surfaced via `\.acceptInvite`.
     @discardableResult
     func acceptInvite(shareURL: String, pingRecordName: String) async throws -> CloudService.AcceptOutcome {
         guard let url = URL(string: shareURL) else {
             throw FriendController.FriendError.missingShareURLInPayload
         }
         // The invite carried the puzzle's XD source, so hand it to the accept
         // path: it builds a playable game from this without waiting on the
         // shared-zone fetch. nil for invites from older senders or already
         // consumed rows — the accept path then fetches as before.
         let prefetchedPuzzleSource = puzzleSource(forPingRecordName: pingRecordName)
         let outcome: CloudService.AcceptOutcome
         do {
             outcome = try await cloudService.acceptShare(
                 url: url,
                 prefetchedPuzzleSource: prefetchedPuzzleSource
             )
         } catch let error as CKError where error.code == .unknownItem {
             // Stale share: the row needs to go away too, but the next
             // `applyInvitePings` will GC it if this cleanup itself fails.
             // The user-visible signal here is `.unavailable`, so don't let a
             // cleanup error clobber it — log and continue.
             do {
                 try await deleteInviteAndPing(pingRecordName: pingRecordName)
                 syncMonitor.note("accept invite: removed stale invite \(pingRecordName)")
             } catch {
                 syncMonitor.note("accept invite: stale-invite cleanup failed for \(pingRecordName) — \(error)")
             }
             throw InviteAcceptanceError.unavailable
         }
         try await deleteInviteAndPing(pingRecordName: pingRecordName)
         return outcome
     }
 
     /// Accepts the pending invite for `gameID`, if one is still recorded
     /// locally. The puzzle-display join path calls this when the user reached
     /// a not-yet-joined shared game by tapping its `.invite` notification:
     /// that tap only navigates, so the CKShare must still be accepted here.
     /// The durable `InviteEntity` (written when the `.invite` Ping arrived)
     /// carries the share URL. Throws `InviteAcceptanceError.unavailable` when
     /// no such invite exists — the same error the stale-share case surfaces.
     func acceptPendingInvite(gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(format: "gameID == %@", gameID as CVarArg)
         req.sortDescriptors = [
             NSSortDescriptor(keyPath: \InviteEntity.createdAt, ascending: false)
         ]
         req.fetchLimit = 1
         guard let invite = (try? ctx.fetch(req))?.first,
               let shareURL = invite.shareURL,
               let pingRecordName = invite.pingRecordName
         else {
             throw InviteAcceptanceError.unavailable
         }
         try await acceptInvite(shareURL: shareURL, pingRecordName: pingRecordName)
     }
 
     /// The XD source recorded on the durable invite for `pingRecordName`, if
     /// the inviting build carried one. Read just before acceptance so the
     /// accept path can construct a playable game without the shared-zone fetch.
     private func puzzleSource(forPingRecordName pingRecordName: String) -> String? {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(format: "pingRecordName == %@", pingRecordName)
         req.fetchLimit = 1
         guard let source = (try? ctx.fetch(req))?.first?.puzzleSource, !source.isEmpty else {
             return nil
         }
         return source
     }
 
     private func deleteInviteAndPing(pingRecordName: String) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(format: "pingRecordName == %@", pingRecordName)
         for invite in try ctx.fetch(req) {
             if let inviterAuthorID = invite.inviterAuthorID {
                 await friendController.deleteFriendZonePing(
                     fromFriendAuthorID: inviterAuthorID,
                     recordName: pingRecordName
                 )
             }
             ctx.delete(invite)
         }
         if ctx.hasChanges {
             try ctx.save()
             await refreshAppBadge("delete invite")
         }
     }
 
     /// Declines a pending game invite: marks the durable `InviteEntity` rows for
     /// `gameID` as a `"declined"` tombstone (which prevents the invite from
     /// resurrecting locally if CloudKit deletion is delayed), sends a `.decline`
     /// Ping back to each inviter so they free our seat and see a banner, consumes
     /// the source invite Ping so sibling devices clear their rows, and refreshes
     /// the badge. Surfaced via `\.declineInvite`; the AppServices entry point
     /// keeps invite mutation and the badge refresh in one place, mirroring
     /// `acceptInvite`.
     func declineInvite(gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         req.predicate = NSPredicate(
             format: "gameID == %@ AND status == %@", gameID as CVarArg, "pending"
         )
         let invites = try ctx.fetch(req)
         guard !invites.isEmpty else { return }
         let declined = invites.compactMap { invite -> (inviterAuthorID: String, pingRecordName: String, gameTitle: String)? in
             guard let inviterAuthorID = invite.inviterAuthorID,
                   let pingRecordName = invite.pingRecordName
             else { return nil }
             return (inviterAuthorID, pingRecordName, invite.gameTitle ?? "")
         }
         for invite in invites {
             invite.status = "declined"
         }
         if ctx.hasChanges {
             try ctx.save()
             await refreshAppBadge("decline invite")
         }
         let declinerAuthorID = identity.currentID
         let declinerName = preferences.name
         for (inviterAuthorID, pingRecordName, gameTitle) in declined {
             // Tell the inviter so they free our seat and get a banner. Best
             // effort — a failed send must not strand the local tombstone or
             // block the source-Ping cleanup; the inviter can always re-invite.
             if let declinerAuthorID, !declinerAuthorID.isEmpty {
                 do {
                     try await friendController.sendDecline(
                         toInviterAuthorID: inviterAuthorID,
                         gameID: gameID,
                         gameTitle: gameTitle,
                         declinerAuthorID: declinerAuthorID,
                         declinerName: declinerName
                     )
                 } catch {
                     syncMonitor.note("decline invite: send decline failed for \(gameID.uuidString) — \(error.localizedDescription)")
                 }
             }
             await friendController.deleteFriendZonePing(
                 fromFriendAuthorID: inviterAuthorID,
                 recordName: pingRecordName
             )
         }
     }
 
     /// Blocks a collaborator: marks the friendship blocked and tears down the
     /// friend zone, leaves every game they currently share with us, and drops
     /// their pending invites. Games we *own* that they joined are untouched.
     /// Surfaced via `\.blockFriend`.
     func blockFriend(authorID: String) async {
         do {
             try await friendController.blockAndTeardown(friendAuthorID: authorID)
         } catch {
             announcements.post(Announcement(
                 id: "block-friend-error-\(authorID)",
                 scope: .global,
                 severity: .error,
                 title: "Blocking Failed",
                 body: error.localizedDescription,
                 dismissal: .manual
             ))
             return
         }
 
         let ctx = persistence.container.newBackgroundContext()
         let gameIDsToLeave: [UUID] = ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "databaseScope == 1")
             var ids: [UUID] = []
             for game in (try? ctx.fetch(req)) ?? [] {
                 guard let gid = game.id else { continue }
                 var authors = Set<String>()
                 if let owner = game.ckZoneOwnerName { authors.insert(owner) }
                 let mReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
                 mReq.predicate = NSPredicate(format: "game == %@", game)
                 for m in (try? ctx.fetch(mReq)) ?? [] {
                     if let a = m.authorID { authors.insert(a) }
                 }
                 let pReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
                 pReq.predicate = NSPredicate(format: "game == %@", game)
                 for p in (try? ctx.fetch(pReq)) ?? [] {
                     if let a = p.authorID { authors.insert(a) }
                 }
                 if authors.contains(authorID) { ids.append(gid) }
             }
             return ids
         }
         for gid in gameIDsToLeave {
             try? await shareController.leaveShare(gameID: gid)
         }
 
         // Drop their pending invites. Future inbound `.invite` Pings from a
         // blocked sender are caught by `consumeStaleInvites`, which deletes
         // the Ping so it doesn't re-fire across cold starts.
         let vctx = persistence.viewContext
         let iReq = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
         iReq.predicate = NSPredicate(format: "inviterAuthorID == %@", authorID)
         for invite in (try? vctx.fetch(iReq)) ?? [] { vctx.delete(invite) }
         if vctx.hasChanges {
             try? vctx.save()
             await refreshAppBadge("block friend")
         }
     }
 
     /// Deletes `.invite` Pings that are no longer actionable on this device —
     /// the game is already in the local library (joined here or on a sibling),
     /// or the inviter is blocked — and returns the surviving pings. Running
     /// this upstream of both `applyInvitePings` and the notification loop
     /// keeps the staleness rule in one place; without it, an orphaned invite
     /// Ping re-fires a notification on every cold start because the in-memory
     /// dedup caches reset.
     private func consumeStaleInvites(_ pings: [Ping]) async -> [Ping] {
         let candidates = pings.filter {
             $0.kind == .invite &&
             $0.authorID != identity.currentID &&
             $0.addressee == identity.currentID
         }
         guard !candidates.isEmpty else { return pings }
 
         let currentAuthorID = identity.currentID
         let ctx = persistence.container.newBackgroundContext()
         let staleNames: Set<String> = ctx.performAndWait {
             Self.staleInviteRecordNames(
                 among: candidates,
                 in: ctx,
                 currentAuthorID: currentAuthorID
             )
         }
         guard !staleNames.isEmpty else { return pings }
 
         for ping in candidates where staleNames.contains(ping.recordName) {
             await friendController.deleteFriendZonePing(
                 fromFriendAuthorID: ping.authorID,
                 recordName: ping.recordName
             )
             syncMonitor.note(
                 "ping(invite): consumed stale invite \(ping.recordName) for \(ping.gameID.uuidString)"
             )
         }
         return pings.filter { !staleNames.contains($0.recordName) }
     }
 
     nonisolated static func staleInviteRecordNames(
         among pings: [Ping],
         in ctx: NSManagedObjectContext,
         currentAuthorID: String?
     ) -> Set<String> {
         var names: Set<String> = []
         for ping in pings where ping.kind == .invite &&
             ping.authorID != currentAuthorID &&
             ping.addressee == currentAuthorID {
             guard FriendZone.InvitePayload.decode(ping.payload) != nil else {
                 names.insert(ping.recordName)
                 continue
             }
 
             let blockedReq = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             blockedReq.predicate = NSPredicate(
                 format: "authorID == %@ AND isBlocked == YES", ping.authorID
             )
             blockedReq.fetchLimit = 1
             if ((try? ctx.count(for: blockedReq)) ?? 0) > 0 {
                 names.insert(ping.recordName)
                 continue
             }
 
             let inviteReq = NSFetchRequest<InviteEntity>(entityName: "InviteEntity")
             inviteReq.predicate = NSPredicate(format: "pingRecordName == %@", ping.recordName)
             inviteReq.fetchLimit = 1
             if let invite = try? ctx.fetch(inviteReq).first,
                invite.status != "pending" {
                 names.insert(ping.recordName)
                 continue
             }
 
             let gameReq = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             gameReq.predicate = NSPredicate(format: "id == %@", ping.gameID as CVarArg)
             gameReq.fetchLimit = 1
             if ((try? ctx.count(for: gameReq)) ?? 0) > 0 {
                 names.insert(ping.recordName)
             }
         }
         return names
     }
 
     func presentPings(_ pings: [Ping]) async {
         let claimed = claimPingsForHandling(pings)
         guard !claimed.isEmpty else { return }
         let pings = await consumeStaleInvites(claimed)
         guard !pings.isEmpty else { return }
         let newlyInvited = applyInvitePings(pings)
         // Reflect any newly-stored pending invite in the app-icon badge now —
         // before the notification-authorization guard — so the badge updates
         // even when the banner is suppressed or unauthorized.
         await refreshAppBadge("present pings")
         // `.friend` is the friendship-bootstrap handshake. `.join` and `.hail`
         // are legacy live-notification/bootstrap kinds; APNs and Game-record
         // engagement creds own those jobs now. System pings do not require
         // notification authorization.
         let (systemPings, playerFacingPings) = pings.partitioned {
             $0.kind == .friend || $0.kind == .join || $0.kind == .hail
         }
         for ping in systemPings where ping.kind == .friend {
             await friendController.applyFriendPing(
                 ping,
                 localAuthorID: identity.currentID,
                 localDisplayName: preferences.name
             )
         }
         // Free the seat for any invitee who declined. Done before the
         // notification-authorization gate so the share frees even when the
         // banner can't be shown; the banner itself is queued by the loop below.
         for ping in playerFacingPings where ping.kind == .decline {
             await applyDeclinePing(ping)
         }
         guard !playerFacingPings.isEmpty else { return }
         guard await canPresentNotifications() else {
             syncMonitor.note("ping: local notification skipped — authorization not granted")
             return
         }
 
         let center = UNUserNotificationCenter.current()
         for ping in playerFacingPings {
             if ping.kind == .invite, ping.addressee != identity.currentID {
                 continue
             }
             // A directed ping (`addressee` set) targets one player by
             // authorID. Ignore one addressed to someone else — another user's
             // device receives and consumes it. nil ⇒ broadcast, which is now
             // legacy and ignored for `.invite`.
             if let addressee = ping.addressee, addressee != identity.currentID {
                 continue
             }
             if ping.authorID == identity.currentID {
                 syncMonitor.note("ping(\(ping.kind.rawValue)): skipped self-authored record \(ping.recordName)")
                 continue
             }
             // A directed ping addressed to us is consumed by this account:
             // once handled — shown, suppressed, or a duplicate — delete it so
             // it stops re-notifying and the deletion withdraws any copy our
             // sibling devices showed. Broadcast pings are left as-is. `.decline`
             // is excluded: it lives in the friend zone, not the game zone this
             // path deletes from, so `applyDeclinePing` consumes it instead.
             let consume = ping.addressee != nil
                 && ping.kind != .invite
                 && ping.kind != .decline
             func consumeIfDirected() async {
                 guard consume else { return }
                 await syncEngine.deletePing(recordName: ping.recordName, gameID: ping.gameID)
             }
             if NotificationState.isSuppressed(gameID: ping.gameID) {
                 syncMonitor.note("ping(\(ping.kind.rawValue)): suppressed — puzzle is active for \(ping.gameID.uuidString)")
                 await consumeIfDirected()
                 continue
             }
             // Notify for an invite only the first time it syncs from the
             // server (its durable row was just created). A still-pending
             // invite's Ping is re-fetched on every cold start; without this
             // gate the banner would repeat on every app open until the invite
             // is accepted or declined. The Invited row itself is unaffected —
             // `applyInvitePings` keeps it regardless.
             if ping.kind == .invite, !newlyInvited.contains(ping.recordName) {
                 syncMonitor.note("ping(invite): already recorded, not re-notifying for \(ping.gameID.uuidString)")
                 continue
             }
             // Invite banners are user-toggleable; the invite row itself still
             // lands in the Invited section through `applyInvitePings`.
             if ping.kind == .invite, !preferences.notifiesInvitations {
                 syncMonitor.note("ping(invite): banner disabled in settings for \(ping.gameID.uuidString)")
                 continue
             }
 
             let content = UNMutableNotificationContent()
             content.title = "Crossmate"
             // Local notifications never pass through the Notification Service
             // Extension, so the nickname substitution the NSE does for worker
             // pushes happens here instead, off the same App Group directory.
             content.body = Self.bodyText(
                 for: ping,
                 nickname: NicknameDirectory.entry(for: ping.authorID)?.nickname
             )
             content.sound = .default
             content.userInfo = [
                 "gameID": ping.gameID.uuidString,
                 "pingKind": ping.kind.rawValue
             ]
 
             let request = UNNotificationRequest(
                 identifier: "ping-\(ping.gameID.uuidString)-\(UUID().uuidString)",
                 content: content,
                 trigger: nil
             )
             do {
                 try await center.add(request)
                 syncMonitor.note("ping(\(ping.kind.rawValue)): queued local notification for \(ping.gameID.uuidString)")
                 await consumeIfDirected()
             } catch {
                 syncMonitor.note("ping(\(ping.kind.rawValue)): local notification failed — \(error.localizedDescription)")
             }
         }
     }
 
     /// Frees the seat held by an invitee who declined: asks `ShareController`
     /// to remove them from the game's `CKShare` so the owner can invite someone
     /// else, then consumes the `.decline` Ping from the friend zone so it stops
     /// re-firing. The decliner is the ping's author; only the addressed owner
     /// acts. The ping is consumed only on a successful free — a transient
     /// failure leaves it so the next sync retries rather than stranding the
     /// seat — which also means releasing the in-memory handling claim, since a
     /// claimed record is skipped on re-delivery and would otherwise suppress
     /// the retry until the app restarts. The banner is queued separately by
     /// `presentPings`.
     private func applyDeclinePing(_ ping: Ping) async {
         guard ping.addressee == identity.currentID,
               ping.authorID != identity.currentID,
               !ping.authorID.isEmpty
         else { return }
         do {
             try await shareController.removeFriendParticipant(
                 fromGameID: ping.gameID,
                 userRecordName: ping.authorID
             )
             // Consume from the friend zone (not the game zone) — that's where a
             // decline lives, so the loop's game-zone consume path can't reach it.
             await friendController.deleteFriendZonePing(
                 fromFriendAuthorID: ping.authorID,
                 recordName: ping.recordName
             )
             syncMonitor.note("ping(decline): freed seat for \(ping.authorID) in \(ping.gameID.uuidString)")
         } catch {
             // Release the claim so the re-delivered decline reprocesses on the
             // next sync instead of being dropped as already-handled. A duplicate
             // decline banner on the retry is the acceptable cost of not
             // stranding the seat for the rest of the session.
             releaseHandlingClaim(ping.recordName)
             syncMonitor.note("ping(decline): free seat failed for \(ping.gameID.uuidString) — \(error.localizedDescription)")
         }
     }
 
     private func claimPingsForHandling(_ pings: [Ping]) -> [Ping] {
         var unclaimed: [Ping] = []
         for ping in pings {
             guard claimedPingRecordNames.insert(ping.recordName).inserted else {
                 syncMonitor.note("ping(\(ping.kind.rawValue)): already-handled record \(ping.recordName)")
                 continue
             }
             claimedPingRecordNameOrder.append(ping.recordName)
             unclaimed.append(ping)
         }
         if claimedPingRecordNameOrder.count > claimedPingRecordNameCap {
             let overflow = claimedPingRecordNameOrder.count - claimedPingRecordNameCap
             for recordName in claimedPingRecordNameOrder.prefix(overflow) {
                 claimedPingRecordNames.remove(recordName)
             }
             claimedPingRecordNameOrder.removeFirst(overflow)
         }
         return unclaimed
     }
 
     /// Drops a record from the handling claim so a later sync can reprocess it.
     /// Used when handling failed transiently and the source record was left in
     /// place for retry; without this the claim would skip the re-delivery.
     private func releaseHandlingClaim(_ recordName: String) {
         guard claimedPingRecordNames.remove(recordName) != nil else { return }
         claimedPingRecordNameOrder.removeAll { $0 == recordName }
     }
 
     private func canPresentNotifications() async -> Bool {
         let center = UNUserNotificationCenter.current()
         let settings = await center.notificationSettings()
         switch settings.authorizationStatus {
         case .authorized, .provisional, .ephemeral:
             return true
         default:
             return false
         }
     }
 
     nonisolated static func bodyText(for ping: Ping, nickname: String? = nil) -> String {
         let puzzleSuffix = ping.puzzleTitle.isEmpty ? "the puzzle" : "the puzzle '\(ping.puzzleTitle)'"
         switch ping.kind {
         case .invite:
             let player = nickname
                 ?? (ping.playerName.isEmpty ? "A player" : ping.playerName)
             return "\(player) invited you to \(puzzleSuffix)"
         case .decline:
             let player = nickname
                 ?? (ping.playerName.isEmpty ? "A player" : ping.playerName)
             return "\(player) declined your invitation to \(puzzleSuffix)"
         case .friend, .join, .hail:
             // System-only kinds handled by the friendship-bootstrap /
             // engagement paths; never presented as a notification. If this
             // text surfaces in a log or alert, `presentPings` dispatch has
             // broken.
             return "system-only ping should not be presented"
         }
     }
 }
 
 private extension Array {
     /// Splits the collection into `(matched, rejected)` in one pass.
     func partitioned(by predicate: (Element) -> Bool) -> ([Element], [Element]) {
         var matched: [Element] = []
         var rejected: [Element] = []
         for element in self {
             if predicate(element) {
                 matched.append(element)
             } else {
                 rejected.append(element)
             }
         }
         return (matched, rejected)
     }
 }