crossmate

FriendController.swift (41874B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Sibling of `ShareController`, but for *friend* mailboxes rather than game
 /// zones. A friendship is a durable, pairwise channel built from two mailbox
 /// zones, both named `friend-<pairKey>` and distinguished by owner: each user
 /// owns one (their *inbox*, in their private database, carrying a zone-wide
 /// `CKShare` with the friend as a `.readWrite` participant) and joins the
 /// other's (their *outbox*, in their shared database). You write to a friend by
 /// writing into their inbox (your outbox); you receive by reading your own
 /// inbox. Blocking downgrades the friend to `.readOnly` on the inbox you own —
 /// server-enforced and reversible by upgrading back, with no teardown.
 ///
 /// Bootstrap rides the *game* zone the two users already share and is
 /// symmetric: each side ensures its own inbox exists and enqueues a `.friend`
 /// `Ping` whose `payload` carries that inbox's share URL. The other device
 /// applies it (`applyFriendPing`) and accepts the share — gaining write access
 /// to that inbox — without any out-of-band link.
 @MainActor
 final class FriendController {
     /// Mints (if needed) and publishes this device's per-pair invite encryption
     /// key into the friend zone so the pair can seal invite pushes. Supplied by
     /// `AppServices`; nil where push isn't wired (e.g. tests).
     typealias FriendInvitationKeyPublisher =
         (_ pairKey: String, _ friendZoneID: CKRecordZone.ID, _ friendZoneScope: DatabaseScope) async -> Void
 
     let container: CKContainer
     private let persistence: PersistenceController
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor?
     private let eventLog: EventLog?
     private let fetchAccountDecisionRecord: (CKRecord.ID) async throws -> CKRecord
     private let publishFriendInvitationKey: FriendInvitationKeyPublisher?
 
     init(
         container: CKContainer,
         persistence: PersistenceController,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor? = nil,
         eventLog: EventLog? = nil,
         publishFriendInvitationKey: FriendInvitationKeyPublisher? = nil,
         fetchAccountDecisionRecord: ((CKRecord.ID) async throws -> CKRecord)? = nil
     ) {
         self.container = container
         self.persistence = persistence
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.eventLog = eventLog
         self.publishFriendInvitationKey = publishFriendInvitationKey
         self.fetchAccountDecisionRecord = fetchAccountDecisionRecord
             ?? { try await container.privateCloudDatabase.record(for: $0) }
     }
 
     enum FriendError: Error {
         case invalidShareRecord
         case missingShareURL
         case participantNotFound
         case missingShareURLInPayload
         case friendNotFound
         case friendBlocked
         case friendshipNotReady
         case payloadEncodingFailed
     }
 
     // MARK: - Bootstrap
 
     /// Ensures this device's *inbox* mailbox for the pair exists and is shared
     /// to the friend, then enqueues a `.friend` Ping carrying the inbox share
     /// URL so the friend can accept it and gain write access. Symmetric: both
     /// sides run this for the pair — there is no elected owner. Idempotent — a
     /// no-op once this side's inbox is established (the friend's own
     /// `applyFriendPing` records their half independently). `viaGameID` is the
     /// shared game whose zone carries the bootstrap Ping. The local display name
     /// is *not* seeded here: it is written into our outbox by `applyFriendPing`,
     /// which is the first moment we have write access to it.
     func establish(
         localAuthorID: String,
         remoteAuthorID: String,
         localDisplayName: String?,
         viaGameID: UUID
     ) async {
         guard !remoteAuthorID.isEmpty,
               localAuthorID != remoteAuthorID
         else { return }
 
         let pairKey = FriendZone.pairKey(localAuthorID, remoteAuthorID)
         if FriendZone.inboxEstablished(pairKey: pairKey) { return }
         let zoneID = FriendZone.inboxZoneID(pairKey: pairKey)
 
         syncMonitor?.recordStart("establish friendship")
         do {
             try await createZone(zoneID)
 
             // A sibling device on this same iCloud account may have already
             // created the inbox share; the per-device marker can't see its
             // work. If the share exists we adopt locally *without* re-creating
             // it or re-enqueuing the `.friend` Ping — already delivered.
             if try await existingZoneWideShare(zoneID: zoneID) != nil {
                 persistFriend(authorID: remoteAuthorID, pairKey: pairKey)
                 FriendZone.markInboxEstablished(pairKey: pairKey)
                 syncMonitor?.recordSuccess("establish friendship")
                 return
             }
 
             let share: CKShare
             do {
                 share = try await saveZoneWideShare(
                     zoneID: zoneID,
                     addingParticipant: remoteAuthorID
                 )
             } catch let error as CKError where error.code == .serverRecordChanged {
                 // Lost the create race to a sibling between the check above and
                 // this save. The share now exists; adopt it without re-sending.
                 persistFriend(authorID: remoteAuthorID, pairKey: pairKey)
                 FriendZone.markInboxEstablished(pairKey: pairKey)
                 syncMonitor?.recordSuccess("establish friendship")
                 return
             }
             guard let url = share.url else { throw FriendError.missingShareURL }
 
             persistFriend(authorID: remoteAuthorID, pairKey: pairKey)
             FriendZone.markInboxEstablished(pairKey: pairKey)
 
             let payload = FriendZone.BootstrapPayload(
                 friendShareURL: url.absoluteString,
                 pairKey: pairKey,
                 ownerAuthorID: localAuthorID
             )
             await syncEngine.enqueuePing(
                 kind: .friend,
                 gameID: viaGameID,
                 authorID: localAuthorID,
                 playerName: localDisplayName ?? "",
                 payload: payload.encodedString()
             )
             syncMonitor?.recordSuccess("establish friendship")
         } catch {
             syncMonitor?.recordError("establish friendship", error)
         }
     }
 
     /// Writes the local user's current name into a just-recorded friend zone
     /// as a `name` Decision, at the current (un-bumped) generation: a seed is
     /// "the name as of this friendship", never a rename, so it must lose to
     /// any real rename racing it. This is how a friend made *after* the last
     /// rename learns the name — the rename fan-out only reaches zones that
     /// existed at the time.
     private func seedOwnNameDecision(
         localAuthorID: String,
         localDisplayName: String?,
         zoneID: CKRecordZone.ID
     ) async {
         let name = (localDisplayName ?? "")
             .trimmingCharacters(in: .whitespacesAndNewlines)
         guard !name.isEmpty else { return }
         await syncEngine.enqueueNameDecision(
             authorID: localAuthorID,
             name: name,
             version: NameVersionStore.current(authorID: localAuthorID),
             zoneID: zoneID,
             // The seed is only ever written into the friend's inbox (our
             // outbox), a zone the friend owns.
             scope: .shared
         )
     }
 
     // MARK: - Participant side
 
     /// Handles an inbound `.friend` Ping: accepts the friend-zone share and
     /// records the friendship. Idempotent — a duplicate Ping for an
     /// already-established pair is dropped. `localAuthorID`/`localDisplayName`
     /// let the acceptor seed its own name Decision into the just-joined zone
     /// so the owner learns this side's name without waiting for a rename.
     func applyFriendPing(
         _ ping: Ping,
         localAuthorID: String?,
         localDisplayName: String?
     ) async {
         guard ping.kind == .friend,
               let payload = FriendZone.BootstrapPayload.decode(ping.payload)
         else { return }
         guard FriendZone.canAcceptBootstrap(payload, localAuthorID: localAuthorID) else { return }
         // Gate on whether we've accepted *their* inbox share, not on whether a
         // friendship row exists: our own `establish` may have created the row
         // already, but we still owe the accept that gives us write access to
         // their inbox (our outbox).
         if FriendZone.outboxAccepted(pairKey: payload.pairKey) { return }
         guard let url = URL(string: payload.friendShareURL) else { return }
 
         syncMonitor?.recordStart("accept friendship")
         do {
             let metadata = try await fetchShareMetadata(url: url)
             // The accepted zone is the friend's inbox — our outbox. Its owner
             // name is the friend's CloudKit user-record name.
             let outboxZoneID = metadata.share.recordID.zoneID
             // Both mailbox zones are deterministically named `friend-<pairKey>`,
             // so a legitimate outbox always matches. The share URL and the zone
             // it targets are attacker-controllable: a co-player can mint a share
             // on a zone he owns but *names* for another pair, and `payload.pairKey`
             // is already pinned to `ownerAuthorID` by `canAcceptBootstrap`. Reject
             // unless the accepted zone's name matches that pairKey, so a forged
             // share can't be bound to this friendship and used to flow forged
             // Decision/Ping records under a borrowed identity. Validate before
             // accepting so we never take on a mis-named zone at all.
             guard outboxZoneID.zoneName == FriendZone.zoneName(pairKey: payload.pairKey) else {
                 syncMonitor?.note("accept friendship rejected: accepted zone name does not match pair key")
                 return
             }
             // The name check alone is spoofable: a co-player can *name* his own
             // zone for the (us, Carol) pair and claim `ownerAuthorID: Carol` —
             // the pairKey then pins to Carol and both checks above pass, binding
             // Carol's friendship to a zone the forger owns (leaking our name/
             // invite key to him, letting his zone authenticate `.decline` Pings
             // as Carol, and blocking the real Carol's bootstrap behind
             // `outboxAccepted`). The zone's `ownerName` is CloudKit-authoritative
             // — it is the actual owner's user-record name, which a legitimate
             // outbox's owner always is — so also require it to be the claimed
             // friend. (Never `CKCurrentUserDefaultName` here: this is a fetched
             // share we don't own, and `canAcceptBootstrap` already rejects
             // self-pairs.)
             guard outboxZoneID.ownerName == payload.ownerAuthorID else {
                 syncMonitor?.note("accept friendship rejected: accepted zone owner does not match claimed friend")
                 return
             }
             try await accept(metadata)
             FriendZone.markOutboxAccepted(pairKey: payload.pairKey)
             persistFriend(authorID: payload.ownerAuthorID, pairKey: payload.pairKey)
             if let localAuthorID, !localAuthorID.isEmpty {
                 // Tell the friend our name by writing into their inbox (our
                 // outbox) — the first moment we have write access to it.
                 await seedOwnNameDecision(
                     localAuthorID: localAuthorID,
                     localDisplayName: localDisplayName,
                     zoneID: outboxZoneID
                 )
             }
             // Publish our per-pair invite encryption key into the outbox so the
             // friend can decrypt invite pushes we seal; self-heals on the next
             // push-registration refresh if this misses.
             Task { [weak self] in
                 await self?.publishFriendInvitationKey?(payload.pairKey, outboxZoneID, .shared)
             }
             syncMonitor?.recordSuccess("accept friendship")
             // `applyFriendPing` runs inside the `onPings` CKSyncEngine
             // delegate callback. Awaiting a call back into CKSyncEngine from
             // there trips its serialization guard and crashes
             // (CKSyncEngine.swift:293: "Cannot await a call into CKSyncEngine
             // from within a delegate callback"). Detach the post-accept
             // refresh so the delegate callback returns first; it only needs
             // to land eventually.
             // Detached (not a plain `Task {}`): a `Task {}` here inherits this
             // @MainActor context and can run `fetchChanges()` at one of the
             // delegate callback's own suspension points — before `handleEvent`
             // returns — so CKSyncEngine's guard still trips. A detached task
             // runs off this actor, after the callback unwinds. (`Task {}` was
             // the original, insufficient fix; the trap recurred in 2026.310.)
             Task.detached { [syncEngine, syncMonitor] in
                 await syncMonitor?.run("friendship accept fetch") {
                     try await syncEngine.fetchChanges()
                 }
             }
         } catch {
             syncMonitor?.recordError("accept friendship", error)
         }
     }
 
     // MARK: - Bootstrap heal
 
     /// Launch-time repair for half-established friendships. The `.friend`
     /// bootstrap Ping is delivered exactly once, via the carrier game zone's
     /// delta fetch; if the recipient's accept fails at that moment nothing
     /// ever re-sends it — `establish` is marker-gated and its adopt paths
     /// assume a sibling already delivered — so the pair is stuck: the friend
     /// never gains write access to our inbox and their `inviteFriend` throws
     /// `friendshipNotReady` forever.
     ///
     /// The inbox share's participant list is server truth for whether the
     /// friend got in. For each unblocked friend still not `.accepted` there,
     /// re-enqueue the bootstrap Ping through a game they collaborate on
     /// (re-adding the participant first if the share lost them). Healthy
     /// pairs cost one share fetch; a per-pair cooldown bounds Ping accrual
     /// while a friend's devices stay dormant. This heals the *friend's*
     /// missing acceptance — our own missing acceptance of their inbox is
     /// healed by the same pass running on their devices.
     func healPendingBootstraps(localAuthorID: String, localDisplayName: String?) async {
         guard !localAuthorID.isEmpty else { return }
 
         struct PendingPair {
             let friendAuthorID: String
             let pairKey: String
             let viaGameID: UUID?
         }
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "isBlocked == NO")
         let pairs: [PendingPair] = ((try? ctx.fetch(req)) ?? []).compactMap { friend in
             guard let authorID = friend.authorID, !authorID.isEmpty,
                   let pairKey = friend.pairKey
             else { return nil }
             return PendingPair(
                 friendAuthorID: authorID,
                 pairKey: pairKey,
                 viaGameID: Self.bootstrapCarrierGameID(friendAuthorID: authorID, in: ctx)
             )
         }
         guard !pairs.isEmpty else { return }
 
         var healthy = 0, announced = 0, skipped = 0
         for pair in pairs {
             do {
                 guard var share = try await existingZoneWideShare(
                     zoneID: FriendZone.inboxZoneID(pairKey: pair.pairKey)
                 ) else {
                     // Nothing to announce: the inbox share was never created.
                     // `establish` owns that repair.
                     skipped += 1
                     continue
                 }
                 let participant = share.participants.first {
                     $0.userIdentity.userRecordID?.recordName == pair.friendAuthorID
                 }
                 if participant?.acceptanceStatus == .accepted {
                     healthy += 1
                     continue
                 }
                 guard FriendZone.canAttemptBootstrapHeal(pairKey: pair.pairKey) else {
                     skipped += 1
                     continue
                 }
                 guard let viaGameID = pair.viaGameID else {
                     // No live carrier zone reaches this friend; a future
                     // shared game re-runs `establish` via reconcile anyway.
                     skipped += 1
                     continue
                 }
                 if participant == nil || participant?.acceptanceStatus == .removed {
                     // The friend can only accept a zone-wide share they are
                     // invited to (publicPermission is .none), so restore the
                     // participant before re-announcing.
                     let restored = try await fetchParticipant(
                         forUserRecordName: pair.friendAuthorID
                     )
                     restored.permission = .readWrite
                     share.addParticipant(restored)
                     guard let saved = try await container.privateCloudDatabase
                         .save(share) as? CKShare
                     else { throw FriendError.invalidShareRecord }
                     share = saved
                 }
                 guard let url = share.url else { throw FriendError.missingShareURL }
                 FriendZone.markBootstrapHealAttempted(pairKey: pair.pairKey)
                 let payload = FriendZone.BootstrapPayload(
                     friendShareURL: url.absoluteString,
                     pairKey: pair.pairKey,
                     ownerAuthorID: localAuthorID
                 )
                 await syncEngine.enqueuePing(
                     kind: .friend,
                     gameID: viaGameID,
                     authorID: localAuthorID,
                     playerName: localDisplayName ?? "",
                     payload: payload.encodedString()
                 )
                 announced += 1
                 syncMonitor?.note(
                     "friendship heal: re-announced inbox share to " +
                     "\(pair.friendAuthorID.prefix(8))… via game " +
                     "\(viaGameID.uuidString.prefix(8))"
                 )
             } catch {
                 skipped += 1
                 syncMonitor?.note(
                     "friendship heal: check failed for " +
                     "\(pair.friendAuthorID.prefix(8))… — \(error.localizedDescription)"
                 )
             }
         }
         syncMonitor?.note(
             "friendship heal: pairs=\(pairs.count) healthy=\(healthy) " +
             "announced=\(announced) skipped=\(skipped)"
         )
     }
 
     /// A collaborative game the friend is known to play, used as the carrier
     /// zone for a bootstrap re-announcement — their devices sync it, so the
     /// Ping reaches them. The most recently updated game is the liveliest
     /// channel.
     private static func bootstrapCarrierGameID(
         friendAuthorID: String,
         in ctx: NSManagedObjectContext
     ) -> UUID? {
         let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         req.predicate = NSPredicate(
             format: "authorID == %@ AND game.isAccessRevoked == NO AND " +
                 "(game.databaseScope == 1 OR game.ckShareRecordName != nil)",
             friendAuthorID
         )
         req.sortDescriptors = [NSSortDescriptor(key: "game.updatedAt", ascending: false)]
         req.fetchLimit = 1
         return (try? ctx.fetch(req).first)?.game?.id
     }
 
     // MARK: - Re-invite
 
     /// Writes an `.invite` Ping carrying the game's share URL into the friend
     /// zone. The friend must already be added as a participant on the game's
     /// `CKShare` (the caller does that via `ShareController` and passes the
     /// resulting URL in). No-ops for an unknown or blocked friend. The optional
     /// `gridSilhouette` is a `GridSilhouette`-encoded segment that lets the
     /// recipient's "Invited" row preview the puzzle's shape.
     func sendInvite(
         toFriendAuthorID friendAuthorID: String,
         gameID: UUID,
         gameTitle: String,
         inviterAuthorID: String,
         inviterName: String,
         gameShareURL: URL,
         gridSilhouette: String? = nil,
         puzzleSource: String? = nil,
         notification: String? = nil,
         rollbackParticipantOnFailure: Bool = false
     ) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", friendAuthorID)
         req.fetchLimit = 1
         guard let friend = try ctx.fetch(req).first else {
             throw FriendError.friendNotFound
         }
         guard !friend.isBlocked else { throw FriendError.friendBlocked }
         guard let pairKey = friend.pairKey else { throw FriendError.friendNotFound }
         try await ensureOutboxAccepted(pairKey: pairKey, friendAuthorID: friendAuthorID)
 
         let payload = FriendZone.InvitePayload(
             gameShareURL: gameShareURL.absoluteString,
             gridSilhouette: gridSilhouette,
             puzzleSource: puzzleSource,
             notification: notification
         )
         guard let encoded = payload.encodedString() else {
             throw FriendError.payloadEncodingFailed
         }
 
         try await syncEngine.enqueueFriendZonePing(
             kind: .invite,
             gameID: gameID,
             gameTitle: gameTitle,
             authorID: inviterAuthorID,
             playerName: inviterName,
             addressee: friendAuthorID,
             friendZoneID: FriendZone.outboxZoneID(pairKey: pairKey, friendAuthorID: friendAuthorID),
             friendZoneScope: .shared,
             payload: encoded,
             rollbackParticipantOnFailure: rollbackParticipantOnFailure,
             waitForServerConfirmation: true
         )
     }
 
     /// Writes a `.decline` Ping into the friend zone telling the inviter we
     /// turned down their game invite, so their device frees our seat on the
     /// game's `CKShare` and surfaces a banner. Mirrors `sendInvite` reversed:
     /// `declinerAuthorID` is us (the sender), `inviterAuthorID` the addressee.
     /// Carries no payload — `(gameID, declinerAuthorID)` fully identify the seat
     /// to free. No-ops for an unknown or blocked friend.
     func sendDecline(
         toInviterAuthorID inviterAuthorID: String,
         gameID: UUID,
         gameTitle: String,
         declinerAuthorID: String,
         declinerName: String
     ) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", inviterAuthorID)
         req.fetchLimit = 1
         guard let friend = try ctx.fetch(req).first else {
             throw FriendError.friendNotFound
         }
         guard !friend.isBlocked else { throw FriendError.friendBlocked }
         guard let pairKey = friend.pairKey else { throw FriendError.friendNotFound }
         try await ensureOutboxAccepted(pairKey: pairKey, friendAuthorID: inviterAuthorID)
 
         try await syncEngine.enqueueFriendZonePing(
             kind: .decline,
             gameID: gameID,
             gameTitle: gameTitle,
             authorID: declinerAuthorID,
             playerName: declinerName,
             addressee: inviterAuthorID,
             friendZoneID: FriendZone.outboxZoneID(pairKey: pairKey, friendAuthorID: inviterAuthorID),
             friendZoneScope: .shared
         )
     }
 
     /// Consume-deletes a directed Ping from the pairwise friend zone — an
     /// `.invite` once it has been accepted or found stale, or a `.decline` once
     /// the addressed inviter has freed the seat. Removing the source record
     /// stops it re-creating on the recipient's devices and withdraws any banner
     /// a sibling showed. `friendAuthorID` is the *other* party on the zone (the
     /// inviter for an invite we consume, the decliner for a decline we consume).
     func deleteFriendZonePing(fromFriendAuthorID friendAuthorID: String, recordName: String) async {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", friendAuthorID)
         req.fetchLimit = 1
         guard let friend = try? ctx.fetch(req).first,
               let pairKey = friend.pairKey
         else { return }
 
         // A consumed Ping is always one we *received* — an `.invite` we were
         // sent, or a `.decline` sent to us — so it lives in our own inbox (the
         // zone we own, private engine).
         await syncEngine.deletePing(
             recordName: recordName,
             zoneID: FriendZone.inboxZoneID(pairKey: pairKey),
             databaseScope: .private
         )
     }
 
     // MARK: - Block / Unblock
 
     /// Blocks a friend by downgrading them to `.readOnly` on the inbox we own,
     /// so they can no longer write invites / name / key records to us. This is
     /// server-enforced and inherently account-wide (one share), so every device
     /// on this account gets it for free; it is fully reversible by `unblock`,
     /// which upgrades the same participant back to `.readWrite`. The zone and
     /// share are left intact — nothing is torn down. The versioned `block`
     /// Decision converges the UI flag across our own devices.
     func block(friendAuthorID: String) async throws {
         try await setBlocked(friendAuthorID: friendAuthorID, blocked: true)
     }
 
     /// Reverses `block`: upgrades the friend back to `.readWrite` on our inbox
     /// and clears the local/UI flag. No carrier and no re-acceptance — the
     /// channel was never torn down.
     func unblock(friendAuthorID: String) async throws {
         try await setBlocked(friendAuthorID: friendAuthorID, blocked: false)
     }
 
     private func setBlocked(friendAuthorID: String, blocked: Bool) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", friendAuthorID)
         req.fetchLimit = 1
         guard let friend = try ctx.fetch(req).first,
               let pairKey = friend.pairKey
         else { return }
         let version = friend.blockVersion + 1
 
         let label = blocked ? "block friend" : "unblock friend"
         syncMonitor?.recordStart(label)
         do {
             try await setInboxParticipantPermission(
                 friendAuthorID: friendAuthorID,
                 pairKey: pairKey,
                 permission: blocked ? .readOnly : .readWrite
             )
             friend.isBlocked = blocked
             friend.blockVersion = version
             try ctx.save()
 
             // Converge the UI flag across our own devices. Enforcement itself is
             // the server-side share permission change above, which is
             // account-wide, so this Decision only needs to carry the flag
             // (versioned, so a stale copy can't resurrect a cleared block).
             await syncEngine.enqueueDecision(
                 kind: RecordSerializer.blockDecisionKind,
                 key: friendAuthorID,
                 payload: blocked ? "1" : "0",
                 version: version
             )
             syncMonitor?.recordSuccess(label)
         } catch {
             syncMonitor?.recordError(label, error)
             throw error
         }
     }
 
     /// Fetches the zone-wide `CKShare` on our inbox and sets the friend
     /// participant's permission, then saves. Fetch-then-save uses the server's
     /// current change tag so the permission write doesn't lose a tag race.
     private func setInboxParticipantPermission(
         friendAuthorID: String,
         pairKey: String,
         permission: CKShare.ParticipantPermission
     ) async throws {
         let zoneID = FriendZone.inboxZoneID(pairKey: pairKey)
         let shareID = CKRecord.ID(recordName: CKRecordNameZoneWideShare, zoneID: zoneID)
         let database = container.privateCloudDatabase
         guard let share = try await database.record(for: shareID) as? CKShare else {
             throw FriendError.invalidShareRecord
         }
         guard let participant = share.participants.first(where: {
             $0.userIdentity.userRecordID?.recordName == friendAuthorID
         }) else {
             throw FriendError.participantNotFound
         }
         participant.permission = permission
         _ = try await database.save(share)
     }
 
     /// Ensures this device has accepted the friend's inbox share before trying
     /// to write a Ping/Decision to it. The UserDefaults marker is the fast path;
     /// a direct shared-zone probe covers restored devices or marker loss after
     /// CloudKit has already delivered the accepted zone.
     func ensureOutboxReady(friendAuthorID: String) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", friendAuthorID)
         req.fetchLimit = 1
         guard let friend = try ctx.fetch(req).first else {
             throw FriendError.friendNotFound
         }
         guard !friend.isBlocked else { throw FriendError.friendBlocked }
         guard let pairKey = friend.pairKey else { throw FriendError.friendNotFound }
         try await ensureOutboxAccepted(pairKey: pairKey, friendAuthorID: friendAuthorID)
     }
 
     private func ensureOutboxAccepted(pairKey: String, friendAuthorID: String) async throws {
         if FriendZone.outboxAccepted(pairKey: pairKey) { return }
         let zoneID = FriendZone.outboxZoneID(pairKey: pairKey, friendAuthorID: friendAuthorID)
         if try await zoneExists(zoneID, in: container.sharedCloudDatabase) {
             FriendZone.markOutboxAccepted(pairKey: pairKey)
             return
         }
         throw FriendError.friendshipNotReady
     }
 
     // MARK: - Rename
 
     /// Sets (or, with an empty string, clears) the user's private nickname
     /// for a friend. The nickname lives on the local `FriendEntity` and is
     /// made authoritative across the user's own devices via a versioned
     /// `nickname` Decision in the account zone — the same channel `block`
     /// rides; it is never written into the friend zone, so the friend never
     /// sees it. Each rename bumps the per-friend generation so the newest
     /// rename wins any cross-device race (`applyDecisionRecord`).
     func setNickname(friendAuthorID: String, nickname: String) async throws {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "authorID == %@", friendAuthorID)
         req.fetchLimit = 1
         guard let friend = try ctx.fetch(req).first else {
             throw FriendError.friendNotFound
         }
         let trimmed = nickname.trimmingCharacters(in: .whitespacesAndNewlines)
         let version = friend.nicknameVersion + 1
         friend.nickname = trimmed.isEmpty ? nil : trimmed
         friend.nicknameVersion = version
         try ctx.save()
         FriendEntity.rebuildNicknameDirectory(in: ctx)
         // An empty payload propagates the clear: the Decision record stays
         // (preserving the version) but applies as "no nickname".
         await syncEngine.enqueueDecision(
             kind: RecordSerializer.nicknameDecisionKind,
             key: friendAuthorID,
             payload: trimmed.isEmpty ? nil : trimmed,
             version: version
         )
     }
 
     // MARK: - CloudKit helpers
 
     private func createZone(_ zoneID: CKRecordZone.ID) async throws {
         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)
         }
     }
 
     private func saveZoneWideShare(
         zoneID: CKRecordZone.ID,
         addingParticipant remoteAuthorID: String
     ) async throws -> CKShare {
         let share = CKShare(recordZoneID: zoneID)
         share.publicPermission = .none
         let participant = try await fetchParticipant(forUserRecordName: remoteAuthorID)
         participant.permission = .readWrite
         share.addParticipant(participant)
         let saved = try await container.privateCloudDatabase.save(share)
         guard let savedShare = saved as? CKShare else {
             throw FriendError.invalidShareRecord
         }
         return savedShare
     }
 
     /// The zone-wide `CKShare` for `zoneID` in our private database, or `nil`
     /// if it doesn't exist yet. Lets an owner-side device detect a friend zone
     /// a sibling device on the same iCloud account already shared.
     private func existingZoneWideShare(
         zoneID: CKRecordZone.ID
     ) async throws -> CKShare? {
         let shareID = CKRecord.ID(
             recordName: CKRecordNameZoneWideShare,
             zoneID: zoneID
         )
         do {
             let record = try await container.privateCloudDatabase.record(for: shareID)
             return record as? CKShare
         } catch let error as CKError
             where error.code == .unknownItem || error.code == .zoneNotFound {
             return nil
         }
     }
 
     private func zoneExists(_ zoneID: CKRecordZone.ID, in database: CKDatabase) async throws -> Bool {
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Bool, Error>) in
             var exists = false
             var perZoneError: Error?
             let op = CKFetchRecordZonesOperation(recordZoneIDs: [zoneID])
             op.qualityOfService = .userInitiated
             op.perRecordZoneResultBlock = { _, result in
                 switch result {
                 case .success:
                     exists = true
                 case .failure(let error as CKError)
                     where error.code == .zoneNotFound || error.code == .unknownItem:
                     exists = false
                 case .failure(let error):
                     perZoneError = error
                 }
             }
             op.fetchRecordZonesResultBlock = { result in
                 switch result {
                 case .success:
                     if let perZoneError {
                         cont.resume(throwing: perZoneError)
                     } else {
                         cont.resume(returning: exists)
                     }
                 case .failure(let error as CKError)
                     where error.code == .zoneNotFound || error.code == .unknownItem:
                     cont.resume(returning: false)
                 case .failure(let error):
                     cont.resume(throwing: error)
                 }
             }
             database.add(op)
         }
     }
 
     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: FriendError.participantNotFound)
                     }
                 case .failure(let error):
                     cont.resume(throwing: error)
                 }
             }
             self.container.add(op)
         }
     }
 
     private func fetchShareMetadata(url: URL) async throws -> CKShare.Metadata {
         try await withCheckedThrowingContinuation { cont in
             var metadata: CKShare.Metadata?
             let op = CKFetchShareMetadataOperation(shareURLs: [url])
             op.shouldFetchRootRecord = false
             op.perShareMetadataResultBlock = { _, result in
                 if case .success(let m) = result { metadata = m }
             }
             op.fetchShareMetadataResultBlock = { result in
                 switch result {
                 case .success:
                     if let metadata {
                         cont.resume(returning: metadata)
                     } else {
                         cont.resume(throwing: FriendError.invalidShareRecord)
                     }
                 case .failure(let error):
                     cont.resume(throwing: error)
                 }
             }
             self.container.add(op)
         }
     }
 
     private func accept(_ metadata: CKShare.Metadata) async throws {
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             let op = CKAcceptSharesOperation(shareMetadatas: [metadata])
             op.acceptSharesResultBlock = { result in cont.resume(with: result) }
             self.container.add(op)
         }
     }
 
     // MARK: - Core Data
 
     /// Records the friendship row. The display name is deliberately *not*
     /// written here — it arrives exclusively via the friend's `name` Decision
     /// (`RecordSerializer.applyDecisionRecord`); until that syncs, the invite
     /// surfaces fall back to the freshest per-game Player snapshot, then
     /// "Player". Both mailbox zones are derivable from `pairKey` + `authorID`,
     /// so no zone fields are stored. The invite encryption key is published from
     /// `applyFriendPing` instead — the first point we have outbox write access.
     private func persistFriend(authorID: String, pairKey: String) {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
         req.predicate = NSPredicate(format: "pairKey == %@", pairKey)
         req.fetchLimit = 1
         let entity = (try? ctx.fetch(req).first) ?? FriendEntity(context: ctx)
         entity.authorID = authorID
         entity.pairKey = pairKey
         if entity.createdAt == nil { entity.createdAt = Date() }
         do {
             try ctx.save()
             Task { [weak self] in
                 await self?.applyAccountNicknameDecisionIfPresent(for: authorID)
             }
         } catch {
             eventLog?.note("FriendController: persistFriend save failed — \(error)", level: "error")
         }
     }
 
     /// A sibling can set a nickname before this device has bootstrapped the
     /// `FriendEntity`. CKSyncEngine will then advance past the account-zone
     /// Decision without applying it because there is no friend row yet. After
     /// bootstrap creates the row, fetch the deterministic Decision directly
     /// and replay it once.
     func applyAccountNicknameDecisionIfPresent(for friendAuthorID: String) async {
         let recordName = RecordSerializer.decisionRecordName(
             kind: RecordSerializer.nicknameDecisionKind,
             key: friendAuthorID
         )
         let recordID = CKRecord.ID(
             recordName: recordName,
             zoneID: RecordSerializer.accountZoneID
         )
         do {
             let record = try await fetchAccountDecisionRecord(recordID)
             let ctx = persistence.viewContext
             let wrote = RecordSerializer.applyDecisionRecord(
                 record,
                 to: ctx,
                 localAuthorID: nil,
                 databaseScope: .private
             )
             if wrote {
                 try ctx.save()
                 FriendEntity.rebuildNicknameDirectory(in: ctx)
                 eventLog?.note(
                     "FriendController: replayed nickname decision \(recordName)",
                     level: "info"
                 )
             }
         } catch let error as CKError
             where error.code == .unknownItem || error.code == .zoneNotFound {
             // Most friendships will not have a private nickname yet.
         } catch {
             eventLog?.note(
                 "FriendController: nickname decision replay failed for \(friendAuthorID) — \(error)",
                 level: "error"
             )
         }
     }
 }
 
 extension FriendController.FriendError: LocalizedError {
     var errorDescription: String? {
         switch self {
         case .invalidShareRecord:
             return "The crossmate record in iCloud is invalid."
         case .missingShareURL, .missingShareURLInPayload:
             return "The crossmate share link is missing."
         case .participantNotFound:
             return "That player could not be found in iCloud."
         case .friendNotFound:
             return "That Crossmate is not available yet."
         case .friendBlocked:
             return "That Crossmate is blocked."
         case .friendshipNotReady:
             return "This Crossmate is still syncing. Try again in a moment."
         case .payloadEncodingFailed:
             return "The invitation could not be prepared."
         }
     }
 }