crossmate

RecordSerializer.swift (78687B)

---

 import CloudKit
 import CoreData
 import CryptoKit
 import Foundation
 
 /// Pure-function helpers for converting between the app's Core Data / in-memory
 /// models and CloudKit `CKRecord` objects. Stateless — all context is passed in.
 enum RecordSerializer {
 
     // MARK: - Direct fetch key sets
 
     static let gameDesiredKeys: [CKRecord.FieldKey] = [
         "title",
         "completedAt",
         "completedBy",
         "shareRecordName",
         "roomCredential",
         "pushCredential",
         "puzzleSource",
         "syncVersion",
     ]
 
     // authorID/deviceID are not stored as fields — they're recovered from the
     // record name (`moves-<gameID>-<authorID>-<deviceID>`).
     static let movesDesiredKeys: [CKRecord.FieldKey] = [
         "cells",
         "updatedAt",
     ]
 
     // authorID is recovered from the record name (`player-<gameID>-<authorID>`).
     static let playerDesiredKeys: [CKRecord.FieldKey] = [
         "name",
         "updatedAt",
         "selRow",
         "selCol",
         "selDir",
         "presenceUntil",
         "readThrough",
         "viewedAt",
         "timeLog",
         "pushAddress",
     ]
 
     // authorID/deviceID are recovered from the record name.
     static let pingDesiredKeys: [CKRecord.FieldKey] = [
         "playerName",
         "puzzleTitle",
         "kind",
         "payload",
         "addressee",
     ]
 
     static let pingDeletionDesiredKeys: [CKRecord.FieldKey] = [
         "kind",
     ]
 
     // MARK: - Device identity
 
     /// A stable per-device identifier appended to move and snapshot record
     /// names to prevent two devices owned by the same iCloud user from
     /// producing identical record names when both assign the same Lamport
     /// clock value while offline.
     ///
     /// Stored in UserDefaults so it survives app restarts but resets on
     /// reinstall (which is fine — a reinstalled app has no local moves to
     /// conflict with).
     static let localDeviceID: String = {
         let key = "crossmate.localDeviceID"
         if let stored = UserDefaults.standard.string(forKey: key) {
             return stored
         }
         let new = UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
         UserDefaults.standard.set(new, forKey: key)
         return new
     }()
 
     // MARK: - Record names
 
     static func recordName(forGameID gameID: UUID) -> String {
         "game-\(gameID.uuidString)"
     }
 
     /// Recovers the game UUID from a `"game-<UUID>"` record or zone name — the
     /// inverse of `recordName(forGameID:)`. Returns nil when the name isn't a
     /// game name or the UUID doesn't parse. A game's zone name and its root
     /// record name are identical, so this also resolves a share's zone.
     static func gameID(fromGameRecordName name: String) -> UUID? {
         guard name.hasPrefix("game-") else { return nil }
         return UUID(uuidString: String(name.dropFirst("game-".count)))
     }
 
     /// One Moves record per `(game, authorID, deviceID)`. Each device only
     /// writes to its own slot, so there are no write-write conflicts on the
     /// `cells` field.
     static func recordName(
         forMovesInGame gameID: UUID,
         authorID: String,
         deviceID: String
     ) -> String {
         "moves-\(gameID.uuidString)-\(authorID)-\(deviceID)"
     }
 
     /// One Journal record per `(game, authorID, deviceID)` — this device's
     /// whole local move log, uploaded once at completion (Phase 2). Same
     /// `(game, author, device)` shape as the Moves record so collaborators'
     /// uploads stay distinct and mergeable by timestamp for replay.
     static func recordName(
         forJournalInGame gameID: UUID,
         authorID: String,
         deviceID: String
     ) -> String {
         "journal-\(gameID.uuidString)-\(authorID)-\(deviceID)"
     }
 
     /// One player record per (game, author). Each participant only ever
     /// writes to their own slot, so there are no write-write conflicts on
     /// the field.
     static func recordName(forPlayerInGame gameID: UUID, authorID: String) -> String {
         "player-\(gameID.uuidString)-\(authorID)"
     }
 
     /// One Ping record per event. `deviceID` keeps cross-device writes from
     /// the same iCloud user unique (authorID is identical across that user's
     /// devices), and the event timestamp covers repeated pings from the same
     /// device.
     static func recordName(
         forPingInGame gameID: UUID,
         authorID: String,
         deviceID: String,
         eventTimestampMs: Int64
     ) -> String {
         "ping-\(gameID.uuidString)-\(authorID)-\(deviceID)-\(eventTimestampMs)"
     }
 
     /// One `Decision` record per `(kind, key)`. A durable, per-user fact that
     /// must agree across a single iCloud user's own devices — the durable
     /// counterpart to the transient `Ping`. Lives in the account zone; the
     /// deterministic name makes every write an idempotent upsert. `kind`
     /// carries no dashes (so the first dash after the prefix splits cleanly);
     /// `key` may contain dashes.
     static func decisionRecordName(kind: String, key: String) -> String {
         "decision-\(kind)-\(key)"
     }
 
     /// Parses `decision-<kind>-<key>`. `kind` is the segment up to the first
     /// dash after the prefix; `key` is the remainder.
     static func parseDecisionRecordName(_ name: String) -> (kind: String, key: String)? {
         let prefix = "decision-"
         guard name.hasPrefix(prefix) else { return nil }
         let rest = name.dropFirst(prefix.count)
         guard let dash = rest.firstIndex(of: "-") else { return nil }
         let kind = String(rest[rest.startIndex..<dash])
         let key = String(rest[rest.index(after: dash)...])
         guard !kind.isEmpty, !key.isEmpty else { return nil }
         return (kind, key)
     }
 
     /// Kind for the display-name Decision: `decision-name-<authorID>`, payload
     /// = the display name, `version` = the author's monotonic rename
     /// generation. The author writes their own copy into their account zone
     /// (own-device convergence and restore durability) and into every friend
     /// zone they participate in (the friend's devices read it from there) —
     /// names never sync through any other channel.
     static let nameDecisionKind = "name"
 
     static func nameDecisionName(authorID: String) -> String {
         decisionRecordName(kind: nameDecisionKind, key: authorID)
     }
 
     /// Parses a display-name Decision into its subject author, name, and
     /// version. Returns `nil` for any other decision or an empty payload.
     static func parseNameDecision(
         _ record: CKRecord
     ) -> (authorID: String, name: String, version: Int64)? {
         guard record.recordType == "Decision",
               let (kind, key) = parseDecisionRecordName(record.recordID.recordName),
               kind == nameDecisionKind,
               ((record["kind"] as? String) ?? nameDecisionKind) == nameDecisionKind,
               let name = record["payload"] as? String,
               !name.isEmpty
         else { return nil }
         return (key, name, decisionVersion(record))
     }
 
     /// Kind for the friend-nickname Decision: `decision-nickname-<authorID>`,
     /// payload = the nickname this user privately calls that friend (absent or
     /// empty = cleared, fall back to the friend's own name), `version` = this
     /// user's monotonic rename generation for that friend. Lives only in the
     /// account zone — it's the user's own label, never shared with the friend.
     static let nicknameDecisionKind = "nickname"
     static let encryptionKeyDecisionKind = "encryptionKey"
 
     /// Kind for the friend-block Decision: `decision-block-<authorID>`, payload
     /// `"1"` blocked / `"0"` unblocked, `version` = this user's monotonic block
     /// generation for that friend. Lives only in the account zone and converges
     /// the *UI* flag across the user's own devices — the actual enforcement is
     /// the server-side `.readOnly` downgrade on the inbox share, which is
     /// inherently account-wide.
     static let blockDecisionKind = "block"
 
     static let accountDecisionKind = "account"
     static let accountPushAddressDecisionKey = "pushAddress"
     /// Key for the account-wide push *secret* decision. The secret is the HMAC
     /// key from which every per-game push address is derived (see
     /// `deriveGameAddress`); it converges across the account's own devices the
     /// same way the account address does, and is never sent to peers or the
     /// push worker — only the derived per-game addresses are.
     static let accountPushSecretDecisionKey = "pushSecret"
 
     static var accountPushAddressDecisionName: String {
         decisionRecordName(kind: accountDecisionKind, key: accountPushAddressDecisionKey)
     }
 
     static var accountPushSecretDecisionName: String {
         decisionRecordName(kind: accountDecisionKind, key: accountPushSecretDecisionKey)
     }
 
     /// A push-address/secret Decision is authoritative only from *this
     /// account's* zone in the private database. Match on zone name + private
     /// scope, mirroring the `nickname` case in `applyDecisionRecord`: a friend
     /// holds `.readWrite` on our private `friend-<pairKey>` inbox (also scope
     /// 0), so without the zone-name check a forged `decision-account-pushSecret`
     /// dropped there would be adopted as our own HMAC secret and re-derive every
     /// per-game push address. An `==` on the full `zoneID` is unreliable — a
     /// record fetched back from CloudKit often loses the
     /// `CKCurrentUserDefaultName` owner placeholder — so match the name.
     static func isAccountZonePrivateDecision(
         _ record: CKRecord,
         databaseScope: DatabaseScope
     ) -> Bool {
         record.recordID.zoneID.zoneName == accountZoneID.zoneName
             && databaseScope == .private
     }
 
     static func parseAccountPushAddressDecision(
         _ record: CKRecord,
         databaseScope: DatabaseScope
     ) -> String? {
         guard record.recordType == "Decision",
               record.recordID.recordName == accountPushAddressDecisionName,
               (record["kind"] as? String) == accountDecisionKind,
               isAccountZonePrivateDecision(record, databaseScope: databaseScope),
               let address = record["payload"] as? String,
               !address.isEmpty
         else { return nil }
         return address
     }
 
     /// Default generation for a `version`-less Decision — any record written by
     /// the pre-rotation code. Matched to the value a fresh mint uses so legacy
     /// and freshly-minted secrets share a generation and converge via the
     /// equal-version "server wins" rule, while a deliberate rotation (2+)
     /// supersedes them. Mapping to 0 instead would let the first post-update
     /// mint clobber an already-converged legacy secret.
     static let decisionBaseVersion: Int64 = 1
 
     /// The monotonic generation of a Decision. Higher wins: an inbound or
     /// conflicting record at a higher version supersedes the local value; equal
     /// versions converge on whoever reached the server first. Absent (legacy)
     /// records report `decisionBaseVersion`.
     static func decisionVersion(_ record: CKRecord) -> Int64 {
         (record["version"] as? Int64) ?? decisionBaseVersion
     }
 
     static func parseAccountPushSecretDecision(
         _ record: CKRecord,
         databaseScope: DatabaseScope
     ) -> (secret: String, version: Int64)? {
         guard record.recordType == "Decision",
               record.recordID.recordName == accountPushSecretDecisionName,
               (record["kind"] as? String) == accountDecisionKind,
               isAccountZonePrivateDecision(record, databaseScope: databaseScope),
               let secret = record["payload"] as? String,
               !secret.isEmpty
         else { return nil }
         return (secret, decisionVersion(record))
     }
 
     /// Derives this account's push address for one game as
     /// `HMAC-SHA256(secret, gameID)`, base64url-encoded. Deterministic, so every
     /// one of the account's devices computes the identical address for a game
     /// without any negotiation, and per-game scoped: a peer holding one game's
     /// address can't compute another's without the secret, which never leaves
     /// the account's devices. Rotation is by changing the secret.
     static func deriveGameAddress(secret: String, gameID: UUID) -> String {
         let key = SymmetricKey(data: Data(secret.utf8))
         let mac = HMAC<SHA256>.authenticationCode(
             for: Data(gameID.uuidString.utf8),
             using: key
         )
         return Data(mac).base64EncodedString()
             .replacingOccurrences(of: "+", with: "-")
             .replacingOccurrences(of: "/", with: "_")
             .replacingOccurrences(of: "=", with: "")
     }
 
     // MARK: - Zone
 
     /// Zone ID for a per-game zone. `ownerName` defaults to the current user
     /// placeholder; pass an explicit value for shared games where the zone is
     /// owned by another iCloud account.
     static func zoneID(
         for gameID: UUID,
         ownerName: String = CKCurrentUserDefaultName
     ) -> CKRecordZone.ID {
         CKRecordZone.ID(zoneName: "game-\(gameID.uuidString)", ownerName: ownerName)
     }
 
     // MARK: - Inbound record identity
 
     /// The record types that live in per-game zones (plus the archive zone)
     /// and therefore must pass `isTrustedGameScopedRecord` /
     /// `isTrustedGameScopedDeletion` before touching a game-scoped apply
     /// path. Everything else (Decision, share metadata, …) has its own
     /// zone/scope gates.
     static func isGameScopedRecordType(_ type: CKRecord.RecordType) -> Bool {
         switch type {
         case "Game", "Moves", "Player", "Ping", "Journal",
              Archive.recordType, Archive.legacyRecordType:
             return true
         default:
             return false
         }
     }
 
     /// CloudKit reports the creator of a record that the *fetching* user
     /// created themselves as the `CKCurrentUserDefaultName` placeholder, not
     /// their concrete user-record name — so the placeholder must be accepted
     /// alongside the claimed author, or every self-authored record is
     /// rejected when it round-trips (fresh install, second device, replay).
     /// This does not weaken the impersonation defense: a record created by a
     /// *remote* participant always arrives with their concrete creator ID,
     /// never the placeholder.
     private static func creatorMatches(
         _ creatorUserRecordName: String?,
         claimedAuthorID: String
     ) -> Bool {
         creatorUserRecordName == claimedAuthorID
             || creatorUserRecordName == CKCurrentUserDefaultName
     }
 
     /// Returns whether a fetched record is safe to route into a game-scoped
     /// apply path. Record names are writable by share participants, so they
     /// are only an assertion until they agree with CloudKit's zone identity.
     ///
     /// Moves, Player, Journal, and Ping records additionally claim an author
     /// in their name. CloudKit supplies the immutable creator identity for a
     /// record; require it to match so a collaborator cannot create a new row
     /// in their own name space that impersonates another participant. `Game`
     /// has no claimed author — its root record is authenticated by requiring
     /// its record name to be exactly the per-game zone name.
     static func isTrustedGameScopedRecord(_ record: CKRecord) -> Bool {
         isTrustedGameScopedRecord(
             record,
             creatorUserRecordName: record.creatorUserRecordID?.recordName
         )
     }
 
     /// Variant used by tests to exercise CloudKit provenance without needing
     /// a server-created CKRecord.
     static func isTrustedGameScopedRecord(
         _ record: CKRecord,
         creatorUserRecordName: String?
     ) -> Bool {
         let recordID = record.recordID
         switch record.recordType {
         case "Game":
             guard let gameID = gameID(fromGameRecordName: recordID.recordName) else {
                 return false
             }
             return recordID.zoneID.zoneName == recordName(forGameID: gameID)
 
         case "Moves":
             guard let (gameID, authorID, _) = parseMovesRecordName(recordID.recordName) else {
                 return false
             }
             return recordID.zoneID.zoneName == recordName(forGameID: gameID)
                 && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
 
         case "Player":
             guard let (gameID, authorID) = parsePlayerRecordName(recordID.recordName) else {
                 return false
             }
             return recordID.zoneID.zoneName == recordName(forGameID: gameID)
                 && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
 
         case "Journal":
             guard let (gameID, authorID, _) = parseJournalRecordName(recordID.recordName) else {
                 return false
             }
             return recordID.zoneID.zoneName == recordName(forGameID: gameID)
                 && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
 
         case "Ping":
             guard let (gameID, authorID, _) = parsePingRecordName(recordID.recordName),
                   creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
             else { return false }
             // Friend-zone pings deliberately carry the target game's ID while
             // living in a deterministic friend mailbox. Game-zone pings must
             // still be confined to the game named by their record.
             return !recordID.zoneID.zoneName.hasPrefix("game-")
                 || recordID.zoneID.zoneName == recordName(forGameID: gameID)
 
         case Archive.recordType:
             guard let gameID = Archive.originalGameID(fromName: recordID.recordName),
                   recordID.recordName == Archive.recordName(forOriginalGameID: gameID),
                   recordID.zoneID.zoneName == Archive.zoneName
             else { return false }
             return true
 
         case Archive.legacyRecordType:
             guard let gameID = Archive.originalGameID(fromName: recordID.recordName),
                   recordID.recordName == Archive.legacyRecordName(
                     forOriginalGameID: gameID
                   ),
                   recordID.zoneID.zoneName == Archive.legacyZoneID(
                     forOriginalGameID: gameID
                   ).zoneName
             else { return false }
             return true
 
         default:
             return false
         }
     }
 
     /// Deletions do not carry creator metadata, but CloudKit does retain their
     /// full record identity. Reject a deletion whose name is not confined to
     /// the game zone before it can match a local row. Only consulted for
     /// `isGameScopedRecordType` types; anything else is out of scope here.
     static func isTrustedGameScopedDeletion(
         recordID: CKRecord.ID,
         recordType: CKRecord.RecordType
     ) -> Bool {
         let gameID: UUID?
         switch recordType {
         case "Game":
             gameID = Self.gameID(fromGameRecordName: recordID.recordName)
         case "Moves":
             gameID = parseMovesRecordName(recordID.recordName)?.0
         case "Player":
             gameID = parsePlayerRecordName(recordID.recordName)?.0
         case "Journal":
             gameID = parseJournalRecordName(recordID.recordName)?.0
         case "Ping":
             // Same confinement rule as the record case: a friend-mailbox ping
             // names a game outside its zone by design; a game-zone ping must
             // name its own zone's game.
             guard let (pingGameID, _, _) = parsePingRecordName(recordID.recordName) else {
                 return false
             }
             return !recordID.zoneID.zoneName.hasPrefix("game-")
                 || recordID.zoneID.zoneName == recordName(forGameID: pingGameID)
         case Archive.recordType:
             guard let originalID = Archive.originalGameID(fromName: recordID.recordName) else {
                 return false
             }
             return recordID.recordName == Archive.recordName(forOriginalGameID: originalID)
                 && recordID.zoneID.zoneName == Archive.zoneName
         case Archive.legacyRecordType:
             guard let originalID = Archive.originalGameID(fromName: recordID.recordName) else {
                 return false
             }
             return recordID.recordName == Archive.legacyRecordName(
                 forOriginalGameID: originalID
             ) && recordID.zoneID.zoneName == Archive.legacyZoneID(
                 forOriginalGameID: originalID
             ).zoneName
         default:
             return false
         }
         guard let gameID else { return false }
         return recordID.zoneID.zoneName == recordName(forGameID: gameID)
     }
 
     /// Matches the local row for a record by its full zone identity, so a
     /// private-zone record can never match a same-named shared-zone row (or
     /// vice versa, or two shares of the same game by different owners).
     ///
     /// The owner name participates only for shared-database zones. CloudKit
     /// does not reliably round-trip the `CKCurrentUserDefaultName` placeholder
     /// for the current user's own zones — a fetched zone ID often carries the
     /// concrete user-record ID instead (see `isAccountZonePrivateDecision`) —
     /// so private rows always store `nil` and match on zone name alone, which
     /// is unambiguous there: every private-database zone belongs to the
     /// current user.
     static func gameIdentityPredicate(
         recordName: String,
         zoneID: CKRecordZone.ID,
         databaseScope: DatabaseScope,
         entityPrefix: String = ""
     ) -> NSPredicate {
         let zonePrefix = entityPrefix.isEmpty ? "" : "\(entityPrefix)."
         if databaseScope == .private {
             return NSPredicate(
                 format: "ckRecordName == %@ AND \(zonePrefix)ckZoneName == %@ AND \(zonePrefix)ckZoneOwnerName == NIL",
                 recordName,
                 zoneID.zoneName
             )
         }
         return NSPredicate(
             format: "ckRecordName == %@ AND \(zonePrefix)ckZoneName == %@ AND \(zonePrefix)ckZoneOwnerName == %@",
             recordName,
             zoneID.zoneName,
             zoneID.ownerName
         )
     }
 
     /// Zone ID for the user's account-wide zone in the private database. Holds
     /// records that coordinate state between a single iCloud user's own
     /// devices — never shared with collaborators, since the private database
     /// itself isn't reachable to anyone else.
     static let accountZoneID = CKRecordZone.ID(
         zoneName: "account",
         ownerName: CKCurrentUserDefaultName
     )
 
     // MARK: - Moves record building
 
     static func movesRecord(
         from view: MovesValue,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) throws -> CKRecord {
         let movesName = recordName(
             forMovesInGame: view.gameID,
             authorID: view.authorID,
             deviceID: view.deviceID
         )
         let record = restoreOrCreate(
             recordType: "Moves",
             recordName: movesName,
             zone: zone,
             systemFields: systemFields
         )
 
         // authorID/deviceID live in the record name, not as fields.
         record["updatedAt"] = view.updatedAt as CKRecordValue
         record["cells"] = try MovesCodec.encode(view.cells) as CKRecordValue
 
         return record
     }
 
     // MARK: - Journal record building
 
     /// Builds the `Journal` record carrying this device's full move log as a
     /// `CKAsset`. Write-once at completion, so there is no system-fields
     /// archive (mirrors `Ping`/`Decision`): a fresh record each build, and a
     /// re-send of an already-uploaded journal is a benign conflict the send
     /// path drops. The encoded entries are written to a temp file the same way
     /// `populateGameRecord` stages `puzzleSource` — CloudKit copies the asset
     /// on upload and the OS reaps the temporary directory.
     static func journalRecord(
         gameID: UUID,
         authorID: String,
         deviceID: String,
         updatedAt: Date,
         entries: [JournalValue],
         zone: CKRecordZone.ID
     ) throws -> CKRecord {
         let name = recordName(forJournalInGame: gameID, authorID: authorID, deviceID: deviceID)
         let recordID = CKRecord.ID(recordName: name, zoneID: zone)
         let record = CKRecord(recordType: "Journal", recordID: recordID)
         // authorID/deviceID live in the record name, not as fields.
         record["updatedAt"] = updatedAt as CKRecordValue
 
         let data = try JournalCodec.encode(entries)
         let url = FileManager.default.temporaryDirectory
             .appendingPathComponent(UUID().uuidString)
             .appendingPathExtension("json")
         try data.write(to: url, options: .atomic)
         record["entries"] = CKAsset(fileURL: url)
 
         return record
     }
 
     static func gameRecord(
         from entity: GameEntity,
         recordID: CKRecord.ID,
         includePuzzleSource: Bool
     ) -> CKRecord? {
         guard entity.ckRecordName != nil else { return nil }
         let record: CKRecord
         if let fields = entity.ckSystemFields,
            let restored = decodeRecord(from: fields) {
             record = restored
         } else {
             record = CKRecord(recordType: "Game", recordID: recordID)
         }
         populateGameRecord(record, from: entity, includePuzzleSource: includePuzzleSource)
         return record
     }
 
     static func populateGameRecord(
         _ record: CKRecord,
         from entity: GameEntity,
         includePuzzleSource: Bool
     ) {
         // `title`, `shareRecordName`, and `syncVersion` are owner-authoritative:
         // the title and protocol come from the game the owner created, and only
         // owner devices track the share record. A participant only re-saves this record to
         // mint the engagement/notification creds below, and at join time its
         // local `title` is still the transient "Joining…" placeholder
         // (`SyncEngine.handleFetchedDatabaseChanges`) until the owner's Game
         // record lands. Writing it from a participant would LWW-clobber the real
         // title on the shared record for everyone — so a non-owner leaves these
         // fields untouched and the server keeps the owner's value.
         let isOwner = entity.databaseScope == 0
         if isOwner {
             record["title"] = entity.title as CKRecordValue?
             // Owner-side share marker. Propagated so other owner-devices can flip
             // their `isShared` flag without reading the zone's CKShare directly.
             record["shareRecordName"] = entity.ckShareRecordName as CKRecordValue?
             record["syncVersion"] = GameSyncVersion.normalized(entity.syncVersion) as CKRecordValue
         }
         // Completion is terminal. A metadata-only save from a participant with
         // a stale local row must not clear a completion already present in the
         // restored server record.
         if let completedAt = entity.completedAt {
             record["completedAt"] = completedAt as CKRecordValue
             // Solver's authorID on a win; nil for a resignation.
             record["completedBy"] = entity.completedBy as CKRecordValue?
         }
         // The shared live-engagement room credentials (encoded
         // EngagementRoomCredentials). Any present participant may mint these
         // when the field is empty; convergence is plain record-level LWW, and
         // peers connect to whatever creds the field currently holds.
         // Stored as UTF-8 BYTES (matching cells/timeLog), not STRING — these
         // are opaque JSON blobs, not queryable text.
         record["roomCredential"] = entity.engagement?.data(using: .utf8) as CKRecordValue?
         // The shared per-game notification credentials (encoded
         // GamePushCredentials: the push auth secret + credID, plus the
         // worker-blind content key the payload is encrypted under). Synced to
         // participants like `engagement`; any participant may mint it when
         // empty, and record-level LWW converges concurrent mints.
         record["pushCredential"] = entity.notification?.data(using: .utf8) as CKRecordValue?
         guard includePuzzleSource, let source = entity.puzzleSource else { return }
         let url = FileManager.default.temporaryDirectory
             .appendingPathComponent(UUID().uuidString)
             .appendingPathExtension("xd")
         try? source.write(to: url, atomically: true, encoding: .utf8)
         record["puzzleSource"] = CKAsset(fileURL: url)
     }
 
     /// Builds a freshly-minted Ping record. Pings are write-once — they have
     /// no Core Data equivalent and no system-fields archive.
     /// - `authorID` + `deviceID` together let receivers filter out self-sends.
     ///   authorID alone is insufficient for kinds (e.g. `.opened`) that fire
     ///   between a single user's own devices, where authorID is identical.
     /// - `playerName` and `puzzleTitle` let receivers render the alert body.
     /// - `kind` distinguishes the bootstrap kinds current clients write
     ///   (.friend / .invite / .decline); legacy `.join`/`.hail` records
     ///   remain parseable but are no longer produced.
     static func pingRecord(
         gameID: UUID,
         authorID: String,
         deviceID: String,
         playerName: String,
         puzzleTitle: String,
         eventTimestampMs: Int64,
         kind: PingKind,
         payload: String? = nil,
         addressee: String? = nil,
         zone: CKRecordZone.ID
     ) -> CKRecord {
         let name = recordName(
             forPingInGame: gameID,
             authorID: authorID,
             deviceID: deviceID,
             eventTimestampMs: eventTimestampMs
         )
         let recordID = CKRecord.ID(recordName: name, zoneID: zone)
         let record = CKRecord(recordType: "Ping", recordID: recordID)
         // authorID/deviceID live in the record name, not as fields.
         record["playerName"] = playerName as CKRecordValue
         record["puzzleTitle"] = puzzleTitle as CKRecordValue
         record["kind"] = kind.rawValue as CKRecordValue
         // Directed pings target one player by authorID; nil ⇒ broadcast (every
         // recipient acts on it).
         if let addressee {
             record["addressee"] = addressee as CKRecordValue
         }
         if let payload {
             record["payload"] = payload as CKRecordValue
         }
         return record
     }
 
     /// Builds a `Decision` record. The identity (`kind` + `key`) lives in the
     /// record name, which keeps every write an idempotent upsert; `key` is not
     /// duplicated as a field. `payload` is the generic, kind-specific extra
     /// slot — empty for `block`, where presence alone is the fact — mirroring
     /// `Ping.payload`. `systemFields` is the archived server record (with its
     /// change tag): pass it so a re-send carries the current tag and CloudKit
     /// accepts the update (e.g. rotating the push secret) instead of rejecting
     /// it as a colliding create. Decisions are therefore upsertable, not
     /// write-once; a payload-less write clears any value a restored record held.
     static func decisionRecord(
         kind: String,
         key: String,
         payload: String? = nil,
         zone: CKRecordZone.ID,
         systemFields: Data? = nil,
         version: Int64? = nil
     ) -> CKRecord {
         let name = decisionRecordName(kind: kind, key: key)
         let record = restoreOrCreate(
             recordType: "Decision",
             recordName: name,
             zone: zone,
             systemFields: systemFields
         )
         record["kind"] = kind as CKRecordValue
         record["payload"] = payload.map { $0 as CKRecordValue }
         record["version"] = version.map { $0 as CKRecordValue }
         return record
     }
 
     static func playerRecord(
         gameID: UUID,
         authorID: String,
         name: String,
         updatedAt: Date,
         selection: PlayerSelection?,
         presenceUntil: Date? = nil,
         readThrough: Date? = nil,
         viewedAt: Date? = nil,
         timeLog: Data? = nil,
         pushAddress: String? = nil,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) -> CKRecord {
         let recordName = recordName(forPlayerInGame: gameID, authorID: authorID)
         let record = restoreOrCreate(
             recordType: "Player",
             recordName: recordName,
             zone: zone,
             systemFields: systemFields
         )
 
         // authorID lives in the record name, not as a field.
         record["name"] = name as CKRecordValue
         record["updatedAt"] = updatedAt as CKRecordValue
         if let selection {
             record["selRow"] = Int64(selection.row) as CKRecordValue
             record["selCol"] = Int64(selection.col) as CKRecordValue
             record["selDir"] = Int64(selection.direction.rawValue) as CKRecordValue
         } else {
             record["selRow"] = nil
             record["selCol"] = nil
             record["selDir"] = nil
         }
         // The forward-dated presence lease, shipped as the `presenceUntil`
         // CKRecord field.
         if let presenceUntil {
             record["presenceUntil"] = presenceUntil as CKRecordValue
         } else {
             record["presenceUntil"] = nil
         }
         // `readThrough` is the true read watermark — the latest other-author
         // move time this account has actually seen. Never forward-dated, so a
         // peer's session-end summary windows only on moves we genuinely missed.
         if let readThrough {
             record["readThrough"] = readThrough as CKRecordValue
         } else {
             record["readThrough"] = nil
         }
         if let viewedAt {
             record["viewedAt"] = viewedAt as CKRecordValue
         } else {
             record["viewedAt"] = nil
         }
         // `timeLog` is the device-keyed solve-time log (encoded `TimeLog`):
         // each device's active-play intervals plus its open session. Unlike the
         // other LWW fields here, a device only ever mutates its own slot, so
         // concurrent sibling writes converge by device once merged on apply.
         if let timeLog, !timeLog.isEmpty {
             record["timeLog"] = timeLog as CKRecordValue
         } else {
             record["timeLog"] = nil
         }
         if let pushAddress, !pushAddress.isEmpty {
             record["pushAddress"] = pushAddress as CKRecordValue
         } else {
             record["pushAddress"] = nil
         }
 
         return record
     }
 
     /// Reads `presenceUntil` off an inbound Player record — the per-account horizon
     /// for collaborator moves this user has read or is actively watching.
     /// Active puzzle sessions may lease the horizon into the near future and
     /// close it with a lower current-time write, so callers must apply this
     /// only after accepting the Player record under last-writer-wins
     /// freshness checks.
     /// Returns `nil` if the field is missing — older records, or a slot that
     /// has not yet recorded a view.
     static func parsePlayerPresenceUntil(from record: CKRecord) -> Date? {
         record["presenceUntil"] as? Date
     }
 
     /// Reads `readThrough` off an inbound Player record — the per-account read
     /// watermark: the latest other-author move time this user has actually
     /// seen. Unlike `presenceUntil` it is never leased into the future, so the
     /// session-end push uses it to decide what a recipient still hasn't seen.
     /// Returns `nil` for records that predate the field or a slot that has not
     /// recorded a read yet.
     static func parsePlayerReadThrough(from record: CKRecord) -> Date? {
         record["readThrough"] as? Date
     }
 
     /// Reads `selRow`/`selCol`/`selDir` off an inbound Player record. These
     /// fields carry the peer's cursor track start, not their exact local
     /// reticle. Returns `nil` if any field is missing — the peer either hasn't
     /// published a track yet or has cleared theirs (e.g. left the puzzle view).
     static func parsePlayerSelection(from record: CKRecord) -> PlayerSelection? {
         guard let row = record["selRow"] as? Int64,
               let col = record["selCol"] as? Int64,
               let dirRaw = record["selDir"] as? Int64,
               let direction = PlayerSelection.Direction(rawValue: Int(dirRaw))
         else { return nil }
         return PlayerSelection(row: Int(row), col: Int(col), direction: direction)
     }
 
     /// Reads `viewedAt` off an inbound Player record — this account's "last
     /// viewed" cutoff, written on leave and shared across the author's own
     /// devices so a sibling converges on the latest view time rather than
     /// recomputing the catch-up baseline from its own (possibly stale) view.
     /// Returns `nil` when the account has not yet left a game with peers.
     static func parsePlayerViewedAt(from record: CKRecord) -> Date? {
         record["viewedAt"] as? Date
     }
 
     /// Reads `timeLog` off an inbound Player record — the encoded `TimeLog`
     /// of device-keyed solve-time intervals. Returns `nil` for records that
     /// predate the field (or before the schema deploy), which the clock treats
     /// as a zero contribution.
     static func parsePlayerTimeLog(from record: CKRecord) -> Data? {
         record["timeLog"] as? Data
     }
 
     /// Reads `pushAddress` off an inbound Player record — the per-(account,
     /// game) capability token a co-participant uses to address a push to this
     /// player for this game. Possession is gated by the share ACL (only
     /// participants can read the record), so the token, not an identity, is
     /// the authorisation. Returns `nil` for older records or a slot that has
     /// not yet minted one.
     static func parsePlayerPushAddress(from record: CKRecord) -> String? {
         record["pushAddress"] as? String
     }
 
     /// Parses an incoming `Player` record name back into its `(gameID,
     /// authorID)` components. Returns `nil` if the name doesn't match the
     /// `player-<UUID>-<authorID>` shape.
     static func parsePlayerRecordName(_ name: String) -> (UUID, String)? {
         guard name.hasPrefix("player-") else { return nil }
         let rest = name.dropFirst("player-".count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let authorPart = String(rest.suffix(from: rest.index(rest.startIndex, offsetBy: uuidLength + 1)))
         guard !authorPart.isEmpty else { return nil }
         return (gameID, authorPart)
     }
 
     /// Parses an incoming `Moves` CKRecord into a `MovesValue`. Returns `nil`
     /// if the record name doesn't match the `moves-<gameUUID>-<authorID>-<deviceID>`
     /// shape or the cells payload fails to decode.
     static func parseMovesRecord(_ record: CKRecord) -> MovesValue? {
         guard record.recordType == "Moves" else { return nil }
         guard let (gameID, authorID, deviceID) = parseMovesRecordName(
             record.recordID.recordName
         ) else { return nil }
         guard let data = record["cells"] as? Data,
               let cells = try? MovesCodec.decode(data)
         else { return nil }
         let updatedAt = record["updatedAt"] as? Date
             ?? record.modificationDate
             ?? Date()
         return MovesValue(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             cells: cells,
             updatedAt: updatedAt
         )
     }
 
     /// Parses `moves-<gameUUID>-<authorID>-<deviceID>` into its three parts.
     /// `deviceID` is the suffix after the final `-`; `authorID` may itself
     /// contain dashes (e.g. CloudKit user record names with no dashes today,
     /// but we don't want to assume).
     static func parseMovesRecordName(_ name: String) -> (UUID, String, String)? {
         let prefix = "moves-"
         guard name.hasPrefix(prefix) else { return nil }
         let rest = name.dropFirst(prefix.count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
         let tail = rest[afterUUID...]
         guard let lastDash = tail.lastIndex(of: "-") else { return nil }
         let authorID = String(tail[tail.startIndex..<lastDash])
         let deviceID = String(tail[tail.index(after: lastDash)...])
         guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
         return (gameID, authorID, deviceID)
     }
 
     /// Parses `journal-<gameUUID>-<authorID>-<deviceID>` into its three parts.
     /// Same decomposition as `parseMovesRecordName` (deviceID is the suffix
     /// after the final `-`; authorID may itself contain dashes).
     static func parseJournalRecordName(_ name: String) -> (UUID, String, String)? {
         let prefix = "journal-"
         guard name.hasPrefix(prefix) else { return nil }
         let rest = name.dropFirst(prefix.count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
         let tail = rest[afterUUID...]
         guard let lastDash = tail.lastIndex(of: "-") else { return nil }
         let authorID = String(tail[tail.startIndex..<lastDash])
         let deviceID = String(tail[tail.index(after: lastDash)...])
         guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
         return (gameID, authorID, deviceID)
     }
 
     /// Parses `ping-<gameUUID>-<authorID>-<deviceID>-<eventTimestampMs>` into
     /// its identity components. Splits from the right: the trailing
     /// `eventTimestampMs` is dash-free digits and `deviceID` is a dash-free hex
     /// id, so both peel off cleanly; `authorID` is the remainder and may itself
     /// contain dashes (same tolerance as `parseMovesRecordName`). Returns nil if
     /// the name isn't a ping name or the UUID doesn't parse.
     static func parsePingRecordName(_ name: String) -> (UUID, String, String)? {
         let prefix = "ping-"
         guard name.hasPrefix(prefix) else { return nil }
         let rest = name.dropFirst(prefix.count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
         // `<authorID>-<deviceID>-<eventTimestampMs>`
         let tail = rest[afterUUID...]
         guard let tsDash = tail.lastIndex(of: "-") else { return nil }
         let authorAndDevice = tail[tail.startIndex..<tsDash]
         guard let deviceDash = authorAndDevice.lastIndex(of: "-") else { return nil }
         let authorID = String(authorAndDevice[authorAndDevice.startIndex..<deviceDash])
         let deviceID = String(authorAndDevice[authorAndDevice.index(after: deviceDash)...])
         guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
         return (gameID, authorID, deviceID)
     }
 
     // MARK: - Bounded asset reads
 
     /// A `CKAsset` staging file rejected before it was read into memory.
     enum AssetReadError: Error, CustomStringConvertible {
         case oversized(bytes: Int, limit: Int)
         case unknownSize
 
         var description: String {
             switch self {
             case .oversized(let bytes, let limit):
                 return "asset exceeds \(limit) bytes (\(bytes))"
             case .unknownSize:
                 return "asset file size unavailable"
             }
         }
     }
 
     /// Reads an untrusted `CKAsset` staging file only after its on-disk size
     /// passes `limit`. A co-player controls the asset's content, and an asset
     /// is an external file that can dwarf the ~1 MB record limit — so never
     /// `Data(contentsOf:)` one unchecked. Fails closed when the size can't be
     /// determined.
     static func boundedAssetData(at url: URL, limit: Int) throws -> Data {
         guard let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize else {
             throw AssetReadError.unknownSize
         }
         guard size <= limit else {
             throw AssetReadError.oversized(bytes: size, limit: limit)
         }
         return try Data(contentsOf: url)
     }
 
     // MARK: - Applying incoming CKRecords to Core Data
 
     /// Returns the `GameEntity` for `gameID`, creating an unpopulated stub if
     /// none exists yet. Moves and Player records can arrive in a different
     /// fetch batch than the Game record that created the zone — on
     /// a fresh device CKSyncEngine paginates the initial pull and there is no
     /// guarantee that Game comes first. Without this stub the parent lookup
     /// fails, the inbound record is dropped, but CKSyncEngine still advances
     /// its change token, so the gap is invisible until the next state reset.
     /// The stub uses empty `title` / `puzzleSource` so `GameSummary.init?`
     /// filters it out of the library until `applyGameRecord` arrives with
     /// the real metadata and updates the same row (matched by `ckRecordName`).
     static func ensureGameEntity(
         forGameID gameID: UUID,
         zoneID: CKRecordZone.ID,
         databaseScope: DatabaseScope = .private,
         in ctx: NSManagedObjectContext
     ) -> GameEntity {
         let name = recordName(forGameID: gameID)
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = gameIdentityPredicate(
             recordName: name,
             zoneID: zoneID,
             databaseScope: databaseScope
         )
         req.fetchLimit = 1
         if let existing = try? ctx.fetch(req).first { return existing }
         let entity = GameEntity(context: ctx)
         entity.id = gameID
         entity.ckRecordName = name
         entity.ckZoneName = zoneID.zoneName
         // Scope, not the owner-name spelling, decides ownership: a private-DB
         // zone always belongs to the current user even when its fetched zone
         // ID carries the concrete user-record ID instead of the placeholder.
         entity.ckZoneOwnerName = databaseScope == .private ? nil : zoneID.ownerName
         entity.databaseScope = databaseScope.rawValue
         entity.syncVersion = GameSyncVersion.legacy
         entity.title = ""
         entity.puzzleSource = ""
         entity.createdAt = Date()
         entity.updatedAt = Date()
         return entity
     }
 
     static func applyGameRecord(
         _ record: CKRecord,
         to context: NSManagedObjectContext,
         databaseScope: DatabaseScope = .private,
         onEngagementChange: ((UUID) -> Void)? = nil,
         onCompletedTransition: ((UUID) -> Void)? = nil,
         onContentKeyChange: ((UUID) -> Void)? = nil,
         onStaleCredentials: ((String) -> Void)? = nil,
         onDiagnostic: ((String) -> Void)? = nil
     ) -> GameEntity {
         let recordName = record.recordID.recordName
         let entity = fetchOrCreate(
             entityName: "GameEntity",
             recordName: recordName,
             zoneID: record.recordID.zoneID,
             databaseScope: databaseScope,
             in: context
         ) as! GameEntity
 
         // Recover the UUID from the record name ("game-<UUID>") so the
         // library query, which filters on `entity.id`, doesn't silently drop
         // newly-synced games.
         if entity.id == nil {
             let uuidString = String(recordName.dropFirst("game-".count))
             entity.id = UUID(uuidString: uuidString)
         }
 
         // Drop fetched snapshots older than what we already have; adopting
         // them downgrades the local etag and OpLock-fails the next save
         // (same rationale as `applyMovesRecord` / `applyPlayerRecord`).
         if entity.ckSystemFields != nil,
            !incomingIsAtLeastAsFresh(record, existingFields: entity.ckSystemFields) {
             return entity
         }
 
         // Always adopt the fresher etag and zone identity so the next outbound
         // push uses a current change tag and routes to the right zone.
         entity.ckRecordName = recordName
         entity.ckSystemFields = encodeSystemFields(of: record)
         entity.ckZoneName = record.recordID.zoneID.zoneName
         // Scope, not the owner-name spelling, decides ownership — CloudKit
         // round-trips a private zone's owner as either the placeholder or the
         // concrete user-record ID, and `gameIdentityPredicate` relies on
         // private rows always storing nil.
         entity.ckZoneOwnerName =
             databaseScope == .private ? nil : record.recordID.zoneID.ownerName
         entity.databaseScope = databaseScope.rawValue
 
         // The owner chooses and may advance the game's protocol. Participants
         // never write this field, so they can adopt it even while an unrelated
         // metadata save is pending. An owner with a pending local save keeps
         // its chosen value until that save round-trips.
         if databaseScope == .shared || !entity.hasPendingSave {
             entity.syncVersion = GameSyncVersion.normalized(
                 (record["syncVersion"] as? Int64) ?? GameSyncVersion.legacy
             )
         }
 
         // Local mutable fields take precedence while a push is in flight.
         // The flag is set atomically with the local write (in `markCompleted`,
         // `resignGame`, `persistShareName`) and cleared once `SyncEngine`
         // confirms the push landed. Writing server values here would clobber
         // the pending change and the next outbound push would then serialise
         // the clobbered value, permanently losing it server-side.
         guard !entity.hasPendingSave else { return entity }
 
         // Seed createdAt/updatedAt from the server record only on first sight,
         // so a newly-arrived game has something for the library to order by.
         // After that, the library timestamp tracks *gameplay* (Moves) alone.
         // The Game record's modificationDate advances on non-gameplay writes
         // too — engagement/push credentials, share metadata, the notification
         // field — so adopting it on every fetch made a game look freshly
         // "updated" when nothing was played (e.g. a peer, or this device,
         // merely moved the cursor or re-minted a credential). Gameplay flows
         // through the Moves path, which sets updatedAt independently; the
         // winning move is itself a move, so completion still advances it.
         if entity.createdAt == nil {
             entity.createdAt = record.creationDate ?? Date()
         }
         if entity.updatedAt == nil {
             entity.updatedAt = record.modificationDate ?? Date()
         }
 
         entity.title = record["title"] as? String ?? entity.title
         // Capture the prior completion state before overwriting it: a
         // not-completed → completed transition learned purely via sync (this
         // device wasn't present when the puzzle was finished) does NOT run the
         // local completion path, so it never uploads this device's journal.
         // Replay's strict completeness would then wait on it forever. Signal
         // the transition so the caller can enqueue the upload.
         let wasCompleted = entity.completedAt != nil
         let incomingCompletedAt = record["completedAt"] as? Date
         if let incomingCompletedAt {
             entity.completedAt = incomingCompletedAt
             entity.completedBy = record["completedBy"] as? String
         } else if entity.completedAt == nil {
             entity.completedAt = nil
             entity.completedBy = nil
         }
         if !wasCompleted, entity.completedAt != nil, let id = entity.id {
             onCompletedTransition?(id)
         }
         // Owner-side share marker — set on the device that created the share
         // and round-tripped via the Game record so other owner-devices learn
         // the game is shared. On participant devices `databaseScope == 1`
         // already implies shared, but keeping the field in sync is harmless.
         if let shareRecordName = record["shareRecordName"] as? String {
             entity.ckShareRecordName = shareRecordName
         }
 
         // Adopt the engagement creds (skipped above while a local mint is
         // still pushing, via the hasPendingSave guard). A change here is the
         // signal a peer minted/rotated the room, so the receiver reconciles
         // its live connection toward the new creds.
         let incomingEngagement = (record["roomCredential"] as? Data)
             .flatMap { String(data: $0, encoding: .utf8) }
         if entity.engagement != incomingEngagement {
             entity.engagement = incomingEngagement
             if let id = entity.id { onEngagementChange?(id) }
         }
 
         // Adopt the shared notification credentials. The credential is read
         // lazily at registration/publish time, so converging the field is
         // enough — but a change may carry a new embedded content key, so fire
         // `onContentKeyChange` to re-mirror the App Group key directory the NSE
         // reads. This is what lets a freshly-joined participant decrypt the
         // first push it receives, rather than waiting for the next launch heal.
         //
         // Adoption is generation-gated: rotation replaces the credential at a
         // higher `gen`, and the Game record is pushed whole, so a stale device
         // re-pushing an unrelated change (its inbound applies were blocked by
         // its own `hasPendingSave`) can land the *old* credential back on the
         // server. Adopting that here would silently re-admit a departed
         // participant. Instead keep the newer local credential, flag our copy
         // as pending, and hand the record name to `onStaleCredentials` so the
         // caller re-pushes it — healing the server to the rotated value.
         let incomingNotification = (record["pushCredential"] as? Data)
             .flatMap { String(data: $0, encoding: .utf8) }
         if entity.notification != incomingNotification {
             let localGen = GamePushCredentials.decode(entity.notification)?.generation
             let incomingGen = GamePushCredentials.decode(incomingNotification)?.generation
             // A local credential is superseded only by an inbound one of equal
             // or higher generation (equal = concurrent rotations; the server
             // copy wins the tie). An inbound *absence* never clears a local
             // credential — creds are minted once and only ever replaced, so a
             // missing field is always a stale record.
             let incomingSupersedes: Bool
             if localGen == nil {
                 incomingSupersedes = true
             } else if let incomingGen, let localGen {
                 incomingSupersedes = incomingGen >= localGen
             } else {
                 incomingSupersedes = false
             }
             if incomingSupersedes {
                 entity.notification = incomingNotification
                 if let id = entity.id { onContentKeyChange?(id) }
             } else {
                 onDiagnostic?(
                     "stale pushCredential for \(recordName) " +
                     "(inbound gen \(incomingGen.map(String.init) ?? "none") < " +
                     "local gen \(localGen.map(String.init) ?? "none")) — keeping local, re-pushing"
                 )
                 entity.hasPendingSave = true
                 onStaleCredentials?(recordName)
             }
         }
 
         if let asset = record["puzzleSource"] as? CKAsset,
            let fileURL = asset.fileURL {
             do {
                 // A co-player writes this asset into the shared zone, so treat
                 // its size as untrusted: reject an oversized blob before reading
                 // it into memory. The parser enforces the same bound, but the
                 // asset is an external file that could dwarf the ~1 MB record
                 // limit, so gate on the on-disk size first.
                 if let size = try? fileURL.resourceValues(forKeys: [.fileSizeKey]).fileSize,
                    size > XD.maxSourceBytes {
                     onDiagnostic?(
                         "puzzleSource asset for \(recordName) " +
                         "exceeds \(XD.maxSourceBytes) bytes (\(size)) — skipping"
                     )
                     return entity
                 }
                 let source = try String(contentsOf: fileURL, encoding: .utf8)
                 entity.puzzleSource = source
                 if let xd = try? XD.parse(source) {
                     let puzzle = Puzzle(xd: xd)
                     entity.puzzleParserVersion = Int64(XD.currentParserVersion)
                     // The title is always derived from the puzzle content (there
                     // is no custom game title), so trust the asset over the
                     // record's `title` field — which was already applied above.
                     // This re-derives the real title even when `record["title"]`
                     // carried a stale value, e.g. a participant's transient
                     // "Joining…" placeholder that a prior build wrote to the
                     // shared record, so the title self-heals on the next sync
                     // that carries the asset.
                     entity.title = puzzle.title
                     entity.populateCachedSummaryFields(from: puzzle)
                 }
             } catch {
                 // CKSyncEngine has already committed this batch by the time
                 // the delegate returns, so re-throwing wouldn't redeliver.
                 // Surface the dropped puzzle source instead of silently
                 // leaving the entity without playable content.
                 let nsError = error as NSError
                 onDiagnostic?(
                     "puzzleSource asset read failed for \(recordName) " +
                     "— domain=\(nsError.domain) code=\(nsError.code) " +
                     "\(nsError.localizedDescription)"
                 )
             }
         }
 
         return entity
     }
 
     /// Upserts the `MovesEntity` for `value`. The cells blob is taken straight
     /// off the record so any forward-compat fields the encoder added are
     /// preserved verbatim. Bumps the parent `GameEntity.updatedAt` if the
     /// record is fresher. Returns `true` when cells/updatedAt were adopted,
     /// `false` when the local-device-row guard short-circuited the body so
     /// callers can skip the downstream grid refresh.
     ///
     /// `onNewAuthor` fires with the authorID when this record creates the first
     /// `MovesEntity` row by a *remote* contributor — i.e. a participant the
     /// roster can only discover from their moves (no `Player` record yet, see
     /// `PlayerRoster.refresh`). Callers use it to trigger a one-off roster
     /// refresh on a new collaborator's first move without refreshing on every
     /// subsequent keystroke or sibling-device row.
     @discardableResult
     static func applyMovesRecord(
         _ record: CKRecord,
         value: MovesValue,
         to ctx: NSManagedObjectContext,
         databaseScope: DatabaseScope = .private,
         localAuthorID: String? = nil,
         onNewAuthor: ((String) -> Void)? = nil
     ) -> Bool {
         let ckName = record.recordID.recordName
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = gameIdentityPredicate(
             recordName: ckName,
             zoneID: record.recordID.zoneID,
             databaseScope: databaseScope,
             entityPrefix: "game"
         )
         req.fetchLimit = 1
 
         let entity: MovesEntity
         let foundExisting: Bool
         let authorAlreadyKnown: Bool
         if let existing = try? ctx.fetch(req).first {
             entity = existing
             foundExisting = true
             authorAlreadyKnown = true
         } else {
             let authorReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
             authorReq.predicate = NSPredicate(
                 format: "game.id == %@ AND authorID == %@",
                 value.gameID as CVarArg,
                 value.authorID
             )
             authorReq.fetchLimit = 1
             authorAlreadyKnown = ((try? ctx.fetch(authorReq).first) != nil)
 
             let game = ensureGameEntity(
                 forGameID: value.gameID,
                 zoneID: record.recordID.zoneID,
                 databaseScope: databaseScope,
                 in: ctx
             )
             entity = MovesEntity(context: ctx)
             entity.game = game
             foundExisting = false
         }
 
         // Drop fetched snapshots that are older than what we already have.
         // The writeback after a successful push advances `ckSystemFields` to
         // the latest server etag; a query that started before that push
         // landed can return the prior server state, and adopting it here
         // would downgrade the etag and OpLock-fail the next save.
         if foundExisting,
            !incomingIsAtLeastAsFresh(record, existingFields: entity.ckSystemFields) {
             return false
         }
 
         // Adopt system fields so future saves target the server's current
         // change tag. If this is our own per-device row and it already
         // exists locally, the local value state is authoritative; tokenless
         // push-driven direct fetches can re-deliver an older server copy while
         // newer edits are still queued for upload.
         entity.ckRecordName = ckName
         entity.ckSystemFields = encodeSystemFields(of: record)
         entity.authorID = value.authorID
         entity.deviceID = value.deviceID
         let isLocalDeviceRow = value.authorID == localAuthorID
             && value.deviceID == localDeviceID
         guard !foundExisting || !isLocalDeviceRow else { return false }
         let previousUpdatedAt = entity.updatedAt ?? .distantPast
         let previousCells = (entity.cells.flatMap { try? MovesCodec.decode($0) }) ?? [:]
         let mergedCells = mergeIncomingMovesCells(
             existing: previousCells,
             incoming: value.cells
         )
         let mergedUpdatedAt = max(
             previousUpdatedAt,
             value.updatedAt,
             mergedCells.values.map(\.updatedAt).max() ?? .distantPast
         )
 
         entity.updatedAt = mergedUpdatedAt
         entity.cells = (try? MovesCodec.encode(mergedCells)) ?? ((record["cells"] as? Data) ?? Data())
 
         if let game = entity.game,
            game.updatedAt.map({ $0 < mergedUpdatedAt }) ?? true {
             game.updatedAt = mergedUpdatedAt
         }
         // A newly-seen remote author is the roster's only cue to
         // a contributor who hasn't published a `Player` record yet. Signal it
         // once here; repeat moves and sibling-device rows by a known author
         // don't.
         if !foundExisting,
            !authorAlreadyKnown,
            value.authorID != localAuthorID,
            value.authorID != CKCurrentUserDefaultName,
            !value.authorID.isEmpty {
             onNewAuthor?(value.authorID)
         }
         return true
     }
 
     private static func mergeIncomingMovesCells(
         existing: [GridPosition: TimestampedCell],
         incoming: [GridPosition: TimestampedCell]
     ) -> [GridPosition: TimestampedCell] {
         var cells = existing
         for (position, incomingCell) in incoming {
             if let existingCell = cells[position],
                existingCell.compareRevision(to: incomingCell) != .orderedAscending {
                 continue
             }
             cells[position] = incomingCell
         }
         return cells
     }
 
     /// Projects an inbound `Decision` record onto local Core Data. For
     /// `kind == "block"` this upserts a `FriendEntity` tombstone keyed by the
     /// blocked author so the block becomes authoritative across the user's own
     /// devices: `applyInvitePings` (authorID-keyed) and the friendship
     /// bootstrap's `friendExists` (pairKey-keyed) both then suppress the
     /// blocked collaborator everywhere. A device that never befriended the
     /// author still gets a minimal blocked row. Returns `true` when a row was
     /// written. `localAuthorID` lets the pairKey be derived for the bootstrap
     /// short-circuit; it's deterministic from the unordered author pair.
     @discardableResult
     static func applyDecisionRecord(
         _ record: CKRecord,
         to ctx: NSManagedObjectContext,
         localAuthorID: String?,
         databaseScope: DatabaseScope = .private
     ) -> Bool {
         guard record.recordType == "Decision" else { return false }
         // Identity comes from the record name (always present, immutable);
         // `kind` is also mirrored as a field, name-parse as the fallback.
         let parsed = parseDecisionRecordName(record.recordID.recordName)
         guard let kind = (record["kind"] as? String) ?? parsed?.kind,
               let key = parsed?.key,
               !kind.isEmpty, !key.isEmpty
         else { return false }
 
         switch kind {
         case blockDecisionKind:
             // A block is the user's own choice, authoritative across their
             // devices — honored only from the account zone in the private
             // database. Friend zones are writable by the other participant, who
             // must not be able to block (or unblock) a third party on this
             // user's behalf. Same gate as `nickname`/`left`.
             guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
             else { return false }
             // Versioned so a stale copy can't resurrect a cleared block (or
             // re-clear a fresh one). Payload `"0"` means unblocked; anything
             // else (including a legacy payload-less record) means blocked.
             let version = decisionVersion(record)
             let blocked = (record["payload"] as? String) != "0"
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(format: "authorID == %@", key)
             req.fetchLimit = 1
             let friend = (try? ctx.fetch(req).first) ?? FriendEntity(context: ctx)
             guard version >= friend.blockVersion else { return false }
             friend.authorID = key
             friend.isBlocked = blocked
             friend.blockVersion = version
             if friend.pairKey == nil,
                let localAuthorID, !localAuthorID.isEmpty {
                 friend.pairKey = FriendZone.pairKey(localAuthorID, key)
             }
             if friend.createdAt == nil { friend.createdAt = Date() }
             return true
         case "left":
             // The user left this shared game on another of their devices.
             // Hard-delete the local row so it stops hanging around (the
             // shared-zone deletion alone would only flag it access-revoked,
             // see SyncEngine.handleFetchedDatabaseChanges). Idempotent: a
             // re-applied decision after the row is gone is a no-op. Guarded
             // to participant rows (databaseScope == 1) so a same-id owned
             // copy is never collateral.
             //
             // The decision itself is a self-authored cross-device signal, so
             // honor it only from the account zone in the private database — a
             // friend must not be able to name a `(gameID)` and evict its
             // participant row out of a zone he can write. Same gate as
             // `nickname`/`block`.
             guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
             else { return false }
             guard let gameID = UUID(uuidString: key) else { return false }
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first,
                   entity.databaseScope == 1 else { return false }
             ctx.delete(entity)
             return true
         case nameDecisionKind:
             // A friend's display name, read out of the pairwise friend zone.
             // Our own copy (key == localAuthorID, account zone) carries no
             // Core Data projection — the local name lives in
             // `PlayerPreferences`; only its version is adopted, by the caller.
             guard let localAuthorID, !localAuthorID.isEmpty,
                   key != localAuthorID,
                   let name = record["payload"] as? String,
                   !name.isEmpty
             else { return false }
             // Provenance: a name Decision is only honored when the zone is *the*
             // pairwise mailbox for (us, key) — the zone name embeds a hash of
             // the author pair, so the claimed subject is verifiable without
             // trusting the record. This also rejects a name Decision for a third
             // party misdelivered into an unrelated zone.
             let pairKey = FriendZone.pairKey(localAuthorID, key)
             let zoneID = record.recordID.zoneID
             guard zoneID.zoneName == FriendZone.zoneName(pairKey: pairKey) else {
                 return false
             }
             // The friend writes their name into *our inbox* (their outbox), so
             // a friend's name only ever arrives via the zone we own — the
             // private engine. Reject one seen at shared scope (that would be
             // the friend's own inbox, not the channel they tell us their name
             // through).
             guard databaseScope == .private else { return false }
             let version = decisionVersion(record)
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(format: "pairKey == %@", pairKey)
             req.fetchLimit = 1
             if let friend = try? ctx.fetch(req).first {
                 guard !friend.isBlocked,
                       version >= friend.displayNameVersion
                 else { return false }
                 friend.displayName = name
                 friend.displayNameVersion = version
                 return true
             }
             // No local row: the bootstrap evidence (game zones, `.friend`
             // Ping) may be long gone on a restored device, but the name
             // Decision arriving from our inbox is itself proof of the
             // friendship — resurrect the row. Both mailbox zones are derivable
             // from `pairKey` + `authorID`, so no zone fields are stored.
             let friend = FriendEntity(context: ctx)
             friend.authorID = key
             friend.pairKey = pairKey
             friend.createdAt = Date()
             friend.displayName = name
             friend.displayNameVersion = version
             return true
         case nicknameDecisionKind:
             // The user's private nickname for a friend, authoritative across
             // their own devices. Honored only from the account zone in our own
             // private database: friend zones are writable by the other
             // participant, who must not be able to relabel people in this
             // user's friends list. Match on zone *name* + private scope, not a
             // full `zoneID ==`: a record fetched back from CloudKit does not
             // reliably carry the `CKCurrentUserDefaultName` owner placeholder
             // `accountZoneID` is built with — its `ownerName` often comes back
             // as the concrete user-record ID, so an `==` silently rejects every
             // synced nickname. Scoping to the private DB keeps the anti-relabel
             // guarantee (a friend can only reach us through the shared DB).
             // Same gate as `block`/`left`.
             guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
             else { return false }
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(format: "authorID == %@", key)
             req.fetchLimit = 1
             // No resurrection: unlike a name Decision, an account-zone row
             // carries no zone provenance to rebuild a usable friendship from,
             // and a zoneless row would surface as an uninvitable friend.
             guard let friend = try? ctx.fetch(req).first else { return false }
             let version = decisionVersion(record)
             guard version >= friend.nicknameVersion else { return false }
             let nickname = (record["payload"] as? String)?
                 .trimmingCharacters(in: .whitespacesAndNewlines)
             // Empty/absent payload is a deliberate clear, not a malformed
             // record — the rename alert's blank entry reverts to their name.
             friend.nickname = (nickname?.isEmpty == false) ? nickname : nil
             friend.nicknameVersion = version
             return true
         case encryptionKeyDecisionKind:
             // Friend-zone message encryption material. Each participant writes
             // only their own key record, named by authorID; the peer mirrors it
             // to the App Group so the Notification Service Extension can
             // decrypt invite pushes before the game zone exists locally.
             guard let localAuthorID, !localAuthorID.isEmpty,
                   key != localAuthorID,
                   let payload = FriendEncryptionKeyPayload.decode(record["payload"] as? String)
             else { return false }
             let pairKey = FriendZone.pairKey(localAuthorID, key)
             let zoneID = record.recordID.zoneID
             guard zoneID.zoneName == FriendZone.zoneName(pairKey: pairKey) else {
                 return false
             }
             // Like the `name` case: the friend writes their key into *our inbox*
             // (their outbox), so it only ever arrives via the zone we own — the
             // private engine. Reject one seen at shared scope (that would be
             // the friend's own inbox, not the channel they publish to us). The
             // zone-name gate alone is insufficient: a peer owns a zone that
             // *names* itself for this pair and shares it to us at shared scope.
             guard databaseScope == .private else { return false }
             FriendEncryptionKeyDirectory.upsert(payload, for: key)
             return false
         default:
             // Unknown kind from a newer build — ignore rather than guess.
             return false
         }
     }
 
     // MARK: - System fields encode/decode
 
     static func encodeSystemFields(of record: CKRecord) -> Data? {
         let coder = NSKeyedArchiver(requiringSecureCoding: true)
         record.encodeSystemFields(with: coder)
         coder.finishEncoding()
         return coder.encodedData
     }
 
     static func decodeRecord(from data: Data) -> CKRecord? {
         guard let coder = try? NSKeyedUnarchiver(forReadingFrom: data) else { return nil }
         coder.requiresSecureCoding = true
         let record = CKRecord(coder: coder)
         coder.finishDecoding()
         return record
     }
 
     /// Returns `true` when `incoming` reflects a server state at least as
     /// recent as the modification date encoded in `existingFields`. Used by
     /// the apply paths to drop fetched snapshots that arrive after our
     /// writeback has already adopted a newer change tag — adopting them
     /// would downgrade the local etag and the next save would OpLock-fail.
     /// Defaults to `true` when either side lacks a modification date so a
     /// first-time fetch can land.
     static func incomingIsAtLeastAsFresh(
         _ incoming: CKRecord,
         existingFields: Data?
     ) -> Bool {
         guard let existingFields,
               let existingRecord = decodeRecord(from: existingFields),
               let existingDate = existingRecord.modificationDate,
               let incomingDate = incoming.modificationDate
         else { return true }
         return incomingDate >= existingDate
     }
 
     // MARK: - Private helpers
 
     /// Restores a `CKRecord` from archived system fields (preserving the
     /// server change tag) or creates a fresh one if no archive is available.
     private static func restoreOrCreate(
         recordType: String,
         recordName: String,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) -> CKRecord {
         if let data = systemFields, let restored = decodeRecord(from: data) {
             return restored
         }
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zone)
         return CKRecord(recordType: recordType, recordID: recordID)
     }
 
     private static func fetchOrCreate(
         entityName: String,
         recordName: String,
         zoneID: CKRecordZone.ID,
         databaseScope: DatabaseScope,
         in context: NSManagedObjectContext
     ) -> NSManagedObject {
         let request = NSFetchRequest<NSManagedObject>(entityName: entityName)
         request.predicate = gameIdentityPredicate(
             recordName: recordName,
             zoneID: zoneID,
             databaseScope: databaseScope
         )
         request.fetchLimit = 1
         if let existing = try? context.fetch(request).first {
             return existing
         }
         return NSEntityDescription.insertNewObject(forEntityName: entityName, into: context)
     }
 
 }