//

//  ChargeInsightsStore.swift

//  USB Meter

//

//  Created by Codex on 10/04/2026.

//

import CoreData

import Foundation

final class ChargeInsightsStore {

    private enum EntityName {

        static let chargedDevice = "ChargedDevice"

        static let chargeCheckpoint = "ChargeCheckpoint"

        static let chargeSessionSample = "ChargeSessionSample"

    private let context: NSManagedObjectContext

    private let stopDetectionHoldDuration: TimeInterval = 20

    private let aggregatedSampleSaveInterval: TimeInterval = 30

    private let completionConfirmationCooldown: TimeInterval = 15 * 60

    private let completionContradictionTolerancePercent = 2.0

    private let minimumWirelessEfficiencyFactor = 0.35

    private let maximumWirelessEfficiencyFactor = 0.95

    private let lowWirelessEfficiencyThreshold = 0.72

    init(context: NSManagedObjectContext) {

        self.context = context

    }

    func refreshContext() {

        context.performAndWait {

            context.processPendingChanges()

        }

    }

        context.performAndWait {

            context.reset()

        }

    }

    func seedDeviceProfilesCatalog(_ profiles: [DeviceProfileDefinition]) -> Bool {

        var didSave = false

        context.performAndWait {

            let now = Date()

            let request = NSFetchRequest<NSManagedObject>(entityName: EntityName.deviceProfile)

            request.predicate = NSPredicate(format: "isCustom == NO OR isCustom == nil")

            let existing = (try? context.fetch(request)) ?? []

            let existingByID: [String: NSManagedObject] = Dictionary(

                grouping: existing,

                by: { stringValue($0, key: "id") ?? "" }

            ).compactMapValues { $0.first }

            for profile in profiles {

                let target: NSManagedObject

                if let row = existingByID[profile.id] {

                    target = row

                } else {

                    target = NSEntityDescription.insertNewObject(

                        forEntityName: EntityName.deviceProfile,

                        into: context

                    )

                    setValue(profile.id, on: target, key: "id")

                    setValue(now, on: target, key: "createdAt")

                }

                applyCatalogProfile(profile, to: target, updatedAt: now)

            }

            didSave = saveContext()

        }

        return didSave

    }

    /// Backfills `profileID` on all ChargedDevice and Powerbank rows that lack one,

    /// and promotes legacy `ChargedDevice` rows with `deviceClass == "powerbank"` to

    /// the dedicated `Powerbank` entity. Idempotent — re-running has no effect once

    /// every row has a `profileID` and no legacy powerbank-class rows remain.

    @discardableResult

    func migrateDevicesToProfiles() -> Bool {

        var didSave = false

        context.performAndWait {

            let now = Date()

            var didChange = false

            // 1. ChargedDevices (including chargers): assign profileID where missing.

            let deviceRequest = NSFetchRequest<NSManagedObject>(entityName: EntityName.chargedDevice)

            let devices = (try? context.fetch(deviceRequest)) ?? []

            // 1a. Promote legacy class-`.powerbank` rows to the Powerbank entity.

            for device in devices {

                guard stringValue(device, key: "deviceClassRawValue") == ChargedDeviceClass.powerbank.rawValue else {

                    continue

                }

                promoteLegacyPowerbankDevice(device, now: now)

                didChange = true

            }

            // 1b. Backfill profileID for the remaining (non-powerbank-class) devices.

            for device in devices where !device.isDeleted {

                guard stringValue(device, key: "profileID") == nil else { continue }

                guard stringValue(device, key: "deviceClassRawValue") != ChargedDeviceClass.powerbank.rawValue else {

                    // Already handled (and deleted) in 1a.

                    continue

                }

                let assignedProfileID = resolveProfileIDForLegacyDevice(device, now: now)

                setValue(assignedProfileID, on: device, key: "profileID")

                setValue(now, on: device, key: "updatedAt")

                didChange = true

            }

            // 2. Powerbanks: backfill profileID where missing.

            let powerbankRequest = NSFetchRequest<NSManagedObject>(entityName: EntityName.powerbank)

            let powerbanks = (try? context.fetch(powerbankRequest)) ?? []

            for powerbank in powerbanks where !powerbank.isDeleted {

                guard stringValue(powerbank, key: "profileID") == nil else { continue }

                let templateID = stringValue(powerbank, key: "deviceTemplateID")

                let assignedProfileID: String

                if let templateID,

                   let catalog = DeviceProfileCatalog.shared.profile(id: templateID),

                   catalog.category == .powerbank {

                    assignedProfileID = templateID

                } else {

                    assignedProfileID = "generic-powerbank"

                }

                setValue(assignedProfileID, on: powerbank, key: "profileID")

                setValue(now, on: powerbank, key: "updatedAt")

                didChange = true

            }

            if didChange {

                didSave = saveContext()

            } else {

                didSave = true // nothing to do counts as success

            }

        }

        return didSave

    }

