← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Sync/RecordSerializer.swift (78687B)

1import CloudKit
2import CoreData
3import CryptoKit
4import Foundation
5
6/// Pure-function helpers for converting between the app's Core Data / in-memory
7/// models and CloudKit `CKRecord` objects. Stateless — all context is passed in.
8enum RecordSerializer {
9
10    // MARK: - Direct fetch key sets
11
12    static let gameDesiredKeys: [CKRecord.FieldKey] = [
13        "title",
14        "completedAt",
15        "completedBy",
16        "shareRecordName",
17        "roomCredential",
18        "pushCredential",
19        "puzzleSource",
20        "syncVersion",
21    ]
22
23    // authorID/deviceID are not stored as fields — they're recovered from the
24    // record name (`moves-<gameID>-<authorID>-<deviceID>`).
25    static let movesDesiredKeys: [CKRecord.FieldKey] = [
26        "cells",
27        "updatedAt",
28    ]
29
30    // authorID is recovered from the record name (`player-<gameID>-<authorID>`).
31    static let playerDesiredKeys: [CKRecord.FieldKey] = [
32        "name",
33        "updatedAt",
34        "selRow",
35        "selCol",
36        "selDir",
37        "presenceUntil",
38        "readThrough",
39        "viewedAt",
40        "timeLog",
41        "pushAddress",
42    ]
43
44    // authorID/deviceID are recovered from the record name.
45    static let pingDesiredKeys: [CKRecord.FieldKey] = [
46        "playerName",
47        "puzzleTitle",
48        "kind",
49        "payload",
50        "addressee",
51    ]
52
53    static let pingDeletionDesiredKeys: [CKRecord.FieldKey] = [
54        "kind",
55    ]
56
57    // MARK: - Device identity
58
59    /// A stable per-device identifier appended to move and snapshot record
60    /// names to prevent two devices owned by the same iCloud user from
61    /// producing identical record names when both assign the same Lamport
62    /// clock value while offline.
63    ///
64    /// Stored in UserDefaults so it survives app restarts but resets on
65    /// reinstall (which is fine — a reinstalled app has no local moves to
66    /// conflict with).
67    static let localDeviceID: String = {
68        let key = "crossmate.localDeviceID"
69        if let stored = UserDefaults.standard.string(forKey: key) {
70            return stored
71        }
72        let new = UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
73        UserDefaults.standard.set(new, forKey: key)
74        return new
75    }()
76
77    // MARK: - Record names
78
79    static func recordName(forGameID gameID: UUID) -> String {
80        "game-\(gameID.uuidString)"
81    }
82
83    /// Recovers the game UUID from a `"game-<UUID>"` record or zone name — the
84    /// inverse of `recordName(forGameID:)`. Returns nil when the name isn't a
85    /// game name or the UUID doesn't parse. A game's zone name and its root
86    /// record name are identical, so this also resolves a share's zone.
87    static func gameID(fromGameRecordName name: String) -> UUID? {
88        guard name.hasPrefix("game-") else { return nil }
89        return UUID(uuidString: String(name.dropFirst("game-".count)))
90    }
91
92    /// One Moves record per `(game, authorID, deviceID)`. Each device only
93    /// writes to its own slot, so there are no write-write conflicts on the
94    /// `cells` field.
95    static func recordName(
96        forMovesInGame gameID: UUID,
97        authorID: String,
98        deviceID: String
99    ) -> String {
100        "moves-\(gameID.uuidString)-\(authorID)-\(deviceID)"
101    }
102
103    /// One Journal record per `(game, authorID, deviceID)` — this device's
104    /// whole local move log, uploaded once at completion (Phase 2). Same
105    /// `(game, author, device)` shape as the Moves record so collaborators'
106    /// uploads stay distinct and mergeable by timestamp for replay.
107    static func recordName(
108        forJournalInGame gameID: UUID,
109        authorID: String,
110        deviceID: String
111    ) -> String {
112        "journal-\(gameID.uuidString)-\(authorID)-\(deviceID)"
113    }
114
115    /// One player record per (game, author). Each participant only ever
116    /// writes to their own slot, so there are no write-write conflicts on
117    /// the field.
118    static func recordName(forPlayerInGame gameID: UUID, authorID: String) -> String {
119        "player-\(gameID.uuidString)-\(authorID)"
120    }
121
122    /// One Ping record per event. `deviceID` keeps cross-device writes from
123    /// the same iCloud user unique (authorID is identical across that user's
124    /// devices), and the event timestamp covers repeated pings from the same
125    /// device.
126    static func recordName(
127        forPingInGame gameID: UUID,
128        authorID: String,
129        deviceID: String,
130        eventTimestampMs: Int64
131    ) -> String {
132        "ping-\(gameID.uuidString)-\(authorID)-\(deviceID)-\(eventTimestampMs)"
133    }
134
135    /// One `Decision` record per `(kind, key)`. A durable, per-user fact that
136    /// must agree across a single iCloud user's own devices — the durable
137    /// counterpart to the transient `Ping`. Lives in the account zone; the
138    /// deterministic name makes every write an idempotent upsert. `kind`
139    /// carries no dashes (so the first dash after the prefix splits cleanly);
140    /// `key` may contain dashes.
141    static func decisionRecordName(kind: String, key: String) -> String {
142        "decision-\(kind)-\(key)"
143    }
144
145    /// Parses `decision-<kind>-<key>`. `kind` is the segment up to the first
146    /// dash after the prefix; `key` is the remainder.
147    static func parseDecisionRecordName(_ name: String) -> (kind: String, key: String)? {
148        let prefix = "decision-"
149        guard name.hasPrefix(prefix) else { return nil }
150        let rest = name.dropFirst(prefix.count)
151        guard let dash = rest.firstIndex(of: "-") else { return nil }
152        let kind = String(rest[rest.startIndex..<dash])
153        let key = String(rest[rest.index(after: dash)...])
154        guard !kind.isEmpty, !key.isEmpty else { return nil }
155        return (kind, key)
156    }
157
158    /// Kind for the display-name Decision: `decision-name-<authorID>`, payload
159    /// = the display name, `version` = the author's monotonic rename
160    /// generation. The author writes their own copy into their account zone
161    /// (own-device convergence and restore durability) and into every friend
162    /// zone they participate in (the friend's devices read it from there) —
163    /// names never sync through any other channel.
164    static let nameDecisionKind = "name"
165
166    static func nameDecisionName(authorID: String) -> String {
167        decisionRecordName(kind: nameDecisionKind, key: authorID)
168    }
169
170    /// Parses a display-name Decision into its subject author, name, and
171    /// version. Returns `nil` for any other decision or an empty payload.
172    static func parseNameDecision(
173        _ record: CKRecord
174    ) -> (authorID: String, name: String, version: Int64)? {
175        guard record.recordType == "Decision",
176              let (kind, key) = parseDecisionRecordName(record.recordID.recordName),
177              kind == nameDecisionKind,
178              ((record["kind"] as? String) ?? nameDecisionKind) == nameDecisionKind,
179              let name = record["payload"] as? String,
180              !name.isEmpty
181        else { return nil }
182        return (key, name, decisionVersion(record))
183    }
184
185    /// Kind for the friend-nickname Decision: `decision-nickname-<authorID>`,
186    /// payload = the nickname this user privately calls that friend (absent or
187    /// empty = cleared, fall back to the friend's own name), `version` = this
188    /// user's monotonic rename generation for that friend. Lives only in the
189    /// account zone — it's the user's own label, never shared with the friend.
190    static let nicknameDecisionKind = "nickname"
191    static let encryptionKeyDecisionKind = "encryptionKey"
192
193    /// Kind for the friend-block Decision: `decision-block-<authorID>`, payload
194    /// `"1"` blocked / `"0"` unblocked, `version` = this user's monotonic block
195    /// generation for that friend. Lives only in the account zone and converges
196    /// the *UI* flag across the user's own devices — the actual enforcement is
197    /// the server-side `.readOnly` downgrade on the inbox share, which is
198    /// inherently account-wide.
199    static let blockDecisionKind = "block"
200
201    static let accountDecisionKind = "account"
202    static let accountPushAddressDecisionKey = "pushAddress"
203    /// Key for the account-wide push *secret* decision. The secret is the HMAC
204    /// key from which every per-game push address is derived (see
205    /// `deriveGameAddress`); it converges across the account's own devices the
206    /// same way the account address does, and is never sent to peers or the
207    /// push worker — only the derived per-game addresses are.
208    static let accountPushSecretDecisionKey = "pushSecret"
209
210    static var accountPushAddressDecisionName: String {
211        decisionRecordName(kind: accountDecisionKind, key: accountPushAddressDecisionKey)
212    }
213
214    static var accountPushSecretDecisionName: String {
215        decisionRecordName(kind: accountDecisionKind, key: accountPushSecretDecisionKey)
216    }
217
218    /// A push-address/secret Decision is authoritative only from *this
219    /// account's* zone in the private database. Match on zone name + private
220    /// scope, mirroring the `nickname` case in `applyDecisionRecord`: a friend
221    /// holds `.readWrite` on our private `friend-<pairKey>` inbox (also scope
222    /// 0), so without the zone-name check a forged `decision-account-pushSecret`
223    /// dropped there would be adopted as our own HMAC secret and re-derive every
224    /// per-game push address. An `==` on the full `zoneID` is unreliable — a
225    /// record fetched back from CloudKit often loses the
226    /// `CKCurrentUserDefaultName` owner placeholder — so match the name.
227    static func isAccountZonePrivateDecision(
228        _ record: CKRecord,
229        databaseScope: DatabaseScope
230    ) -> Bool {
231        record.recordID.zoneID.zoneName == accountZoneID.zoneName
232            && databaseScope == .private
233    }
234
235    static func parseAccountPushAddressDecision(
236        _ record: CKRecord,
237        databaseScope: DatabaseScope
238    ) -> String? {
239        guard record.recordType == "Decision",
240              record.recordID.recordName == accountPushAddressDecisionName,
241              (record["kind"] as? String) == accountDecisionKind,
242              isAccountZonePrivateDecision(record, databaseScope: databaseScope),
243              let address = record["payload"] as? String,
244              !address.isEmpty
245        else { return nil }
246        return address
247    }
248
249    /// Default generation for a `version`-less Decision — any record written by
250    /// the pre-rotation code. Matched to the value a fresh mint uses so legacy
251    /// and freshly-minted secrets share a generation and converge via the
252    /// equal-version "server wins" rule, while a deliberate rotation (2+)
253    /// supersedes them. Mapping to 0 instead would let the first post-update
254    /// mint clobber an already-converged legacy secret.
255    static let decisionBaseVersion: Int64 = 1
256
257    /// The monotonic generation of a Decision. Higher wins: an inbound or
258    /// conflicting record at a higher version supersedes the local value; equal
259    /// versions converge on whoever reached the server first. Absent (legacy)
260    /// records report `decisionBaseVersion`.
261    static func decisionVersion(_ record: CKRecord) -> Int64 {
262        (record["version"] as? Int64) ?? decisionBaseVersion
263    }
264
265    static func parseAccountPushSecretDecision(
266        _ record: CKRecord,
267        databaseScope: DatabaseScope
268    ) -> (secret: String, version: Int64)? {
269        guard record.recordType == "Decision",
270              record.recordID.recordName == accountPushSecretDecisionName,
271              (record["kind"] as? String) == accountDecisionKind,
272              isAccountZonePrivateDecision(record, databaseScope: databaseScope),
273              let secret = record["payload"] as? String,
274              !secret.isEmpty
275        else { return nil }
276        return (secret, decisionVersion(record))
277    }
278
279    /// Derives this account's push address for one game as
280    /// `HMAC-SHA256(secret, gameID)`, base64url-encoded. Deterministic, so every
281    /// one of the account's devices computes the identical address for a game
282    /// without any negotiation, and per-game scoped: a peer holding one game's
283    /// address can't compute another's without the secret, which never leaves
284    /// the account's devices. Rotation is by changing the secret.
285    static func deriveGameAddress(secret: String, gameID: UUID) -> String {
286        let key = SymmetricKey(data: Data(secret.utf8))
287        let mac = HMAC<SHA256>.authenticationCode(
288            for: Data(gameID.uuidString.utf8),
289            using: key
290        )
291        return Data(mac).base64EncodedString()
292            .replacingOccurrences(of: "+", with: "-")
293            .replacingOccurrences(of: "/", with: "_")
294            .replacingOccurrences(of: "=", with: "")
295    }
296
297    // MARK: - Zone
298
299    /// Zone ID for a per-game zone. `ownerName` defaults to the current user
300    /// placeholder; pass an explicit value for shared games where the zone is
301    /// owned by another iCloud account.
302    static func zoneID(
303        for gameID: UUID,
304        ownerName: String = CKCurrentUserDefaultName
305    ) -> CKRecordZone.ID {
306        CKRecordZone.ID(zoneName: "game-\(gameID.uuidString)", ownerName: ownerName)
307    }
308
309    // MARK: - Inbound record identity
310
311    /// The record types that live in per-game zones (plus the archive zone)
312    /// and therefore must pass `isTrustedGameScopedRecord` /
313    /// `isTrustedGameScopedDeletion` before touching a game-scoped apply
314    /// path. Everything else (Decision, share metadata, …) has its own
315    /// zone/scope gates.
316    static func isGameScopedRecordType(_ type: CKRecord.RecordType) -> Bool {
317        switch type {
318        case "Game", "Moves", "Player", "Ping", "Journal",
319             Archive.recordType, Archive.legacyRecordType:
320            return true
321        default:
322            return false
323        }
324    }
325
326    /// CloudKit reports the creator of a record that the *fetching* user
327    /// created themselves as the `CKCurrentUserDefaultName` placeholder, not
328    /// their concrete user-record name — so the placeholder must be accepted
329    /// alongside the claimed author, or every self-authored record is
330    /// rejected when it round-trips (fresh install, second device, replay).
331    /// This does not weaken the impersonation defense: a record created by a
332    /// *remote* participant always arrives with their concrete creator ID,
333    /// never the placeholder.
334    private static func creatorMatches(
335        _ creatorUserRecordName: String?,
336        claimedAuthorID: String
337    ) -> Bool {
338        creatorUserRecordName == claimedAuthorID
339            || creatorUserRecordName == CKCurrentUserDefaultName
340    }
341
342    /// Returns whether a fetched record is safe to route into a game-scoped
343    /// apply path. Record names are writable by share participants, so they
344    /// are only an assertion until they agree with CloudKit's zone identity.
345    ///
346    /// Moves, Player, Journal, and Ping records additionally claim an author
347    /// in their name. CloudKit supplies the immutable creator identity for a
348    /// record; require it to match so a collaborator cannot create a new row
349    /// in their own name space that impersonates another participant. `Game`
350    /// has no claimed author — its root record is authenticated by requiring
351    /// its record name to be exactly the per-game zone name.
352    static func isTrustedGameScopedRecord(_ record: CKRecord) -> Bool {
353        isTrustedGameScopedRecord(
354            record,
355            creatorUserRecordName: record.creatorUserRecordID?.recordName
356        )
357    }
358
359    /// Variant used by tests to exercise CloudKit provenance without needing
360    /// a server-created CKRecord.
361    static func isTrustedGameScopedRecord(
362        _ record: CKRecord,
363        creatorUserRecordName: String?
364    ) -> Bool {
365        let recordID = record.recordID
366        switch record.recordType {
367        case "Game":
368            guard let gameID = gameID(fromGameRecordName: recordID.recordName) else {
369                return false
370            }
371            return recordID.zoneID.zoneName == recordName(forGameID: gameID)
372
373        case "Moves":
374            guard let (gameID, authorID, _) = parseMovesRecordName(recordID.recordName) else {
375                return false
376            }
377            return recordID.zoneID.zoneName == recordName(forGameID: gameID)
378                && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
379
380        case "Player":
381            guard let (gameID, authorID) = parsePlayerRecordName(recordID.recordName) else {
382                return false
383            }
384            return recordID.zoneID.zoneName == recordName(forGameID: gameID)
385                && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
386
387        case "Journal":
388            guard let (gameID, authorID, _) = parseJournalRecordName(recordID.recordName) else {
389                return false
390            }
391            return recordID.zoneID.zoneName == recordName(forGameID: gameID)
392                && creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
393
394        case "Ping":
395            guard let (gameID, authorID, _) = parsePingRecordName(recordID.recordName),
396                  creatorMatches(creatorUserRecordName, claimedAuthorID: authorID)
397            else { return false }
398            // Friend-zone pings deliberately carry the target game's ID while
399            // living in a deterministic friend mailbox. Game-zone pings must
400            // still be confined to the game named by their record.
401            return !recordID.zoneID.zoneName.hasPrefix("game-")
402                || recordID.zoneID.zoneName == recordName(forGameID: gameID)
403
404        case Archive.recordType:
405            guard let gameID = Archive.originalGameID(fromName: recordID.recordName),
406                  recordID.recordName == Archive.recordName(forOriginalGameID: gameID),
407                  recordID.zoneID.zoneName == Archive.zoneName
408            else { return false }
409            return true
410
411        case Archive.legacyRecordType:
412            guard let gameID = Archive.originalGameID(fromName: recordID.recordName),
413                  recordID.recordName == Archive.legacyRecordName(
414                    forOriginalGameID: gameID
415                  ),
416                  recordID.zoneID.zoneName == Archive.legacyZoneID(
417                    forOriginalGameID: gameID
418                  ).zoneName
419            else { return false }
420            return true
421
422        default:
423            return false
424        }
425    }
426
427    /// Deletions do not carry creator metadata, but CloudKit does retain their
428    /// full record identity. Reject a deletion whose name is not confined to
429    /// the game zone before it can match a local row. Only consulted for
430    /// `isGameScopedRecordType` types; anything else is out of scope here.
431    static func isTrustedGameScopedDeletion(
432        recordID: CKRecord.ID,
433        recordType: CKRecord.RecordType
434    ) -> Bool {
435        let gameID: UUID?
436        switch recordType {
437        case "Game":
438            gameID = Self.gameID(fromGameRecordName: recordID.recordName)
439        case "Moves":
440            gameID = parseMovesRecordName(recordID.recordName)?.0
441        case "Player":
442            gameID = parsePlayerRecordName(recordID.recordName)?.0
443        case "Journal":
444            gameID = parseJournalRecordName(recordID.recordName)?.0
445        case "Ping":
446            // Same confinement rule as the record case: a friend-mailbox ping
447            // names a game outside its zone by design; a game-zone ping must
448            // name its own zone's game.
449            guard let (pingGameID, _, _) = parsePingRecordName(recordID.recordName) else {
450                return false
451            }
452            return !recordID.zoneID.zoneName.hasPrefix("game-")
453                || recordID.zoneID.zoneName == recordName(forGameID: pingGameID)
454        case Archive.recordType:
455            guard let originalID = Archive.originalGameID(fromName: recordID.recordName) else {
456                return false
457            }
458            return recordID.recordName == Archive.recordName(forOriginalGameID: originalID)
459                && recordID.zoneID.zoneName == Archive.zoneName
460        case Archive.legacyRecordType:
461            guard let originalID = Archive.originalGameID(fromName: recordID.recordName) else {
462                return false
463            }
464            return recordID.recordName == Archive.legacyRecordName(
465                forOriginalGameID: originalID
466            ) && recordID.zoneID.zoneName == Archive.legacyZoneID(
467                forOriginalGameID: originalID
468            ).zoneName
469        default:
470            return false
471        }
472        guard let gameID else { return false }
473        return recordID.zoneID.zoneName == recordName(forGameID: gameID)
474    }
475
476    /// Matches the local row for a record by its full zone identity, so a
477    /// private-zone record can never match a same-named shared-zone row (or
478    /// vice versa, or two shares of the same game by different owners).
479    ///
480    /// The owner name participates only for shared-database zones. CloudKit
481    /// does not reliably round-trip the `CKCurrentUserDefaultName` placeholder
482    /// for the current user's own zones — a fetched zone ID often carries the
483    /// concrete user-record ID instead (see `isAccountZonePrivateDecision`) —
484    /// so private rows always store `nil` and match on zone name alone, which
485    /// is unambiguous there: every private-database zone belongs to the
486    /// current user.
487    static func gameIdentityPredicate(
488        recordName: String,
489        zoneID: CKRecordZone.ID,
490        databaseScope: DatabaseScope,
491        entityPrefix: String = ""
492    ) -> NSPredicate {
493        let zonePrefix = entityPrefix.isEmpty ? "" : "\(entityPrefix)."
494        if databaseScope == .private {
495            return NSPredicate(
496                format: "ckRecordName == %@ AND \(zonePrefix)ckZoneName == %@ AND \(zonePrefix)ckZoneOwnerName == NIL",
497                recordName,
498                zoneID.zoneName
499            )
500        }
501        return NSPredicate(
502            format: "ckRecordName == %@ AND \(zonePrefix)ckZoneName == %@ AND \(zonePrefix)ckZoneOwnerName == %@",
503            recordName,
504            zoneID.zoneName,
505            zoneID.ownerName
506        )
507    }
508
509    /// Zone ID for the user's account-wide zone in the private database. Holds
510    /// records that coordinate state between a single iCloud user's own
511    /// devices — never shared with collaborators, since the private database
512    /// itself isn't reachable to anyone else.
513    static let accountZoneID = CKRecordZone.ID(
514        zoneName: "account",
515        ownerName: CKCurrentUserDefaultName
516    )
517
518    // MARK: - Moves record building
519
520    static func movesRecord(
521        from view: MovesValue,
522        zone: CKRecordZone.ID,
523        systemFields: Data?
524    ) throws -> CKRecord {
525        let movesName = recordName(
526            forMovesInGame: view.gameID,
527            authorID: view.authorID,
528            deviceID: view.deviceID
529        )
530        let record = restoreOrCreate(
531            recordType: "Moves",
532            recordName: movesName,
533            zone: zone,
534            systemFields: systemFields
535        )
536
537        // authorID/deviceID live in the record name, not as fields.
538        record["updatedAt"] = view.updatedAt as CKRecordValue
539        record["cells"] = try MovesCodec.encode(view.cells) as CKRecordValue
540
541        return record
542    }
543
544    // MARK: - Journal record building
545
546    /// Builds the `Journal` record carrying this device's full move log as a
547    /// `CKAsset`. Write-once at completion, so there is no system-fields
548    /// archive (mirrors `Ping`/`Decision`): a fresh record each build, and a
549    /// re-send of an already-uploaded journal is a benign conflict the send
550    /// path drops. The encoded entries are written to a temp file the same way
551    /// `populateGameRecord` stages `puzzleSource` — CloudKit copies the asset
552    /// on upload and the OS reaps the temporary directory.
553    static func journalRecord(
554        gameID: UUID,
555        authorID: String,
556        deviceID: String,
557        updatedAt: Date,
558        entries: [JournalValue],
559        zone: CKRecordZone.ID
560    ) throws -> CKRecord {
561        let name = recordName(forJournalInGame: gameID, authorID: authorID, deviceID: deviceID)
562        let recordID = CKRecord.ID(recordName: name, zoneID: zone)
563        let record = CKRecord(recordType: "Journal", recordID: recordID)
564        // authorID/deviceID live in the record name, not as fields.
565        record["updatedAt"] = updatedAt as CKRecordValue
566
567        let data = try JournalCodec.encode(entries)
568        let url = FileManager.default.temporaryDirectory
569            .appendingPathComponent(UUID().uuidString)
570            .appendingPathExtension("json")
571        try data.write(to: url, options: .atomic)
572        record["entries"] = CKAsset(fileURL: url)
573
574        return record
575    }
576
577    static func gameRecord(
578        from entity: GameEntity,
579        recordID: CKRecord.ID,
580        includePuzzleSource: Bool
581    ) -> CKRecord? {
582        guard entity.ckRecordName != nil else { return nil }
583        let record: CKRecord
584        if let fields = entity.ckSystemFields,
585           let restored = decodeRecord(from: fields) {
586            record = restored
587        } else {
588            record = CKRecord(recordType: "Game", recordID: recordID)
589        }
590        populateGameRecord(record, from: entity, includePuzzleSource: includePuzzleSource)
591        return record
592    }
593
594    static func populateGameRecord(
595        _ record: CKRecord,
596        from entity: GameEntity,
597        includePuzzleSource: Bool
598    ) {
599        // `title`, `shareRecordName`, and `syncVersion` are owner-authoritative:
600        // the title and protocol come from the game the owner created, and only
601        // owner devices track the share record. A participant only re-saves this record to
602        // mint the engagement/notification creds below, and at join time its
603        // local `title` is still the transient "Joining…" placeholder
604        // (`SyncEngine.handleFetchedDatabaseChanges`) until the owner's Game
605        // record lands. Writing it from a participant would LWW-clobber the real
606        // title on the shared record for everyone — so a non-owner leaves these
607        // fields untouched and the server keeps the owner's value.
608        let isOwner = entity.databaseScope == 0
609        if isOwner {
610            record["title"] = entity.title as CKRecordValue?
611            // Owner-side share marker. Propagated so other owner-devices can flip
612            // their `isShared` flag without reading the zone's CKShare directly.
613            record["shareRecordName"] = entity.ckShareRecordName as CKRecordValue?
614            record["syncVersion"] = GameSyncVersion.normalized(entity.syncVersion) as CKRecordValue
615        }
616        // Completion is terminal. A metadata-only save from a participant with
617        // a stale local row must not clear a completion already present in the
618        // restored server record.
619        if let completedAt = entity.completedAt {
620            record["completedAt"] = completedAt as CKRecordValue
621            // Solver's authorID on a win; nil for a resignation.
622            record["completedBy"] = entity.completedBy as CKRecordValue?
623        }
624        // The shared live-engagement room credentials (encoded
625        // EngagementRoomCredentials). Any present participant may mint these
626        // when the field is empty; convergence is plain record-level LWW, and
627        // peers connect to whatever creds the field currently holds.
628        // Stored as UTF-8 BYTES (matching cells/timeLog), not STRING — these
629        // are opaque JSON blobs, not queryable text.
630        record["roomCredential"] = entity.engagement?.data(using: .utf8) as CKRecordValue?
631        // The shared per-game notification credentials (encoded
632        // GamePushCredentials: the push auth secret + credID, plus the
633        // worker-blind content key the payload is encrypted under). Synced to
634        // participants like `engagement`; any participant may mint it when
635        // empty, and record-level LWW converges concurrent mints.
636        record["pushCredential"] = entity.notification?.data(using: .utf8) as CKRecordValue?
637        guard includePuzzleSource, let source = entity.puzzleSource else { return }
638        let url = FileManager.default.temporaryDirectory
639            .appendingPathComponent(UUID().uuidString)
640            .appendingPathExtension("xd")
641        try? source.write(to: url, atomically: true, encoding: .utf8)
642        record["puzzleSource"] = CKAsset(fileURL: url)
643    }
644
645    /// Builds a freshly-minted Ping record. Pings are write-once — they have
646    /// no Core Data equivalent and no system-fields archive.
647    /// - `authorID` + `deviceID` together let receivers filter out self-sends.
648    ///   authorID alone is insufficient for kinds (e.g. `.opened`) that fire
649    ///   between a single user's own devices, where authorID is identical.
650    /// - `playerName` and `puzzleTitle` let receivers render the alert body.
651    /// - `kind` distinguishes the bootstrap kinds current clients write
652    ///   (.friend / .invite / .decline); legacy `.join`/`.hail` records
653    ///   remain parseable but are no longer produced.
654    static func pingRecord(
655        gameID: UUID,
656        authorID: String,
657        deviceID: String,
658        playerName: String,
659        puzzleTitle: String,
660        eventTimestampMs: Int64,
661        kind: PingKind,
662        payload: String? = nil,
663        addressee: String? = nil,
664        zone: CKRecordZone.ID
665    ) -> CKRecord {
666        let name = recordName(
667            forPingInGame: gameID,
668            authorID: authorID,
669            deviceID: deviceID,
670            eventTimestampMs: eventTimestampMs
671        )
672        let recordID = CKRecord.ID(recordName: name, zoneID: zone)
673        let record = CKRecord(recordType: "Ping", recordID: recordID)
674        // authorID/deviceID live in the record name, not as fields.
675        record["playerName"] = playerName as CKRecordValue
676        record["puzzleTitle"] = puzzleTitle as CKRecordValue
677        record["kind"] = kind.rawValue as CKRecordValue
678        // Directed pings target one player by authorID; nil ⇒ broadcast (every
679        // recipient acts on it).
680        if let addressee {
681            record["addressee"] = addressee as CKRecordValue
682        }
683        if let payload {
684            record["payload"] = payload as CKRecordValue
685        }
686        return record
687    }
688
689    /// Builds a `Decision` record. The identity (`kind` + `key`) lives in the
690    /// record name, which keeps every write an idempotent upsert; `key` is not
691    /// duplicated as a field. `payload` is the generic, kind-specific extra
692    /// slot — empty for `block`, where presence alone is the fact — mirroring
693    /// `Ping.payload`. `systemFields` is the archived server record (with its
694    /// change tag): pass it so a re-send carries the current tag and CloudKit
695    /// accepts the update (e.g. rotating the push secret) instead of rejecting
696    /// it as a colliding create. Decisions are therefore upsertable, not
697    /// write-once; a payload-less write clears any value a restored record held.
698    static func decisionRecord(
699        kind: String,
700        key: String,
701        payload: String? = nil,
702        zone: CKRecordZone.ID,
703        systemFields: Data? = nil,
704        version: Int64? = nil
705    ) -> CKRecord {
706        let name = decisionRecordName(kind: kind, key: key)
707        let record = restoreOrCreate(
708            recordType: "Decision",
709            recordName: name,
710            zone: zone,
711            systemFields: systemFields
712        )
713        record["kind"] = kind as CKRecordValue
714        record["payload"] = payload.map { $0 as CKRecordValue }
715        record["version"] = version.map { $0 as CKRecordValue }
716        return record
717    }
718
719    static func playerRecord(
720        gameID: UUID,
721        authorID: String,
722        name: String,
723        updatedAt: Date,
724        selection: PlayerSelection?,
725        presenceUntil: Date? = nil,
726        readThrough: Date? = nil,
727        viewedAt: Date? = nil,
728        timeLog: Data? = nil,
729        pushAddress: String? = nil,
730        zone: CKRecordZone.ID,
731        systemFields: Data?
732    ) -> CKRecord {
733        let recordName = recordName(forPlayerInGame: gameID, authorID: authorID)
734        let record = restoreOrCreate(
735            recordType: "Player",
736            recordName: recordName,
737            zone: zone,
738            systemFields: systemFields
739        )
740
741        // authorID lives in the record name, not as a field.
742        record["name"] = name as CKRecordValue
743        record["updatedAt"] = updatedAt as CKRecordValue
744        if let selection {
745            record["selRow"] = Int64(selection.row) as CKRecordValue
746            record["selCol"] = Int64(selection.col) as CKRecordValue
747            record["selDir"] = Int64(selection.direction.rawValue) as CKRecordValue
748        } else {
749            record["selRow"] = nil
750            record["selCol"] = nil
751            record["selDir"] = nil
752        }
753        // The forward-dated presence lease, shipped as the `presenceUntil`
754        // CKRecord field.
755        if let presenceUntil {
756            record["presenceUntil"] = presenceUntil as CKRecordValue
757        } else {
758            record["presenceUntil"] = nil
759        }
760        // `readThrough` is the true read watermark — the latest other-author
761        // move time this account has actually seen. Never forward-dated, so a
762        // peer's session-end summary windows only on moves we genuinely missed.
763        if let readThrough {
764            record["readThrough"] = readThrough as CKRecordValue
765        } else {
766            record["readThrough"] = nil
767        }
768        if let viewedAt {
769            record["viewedAt"] = viewedAt as CKRecordValue
770        } else {
771            record["viewedAt"] = nil
772        }
773        // `timeLog` is the device-keyed solve-time log (encoded `TimeLog`):
774        // each device's active-play intervals plus its open session. Unlike the
775        // other LWW fields here, a device only ever mutates its own slot, so
776        // concurrent sibling writes converge by device once merged on apply.
777        if let timeLog, !timeLog.isEmpty {
778            record["timeLog"] = timeLog as CKRecordValue
779        } else {
780            record["timeLog"] = nil
781        }
782        if let pushAddress, !pushAddress.isEmpty {
783            record["pushAddress"] = pushAddress as CKRecordValue
784        } else {
785            record["pushAddress"] = nil
786        }
787
788        return record
789    }
790
791    /// Reads `presenceUntil` off an inbound Player record — the per-account horizon
792    /// for collaborator moves this user has read or is actively watching.
793    /// Active puzzle sessions may lease the horizon into the near future and
794    /// close it with a lower current-time write, so callers must apply this
795    /// only after accepting the Player record under last-writer-wins
796    /// freshness checks.
797    /// Returns `nil` if the field is missing — older records, or a slot that
798    /// has not yet recorded a view.
799    static func parsePlayerPresenceUntil(from record: CKRecord) -> Date? {
800        record["presenceUntil"] as? Date
801    }
802
803    /// Reads `readThrough` off an inbound Player record — the per-account read
804    /// watermark: the latest other-author move time this user has actually
805    /// seen. Unlike `presenceUntil` it is never leased into the future, so the
806    /// session-end push uses it to decide what a recipient still hasn't seen.
807    /// Returns `nil` for records that predate the field or a slot that has not
808    /// recorded a read yet.
809    static func parsePlayerReadThrough(from record: CKRecord) -> Date? {
810        record["readThrough"] as? Date
811    }
812
813    /// Reads `selRow`/`selCol`/`selDir` off an inbound Player record. These
814    /// fields carry the peer's cursor track start, not their exact local
815    /// reticle. Returns `nil` if any field is missing — the peer either hasn't
816    /// published a track yet or has cleared theirs (e.g. left the puzzle view).
817    static func parsePlayerSelection(from record: CKRecord) -> PlayerSelection? {
818        guard let row = record["selRow"] as? Int64,
819              let col = record["selCol"] as? Int64,
820              let dirRaw = record["selDir"] as? Int64,
821              let direction = PlayerSelection.Direction(rawValue: Int(dirRaw))
822        else { return nil }
823        return PlayerSelection(row: Int(row), col: Int(col), direction: direction)
824    }
825
826    /// Reads `viewedAt` off an inbound Player record — this account's "last
827    /// viewed" cutoff, written on leave and shared across the author's own
828    /// devices so a sibling converges on the latest view time rather than
829    /// recomputing the catch-up baseline from its own (possibly stale) view.
830    /// Returns `nil` when the account has not yet left a game with peers.
831    static func parsePlayerViewedAt(from record: CKRecord) -> Date? {
832        record["viewedAt"] as? Date
833    }
834
835    /// Reads `timeLog` off an inbound Player record — the encoded `TimeLog`
836    /// of device-keyed solve-time intervals. Returns `nil` for records that
837    /// predate the field (or before the schema deploy), which the clock treats
838    /// as a zero contribution.
839    static func parsePlayerTimeLog(from record: CKRecord) -> Data? {
840        record["timeLog"] as? Data
841    }
842
843    /// Reads `pushAddress` off an inbound Player record — the per-(account,
844    /// game) capability token a co-participant uses to address a push to this
845    /// player for this game. Possession is gated by the share ACL (only
846    /// participants can read the record), so the token, not an identity, is
847    /// the authorisation. Returns `nil` for older records or a slot that has
848    /// not yet minted one.
849    static func parsePlayerPushAddress(from record: CKRecord) -> String? {
850        record["pushAddress"] as? String
851    }
852
853    /// Parses an incoming `Player` record name back into its `(gameID,
854    /// authorID)` components. Returns `nil` if the name doesn't match the
855    /// `player-<UUID>-<authorID>` shape.
856    static func parsePlayerRecordName(_ name: String) -> (UUID, String)? {
857        guard name.hasPrefix("player-") else { return nil }
858        let rest = name.dropFirst("player-".count)
859        let uuidLength = 36
860        guard rest.count > uuidLength,
861              rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
862        else { return nil }
863        let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
864        guard let gameID = UUID(uuidString: uuidPart) else { return nil }
865        let authorPart = String(rest.suffix(from: rest.index(rest.startIndex, offsetBy: uuidLength + 1)))
866        guard !authorPart.isEmpty else { return nil }
867        return (gameID, authorPart)
868    }
869
870    /// Parses an incoming `Moves` CKRecord into a `MovesValue`. Returns `nil`
871    /// if the record name doesn't match the `moves-<gameUUID>-<authorID>-<deviceID>`
872    /// shape or the cells payload fails to decode.
873    static func parseMovesRecord(_ record: CKRecord) -> MovesValue? {
874        guard record.recordType == "Moves" else { return nil }
875        guard let (gameID, authorID, deviceID) = parseMovesRecordName(
876            record.recordID.recordName
877        ) else { return nil }
878        guard let data = record["cells"] as? Data,
879              let cells = try? MovesCodec.decode(data)
880        else { return nil }
881        let updatedAt = record["updatedAt"] as? Date
882            ?? record.modificationDate
883            ?? Date()
884        return MovesValue(
885            gameID: gameID,
886            authorID: authorID,
887            deviceID: deviceID,
888            cells: cells,
889            updatedAt: updatedAt
890        )
891    }
892
893    /// Parses `moves-<gameUUID>-<authorID>-<deviceID>` into its three parts.
894    /// `deviceID` is the suffix after the final `-`; `authorID` may itself
895    /// contain dashes (e.g. CloudKit user record names with no dashes today,
896    /// but we don't want to assume).
897    static func parseMovesRecordName(_ name: String) -> (UUID, String, String)? {
898        let prefix = "moves-"
899        guard name.hasPrefix(prefix) else { return nil }
900        let rest = name.dropFirst(prefix.count)
901        let uuidLength = 36
902        guard rest.count > uuidLength,
903              rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
904        else { return nil }
905        let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
906        guard let gameID = UUID(uuidString: uuidPart) else { return nil }
907        let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
908        let tail = rest[afterUUID...]
909        guard let lastDash = tail.lastIndex(of: "-") else { return nil }
910        let authorID = String(tail[tail.startIndex..<lastDash])
911        let deviceID = String(tail[tail.index(after: lastDash)...])
912        guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
913        return (gameID, authorID, deviceID)
914    }
915
916    /// Parses `journal-<gameUUID>-<authorID>-<deviceID>` into its three parts.
917    /// Same decomposition as `parseMovesRecordName` (deviceID is the suffix
918    /// after the final `-`; authorID may itself contain dashes).
919    static func parseJournalRecordName(_ name: String) -> (UUID, String, String)? {
920        let prefix = "journal-"
921        guard name.hasPrefix(prefix) else { return nil }
922        let rest = name.dropFirst(prefix.count)
923        let uuidLength = 36
924        guard rest.count > uuidLength,
925              rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
926        else { return nil }
927        let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
928        guard let gameID = UUID(uuidString: uuidPart) else { return nil }
929        let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
930        let tail = rest[afterUUID...]
931        guard let lastDash = tail.lastIndex(of: "-") else { return nil }
932        let authorID = String(tail[tail.startIndex..<lastDash])
933        let deviceID = String(tail[tail.index(after: lastDash)...])
934        guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
935        return (gameID, authorID, deviceID)
936    }
937
938    /// Parses `ping-<gameUUID>-<authorID>-<deviceID>-<eventTimestampMs>` into
939    /// its identity components. Splits from the right: the trailing
940    /// `eventTimestampMs` is dash-free digits and `deviceID` is a dash-free hex
941    /// id, so both peel off cleanly; `authorID` is the remainder and may itself
942    /// contain dashes (same tolerance as `parseMovesRecordName`). Returns nil if
943    /// the name isn't a ping name or the UUID doesn't parse.
944    static func parsePingRecordName(_ name: String) -> (UUID, String, String)? {
945        let prefix = "ping-"
946        guard name.hasPrefix(prefix) else { return nil }
947        let rest = name.dropFirst(prefix.count)
948        let uuidLength = 36
949        guard rest.count > uuidLength,
950              rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
951        else { return nil }
952        let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
953        guard let gameID = UUID(uuidString: uuidPart) else { return nil }
954        let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
955        // `<authorID>-<deviceID>-<eventTimestampMs>`
956        let tail = rest[afterUUID...]
957        guard let tsDash = tail.lastIndex(of: "-") else { return nil }
958        let authorAndDevice = tail[tail.startIndex..<tsDash]
959        guard let deviceDash = authorAndDevice.lastIndex(of: "-") else { return nil }
960        let authorID = String(authorAndDevice[authorAndDevice.startIndex..<deviceDash])
961        let deviceID = String(authorAndDevice[authorAndDevice.index(after: deviceDash)...])
962        guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
963        return (gameID, authorID, deviceID)
964    }
965
966    // MARK: - Bounded asset reads
967
968    /// A `CKAsset` staging file rejected before it was read into memory.
969    enum AssetReadError: Error, CustomStringConvertible {
970        case oversized(bytes: Int, limit: Int)
971        case unknownSize
972
973        var description: String {
974            switch self {
975            case .oversized(let bytes, let limit):
976                return "asset exceeds \(limit) bytes (\(bytes))"
977            case .unknownSize:
978                return "asset file size unavailable"
979            }
980        }
981    }
982
983    /// Reads an untrusted `CKAsset` staging file only after its on-disk size
984    /// passes `limit`. A co-player controls the asset's content, and an asset
985    /// is an external file that can dwarf the ~1 MB record limit — so never
986    /// `Data(contentsOf:)` one unchecked. Fails closed when the size can't be
987    /// determined.
988    static func boundedAssetData(at url: URL, limit: Int) throws -> Data {
989        guard let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize else {
990            throw AssetReadError.unknownSize
991        }
992        guard size <= limit else {
993            throw AssetReadError.oversized(bytes: size, limit: limit)
994        }
995        return try Data(contentsOf: url)
996    }
997
998    // MARK: - Applying incoming CKRecords to Core Data
999
1000    /// Returns the `GameEntity` for `gameID`, creating an unpopulated stub if
1001    /// none exists yet. Moves and Player records can arrive in a different
1002    /// fetch batch than the Game record that created the zone — on
1003    /// a fresh device CKSyncEngine paginates the initial pull and there is no
1004    /// guarantee that Game comes first. Without this stub the parent lookup
1005    /// fails, the inbound record is dropped, but CKSyncEngine still advances
1006    /// its change token, so the gap is invisible until the next state reset.
1007    /// The stub uses empty `title` / `puzzleSource` so `GameSummary.init?`
1008    /// filters it out of the library until `applyGameRecord` arrives with
1009    /// the real metadata and updates the same row (matched by `ckRecordName`).
1010    static func ensureGameEntity(
1011        forGameID gameID: UUID,
1012        zoneID: CKRecordZone.ID,
1013        databaseScope: DatabaseScope = .private,
1014        in ctx: NSManagedObjectContext
1015    ) -> GameEntity {
1016        let name = recordName(forGameID: gameID)
1017        let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
1018        req.predicate = gameIdentityPredicate(
1019            recordName: name,
1020            zoneID: zoneID,
1021            databaseScope: databaseScope
1022        )
1023        req.fetchLimit = 1
1024        if let existing = try? ctx.fetch(req).first { return existing }
1025        let entity = GameEntity(context: ctx)
1026        entity.id = gameID
1027        entity.ckRecordName = name
1028        entity.ckZoneName = zoneID.zoneName
1029        // Scope, not the owner-name spelling, decides ownership: a private-DB
1030        // zone always belongs to the current user even when its fetched zone
1031        // ID carries the concrete user-record ID instead of the placeholder.
1032        entity.ckZoneOwnerName = databaseScope == .private ? nil : zoneID.ownerName
1033        entity.databaseScope = databaseScope.rawValue
1034        entity.syncVersion = GameSyncVersion.legacy
1035        entity.title = ""
1036        entity.puzzleSource = ""
1037        entity.createdAt = Date()
1038        entity.updatedAt = Date()
1039        return entity
1040    }
1041
1042    static func applyGameRecord(
1043        _ record: CKRecord,
1044        to context: NSManagedObjectContext,
1045        databaseScope: DatabaseScope = .private,
1046        onEngagementChange: ((UUID) -> Void)? = nil,
1047        onCompletedTransition: ((UUID) -> Void)? = nil,
1048        onContentKeyChange: ((UUID) -> Void)? = nil,
1049        onStaleCredentials: ((String) -> Void)? = nil,
1050        onDiagnostic: ((String) -> Void)? = nil
1051    ) -> GameEntity {
1052        let recordName = record.recordID.recordName
1053        let entity = fetchOrCreate(
1054            entityName: "GameEntity",
1055            recordName: recordName,
1056            zoneID: record.recordID.zoneID,
1057            databaseScope: databaseScope,
1058            in: context
1059        ) as! GameEntity
1060
1061        // Recover the UUID from the record name ("game-<UUID>") so the
1062        // library query, which filters on `entity.id`, doesn't silently drop
1063        // newly-synced games.
1064        if entity.id == nil {
1065            let uuidString = String(recordName.dropFirst("game-".count))
1066            entity.id = UUID(uuidString: uuidString)
1067        }
1068
1069        // Drop fetched snapshots older than what we already have; adopting
1070        // them downgrades the local etag and OpLock-fails the next save
1071        // (same rationale as `applyMovesRecord` / `applyPlayerRecord`).
1072        if entity.ckSystemFields != nil,
1073           !incomingIsAtLeastAsFresh(record, existingFields: entity.ckSystemFields) {
1074            return entity
1075        }
1076
1077        // Always adopt the fresher etag and zone identity so the next outbound
1078        // push uses a current change tag and routes to the right zone.
1079        entity.ckRecordName = recordName
1080        entity.ckSystemFields = encodeSystemFields(of: record)
1081        entity.ckZoneName = record.recordID.zoneID.zoneName
1082        // Scope, not the owner-name spelling, decides ownership — CloudKit
1083        // round-trips a private zone's owner as either the placeholder or the
1084        // concrete user-record ID, and `gameIdentityPredicate` relies on
1085        // private rows always storing nil.
1086        entity.ckZoneOwnerName =
1087            databaseScope == .private ? nil : record.recordID.zoneID.ownerName
1088        entity.databaseScope = databaseScope.rawValue
1089
1090        // The owner chooses and may advance the game's protocol. Participants
1091        // never write this field, so they can adopt it even while an unrelated
1092        // metadata save is pending. An owner with a pending local save keeps
1093        // its chosen value until that save round-trips.
1094        if databaseScope == .shared || !entity.hasPendingSave {
1095            entity.syncVersion = GameSyncVersion.normalized(
1096                (record["syncVersion"] as? Int64) ?? GameSyncVersion.legacy
1097            )
1098        }
1099
1100        // Local mutable fields take precedence while a push is in flight.
1101        // The flag is set atomically with the local write (in `markCompleted`,
1102        // `resignGame`, `persistShareName`) and cleared once `SyncEngine`
1103        // confirms the push landed. Writing server values here would clobber
1104        // the pending change and the next outbound push would then serialise
1105        // the clobbered value, permanently losing it server-side.
1106        guard !entity.hasPendingSave else { return entity }
1107
1108        // Seed createdAt/updatedAt from the server record only on first sight,
1109        // so a newly-arrived game has something for the library to order by.
1110        // After that, the library timestamp tracks *gameplay* (Moves) alone.
1111        // The Game record's modificationDate advances on non-gameplay writes
1112        // too — engagement/push credentials, share metadata, the notification
1113        // field — so adopting it on every fetch made a game look freshly
1114        // "updated" when nothing was played (e.g. a peer, or this device,
1115        // merely moved the cursor or re-minted a credential). Gameplay flows
1116        // through the Moves path, which sets updatedAt independently; the
1117        // winning move is itself a move, so completion still advances it.
1118        if entity.createdAt == nil {
1119            entity.createdAt = record.creationDate ?? Date()
1120        }
1121        if entity.updatedAt == nil {
1122            entity.updatedAt = record.modificationDate ?? Date()
1123        }
1124
1125        entity.title = record["title"] as? String ?? entity.title
1126        // Capture the prior completion state before overwriting it: a
1127        // not-completed → completed transition learned purely via sync (this
1128        // device wasn't present when the puzzle was finished) does NOT run the
1129        // local completion path, so it never uploads this device's journal.
1130        // Replay's strict completeness would then wait on it forever. Signal
1131        // the transition so the caller can enqueue the upload.
1132        let wasCompleted = entity.completedAt != nil
1133        let incomingCompletedAt = record["completedAt"] as? Date
1134        if let incomingCompletedAt {
1135            entity.completedAt = incomingCompletedAt
1136            entity.completedBy = record["completedBy"] as? String
1137        } else if entity.completedAt == nil {
1138            entity.completedAt = nil
1139            entity.completedBy = nil
1140        }
1141        if !wasCompleted, entity.completedAt != nil, let id = entity.id {
1142            onCompletedTransition?(id)
1143        }
1144        // Owner-side share marker — set on the device that created the share
1145        // and round-tripped via the Game record so other owner-devices learn
1146        // the game is shared. On participant devices `databaseScope == 1`
1147        // already implies shared, but keeping the field in sync is harmless.
1148        if let shareRecordName = record["shareRecordName"] as? String {
1149            entity.ckShareRecordName = shareRecordName
1150        }
1151
1152        // Adopt the engagement creds (skipped above while a local mint is
1153        // still pushing, via the hasPendingSave guard). A change here is the
1154        // signal a peer minted/rotated the room, so the receiver reconciles
1155        // its live connection toward the new creds.
1156        let incomingEngagement = (record["roomCredential"] as? Data)
1157            .flatMap { String(data: $0, encoding: .utf8) }
1158        if entity.engagement != incomingEngagement {
1159            entity.engagement = incomingEngagement
1160            if let id = entity.id { onEngagementChange?(id) }
1161        }
1162
1163        // Adopt the shared notification credentials. The credential is read
1164        // lazily at registration/publish time, so converging the field is
1165        // enough — but a change may carry a new embedded content key, so fire
1166        // `onContentKeyChange` to re-mirror the App Group key directory the NSE
1167        // reads. This is what lets a freshly-joined participant decrypt the
1168        // first push it receives, rather than waiting for the next launch heal.
1169        //
1170        // Adoption is generation-gated: rotation replaces the credential at a
1171        // higher `gen`, and the Game record is pushed whole, so a stale device
1172        // re-pushing an unrelated change (its inbound applies were blocked by
1173        // its own `hasPendingSave`) can land the *old* credential back on the
1174        // server. Adopting that here would silently re-admit a departed
1175        // participant. Instead keep the newer local credential, flag our copy
1176        // as pending, and hand the record name to `onStaleCredentials` so the
1177        // caller re-pushes it — healing the server to the rotated value.
1178        let incomingNotification = (record["pushCredential"] as? Data)
1179            .flatMap { String(data: $0, encoding: .utf8) }
1180        if entity.notification != incomingNotification {
1181            let localGen = GamePushCredentials.decode(entity.notification)?.generation
1182            let incomingGen = GamePushCredentials.decode(incomingNotification)?.generation
1183            // A local credential is superseded only by an inbound one of equal
1184            // or higher generation (equal = concurrent rotations; the server
1185            // copy wins the tie). An inbound *absence* never clears a local
1186            // credential — creds are minted once and only ever replaced, so a
1187            // missing field is always a stale record.
1188            let incomingSupersedes: Bool
1189            if localGen == nil {
1190                incomingSupersedes = true
1191            } else if let incomingGen, let localGen {
1192                incomingSupersedes = incomingGen >= localGen
1193            } else {
1194                incomingSupersedes = false
1195            }
1196            if incomingSupersedes {
1197                entity.notification = incomingNotification
1198                if let id = entity.id { onContentKeyChange?(id) }
1199            } else {
1200                onDiagnostic?(
1201                    "stale pushCredential for \(recordName) " +
1202                    "(inbound gen \(incomingGen.map(String.init) ?? "none") < " +
1203                    "local gen \(localGen.map(String.init) ?? "none")) — keeping local, re-pushing"
1204                )
1205                entity.hasPendingSave = true
1206                onStaleCredentials?(recordName)
1207            }
1208        }
1209
1210        if let asset = record["puzzleSource"] as? CKAsset,
1211           let fileURL = asset.fileURL {
1212            do {
1213                // A co-player writes this asset into the shared zone, so treat
1214                // its size as untrusted: reject an oversized blob before reading
1215                // it into memory. The parser enforces the same bound, but the
1216                // asset is an external file that could dwarf the ~1 MB record
1217                // limit, so gate on the on-disk size first.
1218                if let size = try? fileURL.resourceValues(forKeys: [.fileSizeKey]).fileSize,
1219                   size > XD.maxSourceBytes {
1220                    onDiagnostic?(
1221                        "puzzleSource asset for \(recordName) " +
1222                        "exceeds \(XD.maxSourceBytes) bytes (\(size)) — skipping"
1223                    )
1224                    return entity
1225                }
1226                let source = try String(contentsOf: fileURL, encoding: .utf8)
1227                entity.puzzleSource = source
1228                if let xd = try? XD.parse(source) {
1229                    let puzzle = Puzzle(xd: xd)
1230                    entity.puzzleParserVersion = Int64(XD.currentParserVersion)
1231                    // The title is always derived from the puzzle content (there
1232                    // is no custom game title), so trust the asset over the
1233                    // record's `title` field — which was already applied above.
1234                    // This re-derives the real title even when `record["title"]`
1235                    // carried a stale value, e.g. a participant's transient
1236                    // "Joining…" placeholder that a prior build wrote to the
1237                    // shared record, so the title self-heals on the next sync
1238                    // that carries the asset.
1239                    entity.title = puzzle.title
1240                    entity.populateCachedSummaryFields(from: puzzle)
1241                }
1242            } catch {
1243                // CKSyncEngine has already committed this batch by the time
1244                // the delegate returns, so re-throwing wouldn't redeliver.
1245                // Surface the dropped puzzle source instead of silently
1246                // leaving the entity without playable content.
1247                let nsError = error as NSError
1248                onDiagnostic?(
1249                    "puzzleSource asset read failed for \(recordName) " +
1250                    "— domain=\(nsError.domain) code=\(nsError.code) " +
1251                    "\(nsError.localizedDescription)"
1252                )
1253            }
1254        }
1255
1256        return entity
1257    }
1258
1259    /// Upserts the `MovesEntity` for `value`. The cells blob is taken straight
1260    /// off the record so any forward-compat fields the encoder added are
1261    /// preserved verbatim. Bumps the parent `GameEntity.updatedAt` if the
1262    /// record is fresher. Returns `true` when cells/updatedAt were adopted,
1263    /// `false` when the local-device-row guard short-circuited the body so
1264    /// callers can skip the downstream grid refresh.
1265    ///
1266    /// `onNewAuthor` fires with the authorID when this record creates the first
1267    /// `MovesEntity` row by a *remote* contributor — i.e. a participant the
1268    /// roster can only discover from their moves (no `Player` record yet, see
1269    /// `PlayerRoster.refresh`). Callers use it to trigger a one-off roster
1270    /// refresh on a new collaborator's first move without refreshing on every
1271    /// subsequent keystroke or sibling-device row.
1272    @discardableResult
1273    static func applyMovesRecord(
1274        _ record: CKRecord,
1275        value: MovesValue,
1276        to ctx: NSManagedObjectContext,
1277        databaseScope: DatabaseScope = .private,
1278        localAuthorID: String? = nil,
1279        onNewAuthor: ((String) -> Void)? = nil
1280    ) -> Bool {
1281        let ckName = record.recordID.recordName
1282        let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
1283        req.predicate = gameIdentityPredicate(
1284            recordName: ckName,
1285            zoneID: record.recordID.zoneID,
1286            databaseScope: databaseScope,
1287            entityPrefix: "game"
1288        )
1289        req.fetchLimit = 1
1290
1291        let entity: MovesEntity
1292        let foundExisting: Bool
1293        let authorAlreadyKnown: Bool
1294        if let existing = try? ctx.fetch(req).first {
1295            entity = existing
1296            foundExisting = true
1297            authorAlreadyKnown = true
1298        } else {
1299            let authorReq = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
1300            authorReq.predicate = NSPredicate(
1301                format: "game.id == %@ AND authorID == %@",
1302                value.gameID as CVarArg,
1303                value.authorID
1304            )
1305            authorReq.fetchLimit = 1
1306            authorAlreadyKnown = ((try? ctx.fetch(authorReq).first) != nil)
1307
1308            let game = ensureGameEntity(
1309                forGameID: value.gameID,
1310                zoneID: record.recordID.zoneID,
1311                databaseScope: databaseScope,
1312                in: ctx
1313            )
1314            entity = MovesEntity(context: ctx)
1315            entity.game = game
1316            foundExisting = false
1317        }
1318
1319        // Drop fetched snapshots that are older than what we already have.
1320        // The writeback after a successful push advances `ckSystemFields` to
1321        // the latest server etag; a query that started before that push
1322        // landed can return the prior server state, and adopting it here
1323        // would downgrade the etag and OpLock-fail the next save.
1324        if foundExisting,
1325           !incomingIsAtLeastAsFresh(record, existingFields: entity.ckSystemFields) {
1326            return false
1327        }
1328
1329        // Adopt system fields so future saves target the server's current
1330        // change tag. If this is our own per-device row and it already
1331        // exists locally, the local value state is authoritative; tokenless
1332        // push-driven direct fetches can re-deliver an older server copy while
1333        // newer edits are still queued for upload.
1334        entity.ckRecordName = ckName
1335        entity.ckSystemFields = encodeSystemFields(of: record)
1336        entity.authorID = value.authorID
1337        entity.deviceID = value.deviceID
1338        let isLocalDeviceRow = value.authorID == localAuthorID
1339            && value.deviceID == localDeviceID
1340        guard !foundExisting || !isLocalDeviceRow else { return false }
1341        let previousUpdatedAt = entity.updatedAt ?? .distantPast
1342        let previousCells = (entity.cells.flatMap { try? MovesCodec.decode($0) }) ?? [:]
1343        let mergedCells = mergeIncomingMovesCells(
1344            existing: previousCells,
1345            incoming: value.cells
1346        )
1347        let mergedUpdatedAt = max(
1348            previousUpdatedAt,
1349            value.updatedAt,
1350            mergedCells.values.map(\.updatedAt).max() ?? .distantPast
1351        )
1352
1353        entity.updatedAt = mergedUpdatedAt
1354        entity.cells = (try? MovesCodec.encode(mergedCells)) ?? ((record["cells"] as? Data) ?? Data())
1355
1356        if let game = entity.game,
1357           game.updatedAt.map({ $0 < mergedUpdatedAt }) ?? true {
1358            game.updatedAt = mergedUpdatedAt
1359        }
1360        // A newly-seen remote author is the roster's only cue to
1361        // a contributor who hasn't published a `Player` record yet. Signal it
1362        // once here; repeat moves and sibling-device rows by a known author
1363        // don't.
1364        if !foundExisting,
1365           !authorAlreadyKnown,
1366           value.authorID != localAuthorID,
1367           value.authorID != CKCurrentUserDefaultName,
1368           !value.authorID.isEmpty {
1369            onNewAuthor?(value.authorID)
1370        }
1371        return true
1372    }
1373
1374    private static func mergeIncomingMovesCells(
1375        existing: [GridPosition: TimestampedCell],
1376        incoming: [GridPosition: TimestampedCell]
1377    ) -> [GridPosition: TimestampedCell] {
1378        var cells = existing
1379        for (position, incomingCell) in incoming {
1380            if let existingCell = cells[position],
1381               existingCell.compareRevision(to: incomingCell) != .orderedAscending {
1382                continue
1383            }
1384            cells[position] = incomingCell
1385        }
1386        return cells
1387    }
1388
1389    /// Projects an inbound `Decision` record onto local Core Data. For
1390    /// `kind == "block"` this upserts a `FriendEntity` tombstone keyed by the
1391    /// blocked author so the block becomes authoritative across the user's own
1392    /// devices: `applyInvitePings` (authorID-keyed) and the friendship
1393    /// bootstrap's `friendExists` (pairKey-keyed) both then suppress the
1394    /// blocked collaborator everywhere. A device that never befriended the
1395    /// author still gets a minimal blocked row. Returns `true` when a row was
1396    /// written. `localAuthorID` lets the pairKey be derived for the bootstrap
1397    /// short-circuit; it's deterministic from the unordered author pair.
1398    @discardableResult
1399    static func applyDecisionRecord(
1400        _ record: CKRecord,
1401        to ctx: NSManagedObjectContext,
1402        localAuthorID: String?,
1403        databaseScope: DatabaseScope = .private
1404    ) -> Bool {
1405        guard record.recordType == "Decision" else { return false }
1406        // Identity comes from the record name (always present, immutable);
1407        // `kind` is also mirrored as a field, name-parse as the fallback.
1408        let parsed = parseDecisionRecordName(record.recordID.recordName)
1409        guard let kind = (record["kind"] as? String) ?? parsed?.kind,
1410              let key = parsed?.key,
1411              !kind.isEmpty, !key.isEmpty
1412        else { return false }
1413
1414        switch kind {
1415        case blockDecisionKind:
1416            // A block is the user's own choice, authoritative across their
1417            // devices — honored only from the account zone in the private
1418            // database. Friend zones are writable by the other participant, who
1419            // must not be able to block (or unblock) a third party on this
1420            // user's behalf. Same gate as `nickname`/`left`.
1421            guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
1422            else { return false }
1423            // Versioned so a stale copy can't resurrect a cleared block (or
1424            // re-clear a fresh one). Payload `"0"` means unblocked; anything
1425            // else (including a legacy payload-less record) means blocked.
1426            let version = decisionVersion(record)
1427            let blocked = (record["payload"] as? String) != "0"
1428            let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
1429            req.predicate = NSPredicate(format: "authorID == %@", key)
1430            req.fetchLimit = 1
1431            let friend = (try? ctx.fetch(req).first) ?? FriendEntity(context: ctx)
1432            guard version >= friend.blockVersion else { return false }
1433            friend.authorID = key
1434            friend.isBlocked = blocked
1435            friend.blockVersion = version
1436            if friend.pairKey == nil,
1437               let localAuthorID, !localAuthorID.isEmpty {
1438                friend.pairKey = FriendZone.pairKey(localAuthorID, key)
1439            }
1440            if friend.createdAt == nil { friend.createdAt = Date() }
1441            return true
1442        case "left":
1443            // The user left this shared game on another of their devices.
1444            // Hard-delete the local row so it stops hanging around (the
1445            // shared-zone deletion alone would only flag it access-revoked,
1446            // see SyncEngine.handleFetchedDatabaseChanges). Idempotent: a
1447            // re-applied decision after the row is gone is a no-op. Guarded
1448            // to participant rows (databaseScope == 1) so a same-id owned
1449            // copy is never collateral.
1450            //
1451            // The decision itself is a self-authored cross-device signal, so
1452            // honor it only from the account zone in the private database — a
1453            // friend must not be able to name a `(gameID)` and evict its
1454            // participant row out of a zone he can write. Same gate as
1455            // `nickname`/`block`.
1456            guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
1457            else { return false }
1458            guard let gameID = UUID(uuidString: key) else { return false }
1459            let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
1460            req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
1461            req.fetchLimit = 1
1462            guard let entity = try? ctx.fetch(req).first,
1463                  entity.databaseScope == 1 else { return false }
1464            ctx.delete(entity)
1465            return true
1466        case nameDecisionKind:
1467            // A friend's display name, read out of the pairwise friend zone.
1468            // Our own copy (key == localAuthorID, account zone) carries no
1469            // Core Data projection — the local name lives in
1470            // `PlayerPreferences`; only its version is adopted, by the caller.
1471            guard let localAuthorID, !localAuthorID.isEmpty,
1472                  key != localAuthorID,
1473                  let name = record["payload"] as? String,
1474                  !name.isEmpty
1475            else { return false }
1476            // Provenance: a name Decision is only honored when the zone is *the*
1477            // pairwise mailbox for (us, key) — the zone name embeds a hash of
1478            // the author pair, so the claimed subject is verifiable without
1479            // trusting the record. This also rejects a name Decision for a third
1480            // party misdelivered into an unrelated zone.
1481            let pairKey = FriendZone.pairKey(localAuthorID, key)
1482            let zoneID = record.recordID.zoneID
1483            guard zoneID.zoneName == FriendZone.zoneName(pairKey: pairKey) else {
1484                return false
1485            }
1486            // The friend writes their name into *our inbox* (their outbox), so
1487            // a friend's name only ever arrives via the zone we own — the
1488            // private engine. Reject one seen at shared scope (that would be
1489            // the friend's own inbox, not the channel they tell us their name
1490            // through).
1491            guard databaseScope == .private else { return false }
1492            let version = decisionVersion(record)
1493            let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
1494            req.predicate = NSPredicate(format: "pairKey == %@", pairKey)
1495            req.fetchLimit = 1
1496            if let friend = try? ctx.fetch(req).first {
1497                guard !friend.isBlocked,
1498                      version >= friend.displayNameVersion
1499                else { return false }
1500                friend.displayName = name
1501                friend.displayNameVersion = version
1502                return true
1503            }
1504            // No local row: the bootstrap evidence (game zones, `.friend`
1505            // Ping) may be long gone on a restored device, but the name
1506            // Decision arriving from our inbox is itself proof of the
1507            // friendship — resurrect the row. Both mailbox zones are derivable
1508            // from `pairKey` + `authorID`, so no zone fields are stored.
1509            let friend = FriendEntity(context: ctx)
1510            friend.authorID = key
1511            friend.pairKey = pairKey
1512            friend.createdAt = Date()
1513            friend.displayName = name
1514            friend.displayNameVersion = version
1515            return true
1516        case nicknameDecisionKind:
1517            // The user's private nickname for a friend, authoritative across
1518            // their own devices. Honored only from the account zone in our own
1519            // private database: friend zones are writable by the other
1520            // participant, who must not be able to relabel people in this
1521            // user's friends list. Match on zone *name* + private scope, not a
1522            // full `zoneID ==`: a record fetched back from CloudKit does not
1523            // reliably carry the `CKCurrentUserDefaultName` owner placeholder
1524            // `accountZoneID` is built with — its `ownerName` often comes back
1525            // as the concrete user-record ID, so an `==` silently rejects every
1526            // synced nickname. Scoping to the private DB keeps the anti-relabel
1527            // guarantee (a friend can only reach us through the shared DB).
1528            // Same gate as `block`/`left`.
1529            guard isAccountZonePrivateDecision(record, databaseScope: databaseScope)
1530            else { return false }
1531            let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
1532            req.predicate = NSPredicate(format: "authorID == %@", key)
1533            req.fetchLimit = 1
1534            // No resurrection: unlike a name Decision, an account-zone row
1535            // carries no zone provenance to rebuild a usable friendship from,
1536            // and a zoneless row would surface as an uninvitable friend.
1537            guard let friend = try? ctx.fetch(req).first else { return false }
1538            let version = decisionVersion(record)
1539            guard version >= friend.nicknameVersion else { return false }
1540            let nickname = (record["payload"] as? String)?
1541                .trimmingCharacters(in: .whitespacesAndNewlines)
1542            // Empty/absent payload is a deliberate clear, not a malformed
1543            // record — the rename alert's blank entry reverts to their name.
1544            friend.nickname = (nickname?.isEmpty == false) ? nickname : nil
1545            friend.nicknameVersion = version
1546            return true
1547        case encryptionKeyDecisionKind:
1548            // Friend-zone message encryption material. Each participant writes
1549            // only their own key record, named by authorID; the peer mirrors it
1550            // to the App Group so the Notification Service Extension can
1551            // decrypt invite pushes before the game zone exists locally.
1552            guard let localAuthorID, !localAuthorID.isEmpty,
1553                  key != localAuthorID,
1554                  let payload = FriendEncryptionKeyPayload.decode(record["payload"] as? String)
1555            else { return false }
1556            let pairKey = FriendZone.pairKey(localAuthorID, key)
1557            let zoneID = record.recordID.zoneID
1558            guard zoneID.zoneName == FriendZone.zoneName(pairKey: pairKey) else {
1559                return false
1560            }
1561            // Like the `name` case: the friend writes their key into *our inbox*
1562            // (their outbox), so it only ever arrives via the zone we own — the
1563            // private engine. Reject one seen at shared scope (that would be
1564            // the friend's own inbox, not the channel they publish to us). The
1565            // zone-name gate alone is insufficient: a peer owns a zone that
1566            // *names* itself for this pair and shares it to us at shared scope.
1567            guard databaseScope == .private else { return false }
1568            FriendEncryptionKeyDirectory.upsert(payload, for: key)
1569            return false
1570        default:
1571            // Unknown kind from a newer build — ignore rather than guess.
1572            return false
1573        }
1574    }
1575
1576    // MARK: - System fields encode/decode
1577
1578    static func encodeSystemFields(of record: CKRecord) -> Data? {
1579        let coder = NSKeyedArchiver(requiringSecureCoding: true)
1580        record.encodeSystemFields(with: coder)
1581        coder.finishEncoding()
1582        return coder.encodedData
1583    }
1584
1585    static func decodeRecord(from data: Data) -> CKRecord? {
1586        guard let coder = try? NSKeyedUnarchiver(forReadingFrom: data) else { return nil }
1587        coder.requiresSecureCoding = true
1588        let record = CKRecord(coder: coder)
1589        coder.finishDecoding()
1590        return record
1591    }
1592
1593    /// Returns `true` when `incoming` reflects a server state at least as
1594    /// recent as the modification date encoded in `existingFields`. Used by
1595    /// the apply paths to drop fetched snapshots that arrive after our
1596    /// writeback has already adopted a newer change tag — adopting them
1597    /// would downgrade the local etag and the next save would OpLock-fail.
1598    /// Defaults to `true` when either side lacks a modification date so a
1599    /// first-time fetch can land.
1600    static func incomingIsAtLeastAsFresh(
1601        _ incoming: CKRecord,
1602        existingFields: Data?
1603    ) -> Bool {
1604        guard let existingFields,
1605              let existingRecord = decodeRecord(from: existingFields),
1606              let existingDate = existingRecord.modificationDate,
1607              let incomingDate = incoming.modificationDate
1608        else { return true }
1609        return incomingDate >= existingDate
1610    }
1611
1612    // MARK: - Private helpers
1613
1614    /// Restores a `CKRecord` from archived system fields (preserving the
1615    /// server change tag) or creates a fresh one if no archive is available.
1616    private static func restoreOrCreate(
1617        recordType: String,
1618        recordName: String,
1619        zone: CKRecordZone.ID,
1620        systemFields: Data?
1621    ) -> CKRecord {
1622        if let data = systemFields, let restored = decodeRecord(from: data) {
1623            return restored
1624        }
1625        let recordID = CKRecord.ID(recordName: recordName, zoneID: zone)
1626        return CKRecord(recordType: recordType, recordID: recordID)
1627    }
1628
1629    private static func fetchOrCreate(
1630        entityName: String,
1631        recordName: String,
1632        zoneID: CKRecordZone.ID,
1633        databaseScope: DatabaseScope,
1634        in context: NSManagedObjectContext
1635    ) -> NSManagedObject {
1636        let request = NSFetchRequest<NSManagedObject>(entityName: entityName)
1637        request.predicate = gameIdentityPredicate(
1638            recordName: recordName,
1639            zoneID: zoneID,
1640            databaseScope: databaseScope
1641        )
1642        request.fetchLimit = 1
1643        if let existing = try? context.fetch(request).first {
1644            return existing
1645        }
1646        return NSEntityDescription.insertNewObject(forEntityName: entityName, into: context)
1647    }
1648
1649}