crossmate

Archive.swift (46053B)

---

 import CloudKit
 import Compression
 import CoreData
 import CryptoKit
 import Foundation
 
 /// Serialization + materialization for a finished game's compact private
 /// archive.
 ///
 /// When a participant (not the owner) finishes a shared game, that game's data
 /// lives only in the owner's shared zone; if the owner later deletes it, the
 /// participant keeps a local copy but has no CloudKit backing, so a new device
 /// or reinstall loses it. To close that gap every involved account writes a
 /// self-contained snapshot — final grid + the full multi-author move journal —
 /// into one common zone in *its own* private database. A finished game is immutable
 /// (`isCompleted` latches at completion), so the snapshot needs no
 /// reconciliation: it is written once and only ever read back to rebuild a
 /// standalone completed game on another device or after the original is revoked.
 ///
 /// The snapshot is deliberately *not* a clone of the live multi-record game.
 /// The live representation keys one Core Data entity to one `CKRecord` identity
 /// tied to the shared zone (`RecordBuilder`), and the journal-upload path only
 /// uploads *this device's own* rows — so it cannot reproduce the full
 /// multi-author journal replay needs. Instead everything is folded into a single
 /// `Chronicle` record carrying all metadata and game data in one compressed
 /// payload asset. Once every accepted participant acknowledges that snapshot
 /// (or the retention deadline expires), the owner can delete the much larger
 /// live per-game zone without deleting the compact archive.
 enum Archive {
     /// The compact v1.1.0 record. It deliberately has a new CloudKit type so
     /// its schema contains only the single payload Asset.
     static let recordType = "Chronicle"
     /// Three-asset records written before v1.1.0.
     static let legacyRecordType = "Archive"
     static let zoneName = "completed-archives"
     static let payloadKey = "payload"
 
     /// The keys any fetch must ask for to decode a Chronicle. `completedAt` is
     /// not optional extra metadata: `payload(from:)` cross-checks it against the
     /// blob's own completion time, and a record fetched without it fails that
     /// identity guard exactly as a tampered one would.
     static let payloadDesiredKeys = ["completedAt", payloadKey]
 
     // MARK: - Inbound asset bounds
 
     /// Byte cap on the `cells` asset, checked on disk before it is read. The
     /// largest admissible grid (`XD.maxGridDimension`²) at ~120 bytes of JSON
     /// per cell is under 2 MiB; real puzzles are a few kilobytes.
     static let maxCellsAssetBytes = 2_097_152
 
     /// Byte cap on the merged `journals` asset, checked on disk before it is
     /// read. Wraps per-device `JournalCodec` blobs (each independently capped
     /// at `JournalCodec.maxAssetBytes`) in base64; a real finished game's
     /// merged log is a few hundred kilobytes, so 8 MiB rejects nothing
     /// genuine.
     static let maxJournalsAssetBytes = 8_388_608
 
     /// Bounds both the compressed asset read and the allocation used to
     /// decompress its versioned payload. The payload contains the three legacy
     /// assets plus a small amount of metadata; this leaves ample headroom while
     /// preventing a hostile envelope from requesting an arbitrary allocation.
     static let maxPayloadAssetBytes = 12_582_912
     static let maxDecodedPayloadBytes = 16_777_216
     static let currentPayloadFormatVersion = 3
     private static let maxParticipantCount = 64
 
     /// Upper bound on decoded final-grid cells; `XD.maxGridDimension`² is the
     /// largest cell count any admissible puzzle can produce.
     static let maxCellCount = XD.maxGridDimension * XD.maxGridDimension
 
     /// Upper bound on per-device journals in one archive. Every participant
     /// device that wrote grid state contributes one; real games have a
     /// handful.
     static let maxJournalDeviceCount = 64
 
     /// Namespace for deriving the archive's game id. A fixed random UUID used as
     /// the v5 namespace so `archiveGameID(for:)` is stable across the
     /// participant's own devices yet distinct from the original game id.
     private static let namespace = UUID(uuidString: "1F8B0E2A-3C4D-5E6F-7A8B-9C0D1E2F3A4B")!
 
     // MARK: - Identity
 
     /// The deterministic game id of the archived copy. Derived from the original
     /// game id so every one of the participant's devices computes the same value
     /// (idempotent re-writes, last-writer-wins on a frozen record) while staying
     /// distinct from `originalGameID` — the authoring device still holds the live
     /// original under that id, and Core Data fetches it by `id`.
     static func archiveGameID(for originalGameID: UUID) -> UUID {
         var hasher = Insecure.SHA1()
         hasher.update(data: withUnsafeBytes(of: namespace.uuid) { Data($0) })
         hasher.update(data: withUnsafeBytes(of: originalGameID.uuid) { Data($0) })
         let digest = Array(hasher.finalize())
         var bytes = Array(digest.prefix(16))
         // Stamp version (5) and RFC 4122 variant bits, like a real v5 UUID.
         bytes[6] = (bytes[6] & 0x0F) | 0x50
         bytes[8] = (bytes[8] & 0x3F) | 0x80
         let uuid = (
             bytes[0], bytes[1], bytes[2], bytes[3],
             bytes[4], bytes[5], bytes[6], bytes[7],
             bytes[8], bytes[9], bytes[10], bytes[11],
             bytes[12], bytes[13], bytes[14], bytes[15]
         )
         return UUID(uuid: uuid)
     }
 
     static var zoneID: CKRecordZone.ID {
         CKRecordZone.ID(
             zoneName: zoneName,
             ownerName: CKCurrentUserDefaultName
         )
     }
 
     /// The per-game zone used by archives written before v1.1.0. Kept solely
     /// for backward-compatible reads and one-way migration into `zoneID`.
     static func legacyZoneID(forOriginalGameID gameID: UUID) -> CKRecordZone.ID {
         CKRecordZone.ID(
             zoneName: "archive-\(gameID.uuidString)",
             ownerName: CKCurrentUserDefaultName
         )
     }
 
     static func recordName(forOriginalGameID gameID: UUID) -> String {
         "chronicle-\(gameID.uuidString)"
     }
 
     static func legacyRecordName(forOriginalGameID gameID: UUID) -> String {
         "archive-\(gameID.uuidString)"
     }
 
     /// The original game id encoded in either generation's record name, or
     /// `nil` if the name doesn't match.
     static func originalGameID(fromName name: String) -> UUID? {
         for prefix in ["chronicle-", "archive-"] where name.hasPrefix(prefix) {
             return UUID(uuidString: String(name.dropFirst(prefix.count)))
         }
         return nil
     }
 
     /// Copies the account's mutable unread state from a completed live Game
     /// onto its local Chronicle projection. The Chronicle payload itself stays
     /// immutable; these fields are device-local projections of the canonical
     /// live-game state so the visible Completed tile survives the handoff from
     /// the hidden Game row.
     static func mirrorReadState(from live: GameEntity, to chronicle: GameEntity) {
         if let latest = live.latestOtherMoveAt,
            (chronicle.latestOtherMoveAt ?? .distantPast) < latest {
             chronicle.latestOtherMoveAt = latest
         }
         if let readThrough = live.readThroughAt,
            (chronicle.readThroughAt ?? .distantPast) < readThrough {
             chronicle.readThroughAt = readThrough
         }
     }
 
     static func isArchiveZone(_ zoneName: String) -> Bool {
         zoneName == self.zoneName || zoneName.hasPrefix("archive-")
     }
 
     // MARK: - Final-grid wire format
 
     /// The final state of one cell, captured so the materialized game renders
     /// (and its library thumbnail fills) without replaying the journal.
     struct Cell: Codable, Equatable {
         let row: Int16
         let col: Int16
         let letter: String
         let markCode: Int16
         let letterAuthorID: String?
     }
 
     /// A frozen roster entry carried inside the compressed Chronicle payload.
     /// Names remain optional because v1 Chronicles can recover author IDs from
     /// their journals but cannot reconstruct names after the live zone is gone.
     struct Participant: Codable, Equatable {
         let authorID: String
         let name: String?
     }
 
     private static func encodeCells(_ cells: [Cell]) throws -> Data {
         try JSONEncoder().encode(cells.sorted {
             ($0.row, $0.col) < ($1.row, $1.col)
         })
     }
 
     /// A decoded archive asset that exceeds its entry-count bound. The asset
     /// is rejected whole — a truncated grid or journal set would materialize a
     /// silently incomplete game.
     enum LimitError: Error, CustomStringConvertible {
         case tooManyCells(count: Int)
         case tooManyDeviceJournals(count: Int)
         case tooManyParticipants(count: Int)
 
         var description: String {
             switch self {
             case .tooManyCells(let count):
                 return "cells asset exceeds \(maxCellCount) cells (\(count))"
             case .tooManyDeviceJournals(let count):
                 return "journals asset exceeds \(maxJournalDeviceCount) device journals (\(count))"
             case .tooManyParticipants(let count):
                 return "archive payload exceeds \(maxParticipantCount) participants (\(count))"
             }
         }
     }
 
     private static func decodeCells(_ data: Data) throws -> [Cell] {
         let cells = try JSONDecoder().decode([Cell].self, from: data)
         guard cells.count <= maxCellCount else {
             throw LimitError.tooManyCells(count: cells.count)
         }
         return cells
     }
 
     // MARK: - Per-device journal wire format
 
     /// One device's log on the wire: its `(authorID, deviceID)` key plus the same
     /// `JournalCodec` payload the live `Journal` records use, so encoding fidelity
     /// matches replay exactly.
     private struct DeviceJournalWire: Codable {
         let authorID: String
         let deviceID: String
         let entries: Data
     }
 
     /// The complete archive body. It is encoded as JSON only as an internal
     /// representation, then wrapped in an authenticated, bounded LZFSE envelope
     /// and stored as one CKAsset. No field needs to remain queryable in CloudKit:
     /// record identity carries the original game ID and Crossmate materializes
     /// the complete payload before displaying it.
     private struct Blob: Codable {
         let formatVersion: Int
         let originalGameID: UUID
         let archiveGameID: UUID
         let title: String
         let puzzleSource: String
         let completedAt: Date
         let completedBy: String?
         let solveSeconds: Int
         let replayAvailable: Bool
         /// Added in format 3. A positive value distinguishes a provisional
         /// Chronicle from the terminal no-replay retention fallback.
         let replayMissingDeviceCount: Int?
         let cells: [Cell]
         let journals: [DeviceJournalWire]
         /// Added in format 2. Optional so already-written format-1 payloads
         /// continue to decode and can infer contributors from their journals.
         let wasShared: Bool?
         let participants: [Participant]?
     }
 
     private static let envelopeMagic = Data("CMARCH01".utf8)
     private static let envelopeHeaderBytes = 8 + MemoryLayout<UInt64>.size + 32
 
     enum PayloadError: Error, CustomStringConvertible {
         case oversizedCompressedPayload(bytes: Int)
         case oversizedDecodedPayload(bytes: Int)
         case malformedEnvelope
         case unsupportedFormat(Int)
         case decompressionFailed
         case digestMismatch
         case identityMismatch
         case oversizedPuzzleSource(bytes: Int)
 
         var description: String {
             switch self {
             case .oversizedCompressedPayload(let bytes):
                 return "archive payload exceeds \(maxPayloadAssetBytes) compressed bytes (\(bytes))"
             case .oversizedDecodedPayload(let bytes):
                 return "archive payload exceeds \(maxDecodedPayloadBytes) decoded bytes (\(bytes))"
             case .malformedEnvelope:
                 return "archive payload envelope is malformed"
             case .unsupportedFormat(let version):
                 return "archive payload format \(version) is unsupported"
             case .decompressionFailed:
                 return "archive payload decompression failed"
             case .digestMismatch:
                 return "archive payload digest does not match"
             case .identityMismatch:
                 return "archive payload identity does not match its record"
             case .oversizedPuzzleSource(let bytes):
                 return "archive puzzle source exceeds \(XD.maxSourceBytes) bytes (\(bytes))"
             }
         }
     }
 
     private static func encodeEnvelope(_ decoded: Data) throws -> Data {
         guard decoded.count <= maxDecodedPayloadBytes else {
             throw PayloadError.oversizedDecodedPayload(bytes: decoded.count)
         }
         let compressed = try (decoded as NSData).compressed(using: .lzfse) as Data
         var result = Data()
         result.reserveCapacity(envelopeHeaderBytes + compressed.count)
         result.append(envelopeMagic)
         var length = UInt64(decoded.count).bigEndian
         withUnsafeBytes(of: &length) { result.append(contentsOf: $0) }
         result.append(contentsOf: SHA256.hash(data: decoded))
         result.append(compressed)
         guard result.count <= maxPayloadAssetBytes else {
             throw PayloadError.oversizedCompressedPayload(bytes: result.count)
         }
         return result
     }
 
     private static func decodeEnvelope(_ envelope: Data) throws -> Data {
         guard envelope.count >= envelopeHeaderBytes,
               envelope.prefix(envelopeMagic.count) == envelopeMagic
         else { throw PayloadError.malformedEnvelope }
 
         let lengthRange = envelopeMagic.count..<(envelopeMagic.count + MemoryLayout<UInt64>.size)
         let decodedLength = envelope[lengthRange].reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
         guard decodedLength <= UInt64(maxDecodedPayloadBytes),
               let decodedCount = Int(exactly: decodedLength),
               decodedCount > 0
         else {
             throw PayloadError.oversizedDecodedPayload(bytes: Int(clamping: decodedLength))
         }
 
         let digestStart = lengthRange.upperBound
         let digestEnd = digestStart + 32
         let expectedDigest = envelope[digestStart..<digestEnd]
         let compressed = envelope[digestEnd...]
         guard !compressed.isEmpty else { throw PayloadError.malformedEnvelope }
         var decoded = Data(count: decodedCount)
         let written = decoded.withUnsafeMutableBytes { destination in
             compressed.withUnsafeBytes { source in
                 compression_decode_buffer(
                     destination.bindMemory(to: UInt8.self).baseAddress!,
                     decodedCount,
                     source.bindMemory(to: UInt8.self).baseAddress!,
                     compressed.count,
                     nil,
                     COMPRESSION_LZFSE
                 )
             }
         }
         guard written == decodedCount else { throw PayloadError.decompressionFailed }
         guard Data(SHA256.hash(data: decoded)) == expectedDigest else {
             throw PayloadError.digestMismatch
         }
         return decoded
     }
 
     private static func encodeJournals(_ journals: [DeviceJournal]) throws -> Data {
         try JSONEncoder().encode(journalWire(journals))
     }
 
     private static func journalWire(_ journals: [DeviceJournal]) throws -> [DeviceJournalWire] {
         try journals
             .sorted { ($0.key.authorID, $0.key.deviceID) < ($1.key.authorID, $1.key.deviceID) }
             .map {
                 DeviceJournalWire(
                     authorID: $0.key.authorID,
                     deviceID: $0.key.deviceID,
                     entries: try JournalCodec.encode($0.entries)
                 )
             }
     }
 
     private static func decodeJournals(_ data: Data) throws -> [DeviceJournal] {
         let wire = try JSONDecoder().decode([DeviceJournalWire].self, from: data)
         return try decodeJournals(wire)
     }
 
     private static func decodeJournals(_ wire: [DeviceJournalWire]) throws -> [DeviceJournal] {
         guard wire.count <= maxJournalDeviceCount else {
             throw LimitError.tooManyDeviceJournals(count: wire.count)
         }
         return wire.map {
             DeviceJournal(
                 key: JournalDeviceKey(authorID: $0.authorID, deviceID: $0.deviceID),
                 // `JournalCodec.decode` enforces its own byte/entry bounds, so
                 // one device's over-limit blob degrades to an empty log rather
                 // than sinking the whole archive.
                 entries: (try? JournalCodec.decode($0.entries)) ?? []
             )
         }
     }
 
     // MARK: - Snapshot taken from local Core Data
 
     /// Everything needed to build (or rebuild) the archive record, read off the
     /// local game on a background context at archive time.
     struct Snapshot {
         let originalGameID: UUID
         let title: String
         let puzzleSource: String
         let completedAt: Date
         let completedBy: String?
         /// The frozen solve-clock value in whole seconds (active solving time, the
         /// union across all players) at the moment the game finished. Captured
         /// here because the per-player `Player.timeLog` records it lives on do not
         /// survive into the archive, so the materialised game would otherwise read
         /// zero. Whole seconds — the clock is only ever shown at second
         /// resolution.
         let solveSeconds: Int
         let wasShared: Bool
         let participants: [Participant]
         let cells: [Cell]
         /// The full move log, kept *per contributing device* (not flattened) so
         /// the materialized game replays exactly as the live one does: the replay
         /// assembler merges one log per device and gates on every expected device
         /// being present. See `GameArchiver` for how peers' logs are gathered.
         let journal: [DeviceJournal]
 
         init(
             originalGameID: UUID,
             title: String,
             puzzleSource: String,
             completedAt: Date,
             completedBy: String?,
             solveSeconds: Int,
             wasShared: Bool = false,
             participants: [Participant] = [],
             cells: [Cell],
             journal: [DeviceJournal]
         ) {
             self.originalGameID = originalGameID
             self.title = title
             self.puzzleSource = puzzleSource
             self.completedAt = completedAt
             self.completedBy = completedBy
             self.solveSeconds = solveSeconds
             self.wasShared = wasShared
             self.participants = participants
             self.cells = cells
             self.journal = journal
         }
     }
 
     /// Reads the local game's finished state, with the journal grouped by
     /// contributing device. Returns `nil` if the game is not a completed game or
     /// required fields are missing. The journal here is *local only* — this
     /// device's own log plus any peer logs already cached for replay;
     /// `GameArchiver` augments it with a `fetchReplay` of the shared zone while it
     /// is still reachable.
     static func snapshot(
         forGameID gameID: UUID,
         originalGameID: UUID? = nil,
         in ctx: NSManagedObjectContext
     ) -> Snapshot? {
         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,
               let completedAt = entity.completedAt,
               let source = entity.puzzleSource, !source.isEmpty
         else { return nil }
 
         let cellEntities = (entity.cells as? Set<CellEntity>) ?? []
         let cells = cellEntities.map {
             Cell(
                 row: $0.row,
                 col: $0.col,
                 letter: $0.letter ?? "",
                 markCode: $0.markCode,
                 letterAuthorID: $0.letterAuthorID
             )
         }
 
         let journal = localDeviceJournals(forGameID: gameID, in: ctx)
         var participantsByAuthor: [String: Participant] = [:]
         let playerReq = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         playerReq.predicate = NSPredicate(format: "game == %@", entity)
         for player in (try? ctx.fetch(playerReq)) ?? [] {
             guard let authorID = player.authorID, !authorID.isEmpty else { continue }
             let trimmedName = player.name?.trimmingCharacters(
                 in: .whitespacesAndNewlines
             )
             participantsByAuthor[authorID] = Participant(
                 authorID: authorID,
                 name: trimmedName?.isEmpty == false ? trimmedName : nil
             )
         }
         for encoded in [entity.archiveParticipants, entity.shareParticipants] {
             for authorID in encoded?.split(separator: ",").map(String.init) ?? [] {
                 guard !authorID.isEmpty else { continue }
                 participantsByAuthor[authorID] = participantsByAuthor[authorID]
                     ?? Participant(authorID: authorID, name: nil)
             }
         }
         for deviceJournal in journal where !deviceJournal.key.authorID.isEmpty {
             let authorID = deviceJournal.key.authorID
             participantsByAuthor[authorID] = participantsByAuthor[authorID]
                 ?? Participant(authorID: authorID, name: nil)
         }
 
         return Snapshot(
             originalGameID: originalGameID ?? gameID,
             title: entity.title ?? "",
             puzzleSource: source,
             completedAt: completedAt,
             completedBy: entity.completedBy,
             solveSeconds: solveSeconds(forGameID: gameID, asOf: completedAt, in: ctx),
             wasShared: entity.ckShareRecordName != nil || entity.databaseScope == 1,
             participants: participantsByAuthor.values.sorted {
                 $0.authorID < $1.authorID
             },
             cells: cells,
             journal: journal
         )
     }
 
     /// The union of every player's solve-clock intervals for `gameID`, frozen at
     /// `asOf` (the completion instant). Mirrors `PlayerRoster.solveTime` but reads
     /// from the supplied background context for the archive snapshot.
     private static func solveSeconds(
         forGameID gameID: UUID,
         asOf: Date,
         in ctx: NSManagedObjectContext
     ) -> Int {
         let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
         req.predicate = NSPredicate(format: "game.id == %@", gameID as CVarArg)
         let logs = ((try? ctx.fetch(req)) ?? []).map { TimeLog.decode($0.timeLog) }
         return Int(TimeLog.accumulatedSeconds(
             forLogs: logs,
             localDeviceID: RecordSerializer.localDeviceID,
             asOf: asOf
         ))
     }
 
     /// Groups the local `JournalEntity` rows for a game into per-device logs.
     /// Own rows (`sourceDeviceID == nil`) form one log keyed to this device; peer
     /// rows cached for replay carry their own source key.
     static func localDeviceJournals(
         forGameID gameID: UUID,
         in ctx: NSManagedObjectContext
     ) -> [DeviceJournal] {
         let req = NSFetchRequest<JournalEntity>(entityName: "JournalEntity")
         req.predicate = NSPredicate(format: "gameID == %@", gameID as CVarArg)
         req.sortDescriptors = [NSSortDescriptor(key: "seq", ascending: true)]
         let rows = (try? ctx.fetch(req)) ?? []
 
         var byKey: [JournalDeviceKey: [JournalValue]] = [:]
         for row in rows {
             let key: JournalDeviceKey
             if let device = row.sourceDeviceID {
                 key = JournalDeviceKey(authorID: row.sourceAuthorID ?? "", deviceID: device)
             } else {
                 // This device's own log: keyed to the local device, authored by
                 // whoever typed it (consistently the local user).
                 key = JournalDeviceKey(
                     authorID: row.actingAuthorID ?? "",
                     deviceID: RecordSerializer.localDeviceID
                 )
             }
             byKey[key, default: []].append(MovesJournal.value(from: row))
         }
         return byKey.map { DeviceJournal(key: $0.key, entries: $0.value) }
     }
 
     /// Merges peer logs (e.g. from a `fetchReplay`) into a snapshot's journal,
     /// keeping the local copy of any device already present (it is the
     /// authoritative, possibly-fresher log for this device).
     static func merging(
         _ snapshot: Snapshot,
         peerJournals: [DeviceJournal]
     ) -> Snapshot {
         var byKey: [JournalDeviceKey: [JournalValue]] = [:]
         for journal in peerJournals { byKey[journal.key] = journal.entries }
         for journal in snapshot.journal { byKey[journal.key] = journal.entries }
         return Snapshot(
             originalGameID: snapshot.originalGameID,
             title: snapshot.title,
             puzzleSource: snapshot.puzzleSource,
             completedAt: snapshot.completedAt,
             completedBy: snapshot.completedBy,
             solveSeconds: snapshot.solveSeconds,
             wasShared: snapshot.wasShared,
             participants: snapshot.participants,
             cells: snapshot.cells,
             journal: byKey.map { DeviceJournal(key: $0.key, entries: $0.value) }
         )
     }
 
     // MARK: - Record building
 
     struct RecordPackage {
         let record: CKRecord
         let temporaryAssetFileURLs: [URL]
     }
 
     static func recordPackage(
         from snapshot: Snapshot,
         replayState: ReplayState = .available,
         formatVersion: Int = currentPayloadFormatVersion
     ) throws -> RecordPackage {
         let zone = zoneID
         let recordID = CKRecord.ID(
             recordName: recordName(forOriginalGameID: snapshot.originalGameID),
             zoneID: zone
         )
         let record = CKRecord(recordType: recordType, recordID: recordID)
 
         let replayAvailable = replayState == .available
         let blob = Blob(
             formatVersion: formatVersion,
             originalGameID: snapshot.originalGameID,
             archiveGameID: archiveGameID(for: snapshot.originalGameID),
             title: snapshot.title,
             puzzleSource: snapshot.puzzleSource,
             completedAt: snapshot.completedAt,
             completedBy: snapshot.completedBy,
             solveSeconds: snapshot.solveSeconds,
             replayAvailable: replayAvailable,
             replayMissingDeviceCount: {
                 guard formatVersion >= 3,
                       case .waiting(let missing) = replayState
                 else { return nil }
                 return missing
             }(),
             cells: snapshot.cells.sorted { ($0.row, $0.col) < ($1.row, $1.col) },
             journals: replayAvailable ? try journalWire(snapshot.journal) : [],
             wasShared: formatVersion >= 2 ? snapshot.wasShared : nil,
             participants: formatVersion >= 2 ? snapshot.participants : nil
         )
         let encoded = try JSONEncoder().encode(blob)
         let payload = try asset(for: encodeEnvelope(encoded), ext: "cmarchive")
         record["completedAt"] = snapshot.completedAt
         record[payloadKey] = payload.asset
         return RecordPackage(
             record: record,
             temporaryAssetFileURLs: [payload.url]
         )
     }
 
     private static func asset(for data: Data, ext: String) throws -> (asset: CKAsset, url: URL) {
         let url = FileManager.default.temporaryDirectory
             .appendingPathComponent(UUID().uuidString)
             .appendingPathExtension(ext)
         try data.write(to: url, options: .atomic)
         return (CKAsset(fileURL: url), url)
     }
 
     // MARK: - Materialization
 
     /// The decoded payload of an inbound `Archive` record.
     struct Payload {
         let formatVersion: Int
         let originalGameID: UUID
         let archiveGameID: UUID
         let title: String
         let puzzleSource: String
         let completedAt: Date
         let completedBy: String?
         /// The frozen solve time in whole seconds, or `nil` for archives written
         /// before the field existed (their materialised game simply shows no time).
         let solveSeconds: Int?
         let replayState: ReplayState
         var replayAvailable: Bool { replayState == .available }
         let wasShared: Bool
         let participants: [Participant]
         let cells: [Cell]
         let journal: [DeviceJournal]
     }
 
     enum ReplayState: Equatable {
         case available
         case waiting(missing: Int)
         case unavailable
     }
 
     /// Builds the materialization payload directly from a local snapshot,
     /// without round-tripping through CloudKit. Used to promote the archive on
     /// revocation while still offline — the local game data is fully present, so
     /// the cloud copy need not have landed back.
     static func payload(
         from snapshot: Snapshot,
         replayState: ReplayState = .available
     ) -> Payload {
         let replayAvailable = replayState == .available
         return Payload(
             formatVersion: currentPayloadFormatVersion,
             originalGameID: snapshot.originalGameID,
             archiveGameID: archiveGameID(for: snapshot.originalGameID),
             title: snapshot.title,
             puzzleSource: snapshot.puzzleSource,
             completedAt: snapshot.completedAt,
             completedBy: snapshot.completedBy,
             solveSeconds: snapshot.solveSeconds,
             replayState: replayState,
             wasShared: snapshot.wasShared,
             participants: snapshot.participants,
             cells: snapshot.cells,
             journal: replayAvailable ? snapshot.journal : []
         )
     }
 
     static func payload(
         from record: CKRecord,
         onDiagnostic: ((String) -> Void)? = nil
     ) -> Payload? {
         switch record.recordType {
         case recordType:
             return blobPayload(from: record, onDiagnostic: onDiagnostic)
         case legacyRecordType:
             return legacyPayload(from: record, onDiagnostic: onDiagnostic)
         default:
             return nil
         }
     }
 
     private static func blobPayload(
         from record: CKRecord,
         onDiagnostic: ((String) -> Void)?
     ) -> Payload? {
         guard record.recordType == recordType,
               let recordOriginalID = originalGameID(fromName: record.recordID.recordName),
               record.recordID.recordName == recordName(
                 forOriginalGameID: recordOriginalID
               ),
               let asset = record[payloadKey] as? CKAsset,
               let url = asset.fileURL
         else { return nil }
         do {
             let envelope = try RecordSerializer.boundedAssetData(
                 at: url,
                 limit: maxPayloadAssetBytes
             )
             let decoded = try decodeEnvelope(envelope)
             let blob = try JSONDecoder().decode(Blob.self, from: decoded)
             guard (1...currentPayloadFormatVersion).contains(blob.formatVersion) else {
                 throw PayloadError.unsupportedFormat(blob.formatVersion)
             }
             guard let recordCompletedAt = record["completedAt"] as? Date else {
                 throw PayloadError.identityMismatch
             }
             let completionMetadataMatches = abs(
                 blob.completedAt.timeIntervalSince(recordCompletedAt)
             ) < 0.001
             guard blob.originalGameID == recordOriginalID,
                   blob.archiveGameID == archiveGameID(for: recordOriginalID),
                   completionMetadataMatches
             else { throw PayloadError.identityMismatch }
             let sourceBytes = blob.puzzleSource.utf8.count
             guard sourceBytes <= XD.maxSourceBytes else {
                 throw PayloadError.oversizedPuzzleSource(bytes: sourceBytes)
             }
             guard blob.cells.count <= maxCellCount else {
                 throw LimitError.tooManyCells(count: blob.cells.count)
             }
             let journals = blob.replayAvailable ? try decodeJournals(blob.journals) : []
             let replayState: ReplayState
             if blob.replayAvailable {
                 replayState = .available
             } else if let missing = blob.replayMissingDeviceCount,
                       (1...maxJournalDeviceCount).contains(missing) {
                 replayState = .waiting(missing: missing)
             } else if blob.replayMissingDeviceCount != nil {
                 // An out-of-range count is a corrupt or hostile payload, but the
                 // rest of the Chronicle is still verified and playable. Degrade
                 // to the terminal no-replay state rather than rejecting the
                 // whole archive over a count we only use to word a progress
                 // message.
                 replayState = .unavailable
             } else {
                 replayState = .unavailable
             }
             let participants = try validatedParticipants(
                 blob.participants ?? inferredParticipants(
                     journals: journals,
                     cells: blob.cells,
                     completedBy: blob.completedBy
                 )
             )
             return Payload(
                 formatVersion: blob.formatVersion,
                 originalGameID: blob.originalGameID,
                 archiveGameID: blob.archiveGameID,
                 title: blob.title,
                 puzzleSource: blob.puzzleSource,
                 completedAt: blob.completedAt,
                 completedBy: blob.completedBy,
                 solveSeconds: blob.solveSeconds,
                 replayState: replayState,
                 wasShared: blob.wasShared
                     ?? (Set(participants.map(\.authorID)).count > 1),
                 participants: participants,
                 cells: blob.cells,
                 journal: journals
             )
         } catch {
             onDiagnostic?("archive payload rejected for \(record.recordID.recordName): \(error)")
             return nil
         }
     }
 
     private static func legacyPayload(
         from record: CKRecord,
         onDiagnostic: ((String) -> Void)?
     ) -> Payload? {
         guard record.recordType == legacyRecordType,
               let originalString = record["originalGameID"] as? String,
               let originalGameID = UUID(uuidString: originalString),
               let archiveString = record["archiveGameID"] as? String,
               let archiveGameID = UUID(uuidString: archiveString),
               let completedAt = record["completedAt"] as? Date,
               record.recordID.recordName == legacyRecordName(
                 forOriginalGameID: originalGameID
               ),
               archiveGameID == self.archiveGameID(for: originalGameID)
         else { return nil }
 
         // Each asset is size-gated on disk before it is read, then count-gated
         // on decode. A rejected asset degrades to the same empty default as a
         // missing one: `materialize` refuses an empty `puzzleSource`, so a
         // hostile blob can't smuggle an unbounded read in through the archive
         // path, while a legitimate record with one bad asset still fails soft.
         func decoded<T>(
             _ key: String,
             limit: Int,
             _ decode: (Data) throws -> T
         ) -> T? {
             guard let asset = record[key] as? CKAsset, let url = asset.fileURL
             else { return nil }
             do {
                 let data = try RecordSerializer.boundedAssetData(at: url, limit: limit)
                 return try decode(data)
             } catch {
                 onDiagnostic?(
                     "archive \(key) rejected for " +
                     "\(record.recordID.recordName): \(error)"
                 )
                 return nil
             }
         }
 
         let puzzleSource = decoded("puzzleSource", limit: XD.maxSourceBytes) {
             String(data: $0, encoding: .utf8) ?? ""
         } ?? ""
         let cells = decoded("cells", limit: maxCellsAssetBytes, decodeCells) ?? []
         let journal = decoded("journals", limit: maxJournalsAssetBytes, decodeJournals) ?? []
         let participants: [Participant]
         do {
             participants = try validatedParticipants(
                 inferredParticipants(
                     journals: journal,
                     cells: cells,
                     completedBy: record["completedBy"] as? String
                 )
             )
         } catch {
             onDiagnostic?(
                 "archive participants rejected for " +
                 "\(record.recordID.recordName): \(error)"
             )
             return nil
         }
 
         return Payload(
             formatVersion: 0,
             originalGameID: originalGameID,
             archiveGameID: archiveGameID,
             title: record["title"] as? String ?? "",
             puzzleSource: puzzleSource,
             completedAt: completedAt,
             completedBy: record["completedBy"] as? String,
             solveSeconds: (record["solveSeconds"] as? Int64).map(Int.init),
             replayState: .available,
             wasShared: Set(journal.map(\.key.authorID).filter { !$0.isEmpty }).count > 1,
             participants: participants,
             cells: cells,
             journal: journal
         )
     }
 
     /// Rebuilds a standalone completed, owned game from an archive payload, under
     /// the derived `archiveGameID`. Reapplying refreshes the frozen grid and
     /// replay cache, allowing a complete cloud snapshot to replace an earlier
     /// local no-replay fallback without creating a duplicate. The row is never
     /// enqueued for sync, so it pushes no Game/Moves/Player record — the
     /// `Archive` record in the private zone remains its only cloud identity.
     ///
     /// Each contributing device's log is written as `sourceDeviceID`-tagged
     /// `JournalEntity` rows and `replayCacheComplete` is set, so the existing
     /// replay path (`GameStore.cachedRemoteJournals`) serves the full merged
     /// timeline straight from Core Data — no shared zone to fetch from.
     @discardableResult
     static func materialize(
         _ payload: Payload,
         in ctx: NSManagedObjectContext
     ) -> GameEntity? {
         guard !payload.puzzleSource.isEmpty else { return nil }
         let archiveID = payload.archiveGameID
 
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", archiveID as CVarArg)
         request.fetchLimit = 1
         let entity: GameEntity
         if let existing = try? ctx.fetch(request).first {
             entity = existing
             for cell in (existing.cells as? Set<CellEntity>) ?? [] {
                 ctx.delete(cell)
             }
             for journal in (existing.journal as? Set<JournalEntity>) ?? [] {
                 ctx.delete(journal)
             }
             for player in (existing.players as? Set<PlayerEntity>) ?? [] {
                 ctx.delete(player)
             }
         } else {
             entity = GameEntity(context: ctx)
             entity.id = archiveID
         }
 
         // A sentinel record name: distinct from the `game-` form so no sync
         // path mistakes the archive for a pushable Game record, while staying
         // non-nil for code that fetches games by `ckRecordName`.
         entity.ckRecordName = recordName(forOriginalGameID: payload.originalGameID)
         entity.ckZoneName = zoneID.zoneName
         entity.ckZoneOwnerName = nil
         entity.databaseScope = 0
         entity.syncVersion = GameSyncVersion.legacy
         entity.title = payload.title
         entity.puzzleSource = payload.puzzleSource
         // Chronicles are ordinary library rows to everything that reads the
         // derived columns — the browser's "already have this" lookup queries
         // `cachedPublisher`/`cachedPuzzleDate` directly, and `GameSummary`
         // would otherwise reparse this XD on every list evaluation. The frozen
         // `puzzleParserVersion` is deliberately left alone: it still gates the
         // catalog re-derivation in `preparePuzzleForLoad`.
         if let xd = try? XD.parse(payload.puzzleSource) {
             entity.populateCachedSummaryFields(from: Puzzle(xd: xd))
         }
         entity.completedAt = payload.completedAt
         entity.completedBy = payload.completedBy
         // The frozen solve time the live clock reached; `PlayerRoster.solveTime`
         // returns this for a materialised archive, which has no `timeLog` rows.
         if let solveSeconds = payload.solveSeconds {
             entity.finalSolveSeconds = NSNumber(value: solveSeconds)
         }
         entity.createdAt = payload.completedAt
         entity.updatedAt = payload.completedAt
         entity.archivedAt = payload.completedAt
         entity.archiveGameID = archiveID
         entity.archiveParticipants = payload.wasShared
             ? payload.participants.map(\.authorID).sorted().joined(separator: ",")
             : nil
         entity.isSupersededByChronicle = false
         // Every path that turns a Chronicle payload into a local row arrives
         // here, so this is where the index learns which puzzle the archive
         // holds — knowledge the eviction that follows would otherwise discard.
         ChronicleLedgerEntity.upsert(
             originalGameID: payload.originalGameID,
             publisher: entity.cachedPublisher,
             puzzleDate: entity.cachedPuzzleDate,
             participants: entity.archiveParticipants,
             in: ctx
         )
         // When the live row is still present, it owns the account's mutable
         // unread watermark. Mirror that state before the Chronicle becomes the
         // visible Completed tile (and before retirement may delete the live
         // row), without putting mutable state into the frozen archive payload.
         let liveRequest = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         liveRequest.predicate = NSPredicate(
             format: "id == %@",
             payload.originalGameID as CVarArg
         )
         liveRequest.fetchLimit = 1
         if let live = try? ctx.fetch(liveRequest).first {
             mirrorReadState(from: live, to: entity)
         }
         // Pending Chronicles carry no partial journal, but remain visibly
         // retryable until reconciliation either captures every device or the
         // retention deadline turns them into a terminal no-replay fallback.
         switch payload.replayState {
         case .available:
             entity.replayMissingDeviceCount = nil
             entity.replayUnavailable = false
         case .waiting(let missing):
             entity.replayMissingDeviceCount = NSNumber(value: missing)
             entity.replayUnavailable = false
         case .unavailable:
             entity.replayMissingDeviceCount = nil
             entity.replayUnavailable = true
         }
         entity.replayCacheComplete = payload.replayAvailable
 
         for cell in payload.cells {
             // The payload is peer-controlled; its Int16 fields can't overflow
             // (decode throws first) but negatives must not become cache rows.
             guard cell.row >= 0, cell.col >= 0 else { continue }
             let row = CellEntity(context: ctx)
             row.game = entity
             row.row = cell.row
             row.col = cell.col
             row.letter = cell.letter
             row.markCode = cell.markCode
             row.letterAuthorID = cell.letterAuthorID
         }
 
         for participant in payload.participants {
             let player = PlayerEntity(context: ctx)
             player.game = entity
             player.authorID = participant.authorID
             player.name = participant.name ?? ""
             player.ckRecordName = RecordSerializer.recordName(
                 forPlayerInGame: archiveID,
                 authorID: participant.authorID
             )
             player.updatedAt = payload.completedAt
         }
 
         // Each device's log is stored as `sourceDeviceID`-tagged rows so the
         // replay reader treats every author — including the archiving user's own
         // historical moves — as a cached contributor (the archived game has no
         // *live* local journal to overlay).
         for deviceJournal in payload.replayAvailable ? payload.journal : [] {
             for value in deviceJournal.entries {
                 let row = JournalEntity(context: ctx)
                 row.game = entity
                 MovesJournal.assign(value, to: row, gameID: archiveID)
                 row.sourceAuthorID = deviceJournal.key.authorID
                 row.sourceDeviceID = deviceJournal.key.deviceID
             }
         }
 
         return entity
     }
 
     private static func inferredParticipants(
         journals: [DeviceJournal],
         cells: [Cell],
         completedBy: String?
     ) -> [Participant] {
         var authorIDs = Set(journals.map(\.key.authorID))
         authorIDs.formUnion(cells.compactMap(\.letterAuthorID))
         if let completedBy { authorIDs.insert(completedBy) }
         authorIDs.remove("")
         authorIDs.remove(CKCurrentUserDefaultName)
         return authorIDs.sorted().map { Participant(authorID: $0, name: nil) }
     }
 
     private static func validatedParticipants(
         _ participants: [Participant]
     ) throws -> [Participant] {
         guard participants.count <= maxParticipantCount else {
             throw LimitError.tooManyParticipants(count: participants.count)
         }
         var byAuthor: [String: Participant] = [:]
         for participant in participants where !participant.authorID.isEmpty {
             byAuthor[participant.authorID] = participant
         }
         return byAuthor.values.sorted { $0.authorID < $1.authorID }
     }
 }