crossmate

NotificationState.swift (22434B)

---

 import Foundation
 
 /// Notification suppression state persisted via App Group UserDefaults.
 ///
 /// State tracked:
 /// - `activePuzzleID` (+ local leave-grace) — this device is viewing a puzzle,
 ///   so notifications and the unseen-moves badge for it are skipped.
 ///
 /// `isSuppressed(gameID:)` is the unified gate; presently it is just the
 /// local-active check, kept under that name so callers don't need to know
 /// whether sibling-device presence is part of the rule.
 enum NotificationState {
     static let appGroup = "group.net.inqk.crossmate"
 
     private static let activeKey = "notif.activePuzzleID"
     private static let localActiveUntilKey = "notif.localActiveUntil"
 
     /// Grace window after the user leaves a puzzle during which the game is
     /// still treated as active. Inbound moves or pings fetched while the
     /// puzzle was on screen can finish processing a beat after `.onDisappear`
     /// clears the active ID; without this tail that race re-flags moves the
     /// user already watched arrive as unseen (and can re-notify for them).
     static let leaveGraceWindow: TimeInterval = 15
 
     /// `UserDefaults` itself isn't `Sendable` under strict concurrency, but its
     /// methods are thread-safe in practice. Vouch for that here so the testing
     /// override can flow through a `TaskLocal`.
     struct TestingDefaults: @unchecked Sendable {
         let userDefaults: UserDefaults
     }
 
     /// Test-only override for the storage backend. Production never sets
     /// this; tests inject a per-test UUID-named `UserDefaults` (typically via
     /// `.isolatedNotificationState`) so suites no longer mutate the shared
     /// App-Group store. Implemented as a `TaskLocal` so the override flows
     /// through actor hops and `Task` continuations inside test bodies — a
     /// plain settable static would race when suites run in parallel.
     @TaskLocal static var testingDefaults: TestingDefaults?
 
     nonisolated(unsafe) private static let sharedDefaults: UserDefaults? =
         UserDefaults(suiteName: appGroup)
 
     private static var defaults: UserDefaults? {
         testingDefaults?.userDefaults ?? sharedDefaults
     }
 
     static func activePuzzleID() -> UUID? {
         guard let s = defaults?.string(forKey: activeKey) else { return nil }
         return UUID(uuidString: s)
     }
 
     static func setActivePuzzleID(_ id: UUID?) {
         guard let defaults else { return }
         if let id {
             defaults.set(id.uuidString, forKey: activeKey)
         } else {
             defaults.removeObject(forKey: activeKey)
         }
     }
 
     static func clearActivePuzzleID(if id: UUID, now: Date = Date()) {
         guard activePuzzleID() == id else { return }
         setActivePuzzleID(nil)
         stampLocalActive(id, until: now.addingTimeInterval(leaveGraceWindow), now: now)
     }
 
     /// True if the user is currently viewing the puzzle for `gameID`, or left
     /// it within `leaveGraceWindow`. Active-puzzle suppression applies to all
     /// ping kinds — no notifications fire while you're already in the puzzle
     /// they describe — and the grace tail keeps the just-left puzzle covered
     /// while in-flight inbound work settles.
     static func isActive(gameID: UUID, now: Date = Date()) -> Bool {
         if activePuzzleID() == gameID { return true }
         if let until = localActiveMap()[gameID.uuidString] {
             return now.timeIntervalSince1970 < until
         }
         return false
     }
 
     /// Stamps `id` as locally active until `until`, evicting entries that
     /// have already expired so the map stays small.
     private static func stampLocalActive(_ id: UUID, until: Date, now: Date) {
         guard let defaults else { return }
         var map = localActiveMap()
         map[id.uuidString] = until.timeIntervalSince1970
         let nowTS = now.timeIntervalSince1970
         map = map.filter { $0.value > nowTS }
         defaults.set(map, forKey: localActiveUntilKey)
     }
 
     private static func localActiveMap() -> [String: TimeInterval] {
         defaults?.dictionary(forKey: localActiveUntilKey) as? [String: TimeInterval] ?? [:]
     }
 
     /// The unified suppression gate: the user is viewing `gameID` here
     /// (including the local leave-grace tail). Sibling-device presence used
     /// to factor in here via the `.opened`/`.closed` lease; that subsystem is
     /// gone — cross-device read state now rides `Player.readAt`. The
     /// gate is kept under this name so callers don't need to change.
     static func isSuppressed(gameID: UUID, now: Date = Date()) -> Bool {
         isActive(gameID: gameID, now: now)
     }
 
     private static let legacyLeasePurgeKey = "migration.legacyLeasePurge.v1"
     private static let legacyInvitePurgeKey = "migration.legacyInvitePurge.v1"
     private static let staleHailPurgeKey = "migration.staleHailPurge.v1"
     private static let debugPreviewFriendPurgeKey = "migration.debugPreviewFriendPurge.v1"
     private static let legacyPlayPingPurgeKey = "migration.legacyPlayPingPurge.v1"
 
     /// True if the one-shot cleanup of legacy `.opened`/`.closed` lease pings
     /// has not yet run successfully on this device. The flag is per-device
     /// (App Group UserDefaults), so each device drains its own slice of the
     /// account zone exactly once.
     static func legacyLeasePurgeNeeded() -> Bool {
         defaults?.bool(forKey: legacyLeasePurgeKey) == false
     }
 
     /// Records that the legacy-lease purge completed successfully so the next
     /// launch skips it.
     static func markLegacyLeasePurged() {
         defaults?.set(true, forKey: legacyLeasePurgeKey)
     }
 
     /// True if the one-shot cleanup of legacy broadcast `.invite` pings has
     /// not yet run successfully on this device.
     static func legacyInvitePurgeNeeded() -> Bool {
         defaults?.bool(forKey: legacyInvitePurgeKey) == false
     }
 
     /// Records that the legacy invite purge completed successfully so the next
     /// launch skips it.
     static func markLegacyInvitePurged() {
         defaults?.set(true, forKey: legacyInvitePurgeKey)
     }
 
     /// True if the one-shot cleanup of pre-migration `.hail` pings from game
     /// zones has not yet run successfully on this device.
     static func staleHailPurgeNeeded() -> Bool {
         defaults?.bool(forKey: staleHailPurgeKey) == false
     }
 
     /// Records that the stale-hail purge completed successfully so the next
     /// launch skips it.
     static func markStaleHailPurged() {
         defaults?.set(true, forKey: staleHailPurgeKey)
     }
 
     /// True if the one-shot cleanup of local debug-preview friend rows has
     /// not yet run successfully on this device.
     static func debugPreviewFriendPurgeNeeded() -> Bool {
         defaults?.bool(forKey: debugPreviewFriendPurgeKey) == false
     }
 
     /// Records that the debug-preview friend cleanup completed successfully.
     static func markDebugPreviewFriendPurged() {
         defaults?.set(true, forKey: debugPreviewFriendPurgeKey)
     }
 
     /// True if the one-shot cleanup of retired play-event Ping kinds
     /// (`.check`, `.reveal`, `.resign`, `.win`, and the old session-start
     /// `.join`) has not yet run successfully on this device. Those kinds
     /// were retired when the push worker took over user-facing event
     /// notifications; any records still in game zones are dead weight that
     /// can resurrect obsolete announcements on a zone replay.
     static func legacyPlayPingPurgeNeeded() -> Bool {
         defaults?.bool(forKey: legacyPlayPingPurgeKey) == false
     }
 
     /// Records that the legacy play-ping purge completed successfully.
     static func markLegacyPlayPingPurged() {
         defaults?.set(true, forKey: legacyPlayPingPurgeKey)
     }
 
     /// Exposes the (testing-aware) App Group defaults to siblings in this
     /// module — currently `BadgeState`, which shares storage but lives in
     /// its own namespace.
     static var sharedDefaultsForSiblings: UserDefaults? { defaults }
 }
 
 /// App-icon badge ledger, persisted in the same App Group as
 /// `NotificationState` so the Notification Service Extension can mutate it
 /// from a separate process when an APNs alert arrives. This ledger is only the
 /// provisional push-side input; Core Data remains the app's synced ground truth
 /// for Moves-derived unread state.
 ///
 /// Each game tracks the newest push-side unread event, the newest local seen
 /// horizon, and a suppression horizon. A game is unread from this ledger only
 /// when `unreadAt` is newer than both, so opening a puzzle can defeat stale NSE
 /// entries rather than fighting the old "union forever" set semantics.
 ///
 /// `seenAt` is a true read watermark — it never moves into the future, and it
 /// only advances. `suppressedUntil` is the ledger's mirror of the account's
 /// presence lease: while some device of this account is in the puzzle, pushes
 /// arriving before the horizon are presumed watched live and don't badge.
 /// Unlike `seenAt` it is *collapsible* — leaving the puzzle (or a sibling's
 /// session close syncing in) pulls it back to the leave instant, so a push
 /// that actually arrived after the user stopped looking resurrects as unread.
 /// Folding both meanings into a forward-dated `seenAt`, as before, made the
 /// suppression permanent: `markSeen` is monotonic, so the badge swallowed
 /// every push for the rest of the lease window even after the user left —
 /// the push-ledger twin of the `readAt`/`readThrough` conflation PLAN.md
 /// describes.
 enum BadgeState {
     private static let ledgerKey = "badge.ledger.v2"
     private static let legacyLedgerKey = "badge.ledger.v1"
     private static let legacyUnreadKey = "badge.unreadGameIDs"
     private static let pendingInvitesKey = "badge.pendingInvites.v1"
     private static let legacyReadThroughHealV1Key = "badge.legacyReadThroughHeal.v1"
     private static let legacyReadThroughHealKey = "badge.legacyReadThroughHeal.v2"
 
     private struct Entry: Codable, Equatable {
         var unreadAt: Date? = nil
         var seenAt: Date? = nil
         /// Optional with a default so ledgers written before the field existed
         /// decode as nil (no suppression) rather than failing wholesale.
         var suppressedUntil: Date? = nil
     }
 
     private static var defaults: UserDefaults? {
         NotificationState.sharedDefaultsForSiblings
     }
 
     /// True while a sibling device of this account is present in `gameID`: the
     /// suppression horizon (extended by `accountSeen`/the local lease via
     /// `extendSuppression`/`adoptReadHorizon`) is still in the future. The
     /// Notification Service Extension reads this to deliver passively while the
     /// user is playing on another device, rather than bannering a session
     /// they're watching live.
     static func isSuppressed(gameID: UUID, now: Date = Date()) -> Bool {
         guard let until = loadLedger()[gameID.uuidString]?.suppressedUntil else { return false }
         return until > now
     }
 
     static func unreadGameIDs() -> Set<UUID> {
         let ledger = loadLedger()
         return Set(ledger.compactMap { key, entry in
             guard let gameID = UUID(uuidString: key),
                   let unreadAt = entry.unreadAt,
                   unreadAt > (entry.seenAt ?? .distantPast),
                   unreadAt > (entry.suppressedUntil ?? .distantPast)
             else { return nil }
             return gameID
         })
     }
 
     /// Records a push-side unread event. Returns the resulting ledger-only
     /// unread count so the NSE can stamp the outgoing APNs badge.
     @discardableResult
     static func markUnread(gameID: UUID, at time: Date = Date()) -> Int {
         var ledger = loadLedger()
         var entry = ledger[gameID.uuidString] ?? Entry()
         if (entry.unreadAt ?? .distantPast) < time {
             entry.unreadAt = time
         }
         ledger[gameID.uuidString] = entry
         saveLedger(ledger)
         return unreadGameIDs().count
     }
 
     /// Records that the user has seen this game on this device. Returns the
     /// resulting ledger-only unread count. `time` must not be forward-dated:
     /// `seenAt` is monotonic, so a future value would suppress unread events
     /// irreversibly — that's `suppressedUntil`'s (collapsible) job. Callers
     /// holding a horizon that may reach into the future go through
     /// `adoptReadHorizon`, which splits it.
     @discardableResult
     static func markSeen(gameID: UUID, at time: Date = Date()) -> Int {
         var ledger = loadLedger()
         var entry = ledger[gameID.uuidString] ?? Entry()
         if (entry.seenAt ?? .distantPast) < time {
             entry.seenAt = time
         }
         ledger[gameID.uuidString] = entry
         saveLedger(ledger)
         return unreadGameIDs().count
     }
 
     /// Records an account read horizon that may be forward-dated (a presence
     /// lease, locally minted or received from a sibling device): the watermark
     /// advances only to `min(horizon, now)`, while the suppression horizon
     /// takes the full value. The two halves mirror the `readThrough`/`readAt`
     /// split on the Player record.
     static func adoptReadHorizon(gameID: UUID, horizon: Date, now: Date = Date()) {
         markSeen(gameID: gameID, at: min(horizon, now))
         extendSuppression(gameID: gameID, until: horizon)
     }
 
     /// Raises the suppression horizon for `gameID`, monotonically — a renewal
     /// extends it, while a stale (older) horizon arriving late can't shorten
     /// an active one. The deliberate pull-back on session close goes through
     /// `collapseSuppression`. Mirrors how the presence lease itself behaves
     /// (`GameStore.setReadCursor`'s refresh floor vs. its direct collapse).
     static func extendSuppression(gameID: UUID, until horizon: Date) {
         var ledger = loadLedger()
         var entry = ledger[gameID.uuidString] ?? Entry()
         guard (entry.suppressedUntil ?? .distantPast) < horizon else { return }
         entry.suppressedUntil = horizon
         ledger[gameID.uuidString] = entry
         saveLedger(ledger)
     }
 
     /// Collapses the suppression horizon to `horizon` — the session-close
     /// signal (this device leaving the puzzle, or a sibling's close syncing
     /// in). Direct adoption, not monotonic: the whole point is to pull a
     /// forward-dated lease back to the instant the account stopped looking,
     /// so a push that arrived after that instant counts as unread again. A
     /// game with no ledger entry has nothing to collapse.
     static func collapseSuppression(gameID: UUID, to horizon: Date) {
         var ledger = loadLedger()
         guard var entry = ledger[gameID.uuidString],
               entry.suppressedUntil != horizon
         else { return }
         entry.suppressedUntil = horizon
         ledger[gameID.uuidString] = entry
         saveLedger(ledger)
     }
 
     /// Bulk-applies push-side unread horizons in a single load/save — one
     /// `markUnread`-equivalent per entry. The app uses this to seed Core Data
     /// ground truth into the ledger so the NSE inherits it while the app is
     /// suspended; horizon semantics make a re-seed of an already-seen game a
     /// no-op (its newer `seenAt` still wins).
     static func seedUnread(_ times: [UUID: Date]) {
         guard !times.isEmpty else { return }
         var ledger = loadLedger()
         for (gameID, time) in times {
             var entry = ledger[gameID.uuidString] ?? Entry()
             if (entry.unreadAt ?? .distantPast) < time {
                 entry.unreadAt = time
             }
             ledger[gameID.uuidString] = entry
         }
         saveLedger(ledger)
     }
 
     /// Removes a game from the ledger outright. Called when a game is deleted
     /// or hard-removed: a seen horizon can't help once the game is gone (there
     /// is nothing left to open), so a stale `unreadAt > seenAt` entry would
     /// otherwise count toward the badge forever.
     static func forget(gameID: UUID) {
         var ledger = loadLedger()
         guard ledger.removeValue(forKey: gameID.uuidString) != nil else { return }
         saveLedger(ledger)
     }
 
     /// Authoritative set of games this account has been invited to but not yet
     /// joined. Unlike the horizon ledger, a pending invite is binary — it is
     /// pending or it isn't — so the app overwrites this set wholesale from Core
     /// Data ground truth on every `refreshAppBadge`. The Notification Service
     /// Extension, which can't reach Core Data, unions this into its badge count
     /// so a moves push landing while the app is suspended doesn't drop a still
     /// pending invite from the total.
     static func setPendingInvites(_ ids: Set<UUID>) {
         guard let defaults else { return }
         if ids.isEmpty {
             defaults.removeObject(forKey: pendingInvitesKey)
             return
         }
         defaults.set(ids.map(\.uuidString), forKey: pendingInvitesKey)
     }
 
     static func pendingInviteGameIDs() -> Set<UUID> {
         guard let defaults,
               let raw = defaults.array(forKey: pendingInvitesKey) as? [String]
         else { return [] }
         return Set(raw.compactMap(UUID.init(uuidString:)))
     }
 
     /// Returns true once per install after the read-watermark split, so the app
     /// can backfill `Game.readThroughAt` for pre-split rows that only carried
     /// the older `readAt`/presence cursor, and repair stale first-pass
     /// watermarks. The NSE never calls this.
     static func claimLegacyReadThroughHealNeeded() -> Bool {
         guard let defaults else { return false }
         guard defaults.bool(forKey: legacyReadThroughHealKey) == false else { return false }
         defaults.set(true, forKey: legacyReadThroughHealKey)
         return true
     }
 
     /// Clears the entire ledger (and any legacy stores). Used by the
     /// diagnostics "reset all data" path, which deletes every game at once.
     static func reset() {
         guard let defaults else { return }
         defaults.removeObject(forKey: ledgerKey)
         defaults.removeObject(forKey: legacyLedgerKey)
         defaults.removeObject(forKey: legacyUnreadKey)
         defaults.removeObject(forKey: pendingInvitesKey)
         defaults.removeObject(forKey: legacyReadThroughHealV1Key)
         defaults.removeObject(forKey: legacyReadThroughHealKey)
     }
 
     private static func loadLedger() -> [String: Entry] {
         guard let defaults else { return [:] }
         if let data = defaults.data(forKey: ledgerKey),
            let ledger = try? JSONDecoder().decode([String: Entry].self, from: data) {
             return ledger
         }
         // Neither the pre-horizon set (`badge.unreadGameIDs`) nor the v1 ledger
         // carried trustworthy unread timestamps we can rebuild from: the v1
         // migration fabricated `unreadAt = now` for every legacy entry, which
         // makes an already-seen game look freshly unread and, worse,
         // un-clearable by read state — a future-dated `unreadAt` beats any past
         // `seenAt`, and a deleted game has nothing left to open. Core Data is
         // the durable ground truth for unread-other-moves, so discard both
         // legacy stores and let `refreshAppBadge` re-seed from Core Data on the
         // next run rather than carry phantom badges forward.
         if defaults.object(forKey: legacyLedgerKey) != nil {
             defaults.removeObject(forKey: legacyLedgerKey)
         }
         if defaults.object(forKey: legacyUnreadKey) != nil {
             defaults.removeObject(forKey: legacyUnreadKey)
         }
         return [:]
     }
 
     private static func saveLedger(_ ledger: [String: Entry]) {
         guard let defaults else { return }
         if ledger.isEmpty {
             defaults.removeObject(forKey: ledgerKey)
             return
         }
         if let data = try? JSONEncoder().encode(ledger) {
             defaults.set(data, forKey: ledgerKey)
         }
     }
 }
 
 /// Small App Group ring buffer for visible notification receipts. The
 /// Notification Service Extension runs in a separate process, so it cannot
 /// write to the app's in-memory diagnostics log directly; it records here and
 /// the app drains the entries into `EventLog` when it next runs.
 enum VisibleNotificationReceiptLog {
     struct Entry: Codable, Sendable, Equatable {
         let timestamp: Date
         let source: String
         let body: String
     }
 
     private static let entriesKey = "visibleNotificationReceipts.entries"
     private static let maxEntries = 50
 
     private static var defaults: UserDefaults? {
         NotificationState.sharedDefaultsForSiblings
     }
 
     static func record(body: String, source: String, at timestamp: Date = Date()) {
         guard let defaults else { return }
         var entries = loadEntries(from: defaults)
         entries.append(Entry(
             timestamp: timestamp,
             source: source,
             body: body
         ))
         if entries.count > maxEntries {
             entries.removeFirst(entries.count - maxEntries)
         }
         save(entries, to: defaults)
     }
 
     static func drain() -> [Entry] {
         guard let defaults else { return [] }
         let entries = loadEntries(from: defaults)
         defaults.removeObject(forKey: entriesKey)
         return entries
     }
 
     static func message(for entry: Entry) -> String {
         let escapedBody = entry.body
             .replacingOccurrences(of: "\n", with: " ")
             .trimmingCharacters(in: .whitespacesAndNewlines)
         return "visible notification receipt imported: utc=\(utcString(entry.timestamp)) source=\(entry.source) body=\"\(escapedBody)\""
     }
 
     private static func loadEntries(from defaults: UserDefaults) -> [Entry] {
         guard let data = defaults.data(forKey: entriesKey),
               let entries = try? JSONDecoder().decode([Entry].self, from: data)
         else { return [] }
         return entries
     }
 
     private static func save(_ entries: [Entry], to defaults: UserDefaults) {
         guard let data = try? JSONEncoder().encode(entries) else { return }
         defaults.set(data, forKey: entriesKey)
     }
 
     private static func utcString(_ date: Date) -> String {
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
         formatter.timeZone = TimeZone(secondsFromGMT: 0)
         return formatter.string(from: date)
     }
 }