@bricks-soft/capacitor-location-tracking 8.1.0 → 8.2.0

package/ios/Sources/LocationTrackingPlugin/Engine/MotionStateMachine.swift

@@ -0,0 +1,122 @@
+import Foundation
+
+struct ActivitySample: Equatable {
+    var type: String
+    var confidence: Int
+    var json: TrackingJSON { ["type": type, "confidence": confidence] }
+    static func map(automotive: Bool, cycling: Bool, running: Bool, walking: Bool, stationary: Bool, confidence: Int) -> ActivitySample {
+        ActivitySample(type: automotive ? "in_vehicle" : cycling ? "on_bicycle" : running ? "running" : walking ? "walking" : stationary ? "still" : "unknown", confidence: confidence)
+    }
+}
+
+struct MotionSettings: Equatable {
+    var stationaryRadius = 25.0
+    var minimumConfidence = 75
+    var motionTriggerDelay = 0.0
+    var stopTimeout = 300000.0
+    var disableStopDetection = false
+    var trackingAccuracyThreshold = 100.0
+    static func from(_ config: TrackingJSON) -> MotionSettings {
+        let geo = config.object("geolocation"), activity = config.object("activity")
+        return MotionSettings(stationaryRadius: max(0, geo.number("stationaryRadius", 25)), minimumConfidence: Int(activity.number("minimumActivityRecognitionConfidence", 75)), motionTriggerDelay: max(0, activity.number("motionTriggerDelay")), stopTimeout: max(1, geo.number("stopTimeout", 5)) * 60000, disableStopDetection: activity.flag("disableStopDetection"), trackingAccuracyThreshold: geo.object("filter").number("trackingAccuracyThreshold", 100))
+    }
+}
+
+enum MotionAction: Equatable {
+    case enterMoving(TrackedLocation?)
+    case enterStationary(TrackedLocation?, automatic: Bool)
+    case startStopTimer(Double)
+    case cancelStopTimer
+    case startMotionTrigger(Double)
+    case cancelMotionTrigger
+}
+
+final class MotionStateMachine {
+    private(set) var settings: MotionSettings
+    private(set) var isMoving = false
+    private(set) var anchor: TrackedLocation?
+    private(set) var motionAnchor: TrackedLocation?
+    private(set) var isStopTimerArmed = false
+    private(set) var isMotionTriggerArmed = false
+    static let movingActivities: Set<String> = ["walking", "running", "on_foot", "on_bicycle", "in_vehicle"]
+    init(_ settings: MotionSettings = MotionSettings()) { self.settings = settings }
+    func reset(isMoving: Bool = false, anchor: TrackedLocation? = nil) {
+        self.isMoving = isMoving
+        self.anchor = isMoving ? nil : anchor
+        motionAnchor = isMoving ? anchor : nil
+        isStopTimerArmed = false; isMotionTriggerArmed = false
+    }
+    func offerAnchor(_ location: TrackedLocation?) { if !isMoving && anchor == nil { anchor = location } }
+    func setAnchor(_ location: TrackedLocation) { if !isMoving { anchor = location } }
+    func updateSettings(_ new: MotionSettings) -> [MotionAction] {
+        let old = settings; settings = new
+        if !isMoving {
+            if isMotionTriggerArmed && new.motionTriggerDelay != old.motionTriggerDelay { isMotionTriggerArmed = false; return [.cancelMotionTrigger] }
+            return []
+        }
+        if new.disableStopDetection { return cancelStopTimer() }
+        if !isStopTimerArmed || new.stopTimeout != old.stopTimeout { return restartStopTimer() }
+        return []
+    }
+    func onLocation(_ fix: TrackedLocation) -> [MotionAction] {
+        if !isMoving {
+            guard let current = anchor else { anchor = fix; return [] }
+            if Geo.distance(current, fix) - fix.accuracyMeters > settings.stationaryRadius { return isAccurateEnough(fix) ? enterMoving(fix) : [] }
+            if fix.accuracyMeters < current.accuracyMeters { anchor = fix }
+            return []
+        }
+        guard let reference = motionAnchor else { motionAnchor = fix; return ensureStopTimer() }
+        if Geo.distance(reference, fix) > max(settings.stationaryRadius, fix.accuracyMeters) { motionAnchor = fix; return restartStopTimer() }
+        return ensureStopTimer()
+    }
+    func onActivity(_ sample: ActivitySample) -> [MotionAction] {
+        guard sample.confidence >= settings.minimumConfidence else { return [] }
+        let moving = Self.movingActivities.contains(sample.type)
+        if isMoving {
+            if moving { return restartStopTimer() }
+            return sample.type == "still" ? ensureStopTimer() : []
+        }
+        if moving && settings.motionTriggerDelay <= 0 { return enterMoving(nil) }
+        if moving && !isMotionTriggerArmed { isMotionTriggerArmed = true; return [.startMotionTrigger(settings.motionTriggerDelay)] }
+        if sample.type == "still" && isMotionTriggerArmed { isMotionTriggerArmed = false; return [.cancelMotionTrigger] }
+        return []
+    }
+    func onMotionTriggerElapsed() -> [MotionAction] {
+        let armed = isMotionTriggerArmed; isMotionTriggerArmed = false
+        return armed && !isMoving ? enterMoving(nil) : []
+    }
+    func onStopTimeout(_ location: TrackedLocation?) -> [MotionAction] {
+        let armed = isStopTimerArmed; isStopTimerArmed = false
+        return armed && isMoving ? enterStationary(location, automatic: true) : []
+    }
+    func force(_ moving: Bool, _ location: TrackedLocation?) -> [MotionAction] {
+        if moving { return isMoving ? restartStopTimer() : enterMoving(location) }
+        return isMoving ? enterStationary(location, automatic: false) : []
+    }
+    func isAccurateEnough(_ fix: TrackedLocation) -> Bool { settings.trackingAccuracyThreshold <= 0 || fix.accuracyMeters <= settings.trackingAccuracyThreshold }
+    private func enterMoving(_ fix: TrackedLocation?) -> [MotionAction] {
+        var actions: [MotionAction] = []
+        if isMotionTriggerArmed { isMotionTriggerArmed = false; actions.append(.cancelMotionTrigger) }
+        isMoving = true; anchor = nil; motionAnchor = fix
+        actions.append(.enterMoving(fix)); actions += restartStopTimer()
+        return actions
+    }
+    private func enterStationary(_ fix: TrackedLocation?, automatic: Bool) -> [MotionAction] {
+        var actions = cancelStopTimer()
+        if isMotionTriggerArmed { isMotionTriggerArmed = false; actions.append(.cancelMotionTrigger) }
+        isMoving = false; anchor = fix; motionAnchor = nil
+        actions.append(.enterStationary(fix, automatic: automatic))
+        return actions
+    }
+    private func restartStopTimer() -> [MotionAction] {
+        guard !settings.disableStopDetection else { return [] }
+        isStopTimerArmed = true
+        return [.startStopTimer(settings.stopTimeout)]
+    }
+    private func ensureStopTimer() -> [MotionAction] { isStopTimerArmed ? [] : restartStopTimer() }
+    private func cancelStopTimer() -> [MotionAction] {
+        guard isStopTimerArmed else { return [] }
+        isStopTimerArmed = false
+        return [.cancelStopTimer]
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Engine/SessionDeadline.swift

@@ -0,0 +1,29 @@
+import Foundation
+
+struct TrackingInstant: Equatable {
+    var wall: Double
+    var elapsed: Double
+    var json: TrackingJSON { ["wall": wall, "elapsed": elapsed] }
+    static func from(_ json: TrackingJSON) -> TrackingInstant? {
+        guard let wall = json["wall"] as? Double, let elapsed = json["elapsed"] as? Double else { return nil }
+        return TrackingInstant(wall: wall, elapsed: elapsed)
+    }
+    func continues(_ previous: TrackingInstant) -> Bool {
+        elapsed >= previous.elapsed && abs((wall - elapsed) - (previous.wall - previous.elapsed)) < 2000
+    }
+}
+
+struct SessionDeadline {
+    var startedAt: Double
+    var startedElapsed: Double
+    init(startedAt: Double, startedElapsed: Double?, checkpoint: TrackingInstant?, now: TrackingInstant) {
+        self.startedAt = startedAt
+        if let startedElapsed, let checkpoint, now.continues(checkpoint) { self.startedElapsed = startedElapsed }
+        else { self.startedElapsed = now.elapsed - (now.wall - startedAt) }
+    }
+    init(now: TrackingInstant) { startedAt = now.wall; startedElapsed = now.elapsed }
+    func remaining(minutes: Double, now: TrackingInstant) -> Double? {
+        minutes > 0 ? minutes * 60000 - (now.elapsed - startedElapsed) : nil
+    }
+    func elapsedDeadline(minutes: Double) -> Double? { minutes > 0 ? startedElapsed + minutes * 60000 : nil }
+}

package/ios/Sources/LocationTrackingPlugin/Engine/TrackingEngine.swift

@@ -0,0 +1,344 @@
+import Foundation
+
+final class TrackingEngine {
+    private unowned let core: TrackingCore
+    private(set) var running = false
+    private(set) var provider: TrackingJSON = [:]
+    private var foreground = false
+    private var mode = "location"
+    private(set) var sessionID = UUID().uuidString
+    private var deadline: SessionDeadline?
+    private var motion = MotionStateMachine()
+    private let processor = LocationProcessor()
+    let odometer = Odometer()
+    private var lastFix: TrackedLocation?
+    private var backendLocation: TrackedLocation?
+    private var lastRecorded: TrackedLocation?
+    private var motionRecorded = false
+    private var lastLocationPersisted: Double?
+    private var lastActivityPersisted: Double?
+    private var lastActivityType: String?
+    private var registrationFailures = 0
+    private var armedHeartbeat: HeartbeatWindow?
+    private var lastAttempt: Double?
+    private var checkInConfig: Data?
+    private var assertion: ExecutionAssertion?
+    var geofences: GeofenceManager?
+    private var geofenceDemand = false
+    lazy var timers = TrackingTimers(queue: core.queue, now: { [unowned self] in self.core.clock().elapsed }, automatic: core.automaticTimers)
+    lazy var notifier = CheckInNotifier(queue: core.queue, clock: core.clock) { [weak self] in self?.core.log.write("warn", $0) }
+    init(core: TrackingCore) {
+        self.core = core
+        if let at = core.runtime["trackingStartedAt"] as? Double {
+            deadline = SessionDeadline(startedAt: at, startedElapsed: core.runtime["trackingStartedElapsed"] as? Double, checkpoint: TrackingInstant.from(core.runtime.object("clockCheckpoint")), now: core.clock())
+        }
+    }
+    private var config: TrackingJSON { core.config.value }
+    private var geo: TrackingJSON { config.object("geolocation") }
+    private var bestKnown: TrackedLocation? {
+        let threshold = geo.object("filter").number("trackingAccuracyThreshold", 100)
+        let vetted = backendLocation.flatMap { threshold <= 0 || $0.accuracyMeters <= threshold ? $0 : nil }
+        return [lastFix, TrackedLocation.from(core.runtime.object("lastLocation")), vetted].compactMap { $0 }.max { $0.isOlder(than: $1) } ?? backendLocation
+    }
+    func offerLastLocation(_ location: TrackedLocation?) { backendLocation = location }
+    func context(provider: TrackingJSON, foreground: Bool) { self.provider = provider; self.foreground = foreground }
+    func restore() throws {
+        guard core.runtime.flag("enabled") else { applyProfile(force: true); notifier.cancel(); geofences?.releaseStale(); return }
+        guard !running else { return }
+        if let remaining = deadline?.remaining(minutes: geo.number("stopAfterElapsedMinutes"), now: core.clock()), remaining <= 0 { try stop(reason: "stop_after_elapsed"); return }
+        guard provider["enabled"] as? Bool != false else { scheduleElapsedStop(); return }
+        guard provider.text("permission") == "always" || provider.text("permission") == "when_in_use" else { try stop(reason: "permission_denied"); return }
+        if deadline == nil { deadline = SessionDeadline(now: core.clock()) }
+        try saveSession(enabled: true, mode: core.runtime.text("trackingMode", "location"))
+        guard foreground || provider.text("permission") == "always" else { scheduleElapsedStop(); return }
+        activate(mode: core.runtime.text("trackingMode", "location"), reason: "restore")
+    }
+    func start(mode: String = "location") throws {
+        if running && self.mode == mode { return }
+        guard provider.text("permission") == "always" || provider.text("permission") == "when_in_use" else { throw TrackingError("PERMISSION_DENIED", "Location permission is required") }
+        guard foreground || provider.text("permission") == "always" else { throw TrackingError("PERMISSION_DENIED", "Start When In Use tracking while the app is in the foreground") }
+        let switching = running
+        if switching && self.mode == "location" && motion.isMoving { recordMotion(false, bestKnown) }
+        deadline = SessionDeadline(now: core.clock())
+        try saveSession(enabled: true, mode: mode)
+        if switching { configure(mode: mode); submit("tracking_start", bestKnown, reason: mode == "location" ? "start" : "start_geofences") }
+        else {
+            activate(mode: mode, reason: mode == "location" ? "start" : "start_geofences")
+            core.emit("enabledchange", ["enabled": true, "reason": mode == "location" ? "start" : "start_geofences"])
+        }
+    }
+    private func saveSession(enabled: Bool, mode: String) throws {
+        guard let deadline else { return }
+        try core.updateRuntime(["enabled": enabled, "trackingMode": mode, "isMoving": false, "trackingStartedAt": deadline.startedAt, "trackingStartedElapsed": deadline.startedElapsed])
+    }
+    private func activate(mode: String, reason: String) {
+        running = true; core.syncer.tracking = true
+        processor.reset(); lastAttempt = nil; armedHeartbeat = nil
+        notifier.start()
+        configure(mode: mode)
+        submit("tracking_start", bestKnown, reason: reason)
+    }
+    private func configure(mode: String) {
+        cancelInitialFix(); timers.cancelAll()
+        sessionID = UUID().uuidString
+        self.mode = mode
+        motion = MotionStateMachine(MotionSettings.from(config))
+        motionRecorded = false; lastRecorded = nil; lastActivityType = nil; lastActivityPersisted = nil; lastLocationPersisted = nil; registrationFailures = 0
+        applyProfile()
+        scheduleElapsedStop()
+        if mode == "location" { initialFixRequest() }
+        rescheduleHeartbeat(force: true)
+        touchCheckIn(force: true)
+        updateGeofenceAccess()
+        geofences?.onTrackingStarted(always: provider.text("permission") == "always")
+    }
+    func stop(reason: String = "stop") throws {
+        notifier.cancel()
+        guard running || core.runtime.flag("enabled") else { return }
+        running = false; timers.cancelAll(); armedHeartbeat = nil; lastAttempt = nil
+        assertion?.finish(); assertion = nil
+        geofences?.onTrackingStopped()
+        cancelInitialFix()
+        submit("tracking_stop", bestKnown, reason: reason)
+        let stopped: TrackingJSON = ["enabled": false, "isMoving": false, "lastStopReason": reason, "lastStopAt": iso(Date(timeIntervalSince1970: core.clock().wall / 1000))]
+        do { try core.updateRuntime(stopped) }
+        catch {
+            core.runtime.merge(stopped) { _, new in new }
+            applyProfile(); core.syncer.tracking = false
+            core.emit("enabledchange", ["enabled": false, "reason": reason])
+            throw error
+        }
+        applyProfile(); core.syncer.tracking = false; core.syncer.automatic()
+        core.emit("enabledchange", ["enabled": false, "reason": reason])
+    }
+    func terminate() { if config.object("app").flag("stopOnTerminate", true) { do { try stop(reason: "terminate") } catch { core.log.write("error", "Could not persist termination intent") } } }
+    func active(provider: TrackingJSON, foreground: Bool) {
+        context(provider: provider, foreground: foreground)
+        do { try restore() } catch { core.log.write("error", "Tracking restore failed") }
+        if running { applyProfile(force: true); timers.fireDue(); rescheduleHeartbeat(force: true); touchCheckIn() }
+    }
+    func clockChanged() {
+        update([:]); scheduleElapsedStop(); rescheduleHeartbeat(force: true); timers.fireDue()
+    }
+    func configChanged() {
+        if !config.object("notification").object("resume").flag("enabled") { notifier.cancel() }
+        guard running else {
+            if core.runtime.flag("enabled") { scheduleElapsedStop() }
+            return
+        }
+        execute(motion.updateSettings(MotionSettings.from(config)))
+        guard running else { return }
+        applyProfile(); scheduleElapsedStop(); rescheduleHeartbeat(force: true); touchCheckIn()
+        timers.fireDue()
+    }
+    func providerChanged(_ value: TrackingJSON) {
+        let previous = provider
+        guard !NSDictionary(dictionary: previous).isEqual(to: value) else { return }
+        provider = value
+        core.emit("providerchange", value)
+        guard running else {
+            if core.runtime.flag("enabled") { do { try restore() } catch { core.log.write("error", "Tracking restore failed") } }
+            return
+        }
+        submit("providerchange", bestKnown)
+        if value.flag("enabled") && value.text("permission") == "denied" { try? stop(reason: "permission_denied"); return }
+        if value.flag("enabled") && (!previous.flag("enabled") || previous.text("permission") != value.text("permission")) { applyProfile(force: true) }
+        if previous.text("accuracy") != value.text("accuracy") { updateGeofenceAccess() }
+        if previous.text("permission") != value.text("permission") { geofences?.onTrackingStarted(always: value.text("permission") == "always") }
+    }
+    func changePace(_ moving: Bool) {
+        guard running, mode == "location" else { return }
+        execute(motion.force(moving, motion.isMoving == moving ? nil : bestKnown))
+    }
+    func receive(_ batch: [TrackedLocation], session: String? = nil) {
+        guard running, session == nil || session == sessionID else { return }
+        registrationFailures = 0
+        if let newest = batch.max(by: { $0.isOlder(than: $1) }) { backendLocation = newest }
+        if !batch.isEmpty { touchCheckIn() }
+        for raw in batch {
+            guard running else { return }
+            guard case .accepted(var fix) = processor.process(raw, filter: geo.object("filter")) else { continue }
+            fix.session = core.runtime["trackingStartedAt"] as? Double
+            lastFix = fix
+            geofences?.onLocation(fix)
+            guard running else { return }
+            if mode != "location" {
+                let delta = odometer.onLocation(fix, runtime: core.runtime, threshold: geo.object("filter").number("odometerAccuracyThreshold", 20))
+                if delta > 0 { update(["odometer": core.odometer + delta]) }
+                rememberLocation(fix)
+                continue
+            }
+            let wasMoving = motion.isMoving
+            let oldAnchor = motion.anchor
+            let actions = motion.onLocation(fix)
+            if !wasMoving && !motion.isMoving {
+                if let anchor = motion.anchor, anchor != oldAnchor { rememberLocation(anchor, force: true) }
+                continue
+            }
+            let delta = odometer.onLocation(fix, runtime: core.runtime, threshold: geo.object("filter").number("odometerAccuracyThreshold", 20))
+            if delta > 0 { update(["odometer": core.odometer + delta]) }
+            execute(actions)
+            guard running, wasMoving else { continue }
+            if ElasticDistance.shouldRecord(lastRecorded, fix, geo) { submit("location", fix); lastRecorded = fix; lastLocationPersisted = core.clock().elapsed }
+            else { rememberLocation(fix) }
+        }
+        timers.fireDue()
+    }
+    func initialFix(_ raw: TrackedLocation?) {
+        guard running, mode == "location", !motionRecorded else { return }
+        if let raw, case .accepted(var fix) = processor.process(raw, filter: geo.object("filter")) {
+            fix.session = core.runtime["trackingStartedAt"] as? Double
+            if lastFix == nil || !fix.isOlder(than: lastFix!) { lastFix = fix }
+            motion.setAnchor(fix)
+        }
+        let known = bestKnown
+        motion.offerAnchor(known)
+        recordMotion(false, known)
+    }
+    func activity(_ sample: ActivitySample, session: String? = nil) {
+        guard running, session == nil || session == sessionID, !config.object("activity").flag("disableMotionActivityUpdates"), sample.confidence >= Int(config.object("activity").number("minimumActivityRecognitionConfidence", 75)) else { return }
+        let now = core.clock().elapsed
+        let current = core.runtime.object("activity")
+        if current.text("type") != sample.type || lastActivityPersisted == nil || now - lastActivityPersisted! >= 60000 {
+            update(["activity": sample.json]); lastActivityPersisted = now
+        }
+        if lastActivityType != sample.type { lastActivityType = sample.type; core.emit("activitychange", ["activity": sample.type, "confidence": sample.confidence]) }
+        if mode == "location" { execute(motion.onActivity(sample)) }
+        timers.fireDue()
+    }
+    func registrationFailed(_ error: TrackingError, session: String? = nil) {
+        guard running, session == nil || session == sessionID else { return }
+        registrationFailures += 1
+        let delay = min(300000, 10000 * pow(2, Double(min(10, registrationFailures - 1))))
+        core.emit("locationerror", ["code": error.code, "message": error.message, "backend": PluginInfo.backend, "retryInMs": delay])
+        timers.schedule("request_retry", after: delay) { [weak self] in guard let self, self.running else { return }; self.applyProfile(force: true) }
+    }
+    private func execute(_ actions: [MotionAction]) {
+        for action in actions {
+            guard running else { return }
+            switch action {
+            case .startStopTimer(let delay): timers.schedule("stop_timeout", after: delay) { [weak self] in guard let self, self.running else { return }; self.execute(self.motion.onStopTimeout(self.bestKnown)) }
+            case .cancelStopTimer: timers.cancel("stop_timeout")
+            case .startMotionTrigger(let delay): timers.schedule("motion_trigger", after: delay) { [weak self] in guard let self, self.running else { return }; self.execute(self.motion.onMotionTriggerElapsed()) }
+            case .cancelMotionTrigger: timers.cancel("motion_trigger")
+            case .enterMoving(let location): recordMotion(true, location ?? bestKnown); applyProfile()
+            case .enterStationary(let location, let automatic):
+                recordMotion(false, location)
+                if automatic && geo.flag("stopOnStationary") { try? stop(reason: "stop_on_stationary") }
+                else { applyProfile() }
+            }
+        }
+    }
+    private func recordMotion(_ moving: Bool, _ fix: TrackedLocation?) {
+        update(["isMoving": moving]); submit("motionchange", fix)
+        motionRecorded = true
+        if let fix { lastRecorded = fix; lastLocationPersisted = core.clock().elapsed }
+    }
+    private func rememberLocation(_ fix: TrackedLocation, force: Bool = false) {
+        let now = core.clock().elapsed
+        guard force || lastLocationPersisted == nil || now - lastLocationPersisted! >= 10000 else { return }
+        lastLocationPersisted = now; update(["lastLocation": fix.json])
+    }
+    private func update(_ values: TrackingJSON) {
+        do { try core.updateRuntime(values) }
+        catch { core.runtime.merge(values) { _, new in new }; core.log.write("error", "Tracking state could not be persisted") }
+    }
+    private func applyProfile(force: Bool = false) {
+        guard let source = core.routeSource else { return }
+        let profile = RouteProfile(enabled: running && (mode == "location" || geofenceDemand), moving: mode == "location" ? motion.isMoving : geofenceDemand, accuracy: geo.text("desiredAccuracy", "high"), activityEnabled: mode == "location" && !config.object("activity").flag("disableMotionActivityUpdates"), sessionID: sessionID)
+        DispatchQueue.main.async { source.apply(profile, force: force) }
+    }
+    private func initialFixRequest() {
+        guard core.routeSource != nil else { return }
+        let id = sessionID
+        let options: TrackingJSON = ["desiredAccuracy": geo.text("desiredAccuracy", "high"), "timeout": geo.number("locationTimeout", 30000), "samples": 3, "_rejectMock": geo.object("filter").flag("rejectMockLocations")]
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            self.core.positions.request(id: "route-" + id, options: options, watch: false) { [weak self] result in
+                guard let self else { return }
+                self.core.queue.async { [weak self] in guard let self, self.sessionID == id else { return }; self.initialFix((try? result.get()).map { TrackedLocation($0, receivedAt: self.core.clock()) }) }
+            }
+        }
+    }
+    private func cancelInitialFix() {
+        let id = sessionID, positions = core.positions
+        DispatchQueue.main.async { positions.clear("route-" + id) }
+    }
+    private func scheduleElapsedStop() {
+        timers.cancel("elapsed_stop")
+        guard core.runtime.flag("enabled"), let remaining = deadline?.remaining(minutes: geo.number("stopAfterElapsedMinutes"), now: core.clock()) else { return }
+        timers.schedule("elapsed_stop", after: remaining) { [weak self] in try? self?.stop(reason: "stop_after_elapsed") }
+    }
+    private func touchCheckIn(force: Bool = false) {
+        guard running else { return }
+        let settings = config.object("notification").object("resume")
+        let encoded = try? jsonData(settings)
+        let changed = encoded != checkInConfig
+        checkInConfig = encoded
+        notifier.touch(settings, deadlineElapsed: deadline?.elapsedDeadline(minutes: geo.number("stopAfterElapsedMinutes")), force: force || changed)
+    }
+    private func window() -> HeartbeatWindow {
+        let now = core.clock(), hb = config.object("heartbeat")
+        return HeartbeatWindow.compute(lastRecordAt: timestamp(core.runtime["lastRecordAt"]), lastRecordElapsed: core.runtime["lastRecordElapsed"] as? Double, sameBoot: true, now: now.wall, nowElapsed: now.elapsed, minInterval: hb.number("minInterval", 180), maxInterval: hb.number("maxInterval", 300), enabled: running && hb.flag("enabled", true), noRecordBaseElapsed: deadline?.startedElapsed, lastAttemptElapsed: lastAttempt, trackingStartedAt: deadline?.startedAt)
+    }
+    func recorded() { if running { rescheduleHeartbeat(); touchCheckIn() } }
+    private func rescheduleHeartbeat(force: Bool = false) {
+        let next = window()
+        guard next.enabled else { timers.cancel("heartbeat"); armedHeartbeat = nil; return }
+        guard force || next.needsRearm(armedHeartbeat) else { return }
+        armedHeartbeat = next
+        timers.schedule("heartbeat", after: next.dueElapsed - core.clock().elapsed) { [weak self] in self?.heartbeat() }
+    }
+    func heartbeat() {
+        guard running else { return }
+        if let remaining = deadline?.remaining(minutes: geo.number("stopAfterElapsedMinutes"), now: core.clock()), remaining <= 0 { try? stop(reason: "stop_after_elapsed"); return }
+        let current = window(), now = core.clock()
+        guard current.enabled else { return }
+        guard current.shouldFire(now.elapsed) else { rescheduleHeartbeat(force: true); return }
+        if now.elapsed > current.deadlineElapsed + 1000 { core.log.write("warn", "Heartbeat arrived after heartbeat.maxInterval") }
+        lastAttempt = now.elapsed
+        var wire = core.makeRecord(event: "heartbeat", fix: bestKnown)
+        let next = HeartbeatWindow.compute(lastRecordAt: now.wall, lastRecordElapsed: now.elapsed, sameBoot: true, now: now.wall, nowElapsed: now.elapsed, minInterval: config.object("heartbeat").number("minInterval", 180), maxInterval: config.object("heartbeat").number("maxInterval", 300))
+        wire["heartbeat"] = ["strategy": "timer", "min_interval": config.object("heartbeat").number("minInterval", 180), "max_interval": config.object("heartbeat").number("maxInterval", 300), "next_at": next.nextHeartbeatAt.map { iso(Date(timeIntervalSince1970: $0 / 1000)) } as Any? ?? NSNull(), "battery_exempt": false, "device_idle": false]
+        assertion?.finish()
+        let upload = ExecutionAssertion(); assertion = upload
+        upload.start(seconds: config.object("heartbeat").number("uploadKeepAwake", 10), queue: core.queue)
+        core.deliver(wire, location: bestKnown) { upload.finish() }
+        rescheduleHeartbeat(force: true)
+    }
+    func heartbeatStatus() -> TrackingJSON {
+        let hb = config.object("heartbeat"), current = window()
+        return ["enabled": hb.flag("enabled", true), "minInterval": hb.number("minInterval", 180), "maxInterval": hb.number("maxInterval", 300), "lastRecordAt": core.runtime["lastRecordAt"] ?? NSNull(), "lastHeartbeatAt": core.runtime["lastHeartbeatAt"] ?? NSNull(), "nextHeartbeatAt": current.nextHeartbeatAt.map { iso(Date(timeIntervalSince1970: $0 / 1000)) } as Any? ?? NSNull(), "strategy": current.enabled ? "timer" : "disabled", "canScheduleExactAlarms": false, "isIgnoringBatteryOptimizations": false, "isDeviceIdleMode": false, "isPowerSaveMode": ProcessInfo.processInfo.isLowPowerModeEnabled, "pendingHeartbeats": (try? core.store.count(event: "heartbeat")) ?? 0]
+    }
+    private func timestamp(_ value: Any?) -> Double? {
+        guard let text = value as? String else { return nil }
+        return isoDate(text).map { $0.timeIntervalSince1970 * 1000 }
+    }
+    func geofenceDemandChanged(_ needs: Bool) {
+        guard geofenceDemand != needs else { return }
+        geofenceDemand = needs
+        if running { applyProfile() }
+    }
+    func recordGeofence(_ spec: GeofenceSpec, _ action: GeofenceAction, _ location: TrackedLocation?) {
+        var wire = core.makeRecord(event: "geofence", fix: location)
+        var hit: TrackingJSON = ["identifier": spec.identifier, "action": action.rawValue]
+        if let extras = spec.extras { hit["extras"] = extras }
+        wire["geofence"] = hit
+        core.deliver(wire, location: location)
+    }
+    private func updateGeofenceAccess() { geofences?.setSuspended(provider.text("accuracy") == "approximate") }
+    func geofenceFailures(_ failures: [MonitorFailure]) {
+        for failure in failures {
+            core.log.write("error", failure.message + " (" + failure.code + ")")
+            core.emit("locationerror", ["code": failure.code, "message": failure.message, "backend": PluginInfo.backend, "retryInMs": NSNull()])
+        }
+    }
+    func geofencesBlocked() {
+        core.emit("locationerror", ["code": "PERMISSION_DENIED", "message": "Geofences need precise location; stored geofences stay inactive while location accuracy is approximate", "backend": PluginInfo.backend, "retryInMs": NSNull()])
+    }
+    private func submit(_ event: String, _ location: TrackedLocation?, reason: String? = nil) {
+        var wire = core.makeRecord(event: event, fix: location)
+        if let reason { wire["reason"] = reason }
+        core.deliver(wire, location: location)
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Engine/TrackingTimers.swift

@@ -0,0 +1,35 @@
+import Foundation
+
+final class TrackingTimers {
+    private struct Entry { let at: Double; let action: () -> Void }
+    private let queue: DispatchQueue
+    private let now: () -> Double
+    private let automatic: Bool
+    private var entries: [String: Entry] = [:]
+    private var source: DispatchSourceTimer?
+    init(queue: DispatchQueue, now: @escaping () -> Double, automatic: Bool = true) { self.queue = queue; self.now = now; self.automatic = automatic }
+    deinit { source?.cancel() }
+    func schedule(_ kind: String, after delay: Double, _ action: @escaping () -> Void) {
+        entries[kind] = Entry(at: now() + max(0, delay), action: action)
+        arm()
+    }
+    func cancel(_ kind: String) { entries.removeValue(forKey: kind); arm() }
+    func cancelAll() { entries.removeAll(); source?.cancel(); source = nil }
+    func fireDue() {
+        while let due = entries.min(by: { $0.value.at < $1.value.at }), due.value.at <= now() {
+            entries.removeValue(forKey: due.key)
+            due.value.action()
+        }
+        arm()
+    }
+    private func arm() {
+        guard automatic else { return }
+        guard let first = entries.values.map(\.at).min() else { source?.cancel(); source = nil; return }
+        if source == nil {
+            let timer = DispatchSource.makeTimerSource(queue: queue)
+            timer.setEventHandler { [weak self] in self?.fireDue() }
+            source = timer; timer.resume()
+        }
+        source?.schedule(deadline: .now() + min(86400, max(0.001, (first - now()) / 1000)), leeway: .milliseconds(1000))
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Geofence/DwellTracker.swift

@@ -0,0 +1,35 @@
+import Foundation
+
+final class DwellTracker {
+    private struct Pending { let deadline: Double; let token: Double; let sequence: Int }
+    private let timers: TrackingTimers
+    private let now: () -> Double
+    private let onDue: (String, Double) -> Void
+    private var pending: [String: Pending] = [:]
+    private var sequence = 0
+    init(queue: DispatchQueue, now: @escaping () -> Double, automatic: Bool = true, onDue: @escaping (String, Double) -> Void) {
+        self.now = now; self.onDue = onDue
+        timers = TrackingTimers(queue: queue, now: now, automatic: automatic)
+    }
+    func arm(_ id: String, deadline: Double, token: Double) {
+        sequence += 1
+        let current = sequence
+        pending[id] = Pending(deadline: deadline, token: token, sequence: current)
+        timers.schedule(id, after: deadline - now()) { [weak self] in
+            guard let self, let entry = self.pending[id], entry.sequence == current else { return }
+            self.pending.removeValue(forKey: id)
+            self.onDue(id, entry.token)
+        }
+    }
+    func cancel(_ id: String) { pending.removeValue(forKey: id); timers.cancel(id) }
+    func cancelAll() { pending.removeAll(); timers.cancelAll() }
+    func isArmed(_ id: String) -> Bool { pending[id] != nil }
+    var hasArmed: Bool { !pending.isEmpty }
+    func takeDue(_ at: Double? = nil) -> [(String, Double)] {
+        let limit = at ?? now()
+        let due = pending.filter { $0.value.deadline <= limit }.sorted { $0.value.sequence < $1.value.sequence }
+        for (id, _) in due { pending.removeValue(forKey: id); timers.cancel(id) }
+        return due.map { ($0.key, $0.value.token) }
+    }
+    func fireDue() { timers.fireDue() }
+}

package/ios/Sources/LocationTrackingPlugin/Geofence/GeofenceEventAdapter.swift

@@ -0,0 +1,88 @@
+import Foundation
+
+enum MonitorState: Equatable { case unknown, satisfied, unsatisfied, unmonitored }
+
+struct MonitorFailure: Equatable {
+    var id: String
+    var code: String
+    var message: String
+}
+
+final class GeofenceEventAdapter {
+    private var known: [String: MonitorState] = [:]
+    private var initialTrigger: [String: Bool] = [:]
+    private var reported: [String: Set<String>] = [:]
+    private var ready: Set<String> = []
+    private var expected: Set<String> = []
+    private var held: [String: [(MonitorState, [(String, String)])]] = [:]
+
+    func seed(_ id: String, _ state: MonitorState) {
+        if known[id] == nil { known[id] = state }
+    }
+
+    func expect(_ id: String) {
+        ready.remove(id); expected.insert(id)
+    }
+
+    func restored(_ id: String, initialTriggerEntry: Bool, state: MonitorState) -> ([OsGeofenceTransition], [MonitorFailure]) {
+        initialTrigger[id] = initialTriggerEntry
+        if known[id] == nil { known[id] = state }
+        expected.remove(id); ready.insert(id)
+        var transitions: [OsGeofenceTransition] = [], failures: [MonitorFailure] = []
+        for (state, diagnostics) in held.removeValue(forKey: id) ?? [] {
+            let result = process(id, state, diagnostics)
+            transitions += result.0; failures += result.1
+        }
+        return (transitions, failures)
+    }
+
+    func registered(_ id: String, initialTriggerEntry: Bool) {
+        known[id] = .unknown
+        initialTrigger[id] = initialTriggerEntry
+        reported[id] = nil; held[id] = nil
+        expected.remove(id); ready.insert(id)
+    }
+
+    func registered(_ id: String, initialTriggerEntry: Bool, current: MonitorState) -> ([OsGeofenceTransition], [MonitorFailure]) {
+        registered(id, initialTriggerEntry: initialTriggerEntry)
+        return process(id, current, [])
+    }
+
+    func removed(_ id: String) {
+        known[id] = nil; initialTrigger[id] = nil; reported[id] = nil; held[id] = nil
+        expected.remove(id); ready.remove(id)
+    }
+
+    func retain(_ ids: Set<String>) {
+        known = known.filter { ids.contains($0.key) }
+        initialTrigger = initialTrigger.filter { ids.contains($0.key) }
+        reported = reported.filter { ids.contains($0.key) }
+        held = held.filter { ids.contains($0.key) }
+        expected.formIntersection(ids); ready.formIntersection(ids)
+    }
+
+    func handle(_ id: String, _ state: MonitorState, failures diagnostics: [(String, String)]) -> ([OsGeofenceTransition], [MonitorFailure]) {
+        if !ready.contains(id), expected.contains(id) || known[id] != nil {
+            held[id, default: []].append((state, diagnostics))
+            return ([], [])
+        }
+        return process(id, state, diagnostics)
+    }
+
+    private func process(_ id: String, _ state: MonitorState, _ diagnostics: [(String, String)]) -> ([OsGeofenceTransition], [MonitorFailure]) {
+        var failures: [MonitorFailure] = []
+        for (code, message) in diagnostics where !(reported[id]?.contains(code) ?? false) {
+            reported[id, default: []].insert(code)
+            failures.append(MonitorFailure(id: id, code: code, message: "geofence '\(id)': " + message))
+        }
+        guard diagnostics.isEmpty, state == .satisfied || state == .unsatisfied, let previous = known[id] else { return ([], failures) }
+        reported[id] = nil
+        guard previous != state else { return ([], failures) }
+        known[id] = state
+        if previous == .unknown || previous == .unmonitored {
+            if state == .satisfied { return (initialTrigger[id] ?? true ? [OsGeofenceTransition(id: id, action: .enter, location: nil)] : [], failures) }
+            return ([OsGeofenceTransition(id: id, action: .exit, location: nil, initial: true)], failures)
+        }
+        return ([OsGeofenceTransition(id: id, action: state == .satisfied ? .enter : .exit, location: nil)], failures)
+    }
+}