    private func promoteLegacyPowerbankDevice(_ device: NSManagedObject, now: Date) {

        let legacyID = stringValue(device, key: "id")

        let powerbank = NSEntityDescription.insertNewObject(

            forEntityName: EntityName.powerbank,

            into: context

        )

        setValue(legacyID ?? UUID().uuidString, on: powerbank, key: "id")

        setValue(stringValue(device, key: "name"), on: powerbank, key: "name")

        setValue(stringValue(device, key: "qrIdentifier"), on: powerbank, key: "qrIdentifier")

        setValue(stringValue(device, key: "notes"), on: powerbank, key: "notes")

        setValue("none", on: powerbank, key: "batteryLevelReportingRawValue")

        setValue(Int16(0), on: powerbank, key: "batteryBarsCount")

        setValue(optionalDoubleValue(device, key: "estimatedBatteryCapacityWh") ?? 0, on: powerbank, key: "estimatedBatteryCapacityWh")

        setValue(optionalDoubleValue(device, key: "minimumCurrentAmps") ?? 0, on: powerbank, key: "minimumCurrentAmps")

        setValue("generic-powerbank", on: powerbank, key: "profileID")

        setValue(stringValue(device, key: "deviceTemplateID"), on: powerbank, key: "deviceTemplateID")

        setValue(dateValue(device, key: "createdAt") ?? now, on: powerbank, key: "createdAt")

        setValue(now, on: powerbank, key: "updatedAt")

        track("ChargeInsightsStore: promoted legacy class-.powerbank ChargedDevice (\(legacyID ?? "?")) to Powerbank entity")

        context.delete(device)

    }

    private func resolveProfileIDForLegacyDevice(_ device: NSManagedObject, now: Date) -> String {

        // 1. Direct catalog match by template ID (apple-iphone, apple-watch, etc.).

        if let templateID = stringValue(device, key: "deviceTemplateID"),

           DeviceProfileCatalog.shared.profile(id: templateID) != nil {

            return templateID

        }

        // 2. For chargers, map chargerType to a catalog charger profile.

        if stringValue(device, key: "deviceClassRawValue") == ChargedDeviceClass.charger.rawValue {

            if let chargerTypeRaw = stringValue(device, key: "chargerTypeRawValue"),

               let chargerType = ChargerType(rawValue: chargerTypeRaw) {

                switch chargerType {

                case .appleMagSafe: return "apple-magsafe-charger"

                case .appleWatch: return "apple-watch-charger"

                case .genericMagSafe: return "generic-magsafe-charger"

                case .genericQi: return "generic-qi-charger"

                }

            }

            return "generic-qi-charger"

        }

        // 3. Synthesize a custom DeviceProfile row matching the device's persisted state.

        return synthesizeCustomProfile(from: device, now: now)

    }

    private func synthesizeCustomProfile(from device: NSManagedObject, now: Date) -> String {

        let id = UUID().uuidString

        let deviceName = stringValue(device, key: "name") ?? "Untitled"

        let profileName = "\(deviceName) profile"

        let classRaw = stringValue(device, key: "deviceClassRawValue") ?? ChargedDeviceClass.other.rawValue

        let deviceClass = ChargedDeviceClass(rawValue: classRaw) ?? .other

        let category = ProfileCategory.fromLegacyDeviceClass(deviceClass)

        let supportsWired = (device.value(forKey: "supportsWiredCharging") as? Bool) ?? false

        let supportsWireless = (device.value(forKey: "supportsWirelessCharging") as? Bool) ?? false

        let chargingStateRaw = stringValue(device, key: "chargingStateAvailabilityRawValue") ?? ChargingStateAvailability.onOrOff.rawValue

        let chargingState = ChargingStateAvailability(rawValue: chargingStateRaw) ?? .onOrOff

        let wirelessProfileRaw = stringValue(device, key: "wirelessChargingProfileRawValue") ?? WirelessChargingProfile.genericQi.rawValue

        let wirelessProfile = WirelessChargingProfile(rawValue: wirelessProfileRaw) ?? .genericQi

        let allowedWirelessProfiles = supportsWireless ? [wirelessProfile] : []

        let profile = NSEntityDescription.insertNewObject(

            forEntityName: EntityName.deviceProfile,

            into: context

        )

        setValue(id, on: profile, key: "id")

        setValue(profileName, on: profile, key: "name")

        setValue(category.rawValue, on: profile, key: "categoryRawValue")

        setValue(category.symbolName, on: profile, key: "iconSymbolName")

        setValue(true, on: profile, key: "isCustom")

        setValue(Int16(1), on: profile, key: "schemaVersion")

        setValue(Int32(1000), on: profile, key: "sortOrder")

        setValue("Custom", on: profile, key: "group")

        setValue(supportsWired, on: profile, key: "capWiredCharging")

        setValue(supportsWireless, on: profile, key: "capWirelessCharging")

        setValue(allowedWirelessProfiles.map { $0.rawValue }.joined(separator: ","), on: profile, key: "capWirelessProfilesRawValue")

        setValue(chargingState.rawValue, on: profile, key: "capChargingStateAvailabilityRawValue")

        setValue(false, on: profile, key: "capHasInternalSubject")

        setValue(supportsWireless ? wirelessProfile.rawValue : nil, on: profile, key: "defaultWirelessChargingProfileRawValue")

        setValue(now, on: profile, key: "createdAt")

        setValue(now, on: profile, key: "updatedAt")

        track("ChargeInsightsStore: synthesized custom DeviceProfile \(id) for legacy device \(stringValue(device, key: "id") ?? "?")")

        return id

    }

