crossmate

InviteCoordinator.swift (47002B)

---

 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 `AppActions`.
 @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 store: GameStore
     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 let publishInvitePush: (String, UUID, String, 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,
         store: GameStore,
         syncEngine: SyncEngine,
         announcements: AnnouncementCenter,
         shareController: ShareController,
         friendController: FriendController,
         cloudService: CloudService,
         refreshAppBadge: @escaping (String) async -> Void,
         publishInvitePush: @escaping (String, UUID, String, String) async -> Void
     ) {
         self.persistence = persistence
         self.identity = identity
         self.preferences = preferences
         self.syncMonitor = syncMonitor
         self.eventLog = eventLog
         self.store = store
         self.syncEngine = syncEngine
         self.announcements = announcements
         self.shareController = shareController
         self.friendController = friendController
         self.cloudService = cloudService
         self.refreshAppBadge = refreshAppBadge
         self.publishInvitePush = publishInvitePush
     }
 
     /// 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 `AppActions`.
     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 = Self.fastAcceptPuzzleSource(game?.puzzleSource)
 
         // Make sure the pair's mailbox handshake has completed before mutating
         // the game share. Otherwise the friend can be added as a participant but
         // never receive the invite Ping that tells them about the seat.
         try await friendController.ensureOutboxReady(friendAuthorID: friendAuthorID)
 
         let invitationShare = try await shareController.addFriendParticipant(
             toGameID: gameID,
             userRecordName: friendAuthorID
         )
         // `addFriendParticipant` saves the CKShare, which marks the game shared.
         // Ensure the invite carries the shared push credential minted for that
         // game so the recipient registers under the owner's worker namespace
         // before the canonical Game record necessarily arrives.
         let notification = store.ensurePushCredentials(for: gameID)
             .flatMap { try? $0.encoded() }
         do {
             try await friendController.sendInvite(
                 toFriendAuthorID: friendAuthorID,
                 gameID: gameID,
                 gameTitle: title,
                 inviterAuthorID: localAuthorID,
                 inviterName: preferences.name,
                 gameShareURL: invitationShare.url,
                 gridSilhouette: silhouette,
                 puzzleSource: puzzleSource,
                 notification: notification,
                 rollbackParticipantOnFailure: invitationShare.participantWasAdded
             )
         } catch {
             // Skip the inline seat rollback when the Ping is still in play: a
             // terminal `.deliveryFailed` rolls back later via the async
             // `.failed` delivery update, and a `.deliveryPending` timeout must
             // not disturb a seat whose invite is still queued to deliver.
             let pingStillOwnsRollback: Bool
             switch error as? SyncEngine.PingOutboxError {
             case .deliveryFailed, .deliveryPending:
                 pingStillOwnsRollback = true
             case .syncEngineUnavailable, nil:
                 pingStillOwnsRollback = false
             }
             if invitationShare.participantWasAdded,
                !(error is CancellationError),
                !pingStillOwnsRollback {
                 try? await shareController.removeFriendParticipant(
                     fromGameID: gameID,
                     userRecordName: friendAuthorID
                 )
             }
             throw error
         }
         await publishInvitePush(friendAuthorID, gameID, title, preferences.name)
     }
 
     /// Reverses the CKShare mutation attached to a Ping that CloudKit
     /// permanently rejected. The delivery payload records whether this
     /// particular invitation created the seat, so re-inviting an existing
     /// participant can never remove their earlier access.
     func rollbackUndeliveredInvite(gameID: UUID, friendAuthorID: String) async {
         do {
             try await shareController.removeFriendParticipant(
                 fromGameID: gameID,
                 userRecordName: friendAuthorID
             )
         } catch {
             syncMonitor.recordError("rollback undelivered invite", error)
         }
     }
 
     /// For each collaborative game with newly-known remote authors, asks the
     /// `FriendController` to bootstrap a friendship. `establish` is symmetric
     /// (both sides run it) and a no-op once this side's inbox is published (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)] = await ctx.perform {
             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.establish(
                 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
     /// whose source zone doesn't authenticate the claimed inviter, 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]) async -> Set<String> {
         let candidates = pings.filter {
             $0.kind == .invite &&
             $0.authorID != identity.currentID &&
             $0.addressee == identity.currentID
         }
         // `authorID`/`playerName` are self-asserted: any accepted friend can
         // write an invite Ping claiming to be from a *different* friend, so
         // the Invited row would read "Carol invited you" over the forger's
         // share URL. Authenticate the inviter by the zone the record was
         // written to, exactly as `applyDeclinePing` does for declines. A
         // rejected invite is never stored, so it also never banners — the
         // notification loop only surfaces record names this call inserted.
         let (invites, forged) = candidates.partitioned {
             Self.isAuthenticFriendZonePing($0, localAuthorID: identity.currentID ?? "")
         }
         for ping in forged {
             syncMonitor.note(
                 "ping(invite): rejected — zone \(ping.sourceZoneName) does not " +
                 "authenticate inviter \(ping.authorID) for \(ping.gameID.uuidString)"
             )
         }
         guard !invites.isEmpty else { return [] }
 
         let (inserted, saveError) = await Self.storeInvitePings(
             invites,
             persistence: persistence
         )
         if let saveError {
             eventLog.note("InviteCoordinator: applyInvitePings save failed — \(saveError)", level: "error")
         }
         return inserted
     }
 
     /// Persists already-validated invite Pings and reports only rows inserted
     /// by this ingest. Keeping the inserted-name result tied to the durable
     /// save is what makes a replay idempotent for both the Invited section and
     /// its banner: `presentPings` only notifies for names returned here.
     /// Internal so the retry contract can be covered without constructing the
     /// coordinator's unrelated CloudKit collaborators.
     static func storeInvitePings(
         _ invites: [Ping],
         persistence: PersistenceController
     ) async -> (inserted: Set<String>, saveError: Error?) {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             var insertedPingRecordNames: Set<String> = []
             var handledPingRecordNames: Set<String> = []
             for ping in invites {
                 guard let payload = FriendZone.InvitePayload.decode(ping.payload) else { continue }
                 guard handledPingRecordNames.insert(ping.recordName).inserted 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 = Self.fastAcceptPuzzleSource(payload.puzzleSource)
                 invite.notification = payload.notification
                 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.
                     return ([], error)
                 }
             }
             return (insertedPingRecordNames, nil)
         }
     }
 
     /// 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 `AppActions`.
     @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 prefetchedNotification = notification(forPingRecordName: pingRecordName)
         let outcome: CloudService.AcceptOutcome
         do {
             outcome = try await cloudService.acceptShare(
                 url: url,
                 prefetchedPuzzleSource: prefetchedPuzzleSource,
                 prefetchedNotification: prefetchedNotification
             )
         } catch let error as AcceptedShareError where error.kind == .removed {
             do {
                 try await deleteInviteAndPing(pingRecordName: pingRecordName)
                 syncMonitor.note("accept invite: removed unavailable invite \(pingRecordName)")
             } catch {
                 syncMonitor.note(
                     "accept invite: unavailable-invite cleanup failed for " +
                     "\(pingRecordName) — \(error)"
                 )
             }
             throw error
         } catch let error as CKError where error.code == .unknownItem || error.code == .zoneNotFound {
             // 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
     }
 
     /// 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
         let source = (try? ctx.fetch(req))?.first?.puzzleSource
         return Self.fastAcceptPuzzleSource(source)
     }
 
     nonisolated static func fastAcceptPuzzleSource(_ source: String?) -> String? {
         guard let source, !source.isEmpty else { return nil }
         guard source.utf8.count <= XD.maxSourceBytes else { return nil }
         return source
     }
 
     /// The game notification credential recorded on the durable invite, if the
     /// inviting build carried one. Used with the prefetched puzzle source so the
     /// accepted game is immediately registered under the owner's push namespace.
     private func notification(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 notification = (try? ctx.fetch(req))?.first?.notification,
               !notification.isEmpty
         else {
             return nil
         }
         return notification
     }
 
     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 `AppActions`; 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: downgrades them to read-only on the inbox we own
     /// (server-enforced, reversible — no teardown), hides every game they
     /// currently share with us (reversibly — the share/access is kept, the game
     /// just leaves the list), and drops their pending invites. Games we *own*
     /// that they joined are untouched. Surfaced via `AppActions`.
     func blockFriend(authorID: String) async {
         do {
             try await friendController.block(friendAuthorID: authorID)
         } catch {
             announcements.post(Announcement(
                 id: "block-friend-error-\(authorID)",
                 scope: .global,
                 severity: .error,
                 title: "Blocking Failed",
                 body: error.localizedDescription,
                 dismissal: .manual
             ))
             return
         }
 
         await reconcileGamesHiddenForBlockedFriends(authorID: authorID)
 
         // 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")
         }
     }
 
     /// Reverses `blockFriend`: upgrades the friend back to read-write on the
     /// inbox we own, so they can reach us again with no re-pairing, and reveals
     /// the games hidden at block time. Surfaced via `AppActions`.
     func unblockFriend(authorID: String) async {
         do {
             try await friendController.unblock(friendAuthorID: authorID)
         } catch {
             announcements.post(Announcement(
                 id: "unblock-friend-error-\(authorID)",
                 scope: .global,
                 severity: .error,
                 title: "Unblocking Failed",
                 body: error.localizedDescription,
                 dismissal: .manual
             ))
             return
         }
         await reconcileGamesHiddenForBlockedFriends(authorID: authorID)
         await refreshAppBadge("unblock friend")
     }
 
     /// Re-projects the local game-list hide flag from the durable block table.
     /// Block uses this instead of leaving shares, so unblock can restore games
     /// with no re-invite.
     private func reconcileGamesHiddenForBlockedFriends(authorID: String) async {
         let ctx = persistence.container.newBackgroundContext()
         await ctx.perform {
             _ = GameEntity.reconcileBlockedFriendHiddenGames(forAuthorIDs: [authorID], in: ctx)
             if ctx.hasChanges { try? ctx.save() }
         }
     }
 
     /// 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> = await ctx.perform {
             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 = await 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. `.chronicled` is the
         // completed-game retirement 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
                 || $0.kind == .chronicled
         }
         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()
         let delivered = await center.deliveredNotifications()
         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
             }
             if ping.kind == .invite,
                Self.deliveredInvitePushExists(for: ping.gameID, in: delivered) {
                 syncMonitor.note("ping(invite): push already delivered, not queueing local notification 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`.
     /// Whether a friend-zone Ping (`.invite` or `.decline`) genuinely came
     /// from the friend it names in `authorID`. Both facts checked are
     /// CloudKit-intrinsic fetch metadata, not writable record fields:
     /// - The record sits in `friend-<pairKey(us, ping.authorID)>` — besides us,
     ///   the only account that can write into that zone is that friend, so a
     ///   ping naming a third party — or one forged into some other friend's
     ///   inbox — fails.
     /// - It was fetched from the private database: a legitimate invite or
     ///   decline is always written into *our* inbox, a zone we own. A zone the
     ///   forger owns can carry any name he likes but only ever reaches us
     ///   through the shared database, so requiring `.private` holds even if a
     ///   mis-owned zone slips past acceptance-time checks. (Pings from friends
     ///   still on a pre-mailbox app version can arrive shared-scoped and are
     ///   rejected here; the rejection is logged by the callers.)
     /// Empty inputs (missing local identity, unparsed zone) and an unknown
     /// scope fail closed.
     static func isAuthenticFriendZonePing(_ ping: Ping, localAuthorID: String) -> Bool {
         guard !localAuthorID.isEmpty, !ping.authorID.isEmpty else { return false }
         guard ping.sourceDatabaseScope == .private else { return false }
         let expected = FriendZone.zoneName(
             pairKey: FriendZone.pairKey(localAuthorID, ping.authorID)
         )
         return ping.sourceZoneName == expected
     }
 
     private func applyDeclinePing(_ ping: Ping) async {
         guard let ownerAuthorID = identity.currentID,
               ping.addressee == ownerAuthorID,
               ping.authorID != ownerAuthorID,
               !ping.authorID.isEmpty
         else { return }
         // The decliner is self-reported in `authorID`, but that field is
         // attacker-writable: any accepted friend holds `.readWrite` on your
         // `friend-<pairKey>` inbox and could forge a decline naming a third
         // party to evict them from a game the forger was never in. Authenticate
         // the decliner by the zone the record was written to — only the decliner
         // can write to `friend-<pairKey(owner, decliner)>` — so a decline can
         // only ever free the decliner's own seat. (M3 / [P3-8].)
         guard Self.isAuthenticFriendZonePing(ping, localAuthorID: ownerAuthorID) else {
             syncMonitor.note(
                 "ping(decline): rejected — zone \(ping.sourceZoneName) does not " +
                 "authenticate decliner \(ping.authorID) for \(ping.gameID.uuidString)"
             )
             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
         }
     }
 
     private static func deliveredInvitePushExists(for gameID: UUID, in delivered: [UNNotification]) -> Bool {
         delivered.contains { notification in
             let userInfo = notification.request.content.userInfo
             guard let idString = userInfo["gameID"] as? String,
                   UUID(uuidString: idString) == gameID
             else { return false }
             return userInfo["kind"] as? String == PingKind.invite.rawValue
         }
     }
 
     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, .chronicled:
             // 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)
     }
 }