crossmate

NotificationState.swift (17274B)

---

 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.presenceUntil`. 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)
     }
 
     /// 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 `presenceUntil`/`readThrough` conflation PLAN.md
 /// describes.
 enum BadgeState {
     private static let ledgerKey = "badge.ledger.v2"
     private static let pendingInvitesKey = "badge.pendingInvites.v1"
 
     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`/`presenceUntil`
     /// 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:)))
     }
 
     /// Clears the entire ledger. 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: pendingInvitesKey)
     }
 
     private static func loadLedger() -> [String: Entry] {
         guard let defaults else { return [:] }
         guard let data = defaults.data(forKey: ledgerKey),
               let ledger = try? JSONDecoder().decode([String: Entry].self, from: data)
         else { return [:] }
         return ledger
     }
 
     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)
     }
 }