    private func applyCatalogProfile(

        _ profile: DeviceProfileDefinition,

        to object: NSManagedObject,

        updatedAt: Date

    ) {

        setValue(profile.name, on: object, key: "name")

        setValue(profile.category.rawValue, on: object, key: "categoryRawValue")

        setValue(profile.icon.name, on: object, key: "iconSymbolName")

        setValue(profile.icon.fallbackSystemName, on: object, key: "iconFallbackSymbolName")

        setValue(false, on: object, key: "isCustom")

        setValue(Int16(1), on: object, key: "schemaVersion")

        setValue(Int32(profile.sortOrder), on: object, key: "sortOrder")

        setValue(profile.group, on: object, key: "group")

        setValue(profile.capWiredCharging, on: object, key: "capWiredCharging")

        setValue(profile.capWirelessCharging, on: object, key: "capWirelessCharging")

        setValue(profile.wirelessProfilesCSV, on: object, key: "capWirelessProfilesRawValue")

        setValue(profile.capChargingStateAvailability.rawValue, on: object, key: "capChargingStateAvailabilityRawValue")

        setValue(profile.capHasInternalSubject, on: object, key: "capHasInternalSubject")

        setValue(profile.defaultWirelessChargingProfile?.rawValue, on: object, key: "defaultWirelessChargingProfileRawValue")

        setValue(profile.defaultWiredMinimumCurrentAmps ?? 0, on: object, key: "defaultWiredMinimumCurrentAmps")

        setValue(profile.defaultWirelessMinimumCurrentAmps ?? 0, on: object, key: "defaultWirelessMinimumCurrentAmps")

        setValue(profile.defaultWiredEstimatedBatteryCapacityWh ?? 0, on: object, key: "defaultWiredEstimatedBatteryCapacityWh")

        setValue(profile.defaultWirelessEstimatedBatteryCapacityWh ?? 0, on: object, key: "defaultWirelessEstimatedBatteryCapacityWh")

        setValue(updatedAt, on: object, key: "updatedAt")

    }

    func flushPendingChanges() -> Bool {

        var didSave = false

        context.performAndWait {

            context.processPendingChanges()

            didSave = saveContext()

        }

        return didSave

    }

    func completeExpiredOpenSessions(referenceDate: Date = Date()) -> Bool {

        var didSave = false

        context.performAndWait {

            let expiredSessions = fetchOpenSessionObjects().compactMap { session -> NSManagedObject? in

                guard automaticCompletionDate(for: session, referenceDate: referenceDate) != nil else {

                    return nil

                }

                return session

            }

            guard expiredSessions.isEmpty == false else {

                return

            }

            var chargedDeviceIDsToRefresh = Set<String>()

            for session in expiredSessions {

                guard let completionDate = automaticCompletionDate(for: session, referenceDate: referenceDate) else {

                    continue

                }

                finishSession(

                    session,

                    observedAt: completionDate,

                    finalBatteryPercent: nil,

                    status: .completed

                )

                if let chargedDeviceID = stringValue(session, key: "chargedDeviceID") {

                    chargedDeviceIDsToRefresh.insert(chargedDeviceID)

                }

            }

            guard saveContext() else {

                return

            }

            for chargedDeviceID in chargedDeviceIDsToRefresh {

                refreshDerivedMetrics(forChargedDeviceID: chargedDeviceID)

            }

            didSave = saveContext()

        }

        return didSave

    }

    // Called after every remote CloudKit sync import to resolve sessions that were started

    // independently on different devices while offline.

    //

    // Scenario: session A started on Device 1 and forgotten; user starts session B on Device 2

    // while offline. After sync both appear open for the same meter.

    //

    // Winner = session with the latest startedAt (represents the user's intentional new session).

    // Loser endedAt is set to winner's startedAt so there is no time overlap.

    @discardableResult

    func healDuplicateOpenSessions() -> Bool {

        var didSave = false

        context.performAndWait {

            let openSessions = fetchOpenSessionObjects()

            var sessionsByMAC: [String: [NSManagedObject]] = [:]

            for session in openSessions {

                guard let mac = stringValue(session, key: "meterMACAddress") else { continue }

                sessionsByMAC[mac, default: []].append(session)

            }

            let duplicatedMACs = sessionsByMAC.filter { $0.value.count > 1 }

            guard !duplicatedMACs.isEmpty else { return }

            var chargedDeviceIDsToRefresh = Set<String>()

            for (_, sessions) in duplicatedMACs {

                // Winner = most recently started (explicit user intent); tie-break by measuredEnergyWh

                let winner = sessions.max { a, b in

                    let aDate = (a.value(forKey: "startedAt") as? Date) ?? .distantPast

                    let bDate = (b.value(forKey: "startedAt") as? Date) ?? .distantPast

                    if aDate != bDate { return aDate < bDate }

                    let aEnergy = (a.value(forKey: "measuredEnergyWh") as? Double) ?? 0

                    let bEnergy = (b.value(forKey: "measuredEnergyWh") as? Double) ?? 0

                    return aEnergy < bEnergy

                }

                let winnerStartedAt = (winner?.value(forKey: "startedAt") as? Date) ?? Date()

                for loser in sessions where loser !== winner {

                    // End the loser exactly when the winner began — no overlap.

                    finishSession(loser, observedAt: winnerStartedAt, finalBatteryPercent: nil, status: .abandoned)

                    loser.setValue(true, forKey: "wasConflictHealed")

                    if let chargedDeviceID = stringValue(loser, key: "chargedDeviceID") {

                        chargedDeviceIDsToRefresh.insert(chargedDeviceID)

                    }

                    track("ChargeInsightsStore: healed duplicate open session \(stringValue(loser, key: "id") ?? "?") for meter \(stringValue(loser, key: "meterMACAddress") ?? "?")")

                }

            }

            guard saveContext() else { return }

            for chargedDeviceID in chargedDeviceIDsToRefresh {

                refreshDerivedMetrics(forChargedDeviceID: chargedDeviceID)

            }

            didSave = saveContext()

        }

        return didSave

    }

