crossmate

RecordSerializer.swift (56575B)

---

 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",
         "engagement",
         "notification",
         "puzzleSource",
     ]
 
     static let movesDesiredKeys: [CKRecord.FieldKey] = [
         "authorID",
         "deviceID",
         "cells",
         "updatedAt",
     ]
 
     static let playerDesiredKeys: [CKRecord.FieldKey] = [
         "authorID",
         "name",
         "updatedAt",
         "selRow",
         "selCol",
         "selDir",
         "readAt",
         "readThrough",
         "sessionSnapshot",
         "timeLog",
         "pushAddress",
     ]
 
     static let pingDesiredKeys: [CKRecord.FieldKey] = [
         "authorID",
         "deviceID",
         "playerName",
         "puzzleTitle",
         "kind",
         "payload",
         "addressee",
     ]
 
     static let pingDeletionDesiredKeys: [CKRecord.FieldKey] = [
         "authorID",
         "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 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)
     }
 
     static func parseAccountPushAddressDecision(_ record: CKRecord) -> String? {
         guard record.recordType == "Decision",
               record.recordID.recordName == accountPushAddressDecisionName,
               (record["kind"] as? String) == accountDecisionKind,
               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
     ) -> (secret: String, version: Int64)? {
         guard record.recordType == "Decision",
               record.recordID.recordName == accountPushSecretDecisionName,
               (record["kind"] as? String) == accountDecisionKind,
               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)
     }
 
     /// 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
         )
 
         record["authorID"] = view.authorID as CKRecordValue
         record["deviceID"] = view.deviceID as CKRecordValue
         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)
         record["authorID"] = authorID as CKRecordValue
         record["deviceID"] = deviceID as CKRecordValue
         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` and the `shareRecordName` marker are owner-authoritative: the
         // title comes from the puzzle the owner authored, and only owner devices
         // track the share record. A participant only ever 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["completedAt"] = entity.completedAt as CKRecordValue?
         // Solver's authorID on a win; nil for a resignation. Single-writer
         // (the device that first completes the game) so plain LWW is safe.
         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.
         record["engagement"] = entity.engagement 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["notification"] = entity.notification 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 remaining bootstrap kinds (.join /
     ///   .friend / .invite / .hail).
     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)
         record["authorID"] = authorID as CKRecordValue
         record["deviceID"] = deviceID as CKRecordValue
         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["createdAt"] = Date() as CKRecordValue
         record["version"] = version.map { $0 as CKRecordValue }
         return record
     }
 
     static func playerRecord(
         gameID: UUID,
         authorID: String,
         name: String,
         updatedAt: Date,
         selection: PlayerSelection?,
         readAt: Date? = nil,
         readThrough: Date? = nil,
         sessionSnapshot: Data? = 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
         )
 
         record["authorID"] = authorID as CKRecordValue
         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
         }
         // `readAt` is the forward-dated presence lease (see `GameStore`'s
         // TODO(v4): this field should be renamed to a presence name).
         if let readAt {
             record["readAt"] = readAt as CKRecordValue
         } else {
             record["readAt"] = 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 sessionSnapshot {
             record["sessionSnapshot"] = sessionSnapshot as CKRecordValue
         } else {
             record["sessionSnapshot"] = 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 `readAt` 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 parsePlayerReadAt(from record: CKRecord) -> Date? {
         record["readAt"] 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 `readAt` 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 `sessionSnapshot` off an inbound Player record — the encoded
     /// `SeenBaseline` (this account's "last viewed" cutoff), written on leave.
     /// 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` on older records or when the
     /// account has not yet left a game with peers. (Pre-unification builds wrote
     /// a per-peer Moves-snapshot map here, which simply fails to decode as a
     /// `SeenBaseline` and is ignored — a per-device fallback.)
     static func parsePlayerSessionSnapshot(from record: CKRecord) -> Data? {
         record["sessionSnapshot"] as? Data
     }
 
     /// 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)
     }
 
     // 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,
         in ctx: NSManagedObjectContext
     ) -> GameEntity {
         let name = recordName(forGameID: gameID)
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", name)
         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
         let ownerName = zoneID.ownerName
         let isOwner = ownerName == CKCurrentUserDefaultName
         entity.ckZoneOwnerName = isOwner ? nil : ownerName
         entity.databaseScope = isOwner ? 0 : 1
         entity.title = ""
         entity.puzzleSource = ""
         entity.createdAt = Date()
         entity.updatedAt = Date()
         return entity
     }
 
     static func applyGameRecord(
         _ record: CKRecord,
         to context: NSManagedObjectContext,
         databaseScope: Int16 = 0,
         onEngagementChange: ((UUID) -> Void)? = nil,
         onCompletedTransition: ((UUID) -> Void)? = nil,
         onContentKeyChange: ((UUID) -> Void)? = nil
     ) -> GameEntity {
         let recordName = record.recordID.recordName
         let entity = fetchOrCreate(
             entityName: "GameEntity",
             recordName: recordName,
             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
         let ownerName = record.recordID.zoneID.ownerName
         entity.ckZoneOwnerName = ownerName == CKCurrentUserDefaultName ? nil : ownerName
         entity.databaseScope = databaseScope
 
         // 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
         entity.completedAt = record["completedAt"] as? Date
         entity.completedBy = record["completedBy"] as? String
         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["engagement"] as? String
         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.
         let incomingNotification = record["notification"] as? String
         if entity.notification != incomingNotification {
             entity.notification = incomingNotification
             if let id = entity.id { onContentKeyChange?(id) }
         }
 
         if let asset = record["puzzleSource"] as? CKAsset,
            let fileURL = asset.fileURL {
             do {
                 let source = try String(contentsOf: fileURL, encoding: .utf8)
                 entity.puzzleSource = source
                 if let xd = try? XD.parse(source) {
                     let puzzle = Puzzle(xd: xd)
                     entity.puzzleCmVersion = Int64(XD.currentCmVersion)
                     // 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
                 print(
                     "RecordSerializer: 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,
         localAuthorID: String? = nil,
         onNewAuthor: ((String) -> Void)? = nil
     ) -> Bool {
         let ckName = record.recordID.recordName
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", ckName)
         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,
                 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.updatedAt > incomingCell.updatedAt {
                 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: Int16 = 0
     ) -> 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 "block":
             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)
             friend.authorID = key
             friend.isBlocked = true
             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.
             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: both participants can write into a friend zone, so
             // a name Decision is only honored when the zone is *the* pairwise
             // zone 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
             }
             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 a live friend zone is itself proof of
             // the friendship — resurrect the row from the zone it rode in on.
             let friend = FriendEntity(context: ctx)
             friend.authorID = key
             friend.pairKey = pairKey
             friend.friendZoneName = zoneID.zoneName
             friend.friendZoneOwnerName = zoneID.ownerName
             friend.databaseScope = databaseScope
             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).
             guard record.recordID.zoneID.zoneName == accountZoneID.zoneName,
                   databaseScope == 0
             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
         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,
         in context: NSManagedObjectContext
     ) -> NSManagedObject {
         let request = NSFetchRequest<NSManagedObject>(entityName: entityName)
         request.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         request.fetchLimit = 1
         if let existing = try? context.fetch(request).first {
             return existing
         }
         return NSEntityDescription.insertNewObject(forEntityName: entityName, into: context)
     }
 
 }