crossmate

ShareController.swift (53956B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Manages the lifecycle of `CKShare` objects for per-game zones. Responsible
 /// for creating zone-scoped shares and saving them to CloudKit, refreshing
 /// existing shares on re-present, and letting participants leave a shared game.
 @MainActor
 final class ShareController {
     struct FriendInvitationShare {
         let url: URL
         /// True only when this invitation added the participant. A later Ping
         /// failure may remove that participant without disturbing a seat that
         /// belonged to an earlier, successfully delivered invitation.
         let participantWasAdded: Bool
     }
 
     private static let zoneWideShareRecordName = CKRecordNameZoneWideShare
     static let maximumPeoplePerPuzzle = 3
     private static var maximumInviteesPerPuzzle: Int { maximumPeoplePerPuzzle - 1 }
     private static let ticketPayloadField = "payload"
     private static let countedTicketVersion = 2
 
     private struct TicketPayload: Codable {
         var version: Int
         var remainingSeats: Int
         var claimedAuthorIDs: [String]
     }
 
     /// The seat ticket for public-link sharing: a `ticket`-kind Ping the owner
     /// mints into the game zone alongside the link. Current tickets carry their
     /// remaining-seat count in the existing `payload` string and joiners consume
     /// a seat by saving a decremented record under CloudKit's optimistic lock;
     /// legacy one-seat tickets had no count and are still consumed by deletion.
     /// The `ticket` kind is unknown to `PingKind`, so `Ping.parseRecord` drops
     /// the record everywhere Pings are surfaced.
     private static let ticketPingKind = "ticket"
     private static func ticketRecordName(for gameID: UUID) -> String {
         "ticket-\(gameID.uuidString)"
     }
 
     let container: CKContainer
     private let persistence: PersistenceController
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor?
 
     /// Fired after `persistShareName` has saved the local entity's
     /// `ckShareRecordName`, so dependent state (e.g. the open game's mutator
     /// `isShared` flag) can flip without waiting for the user to re-open.
     var onShareSaved: (@MainActor (UUID) -> Void)?
 
     /// Fired after this device removed an *accepted* participant from a game's
     /// share. The departed device holds the game's push credentials, so the
     /// handler rotates them immediately instead of waiting for the share-record
     /// change to echo back through sync.
     var onParticipantRemoved: (@MainActor (UUID) -> Void)?
 
     /// Author IDs added as direct game participants during this app session,
     /// keyed by game. Re-asserted on every invite save so an eventually-
     /// consistent share fetch — which can omit a participant added moments
     /// earlier — can't drop a prior invitee on the next save. In-memory by
     /// design: it guards the back-to-back invite window within one session;
     /// across a relaunch the server share has had time to converge, and we
     /// still never *remove* a participant that a fetched share does carry.
     private var sessionInvitedAuthorIDs: [UUID: Set<String>] = [:]
 
     enum ShareError: LocalizedError {
         case gameNotFound
         case invalidShareRecord
         case notAnOwner
         case invalidGameRecord
         case missingShareURL
         case collaborationLimitReached(maxPeople: Int)
         case directInvitesExist
 
         var errorDescription: String? {
             switch self {
             case .gameNotFound:
                 "Puzzle not found."
             case .invalidShareRecord:
                 "Invalid share record."
             case .notAnOwner:
                 "Only the owner can share this puzzle."
             case .invalidGameRecord:
                 "Invalid puzzle record."
             case .missingShareURL:
                 "CloudKit did not return a share URL."
             case .collaborationLimitReached(let maxPeople):
                 "This puzzle already has the maximum of \(maxPeople) people."
             case .directInvitesExist:
                 "This puzzle already has direct invites, so a share link isn't available."
             }
         }
     }
 
     init(
         container: CKContainer,
         persistence: PersistenceController,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor? = nil
     ) {
         self.container = container
         self.persistence = persistence
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
     }
 
     /// Returns the `CKShare` and container for `UICloudSharingController`'s
     /// preparation handler. For a first-time share, the returned share is
     /// *unsaved* — `UICloudSharingController` saves it when the user submits
     /// participants. Call `persistShareName(_:for:)` from the controller's
     /// `didSaveShare` delegate callback to record the saved share's name.
     /// For an existing share, the saved share is fetched and returned.
     func prepareShare(for gameID: UUID) async throws -> (CKShare, CKContainer) {
         let share = try await prepareShareRecord(for: gameID, publicPermission: .none)
         return (share, container)
     }
 
     /// Creates or updates the game's CloudKit share as a public collaboration
     /// link and returns the generated URL. This avoids the participant
     /// management UI and lets Crossmate capture the CloudKit save error
     /// directly when link creation fails.
     func createShareLink(for gameID: UUID) async throws -> URL {
         syncMonitor?.recordStart("create share link")
         do {
             // Fetch the share as-is, without flipping its public permission
             // yet, so an existing direct-invite share stays recognisable: it
             // carries non-owner invitees while its public permission is still
             // `.none`. A new share is created with `.readWrite` regardless.
             let share = try await prepareShareRecord(
                 for: gameID,
                 publicPermission: .readWrite,
                 reconfigureExistingPublicPermission: false
             )
             guard Self.inviteeCount(in: share) < Self.maximumInviteesPerPuzzle else {
                 throw ShareError.collaborationLimitReached(maxPeople: Self.maximumPeoplePerPuzzle)
             }
             // Reject converting a direct-invite share into a public link.
             // Under capacity, non-owner invitees on a `.none` share can only be
             // friends added directly — a public link keeps `.readWrite` until it
             // fills (handled by the capacity guard above). Turning it into a link
             // would create the mixed public/direct-participant state CloudKit
             // forbids, so the two routes stay mutually exclusive.
             if share.publicPermission == .none, Self.inviteeCount(in: share) > 0 {
                 throw ShareError.directInvitesExist
             }
             share.publicPermission = .readWrite
             let savedShare: CKShare
             do {
                 savedShare = try await saveShareForLink(share, for: gameID)
             } catch let error as CKError where error.code == .serverRecordChanged {
                 savedShare = try await recoverShareLinkAfterSaveConflict(error, for: gameID)
             }
             // Mint the seat ticket only after the share is saved, but treat a
             // mint failure as fatal to the whole operation. A live public link
             // with no ticket rejects every joiner — their seat check finds no
             // ticket to claim and bounces them. Roll the link back to private so
             // we never hand out an unjoinable link, then surface the error so the
             // caller can retry (e.g. once a missing schema field is deployed).
             do {
                 try await setTicketSeats(
                     max(0, Self.maximumInviteesPerPuzzle - Self.inviteeCount(in: savedShare)),
                     claimedAuthorIDs: Self.inviteeAuthorIDs(in: savedShare),
                     for: gameID,
                     in: savedShare.recordID.zoneID
                 )
             } catch {
                 try? await disablePublicLinkIfNeeded(savedShare, for: gameID)
                 throw error
             }
             let url = try shareURL(from: savedShare)
             syncMonitor?.note("share link created for \(gameID.uuidString): \(url.absoluteString)")
             syncMonitor?.recordSuccess("create share link")
             return url
         } catch {
             syncMonitor?.recordError("create share link", error)
             throw error
         }
     }
 
     /// Ensures the game's `CKShare` exists and adds `userRecordName` as a
     /// `.readWrite` participant. Returns the share URL so the caller can hand
     /// it to the friend via an `.invite` Ping. Idempotent: re-inviting an
     /// already-added participant is a no-op re-save.
     func addFriendParticipant(
         toGameID gameID: UUID,
         userRecordName: String
     ) async throws -> FriendInvitationShare {
         syncMonitor?.recordStart("invite friend to game")
         do {
             let share = try await prepareShareRecord(
                 for: gameID,
                 publicPermission: .none,
                 reconfigureExistingPublicPermission: false
             )
             let participantWasKnown = sessionInvitedAuthorIDs[gameID]?.contains(
                 userRecordName
             ) == true || Self.inviteeAuthorIDs(in: share).contains(userRecordName)
             noteShareState("invite prepared", share: share, gameID: gameID)
             // Re-assert every invitee added this session, not just the new
             // one. CloudKit reads are not read-after-write consistent, so the
             // share fetched above can omit a participant added moments earlier
             // (a second invite right after the first); saving that copy back
             // would silently revoke them. Restoring the full intended set
             // before the save guarantees it can never shrink the invitee list
             // below what we put there.
             var intended = sessionInvitedAuthorIDs[gameID] ?? []
             intended.insert(userRecordName)
             try enforceInviteCapacity(on: share, addingAll: intended)
             for authorID in intended {
                 try await addParticipantIfNeeded(authorID, to: share)
             }
             revokePublicAccessIfFull(of: share)
             noteShareState("invite saving", share: share, gameID: gameID)
             let saved: CKShare
             do {
                 saved = try await saveShareForLink(share, for: gameID)
             } catch let error as CKError where error.code == .serverRecordChanged {
                 saved = try await recoverFriendShareAfterConflict(
                     error,
                     gameID: gameID,
                     userRecordNames: intended
                 )
             }
             sessionInvitedAuthorIDs[gameID] = intended
             noteShareState("invite saved", share: saved, gameID: gameID)
             let url = try shareURL(from: saved)
             syncMonitor?.recordSuccess("invite friend to game")
             return FriendInvitationShare(
                 url: url,
                 participantWasAdded: !participantWasKnown
             )
         } catch {
             syncMonitor?.recordError("invite friend to game", error)
             throw error
         }
     }
 
     /// Removes `userRecordName` from the game's `CKShare`, freeing the seat they
     /// held so the owner can invite someone else. Called on the owner's device
     /// when an invitee declines (an inbound `.decline` Ping): only the owner can
     /// manage participants, so the decline rounds back here to do it. No-ops for
     /// a game we don't own, an unshared game, or a participant who isn't on the
     /// share. Idempotent.
     func removeFriendParticipant(
         fromGameID gameID: UUID,
         userRecordName: String
     ) async throws {
         syncMonitor?.recordStart("free declined seat")
         do {
             let ctx = persistence.viewContext
             let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             request.fetchLimit = 1
             guard let entity = try ctx.fetch(request).first, entity.databaseScope == 0 else {
                 // Not the owner (or the game is gone) — nothing to manage.
                 syncMonitor?.recordSuccess("free declined seat")
                 return
             }
             // Drop the session re-assert first so a concurrent invite save can't
             // resurrect the declined participant via the intended-set restore.
             sessionInvitedAuthorIDs[gameID]?.remove(userRecordName)
 
             let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
             guard let share = try await fetchZoneWideShareIfPresent(zoneName: zoneName),
                   let removed = removeParticipant(userRecordName, from: share)
             else {
                 // No share, or they aren't on it (already removed / never added).
                 syncMonitor?.recordSuccess("free declined seat")
                 return
             }
             noteShareState("participant rollback saving", share: share, gameID: gameID)
             var removedAccepted = removed.acceptanceStatus == .accepted
             do {
                 _ = try await saveShareForLink(share, for: gameID)
             } catch let error as CKError where error.code == .serverRecordChanged {
                 guard let serverShare = (error as NSError)
                     .userInfo[CKRecordChangedErrorServerRecordKey] as? CKShare else {
                     throw error
                 }
                 if let removedAgain = removeParticipant(userRecordName, from: serverShare) {
                     removedAccepted = removedAgain.acceptanceStatus == .accepted
                     _ = try await saveShareForLink(serverShare, for: gameID)
                 } else {
                     // The server copy no longer lists them — another device
                     // already removed them, and its own removal (or the share
                     // echo) drives any rotation.
                     removedAccepted = false
                 }
             }
             // A declined invitee never accepted, so they never had zone access
             // or the game's credentials — no rotation needed. But if the seat
             // freed belonged to an *accepted* participant, their device holds
             // the push credentials: signal the owner-side rotation now rather
             // than waiting for the share-record change to echo back via sync.
             if removedAccepted {
                 onParticipantRemoved?(gameID)
             }
             noteShareState("participant rollback saved", share: share, gameID: gameID)
             syncMonitor?.recordSuccess("free declined seat")
         } catch {
             syncMonitor?.recordError("free declined seat", error)
             throw error
         }
     }
 
     private func addParticipantIfNeeded(
         _ userRecordName: String,
         to share: CKShare
     ) async throws {
         let already = share.participants.contains {
             $0.userIdentity.userRecordID?.recordName == userRecordName
         }
         guard !already else { return }
         let participant = try await fetchParticipant(forUserRecordName: userRecordName)
         participant.permission = .readWrite
         share.addParticipant(participant)
     }
 
     /// Leaves enough CKShare structure in the scrubbed diagnostics log to
     /// distinguish a participant mutation, an ownership/scope mismatch, and a
     /// server-side rejection without exposing full CloudKit identities.
     private func noteShareState(_ phase: String, share: CKShare, gameID: UUID) {
         let participants = share.participants.map { participant in
             let recordName = participant.userIdentity.userRecordID?.recordName ?? "anonymous"
             return "\(recordName){role=\(participant.role.rawValue)," +
                 "status=\(participant.acceptanceStatus.rawValue)," +
                 "permission=\(participant.permission.rawValue)}"
         }.joined(separator: ",")
         syncMonitor?.note(
             "share \(phase): game=\(gameID.uuidString) " +
             "record=\(share.recordID.recordName) " +
             "zone=\(share.recordID.zoneID.zoneName) " +
             "owner=\(share.recordID.zoneID.ownerName) " +
             "publicPermission=\(share.publicPermission.rawValue) " +
             "url=\(share.url == nil ? "missing" : "present") " +
             "participants=[\(participants)]"
         )
     }
 
     /// Removes the non-owner participant matching `userRecordName` from `share`,
     /// returning the removed participant (its `acceptanceStatus` tells the
     /// caller whether the person ever had zone access). Idempotent: a
     /// participant already gone returns `nil` so the caller can skip a
     /// redundant save.
     private func removeParticipant(
         _ userRecordName: String,
         from share: CKShare
     ) -> CKShare.Participant? {
         guard let participant = share.participants.first(where: {
             $0.role != .owner
                 && $0.userIdentity.userRecordID?.recordName == userRecordName
         }) else { return nil }
         share.removeParticipant(participant)
         return participant
     }
 
     /// Caps the share at `maximumInviteesPerPuzzle` distinct invitees, counting
     /// the union of those already on the share and everyone we intend to
     /// (re-)add this save. Author IDs already present don't double-count, so
     /// re-asserting a prior invitee never trips the limit.
     private func enforceInviteCapacity(on share: CKShare, addingAll authorIDs: Set<String>) throws {
         var invitees = Set(Self.inviteeAuthorIDs(in: share))
         invitees.formUnion(authorIDs)
         guard invitees.count <= Self.maximumInviteesPerPuzzle else {
             throw ShareError.collaborationLimitReached(maxPeople: Self.maximumPeoplePerPuzzle)
         }
     }
 
     /// A full puzzle offers no public link: once an invite commits the last
     /// seat, the same save revokes any outstanding link so it stops admitting
     /// joiners at the CloudKit level.
     private func revokePublicAccessIfFull(of share: CKShare) {
         guard Self.inviteeCount(in: share) >= Self.maximumInviteesPerPuzzle else { return }
         share.publicPermission = .none
     }
 
     private static func inviteeCount(in share: CKShare) -> Int {
         inviteeParticipants(in: share).count
     }
 
     private static func inviteeAuthorIDs(in share: CKShare) -> [String] {
         inviteeParticipants(in: share).compactMap {
             $0.userIdentity.userRecordID?.recordName
         }
     }
 
     private static func inviteeParticipants(in share: CKShare) -> [CKShare.Participant] {
         share.participants.filter { participant in
             participant.role != .owner
                 && participant.acceptanceStatus != .removed
         }
     }
 
     private func fetchParticipant(
         forUserRecordName recordName: String
     ) async throws -> CKShare.Participant {
         let lookup = CKUserIdentity.LookupInfo(
             userRecordID: CKRecord.ID(recordName: recordName)
         )
         return try await withCheckedThrowingContinuation { cont in
             var found: CKShare.Participant?
             let op = CKFetchShareParticipantsOperation(userIdentityLookupInfos: [lookup])
             op.perShareParticipantResultBlock = { _, result in
                 if case .success(let participant) = result { found = participant }
             }
             op.fetchShareParticipantsResultBlock = { result in
                 switch result {
                 case .success:
                     if let found {
                         cont.resume(returning: found)
                     } else {
                         cont.resume(throwing: ShareError.invalidShareRecord)
                     }
                 case .failure(let error):
                     cont.resume(throwing: error)
                 }
             }
             self.container.add(op)
         }
     }
 
     private func recoverFriendShareAfterConflict(
         _ error: CKError,
         gameID: UUID,
         userRecordNames: Set<String>
     ) async throws -> CKShare {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
         let share: CKShare
         if let serverShare = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKShare {
             share = serverShare
         } else {
             share = try await fetchExistingShare(
                 recordName: Self.zoneWideShareRecordName,
                 zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
             )
         }
         // Keep the share's metadata current while applying the current link policy.
         configureShare(share, title: entity.title, publicPermission: nil)
         try enforceInviteCapacity(on: share, addingAll: userRecordNames)
         for authorID in userRecordNames {
             try await addParticipantIfNeeded(authorID, to: share)
         }
         revokePublicAccessIfFull(of: share)
         return try await saveShareForLink(share, for: gameID)
     }
 
     /// Returns the saved public share URL for a game, if Crossmate already
     /// knows about its `CKShare`. Stale local share references are cleared so
     /// the caller can safely offer to create a fresh link.
     func existingShareLink(for gameID: UUID) async throws -> URL? {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
         guard entity.databaseScope == 0 else {
             throw ShareError.notAnOwner
         }
         guard let existingName = entity.ckShareRecordName else {
             let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
             do {
                 let share = try await fetchExistingShare(
                     recordName: Self.zoneWideShareRecordName,
                     zoneName: zoneName
                 )
                 entity.ckShareRecordName = share.recordID.recordName
                 try ctx.save()
                 return try await publicLinkURL(from: share, for: gameID)
             } catch let error as CKError where isMissingShare(error) {
                 return nil
             }
         }
 
         do {
             let share = try await fetchExistingShare(
                 recordName: existingName,
                 zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
             )
             return try await publicLinkURL(from: share, for: gameID)
         } catch let error as CKError where error.code == .unknownItem {
             entity.ckShareRecordName = nil
             try ctx.save()
             return nil
         }
     }
 
     /// Resolves a fetched share to its live public link. A full puzzle has no
     /// link to offer — any lingering public permission is revoked so the old
     /// URL stops admitting joiners — and a share without public access
     /// reports `nil` so the caller can offer to create a fresh link.
     private func publicLinkURL(from share: CKShare, for gameID: UUID) async throws -> URL? {
         guard Self.inviteeCount(in: share) < Self.maximumInviteesPerPuzzle else {
             try await disablePublicLinkIfNeeded(share, for: gameID)
             return nil
         }
         guard share.publicPermission != .none else { return nil }
         // Reusing an existing link is the moment to heal a ticket that never
         // landed: a link whose original mint failed stays live but unjoinable
         // until a ticket exists. Best-effort, and only mints when the ticket is
         // absent so a healthy ticket's seat count is never reopened.
         await ensureTicketExists(for: gameID, share: share)
         return share.url
     }
 
     /// Whether the puzzle's invitee seat is already taken, per the share's
     /// actual participant list (a pending invite counts — the seat is
     /// committed once offered). Seeds the share sheet so a full game opens
     /// with invites already disabled instead of surfacing the limit as a
     /// tap-time error. Best-effort: an unshared game or a transient fetch
     /// failure reports `false`, and the capacity check in
     /// `addFriendParticipant` remains the authoritative gate.
     func isAtInviteCapacity(for gameID: UUID) async -> Bool {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? ctx.fetch(request).first,
               entity.databaseScope == 0 else { return false }
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         guard let share = (try? await fetchZoneWideShareIfPresent(zoneName: zoneName)) ?? nil
         else { return false }
         return Self.inviteeCount(in: share) >= Self.maximumInviteesPerPuzzle
     }
 
     /// The author IDs already holding an invitee seat on the game's share.
     /// Seeds the invite UI so a re-opened share sheet shows everyone you've
     /// already added with a checkmark instead of an un-invited glyph, which
     /// otherwise tempts a redundant second invite. Unions the share's current
     /// invitee participants with the author IDs added this session, since an
     /// eventually-consistent share fetch can omit a participant added moments
     /// earlier. Best-effort: an unshared game or a transient fetch failure
     /// falls back to the session set alone.
     func invitedAuthorIDs(for gameID: UUID) async -> Set<String> {
         var invited = invitedAuthorIDsKnownThisSession(for: gameID)
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? ctx.fetch(request).first,
               entity.databaseScope == 0 else { return invited }
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         if let share = (try? await fetchZoneWideShareIfPresent(zoneName: zoneName)) ?? nil {
             invited.formUnion(Self.inviteeAuthorIDs(in: share))
         }
         return invited
     }
 
     /// The author IDs added as invitees during this app session, readable
     /// synchronously so a re-presented share screen can render their checkmark
     /// on the first frame — no await, no animated transition — before the
     /// async invitedAuthorIDs(for:) backfills anyone invited on another device
     /// or in a prior session.
     func invitedAuthorIDsKnownThisSession(for gameID: UUID) -> Set<String> {
         sessionInvitedAuthorIDs[gameID] ?? []
     }
 
     /// The game's grid silhouette for share-link previews, read from the
     /// cached block layout so it costs nothing at link-creation time. Returns
     /// `nil` when the cache hasn't been populated, in which case the link simply
     /// carries no shape segment.
     func gridSilhouette(for gameID: UUID) -> GridSilhouette.Grid? {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? ctx.fetch(request).first else { return nil }
         let width = Int(entity.gridWidth)
         let height = Int(entity.gridHeight)
         guard width > 0, height > 0,
               let mask = entity.blockMask, mask.count == width * height else {
             return nil
         }
         return GridSilhouette.Grid(width: width, height: height, blocks: mask.map { $0 != 0 })
     }
 
     private func prepareShareRecord(
         for gameID: UUID,
         publicPermission: CKShare.ParticipantPermission,
         reconfigureExistingPublicPermission: Bool = true
     ) async throws -> CKShare {
         // For an *existing* share the friend-invite path passes `false`: the
         // share keeps whatever public permission it already had (a brand-new
         // share is still created with the requested `publicPermission`).
         let existingPermission: CKShare.ParticipantPermission? =
             reconfigureExistingPublicPermission ? publicPermission : nil
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
         guard entity.databaseScope == 0 else {
             throw ShareError.notAnOwner
         }
 
         if let existingName = entity.ckShareRecordName {
             do {
                 let existing = try await fetchExistingShare(
                     recordName: existingName,
                     zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
                 )
                 return configureShare(existing, title: entity.title, publicPermission: existingPermission)
             } catch let error as CKError where error.code == .unknownItem {
                 entity.ckShareRecordName = nil
                 try ctx.save()
             }
         }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: CKCurrentUserDefaultName)
 
         // Create the zone directly rather than going through CKSyncEngine.sendChanges(),
         // which can block on post-reset state (stale tokens, in-flight operations).
         // Zone creation is idempotent so this is safe even if the engine already created it.
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             let op = CKModifyRecordZonesOperation(
                 recordZonesToSave: [CKRecordZone(zoneID: zoneID)],
                 recordZoneIDsToDelete: nil
             )
             op.qualityOfService = .userInitiated
             op.modifyRecordZonesResultBlock = { result in cont.resume(with: result) }
             self.container.privateCloudDatabase.add(op)
         }
 
         if let existing = try await fetchZoneWideShareIfPresent(zoneName: zoneName) {
             entity.ckShareRecordName = existing.recordID.recordName
             try ctx.save()
             return configureShare(existing, title: entity.title, publicPermission: existingPermission)
         }
 
         try await ensureGameRecordExists(for: entity, in: zoneID)
 
         let share = CKShare(recordZoneID: zoneID)
         return configureShare(share, title: entity.title, publicPermission: publicPermission)
     }
 
     /// Records the share's CloudKit record name on the local entity so future
     /// invocations of `prepareShare` fetch the existing share. Also enqueues a
     /// Game record push so other owner-devices receive the share marker via
     /// `RecordSerializer.applyGameRecord` and flip their `isShared` flag.
     /// Idempotent.
     func persistShareName(_ recordName: String, for gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else { return }
         guard entity.ckShareRecordName != recordName else { return }
         entity.ckShareRecordName = recordName
         entity.hasPendingSave = true
         try ctx.save()
         if let ckRecordName = entity.ckRecordName {
             await syncEngine.enqueueGame(ckRecordName: ckRecordName)
         }
         onShareSaved?(gameID)
     }
 
     /// Removes the current user's participation from a shared game and deletes
     /// the local entity. No-ops if the game is not a shared (participant) game.
     func leaveShare(gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first,
               entity.databaseScope == 1 else { return }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let ownerName = entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
         let shareID = CKRecord.ID(recordName: Self.zoneWideShareRecordName, zoneID: zoneID)
 
         // A participant leaves a zone-wide share by deleting the CKShare record
         // from the shared database; deleting the zone itself is rejected with
         // "Zone delete not allowed".
         do {
             try await container.sharedCloudDatabase.deleteRecord(withID: shareID)
         } catch let error as CKError where error.code == .unknownItem || error.code == .zoneNotFound {
             // Already gone — proceed to clean up local state.
         }
 
         // Delete the invite Ping that brought us in, if it's still around.
         // It's durable and its usual cleanup (`consumeStaleInvites`) keys off
         // the local GameEntity we're about to remove, so leaving it behind
         // lets the invite resurrect on the next cold start and on sibling
         // devices. Done before the local delete so a query failure can't strand
         // a half-left game.
         await syncEngine.deleteInvitePingsAfterLeave(forGameID: gameID)
 
         // Record the leave as a durable per-user fact so the user's other
         // devices hard-delete this game too. Without it, a sibling sees only
         // the shared-zone deletion — indistinguishable from the owner
         // revoking access — and would mislabel the row "no longer have
         // access" instead of removing it. Best-effort but self-healing: the
         // record is re-consulted on every sync, not consumed once.
         await syncEngine.enqueueDecision(kind: "left", key: gameID.uuidString)
 
         ctx.delete(entity)
         try ctx.save()
     }
 
     /// Best-effort cleanup for terminal games. Deleting a game deletes its
     /// CloudKit zone and therefore the ticket; completion keeps the zone around
     /// for replay/archive, so close the public-link seat explicitly.
     func closeTicketForCompletedGame(gameID: UUID) async {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? ctx.fetch(request).first,
               entity.completedAt != nil else { return }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let ownerName = entity.databaseScope == 0
             ? CKCurrentUserDefaultName
             : (entity.ckZoneOwnerName ?? CKCurrentUserDefaultName)
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
         let database = entity.databaseScope == 1
             ? container.sharedCloudDatabase
             : container.privateCloudDatabase
         let ticketID = CKRecord.ID(recordName: Self.ticketRecordName(for: gameID), zoneID: zoneID)
 
         do {
             try await database.deleteRecord(withID: ticketID)
             syncMonitor?.note("ticket closed for completed game \(gameID.uuidString)")
         } catch let error as CKError where error.code == .unknownItem || error.code == .zoneNotFound {
             // Already gone, or the zone was deleted; either way the link seat is closed.
         } catch {
             syncMonitor?.note(
                 "ticket close skipped for \(gameID.uuidString): \(error.localizedDescription)"
             )
         }
     }
 
     /// Joiner-side seat check, run right after a share acceptance has synced
     /// the new zone. Cooperative by design: CloudKit cannot enforce a
     /// participant cap, so an over-cap joiner leaves voluntarily and a client
     /// that skips the check keeps access until the owner intervenes.
     ///
     /// Directly invited friends always keep their seat — the owner added them
     /// by identity, so the participant list itself is the gate. Link joiners
     /// are admitted while the share is under the cap; simultaneous joiners
     /// that cannot see each other in the participant list yet are settled by
     /// consuming one slot from the zone's ticket Ping. A missing or exhausted
     /// ticket without a prior Player-record footprint means the seat went to
     /// someone else (or the link predates tickets and is considered dead), so
     /// the joiner leaves.
     ///
     /// Only `ShareError.collaborationLimitReached` escapes. A transient
     /// CloudKit failure is traced and the join stands — a failed check must
     /// not turn a successful join into a reported failure; the cap then rests
     /// on the other cooperating clients.
     func confirmSeatAfterJoin(gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try? ctx.fetch(request).first,
               entity.databaseScope == 1 else { return }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let ownerName = entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
 
         let seatLost: Bool
         do {
             seatLost = try await hasLostSeat(gameID: gameID, zoneID: zoneID)
         } catch {
             syncMonitor?.note(
                 "join seat check skipped for \(gameID.uuidString): \(error.localizedDescription)"
             )
             return
         }
         guard seatLost else { return }
 
         // Best-effort: if leaving fails the local row lingers, but the limit
         // error is still the truthful outcome to surface for this join.
         try? await leaveShare(gameID: gameID)
         throw ShareError.collaborationLimitReached(maxPeople: Self.maximumPeoplePerPuzzle)
     }
 
     private func hasLostSeat(gameID: UUID, zoneID: CKRecordZone.ID) async throws -> Bool {
         let database = container.sharedCloudDatabase
         let shareID = CKRecord.ID(recordName: Self.zoneWideShareRecordName, zoneID: zoneID)
         guard let share = try await database.record(for: shareID) as? CKShare else {
             return false
         }
         if share.currentUserParticipant?.role == .privateUser { return false }
         if Self.inviteeCount(in: share) > Self.maximumInviteesPerPuzzle { return true }
         if try await hasNoPlayerFootprint(gameID: gameID, zoneID: zoneID, in: database) == false {
             return false
         }
 
         // Under the cap. A simultaneous link joiner may not be visible in the
         // participant list yet; consuming a ticket seat settles it atomically.
         // A missing ticket counts as no seat available: the participant list is
         // not an authoritative cap for public-link joiners (they don't reliably
         // appear in it), so the ticket is the only real counter. The owner-side
         // rollback and self-heal keep a live link's ticket present, so a genuine
         // joiner meets a real ticket rather than falling through here.
         let ticketID = CKRecord.ID(
             recordName: Self.ticketRecordName(for: gameID),
             zoneID: zoneID
         )
         return try await consumeTicketSeat(ticketID: ticketID, in: database) == false
     }
 
     private func hasNoPlayerFootprint(
         gameID: UUID,
         zoneID: CKRecordZone.ID,
         in database: CKDatabase
     ) async throws -> Bool {
         let myRecordName = try await container.userRecordID().recordName
         let playerID = CKRecord.ID(
             recordName: RecordSerializer.recordName(
                 forPlayerInGame: gameID,
                 authorID: myRecordName
             ),
             zoneID: zoneID
         )
         do {
             _ = try await database.record(for: playerID)
             return false
         } catch let error as CKError where error.code == .unknownItem {
             return true
         }
     }
 
     // MARK: - Helpers
 
     private func fetchExistingShare(
         recordName: String,
         zoneName: String
     ) async throws -> CKShare {
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: CKCurrentUserDefaultName)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
         let record = try await container.privateCloudDatabase.record(for: recordID)
         guard let share = record as? CKShare else {
             throw ShareError.invalidShareRecord
         }
         return share
     }
 
     private func fetchZoneWideShareIfPresent(zoneName: String) async throws -> CKShare? {
         do {
             return try await fetchExistingShare(
                 recordName: Self.zoneWideShareRecordName,
                 zoneName: zoneName
             )
         } catch let error as CKError where isMissingShare(error) {
             return nil
         }
     }
 
     private func isMissingShare(_ error: CKError) -> Bool {
         error.code == .unknownItem || error.code == .zoneNotFound
     }
 
     @discardableResult
     private func configureShare(
         _ share: CKShare,
         title: String?,
         publicPermission: CKShare.ParticipantPermission?
     ) -> CKShare {
         // `nil` leaves the existing public permission untouched — the
         // friend-invite path uses it so re-saving a share doesn't disturb a
         // link the owner created separately while the seat is still open.
         if let publicPermission {
             share.publicPermission = publicPermission
         }
         share[CKShare.SystemFieldKey.title] = title as CKRecordValue?
         return share
     }
 
     /// Saves the zone's counted seat ticket. Recreating a public link resets the
     /// count to the share's currently available invitee seats, which reopens a
     /// freed seat after a participant is removed while keeping a full game closed.
     private func setTicketSeats(
         _ seats: Int,
         claimedAuthorIDs: [String],
         for gameID: UUID,
         in zoneID: CKRecordZone.ID
     ) async throws {
         let ticketID = CKRecord.ID(
             recordName: Self.ticketRecordName(for: gameID),
             zoneID: zoneID
         )
         let ticket: CKRecord
         do {
             ticket = try await container.privateCloudDatabase.record(for: ticketID)
         } catch let error as CKError where error.code == .unknownItem {
             ticket = CKRecord(recordType: "Ping", recordID: ticketID)
         }
         ticket["kind"] = Self.ticketPingKind as CKRecordValue
         try Self.setTicketPayload(
             TicketPayload(
                 version: Self.countedTicketVersion,
                 remainingSeats: seats,
                 claimedAuthorIDs: Self.normalizedClaimedAuthorIDs(claimedAuthorIDs)
             ),
             on: ticket
         )
         do {
             _ = try await container.privateCloudDatabase.save(ticket)
         } catch let error as CKError where error.code == .serverRecordChanged {
             guard let serverTicket = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord else {
                 throw error
             }
             serverTicket["kind"] = Self.ticketPingKind as CKRecordValue
             try Self.setTicketPayload(
                 TicketPayload(
                     version: Self.countedTicketVersion,
                     remainingSeats: seats,
                     claimedAuthorIDs: Self.normalizedClaimedAuthorIDs(claimedAuthorIDs)
                 ),
                 on: serverTicket
             )
             _ = try await container.privateCloudDatabase.save(serverTicket)
         }
     }
 
     /// Best-effort mint of a *missing* seat ticket for an existing public link.
     /// A link created before the ticket mechanism — or one whose original mint
     /// failed (e.g. a not-yet-deployed schema field) — has a live URL but no
     /// ticket, so every link joiner's seat check finds nothing and bounces them.
     /// Reconstructing a ticket from the share's current invitees restores
     /// joinability. Only mints when the ticket is absent: a present ticket is
     /// left untouched so its already-consumed seats aren't reopened.
     private func ensureTicketExists(for gameID: UUID, share: CKShare) async {
         let zoneID = share.recordID.zoneID
         let ticketID = CKRecord.ID(
             recordName: Self.ticketRecordName(for: gameID),
             zoneID: zoneID
         )
         do {
             _ = try await container.privateCloudDatabase.record(for: ticketID)
             // Present already — leave its seat count untouched.
         } catch let error as CKError where error.code == .unknownItem {
             do {
                 try await setTicketSeats(
                     max(0, Self.maximumInviteesPerPuzzle - Self.inviteeCount(in: share)),
                     claimedAuthorIDs: Self.inviteeAuthorIDs(in: share),
                     for: gameID,
                     in: zoneID
                 )
                 syncMonitor?.note("healed missing seat ticket for \(gameID.uuidString)")
             } catch {
                 syncMonitor?.note(
                     "seat ticket heal skipped for \(gameID.uuidString): \(error.localizedDescription)"
                 )
             }
         } catch {
             // Transient fetch failure — the join-time seat check is the backstop.
         }
     }
 
     /// Returns true when this joiner successfully consumed a public-link seat.
     /// Legacy tickets have no seat count and are consumed by deleting the record.
     private func consumeTicketSeat(ticketID: CKRecord.ID, in database: CKDatabase) async throws -> Bool {
         let myRecordName = try await container.userRecordID().recordName
         var attempts = 0
         var ticket: CKRecord?
         while attempts < 4 {
             attempts += 1
             let record: CKRecord
             if let ticket {
                 record = ticket
             } else {
                 do {
                     record = try await database.record(for: ticketID)
                 } catch let error as CKError where error.code == .unknownItem {
                     return false
                 }
             }
 
             guard var payload = Self.ticketPayload(in: record) else {
                 do {
                     try await database.deleteRecord(withID: ticketID)
                     return true
                 } catch let error as CKError where error.code == .unknownItem {
                     return false
                 }
             }
 
             var claimedAuthorIDs = Set(payload.claimedAuthorIDs)
             if claimedAuthorIDs.contains(myRecordName) {
                 return true
             }
 
             guard payload.remainingSeats > 0 else { return false }
             claimedAuthorIDs.insert(myRecordName)
             payload.version = Self.countedTicketVersion
             payload.remainingSeats -= 1
             payload.claimedAuthorIDs = Self.normalizedClaimedAuthorIDs(Array(claimedAuthorIDs))
             try Self.setTicketPayload(payload, on: record)
             do {
                 _ = try await database.save(record)
                 return true
             } catch let error as CKError where error.code == .serverRecordChanged {
                 ticket = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord
             }
         }
         return false
     }
 
     private static func setTicketPayload(_ payload: TicketPayload, on ticket: CKRecord) throws {
         let data = try JSONEncoder().encode(payload)
         ticket[ticketPayloadField] = String(decoding: data, as: UTF8.self) as CKRecordValue
     }
 
     private static func ticketPayload(in ticket: CKRecord) -> TicketPayload? {
         if let value = ticket[ticketPayloadField] as? String,
            let data = value.data(using: .utf8),
            let payload = try? JSONDecoder().decode(TicketPayload.self, from: data) {
             return payload
         }
         return nil
     }
 
     private static func normalizedClaimedAuthorIDs(_ authorIDs: [String]) -> [String] {
         authorIDs.filter { !$0.isEmpty }.sorted()
     }
 
     private func disablePublicLinkIfNeeded(_ share: CKShare, for gameID: UUID) async throws {
         guard share.publicPermission != .none else { return }
         share.publicPermission = .none
         _ = try await saveShareForLink(share, for: gameID)
     }
 
     private func saveShareForLink(_ share: CKShare, for gameID: UUID) async throws -> CKShare {
         let savedRecord = try await container.privateCloudDatabase.save(share)
         guard let savedShare = savedRecord as? CKShare else {
             throw ShareError.invalidShareRecord
         }
         try await persistShareName(savedShare.recordID.recordName, for: gameID)
         return savedShare
     }
 
     private func shareURL(from share: CKShare) throws -> URL {
         guard let url = share.url else {
             throw ShareError.missingShareURL
         }
         return url
     }
 
     private func recoverShareLinkAfterSaveConflict(
         _ error: CKError,
         for gameID: UUID
     ) async throws -> CKShare {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
 
         let share: CKShare
         if let serverShare = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKShare {
             share = serverShare
         } else {
             share = try await fetchExistingShare(
                 recordName: Self.zoneWideShareRecordName,
                 zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
             )
         }
 
         // The conflicting save may have been a sibling device committing the
         // seat; re-check capacity against the server share before re-opening
         // public access.
         guard Self.inviteeCount(in: share) < Self.maximumInviteesPerPuzzle else {
             throw ShareError.collaborationLimitReached(maxPeople: Self.maximumPeoplePerPuzzle)
         }
         configureShare(share, title: entity.title, publicPermission: .readWrite)
         return try await saveShareForLink(share, for: gameID)
     }
 
     /// CloudKit requires the initial records covered by a new share to already
     /// exist on the server or be saved with the share. `CKShareTransferRepresentation`
     /// only returns the share, so save the root game record before handing the
     /// zone-wide share to the system UI.
     private func ensureGameRecordExists(
         for entity: GameEntity,
         in zoneID: CKRecordZone.ID
     ) async throws {
         guard let recordName = entity.ckRecordName else {
             throw ShareError.invalidGameRecord
         }
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
         let record: CKRecord
         let includePuzzleSource: Bool
 
         do {
             record = try await container.privateCloudDatabase.record(for: recordID)
             includePuzzleSource = record["puzzleSource"] == nil
         } catch let error as CKError where error.code == .unknownItem {
             guard let newRecord = RecordSerializer.gameRecord(
                 from: entity,
                 recordID: recordID,
                 includePuzzleSource: true
             ) else {
                 throw ShareError.invalidGameRecord
             }
             record = newRecord
             includePuzzleSource = true
         }
 
         RecordSerializer.populateGameRecord(
             record,
             from: entity,
             includePuzzleSource: includePuzzleSource
         )
         let saved: CKRecord
         do {
             saved = try await container.privateCloudDatabase.save(record)
         } catch let error as CKError where error.code == .serverRecordChanged {
             let serverRecord: CKRecord
             if let conflictRecord = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord {
                 serverRecord = conflictRecord
             } else {
                 serverRecord = try await container.privateCloudDatabase.record(for: recordID)
             }
             RecordSerializer.populateGameRecord(
                 serverRecord,
                 from: entity,
                 includePuzzleSource: serverRecord["puzzleSource"] == nil
             )
             saved = try await container.privateCloudDatabase.save(serverRecord)
         }
         entity.ckSystemFields = RecordSerializer.encodeSystemFields(of: saved)
         entity.lastSyncedAt = Date()
         if entity.ckZoneName == nil {
             entity.ckZoneName = zoneID.zoneName
         }
         try persistence.viewContext.save()
     }
 }