        deviceClass: ChargedDeviceClass,

        hasInternalSubject: Bool = false,

        supportsWirelessCharging: Bool,

        wirelessChargingProfile: WirelessChargingProfile,

        let normalizedChargingSupport = deviceClass.normalizedChargingSupport(

            supportsWiredCharging: supportsWiredCharging,

            supportsWirelessCharging: supportsWirelessCharging

        )

        let normalizedTemplateID = normalizedTemplateID(templateID, kind: .device)

        var didSave = false

        context.performAndWait {

            guard let entity = NSEntityDescription.entity(forEntityName: EntityName.chargedDevice, in: context) else {

                return

            }

            let object = NSManagedObject(entity: entity, insertInto: context)

            let now = Date()

            object.setValue(UUID().uuidString, forKey: "id")

            object.setValue(normalizedName, forKey: "name")

            object.setValue(deviceClass.rawValue, forKey: "deviceClassRawValue")

            object.setValue(hasInternalSubject, forKey: "hasInternalSubject")

            object.setValue(normalizedChargingStateAvailability.supportsChargingWhileOff, forKey: "supportsChargingWhileOff")

            object.setValue(normalizedChargingSupport.wired, forKey: "supportsWiredCharging")

            object.setValue(normalizedChargingSupport.wireless, forKey: "supportsWirelessCharging")

            object.setValue(legacyConfiguredCompletionCurrent(for: configuredCompletionCurrents, chargingTransportMode: .wired), forKey: "wiredChargeCompletionCurrentAmps")

            object.setValue(legacyConfiguredCompletionCurrent(for: configuredCompletionCurrents, chargingTransportMode: .wireless), forKey: "wirelessChargeCompletionCurrentAmps")

            object.setValue(generateQRIdentifier(), forKey: "qrIdentifier")

            object.setValue(now, forKey: "createdAt")

            object.setValue(now, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

        name: String,

        templateID: String?,

        batteryLevelReporting: BatteryLevelReporting,

        batteryBarsCount: Int,

        notes: String?

    ) -> Bool {

        let normalizedName = normalizedText(name)

        guard !normalizedName.isEmpty else { return false }

        var didSave = false

        context.performAndWait {

            guard let entity = NSEntityDescription.entity(forEntityName: EntityName.powerbank, in: context) else {

                return

            }

            let object = NSManagedObject(entity: entity, insertInto: context)

            let now = Date()

            object.setValue(UUID().uuidString, forKey: "id")

            object.setValue(normalizedName, forKey: "name")

            object.setValue(generateQRIdentifier(), forKey: "qrIdentifier")

            object.setValue(normalizedTemplateID(templateID, kind: .device), forKey: "deviceTemplateID")

            object.setValue(batteryLevelReporting.rawValue, forKey: "batteryLevelReportingRawValue")

            object.setValue(Int16(batteryLevelReporting == .bars ? max(1, batteryBarsCount) : 0), forKey: "batteryBarsCount")

            object.setValue(normalizedOptionalText(notes), forKey: "notes")

            object.setValue(now, forKey: "createdAt")

            object.setValue(now, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func updatePowerbank(

        id: UUID,

        name: String,

        templateID: String?,

        batteryLevelReporting: BatteryLevelReporting,

        batteryBarsCount: Int,

        notes: String?

    ) -> Bool {

        let normalizedName = normalizedText(name)

        guard !normalizedName.isEmpty else { return false }

        var didSave = false

        context.performAndWait {

            guard let object = fetchPowerbankObject(id: id.uuidString) else {

                return

            }

            let now = Date()

            object.setValue(normalizedName, forKey: "name")

            object.setValue(normalizedTemplateID(templateID, kind: .device), forKey: "deviceTemplateID")

            object.setValue(batteryLevelReporting.rawValue, forKey: "batteryLevelReportingRawValue")

            object.setValue(Int16(batteryLevelReporting == .bars ? max(1, batteryBarsCount) : 0), forKey: "batteryBarsCount")

            object.setValue(normalizedOptionalText(notes), forKey: "notes")

            object.setValue(now, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func deletePowerbank(id powerbankID: UUID) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let powerbank = fetchPowerbankObject(id: powerbankID.uuidString) else {

                return

            }

            // Detach references from any session that mentions this powerbank as subject or source.

            let subjectSessions = fetchSessions(forPowerbankSubjectID: powerbankID.uuidString)

            for session in subjectSessions {

                if let sessionID = stringValue(session, key: "id") {

                    fetchCheckpointObjects(forSessionID: sessionID).forEach(context.delete)

                    fetchSessionSampleObjects(forSessionID: sessionID).forEach(context.delete)

                }

                context.delete(session)

            }

            let sourceSessions = fetchSessions(forPowerbankSourceID: powerbankID.uuidString)

            for session in sourceSessions {

                session.setValue(nil, forKey: "sourcePowerbankID")

                session.setValue(Date(), forKey: "updatedAt")

            }

            context.delete(powerbank)

            didSave = saveContext()

        }

        return didSave

    }

        name: String,

        let normalizedName = normalizedText(name)

        guard !normalizedName.isEmpty else { return false }

        var didSave = false

        context.performAndWait {

            guard let entity = NSEntityDescription.entity(forEntityName: EntityName.chargedDevice, in: context) else {

                return

            }

            let object = NSManagedObject(entity: entity, insertInto: context)

            let now = Date()

            object.setValue(UUID().uuidString, forKey: "id")

            object.setValue(normalizedName, forKey: "name")

            object.setValue(ChargedDeviceClass.charger.rawValue, forKey: "deviceClassRawValue")

            object.setValue(ChargingStateAvailability.onOnly.rawValue, forKey: "chargingStateAvailabilityRawValue")

            object.setValue(false, forKey: "supportsChargingWhileOff")

            object.setValue(false, forKey: "supportsWiredCharging")

            object.setValue(true, forKey: "supportsWirelessCharging")

            if object.entity.attributesByName["chargerTypeRawValue"] != nil {

                object.setValue(chargerType.rawValue, forKey: "chargerTypeRawValue")

            }

            object.setValue(chargerType.wirelessChargingProfile.rawValue, forKey: "wirelessChargingProfileRawValue")

            object.setValue(nil, forKey: "wiredChargeCompletionCurrentAmps")

            object.setValue(nil, forKey: "wirelessChargeCompletionCurrentAmps")

            object.setValue(normalizedOptionalText(notes), forKey: "notes")

            object.setValue(generateQRIdentifier(), forKey: "qrIdentifier")

            object.setValue(now, forKey: "createdAt")

            object.setValue(now, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func updateDevice(

        name: String,

        deviceClass: ChargedDeviceClass,

        hasInternalSubject: Bool = false,

        supportsWirelessCharging: Bool,

        wirelessChargingProfile: WirelessChargingProfile,

    ) -> Bool {

        let normalizedChargingSupport = deviceClass.normalizedChargingSupport(

            supportsWiredCharging: supportsWiredCharging,

            supportsWirelessCharging: supportsWirelessCharging

        )

        let normalizedTemplateID = normalizedTemplateID(templateID, kind: .device)

        var didSave = false

        context.performAndWait {

            guard let object = fetchChargedDeviceObject(id: id.uuidString) else {

                return

            }

                return

            }

            let previousSupportsChargingWhileOff = boolValue(object, key: "supportsChargingWhileOff")

            let previousSupportsWirelessCharging = self.supportsWirelessCharging(for: object)

            let now = Date()

            object.setValue(normalizedName, forKey: "name")

            object.setValue(deviceClass.rawValue, forKey: "deviceClassRawValue")

            object.setValue(hasInternalSubject, forKey: "hasInternalSubject")

            object.setValue(normalizedChargingStateAvailability.supportsChargingWhileOff, forKey: "supportsChargingWhileOff")

            object.setValue(normalizedChargingSupport.wired, forKey: "supportsWiredCharging")

            object.setValue(normalizedChargingSupport.wireless, forKey: "supportsWirelessCharging")

            object.setValue(legacyConfiguredCompletionCurrent(for: configuredCompletionCurrents, chargingTransportMode: .wired), forKey: "wiredChargeCompletionCurrentAmps")

            object.setValue(legacyConfiguredCompletionCurrent(for: configuredCompletionCurrents, chargingTransportMode: .wireless), forKey: "wirelessChargeCompletionCurrentAmps")

            object.setValue(now, forKey: "updatedAt")

            let shouldRefreshActiveSessions = shouldRecalculateSessionCapacity

                || previousSupportsWiredCharging != normalizedChargingSupport.wired

                || previousSupportsWirelessCharging != normalizedChargingSupport.wireless

            if shouldRecalculateSessionCapacity || shouldRefreshActiveSessions {

                let sessions = fetchSessions(forChargedDeviceID: id.uuidString)

                for session in sessions {

                    if shouldRecalculateSessionCapacity {

                        session.setValue(supportsChargingWhileOff, forKey: "supportsChargingWhileOff")

                        updateCapacityEstimate(for: session)

                        session.setValue(now, forKey: "updatedAt")

                    }

                    }

                    let resolvedSessionChargingTransportMode = resolvedPreferredChargingTransportMode(

                        chargingTransportMode(for: session),

                        supportsWirelessCharging: normalizedChargingSupport.wireless

                        chargingStateMode(for: session),

                    let charger = stringValue(session, key: "chargerID").flatMap(fetchChargedDeviceObject(id:))

                    session.setValue(supportsChargingWhileOff, forKey: "supportsChargingWhileOff")

                    session.setValue(resolvedSessionChargingTransportMode.rawValue, forKey: "chargingTransportRawValue")

                        resolvedStopThreshold(

                            for: object,

                            chargingTransportMode: resolvedSessionChargingTransportMode,

                            charger: charger,

                            fallback: optionalDoubleValue(session, key: "stopThresholdAmps")

                        ) ?? 0,

                    )

                    session.setValue(now, forKey: "updatedAt")

                    updateCapacityEstimate(for: session)

                }

            }

            refreshDerivedMetrics(forChargedDeviceID: id.uuidString)

            didSave = saveContext()

        }

        return didSave

    }

    func updateCharger(

        id: UUID,

        name: String,

    ) -> Bool {

        let normalizedName = normalizedText(name)

        guard !normalizedName.isEmpty else { return false }

        var didSave = false

        context.performAndWait {

            guard let object = fetchChargedDeviceObject(id: id.uuidString) else {

                return

            }

            guard isChargerObject(object) else {

                return

            }

            object.setValue(normalizedName, forKey: "name")

            object.setValue(ChargingStateAvailability.onOnly.rawValue, forKey: "chargingStateAvailabilityRawValue")

            object.setValue(false, forKey: "supportsChargingWhileOff")

            object.setValue(false, forKey: "supportsWiredCharging")

            object.setValue(true, forKey: "supportsWirelessCharging")

            if object.entity.attributesByName["chargerTypeRawValue"] != nil {

                object.setValue(chargerType.rawValue, forKey: "chargerTypeRawValue")

            }

            object.setValue(chargerType.wirelessChargingProfile.rawValue, forKey: "wirelessChargingProfileRawValue")

            object.setValue(Date(), forKey: "updatedAt")

        }

        return didSave

    }

        for snapshot: ChargingMonitorSnapshot,

        chargedDeviceID: UUID,

        chargerID: UUID?,

        chargingStateMode: ChargingStateMode,

        autoStopEnabled: Bool,

        startsFromFlatBattery: Bool

           (initialBatteryPercent.isFinite == false || initialBatteryPercent < 0 || initialBatteryPercent > 100) {

        }

        context.performAndWait {

            }

                return

            }

            }

                chargingTransportMode,

                supportsWiredCharging: supportsWiredCharging(for: chargedDevice),

                supportsWirelessCharging: supportsWirelessCharging(for: chargedDevice)

                chargingStateMode,

                availability: chargingStateAvailability(for: chargedDevice)

            )

            let charger = resolvedChargingTransportMode == .wireless

                ? chargerID.flatMap { fetchChargedDeviceObject(id: $0.uuidString) }

                : nil

                return

            }

            // Wireless transport historically required a charger; accept a powerbank in its place.

            guard resolvedChargingTransportMode == .wired || charger != nil || powerbankSource != nil else {

            }

                chargingTransportMode: resolvedChargingTransportMode,

                chargingStateMode: resolvedChargingStateMode,

                charger: charger,

            )

                for: chargedDevice,

                snapshot: snapshot,

                stopThreshold: stopThreshold,

                chargingStateMode: resolvedChargingStateMode,

                autoStopEnabled: autoStopEnabled

            ) else {

                return

            }

                session.setValue(powerbankIDString, forKey: "sourcePowerbankID")

            }

                session.setValue(unresolvedFlatBatteryPercent, forKey: "startBatteryPercent")

                session.setValue(nil, forKey: "endBatteryPercent")

            } else if let initialBatteryPercent {

                guard insertBatteryCheckpoint(

                    percent: initialBatteryPercent,

                    to: session

                ) != nil else {

                    return

                }

        }

        return didSave

    }

    func pauseSession(id sessionID: UUID, observedAt: Date) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            guard statusValue(session, key: "statusRawValue") == .active else {

                return

            }

            session.setValue(ChargeSessionStatus.paused.rawValue, forKey: "statusRawValue")

            session.setValue(observedAt, forKey: "pausedAt")

            session.setValue(nil, forKey: "belowThresholdSince")

            clearCompletionConfirmationState(for: session)

            session.setValue(observedAt, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func resumeSession(id sessionID: UUID, snapshot: ChargingMonitorSnapshot?) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            guard statusValue(session, key: "statusRawValue") == .paused else {

                return

            }

            let resumedAt = snapshot?.observedAt ?? Date()

                    session,

                    status: .completed

                )

                guard saveContext() else {

                    return

                }

                if let deviceID = stringValue(session, key: "chargedDeviceID") {

                    refreshDerivedMetrics(forChargedDeviceID: deviceID)

                    didSave = saveContext()

                } else {

                    didSave = true

                }

                return

            }

            session.setValue(ChargeSessionStatus.active.rawValue, forKey: "statusRawValue")

            session.setValue(nil, forKey: "pausedAt")

            session.setValue(nil, forKey: "belowThresholdSince")

            clearCompletionConfirmationState(for: session)

            session.setValue(resumedAt, forKey: "lastObservedAt")

            if let snapshot {

                session.setValue(snapshot.currentAmps, forKey: "lastObservedCurrentAmps")

                session.setValue(snapshot.powerWatts, forKey: "lastObservedPowerWatts")

                session.setValue(

                    chargingTransportMode(for: session) == .wired ? snapshot.voltageVolts : nil,

                    forKey: "lastObservedVoltageVolts"

                )

            } else {

                session.setValue(0, forKey: "lastObservedCurrentAmps")

                session.setValue(0, forKey: "lastObservedPowerWatts")

                session.setValue(nil, forKey: "lastObservedVoltageVolts")

            }

            session.setValue(resumedAt, forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func stopSession(

        id sessionID: UUID,

            guard finalBatteryPercent.isFinite, finalBatteryPercent >= 0, finalBatteryPercent <= 100 else {

                return false

            }

        var didSave = false

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            guard statusValue(session, key: "statusRawValue")?.isOpen == true else {

                return

            }

                return

            }

            finishSession(

                session,

                observedAt: observedAt,

                finalBatteryPercent: finalBatteryPercent,

                status: .completed

            )

            guard saveContext() else {

                return

            }

            deviceIDToRefresh = stringValue(session, key: "chargedDeviceID")

        }

        if let deviceID = deviceIDToRefresh {

            context.perform { [weak self] in

                guard let self else { return }

                self.refreshDerivedMetrics(forChargedDeviceID: deviceID)

                self.saveContext()

        }

    }

    func addBatteryCheckpoint(

        percent: Double,

        guard percent.isFinite, percent >= 0, percent <= 100 else {

            return false

        }

        var didSave = false

        context.performAndWait {

            }

                percent: percent,

                measuredEnergyWh: measuredEnergyWh,

            )

        return didSave

    }

    @discardableResult

    func addBatteryCheckpoint(

        percent: Double,

        subject: CheckpointSubject = .chargedDevice,

        barsValue: Int = 0

        guard percent.isFinite, percent >= 0, percent <= 100 else {

            return false

        }

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

                percent: percent,

                measuredEnergyWh: measuredEnergyWh,

                barsValue: barsValue,

            )

        return didSave

    }

    func deleteBatteryCheckpoint(

        id checkpointID: UUID,

        from sessionID: UUID

    ) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString),

                  let checkpoint = fetchCheckpointObject(

                    id: checkpointID.uuidString,

                    sessionID: sessionID.uuidString

                  ) else {

                return

            }

            let chargedDeviceID = stringValue(session, key: "chargedDeviceID")

            context.delete(checkpoint)

            refreshCheckpointDerivedValues(for: session)

            if let chargedDeviceID {

                refreshDerivedMetrics(forChargedDeviceID: chargedDeviceID)

            }

            didSave = saveContext()

        return didSave

    }

    func setTargetBatteryPercent(_ percent: Double?, for sessionID: UUID) -> Bool {

        if let percent, (!percent.isFinite || percent <= 0 || percent > 100) {

            return false

        }

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            session.setValue(percent, forKey: "targetBatteryPercent")

            session.setValue(nil, forKey: "targetBatteryAlertTriggeredAt")

            session.setValue(Date(), forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    @discardableResult

    func confirmCompletion(for sessionID: UUID) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            guard statusValue(session, key: "statusRawValue") == .active else {

                return

            }

                session,

                observedAt: dateValue(session, key: "lastObservedAt") ?? Date(),

                finalBatteryPercent: nil,

                status: .completed

            )

            if saveContext() {

                if let deviceID = stringValue(session, key: "chargedDeviceID") {

                    refreshDerivedMetrics(forChargedDeviceID: deviceID)

                    didSave = saveContext()

                } else {

                    didSave = true

                }

            }

        }

        return didSave

    }

    @discardableResult

    func continueMonitoringDespiteCompletionContradiction(for sessionID: UUID) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            guard statusValue(session, key: "statusRawValue") == .active else {

                return

            }

            clearCompletionConfirmationState(for: session)

            session.setValue(Date(), forKey: "updatedAt")

            didSave = saveContext()

        }

        return didSave

    }

    func setSessionTrim(sessionID: UUID, start: Date?, end: Date?) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString) else {

                return

            }

            let sessionStart = dateValue(session, key: "startedAt") ?? Date.distantPast

            let sessionEnd   = dateValue(session, key: "endedAt")

                ?? dateValue(session, key: "lastObservedAt")

                ?? Date.distantFuture

            let effectiveStart = min(max(start ?? sessionStart, sessionStart), sessionEnd)

            let effectiveEnd   = max(min(end ?? sessionEnd, sessionEnd), effectiveStart)

            let persistedStart = effectiveStart == sessionStart ? nil : effectiveStart

            let persistedEnd   = effectiveEnd == sessionEnd ? nil : effectiveEnd

            let allSamples = fetchSessionSampleObjects(forSessionID: sessionID.uuidString)

                .compactMap { obj -> (timestamp: Date, energy: Double, charge: Double)? in

                    guard let ts = dateValue(obj, key: "timestamp") else { return nil }

                    return (

                        timestamp: ts,

                        energy: doubleValue(obj, key: "measuredEnergyWh"),

                        charge: doubleValue(obj, key: "measuredChargeAh")

                    )

                }

                .sorted { $0.timestamp < $1.timestamp }

            // Each sample stores cumulative energy since session start.

            // Trimmed energy = value at trimEnd  -  value just before trimStart.

            let baselineSample = allSamples.last { $0.timestamp <= effectiveStart }

            let endSample      = allSamples.last { $0.timestamp <= effectiveEnd }

            let baselineEnergy = baselineSample?.energy ?? 0

            let baselineCharge = baselineSample?.charge ?? 0

            if let endSample {

                let trimmedEnergy  = max(endSample.energy - baselineEnergy, 0)

                let trimmedCharge  = max(endSample.charge - baselineCharge, 0)

                session.setValue(trimmedEnergy, forKey: "measuredEnergyWh")

                session.setValue(trimmedCharge, forKey: "measuredChargeAh")

            } else {

                session.setValue(0, forKey: "measuredEnergyWh")

                session.setValue(0, forKey: "measuredChargeAh")

            }

            session.setValue(persistedStart, forKey: "trimStart")

            session.setValue(persistedEnd,   forKey: "trimEnd")

            session.setValue(Date(), forKey: "updatedAt")

            let checkpoints = fetchCheckpointObjects(forSessionID: sessionID.uuidString)

            for checkpoint in checkpoints {

                guard let timestamp = dateValue(checkpoint, key: "timestamp") else { continue }

                if timestamp < effectiveStart || timestamp > effectiveEnd {

                    context.delete(checkpoint)

                    continue

                }

                let checkpointSample = allSamples.last { $0.timestamp <= timestamp }

                let rebasedEnergy = max((checkpointSample?.energy ?? baselineEnergy) - baselineEnergy, 0)

                let rebasedCharge = max((checkpointSample?.charge ?? baselineCharge) - baselineCharge, 0)

                checkpoint.setValue(rebasedEnergy, forKey: "measuredEnergyWh")

                checkpoint.setValue(rebasedCharge, forKey: "measuredChargeAh")

            }

            let remainingCheckpoints = fetchCheckpointObjects(forSessionID: sessionID.uuidString)

                .sorted {

                    (dateValue($0, key: "timestamp") ?? .distantPast)

                        < (dateValue($1, key: "timestamp") ?? .distantPast)

                }

            let restoredInitialCheckpoint = remainingCheckpoints.first { checkpoint in

                let label = stringValue(checkpoint, key: "label")

                let timestamp = dateValue(checkpoint, key: "timestamp") ?? .distantFuture

                return ChargeCheckpointFlag.fromStoredLabel(label) == .initial || timestamp <= effectiveStart

            }

            if persistedStart == nil {

                if let restoredInitialCheckpoint,

                   let percent = optionalDoubleValue(restoredInitialCheckpoint, key: "batteryPercent"),

                   percent >= 0 {

                    session.setValue(percent, forKey: "startBatteryPercent")

                }

            } else {

                session.setValue(nil, forKey: "startBatteryPercent")

            }

            refreshCheckpointDerivedValues(for: session)

            if let chargedDeviceID = stringValue(session, key: "chargedDeviceID") {

                refreshDerivedMetrics(forChargedDeviceID: chargedDeviceID)

            }

            didSave = saveContext()

        }

        return didSave

    }

    func commitSessionTrim(sessionID: UUID) -> Bool {

        var didSave = false

        context.performAndWait {

            guard let session = fetchSessionObject(id: sessionID.uuidString),

                  statusValue(session, key: "statusRawValue")?.isOpen == false else {

                return

            }

            guard dateValue(session, key: "trimStart") != nil

                    || dateValue(session, key: "trimEnd") != nil else {

                return

            }

            let sessionStart = dateValue(session, key: "startedAt") ?? Date.distantPast

            let sessionEnd = dateValue(session, key: "endedAt")

                ?? dateValue(session, key: "lastObservedAt")

                ?? sessionStart

            let effectiveStart = min(max(dateValue(session, key: "trimStart") ?? sessionStart, sessionStart), sessionEnd)

            let effectiveEnd = max(

                min(dateValue(session, key: "trimEnd") ?? sessionEnd, sessionEnd),

                effectiveStart

            )

            let sampleObjects = fetchSessionSampleObjects(forSessionID: sessionID.uuidString)

            let allSamples = sampleObjects

                .compactMap { obj -> (timestamp: Date, energy: Double, charge: Double)? in

                    guard let timestamp = dateValue(obj, key: "timestamp") else { return nil }

                    return (

                        timestamp: timestamp,

                        energy: doubleValue(obj, key: "measuredEnergyWh"),

                        charge: doubleValue(obj, key: "measuredChargeAh")

                    )

                }

                .sorted { $0.timestamp < $1.timestamp }

            let baselineSample = allSamples.last { $0.timestamp <= effectiveStart }

            let endSample = allSamples.last { $0.timestamp <= effectiveEnd }

            let baselineEnergy = baselineSample?.energy ?? 0

            let baselineCharge = baselineSample?.charge ?? 0

            let committedEnergy = endSample.map { max($0.energy - baselineEnergy, 0) }

                ?? doubleValue(session, key: "measuredEnergyWh")

            let committedCharge = endSample.map { max($0.charge - baselineCharge, 0) }

                ?? doubleValue(session, key: "measuredChargeAh")