@cariva-dev/exercise-sdk 2.0.0

package/android/src/main/java/com/carivaexercisesdk/domain/exercise/services/HealthConnectCaloriesFallbackMerger.kt

@@ -0,0 +1,351 @@
+package com.carivaexercisesdk.domain.exercise.services
+
+internal object HealthConnectCaloriesFallbackMerger {
+  fun mergeCaloriesWithFallback(
+          primaryActiveCalories: HealthConnectModuleInternals.NormalizationResult,
+          totalCalories: HealthConnectModuleInternals.NormalizationResult,
+          basalCalories: HealthConnectModuleInternals.NormalizationResult,
+          stepsEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment> = emptyList(),
+          activeTimeEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment> =
+                  emptyList(),
+          distanceEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment> =
+                  emptyList(),
+          basalSeedApplied: Boolean = false,
+          seededFromBeforeSince: Boolean = false,
+          basalSeedAgeHours: Double? = null
+  ): HealthConnectModuleInternals.NormalizationResult {
+    val directActiveCaloriesKcal = primaryActiveCalories.segments.sumOf { it.value }
+    val totalCaloriesKcal = totalCalories.segments.sumOf { it.value }
+    val basalCaloriesKcal = basalCalories.segments.sumOf { it.value }
+
+    val fallbackDerived =
+            deriveFallbackCaloriesSegments(
+                    primaryActiveCalories = primaryActiveCalories.segments,
+                    totalCalories = totalCalories.segments,
+                    basalCalories = basalCalories.segments,
+                    stepsEvidenceSegments = stepsEvidenceSegments,
+                    activeTimeEvidenceSegments = activeTimeEvidenceSegments,
+                    distanceEvidenceSegments = distanceEvidenceSegments
+            )
+    val fallbackFilled =
+            fillUncoveredIntervals(
+                    primarySegments = primaryActiveCalories.segments,
+                    fallbackSegments = fallbackDerived.segments
+            )
+    val warnings =
+            linkedSetOf<String>().apply {
+              addAll(primaryActiveCalories.warnings)
+              addAll(totalCalories.warnings)
+              addAll(basalCalories.warnings)
+              if (basalSeedApplied) {
+                add(HealthConnectInternalsConstants.WARNING_BMR_SEED_FROM_LATEST_BEFORE_SINCE_USED)
+              }
+              if (fallbackDerived.fallbackSuppressedSegments > 0) {
+                add(HealthConnectInternalsConstants.WARNING_BMR_MISSING_FOR_FALLBACK_WINDOW)
+                add(HealthConnectInternalsConstants.WARNING_FALLBACK_SUPPRESSED_DUE_TO_MISSING_BASAL)
+              }
+              if (fallbackDerived.idleGateSuppressedSegments > 0) {
+                add(HealthConnectInternalsConstants.WARNING_FALLBACK_SUPPRESSED_DUE_TO_IDLE_WINDOW)
+              }
+              if (fallbackFilled.fallbackUsedSegments > 0) {
+                add(HealthConnectInternalsConstants.WARNING_CALORIES_FALLBACK_USED)
+                if (primaryActiveCalories.segments.isEmpty()) {
+                  add(HealthConnectInternalsConstants.WARNING_CALORIES_FALLBACK_ONLY_USED)
+                } else {
+                  add(HealthConnectInternalsConstants.WARNING_CALORIES_FALLBACK_PARTIAL_USED)
+                }
+              }
+            }
+
+    val mergedActiveCaloriesKcal = fallbackFilled.segments.sumOf { it.value }
+    val fallbackContributionKcal = maxOf(mergedActiveCaloriesKcal - directActiveCaloriesKcal, 0.0)
+
+    return HealthConnectModuleInternals.NormalizationResult(
+            segments = fallbackFilled.segments,
+            stats = primaryActiveCalories.stats + totalCalories.stats + basalCalories.stats,
+            overlapStrategy = HealthConnectInternalsConstants.OVERLAP_STRATEGY_PROPORTIONAL,
+            warnings = warnings.toList(),
+            diagnostics =
+                    HealthConnectModuleInternals.Diagnostics(
+                            fallbackUsedSegments = fallbackFilled.fallbackUsedSegments,
+                            fallbackSuppressedSegments = fallbackDerived.fallbackSuppressedSegments,
+                            idleGateSuppressedSegments = fallbackDerived.idleGateSuppressedSegments,
+                            basalSeedApplied = basalSeedApplied,
+                            seededFromBeforeSince = seededFromBeforeSince,
+                            basalSeedAgeHours = basalSeedAgeHours,
+                            directActiveCaloriesKcal = directActiveCaloriesKcal,
+                            totalCaloriesKcal = totalCaloriesKcal,
+                            basalCaloriesKcal = basalCaloriesKcal,
+                            mergedActiveCaloriesKcal = mergedActiveCaloriesKcal,
+                            fallbackContributionKcal = fallbackContributionKcal
+                    )
+    )
+  }
+
+  private data class FallbackDeriveResult(
+          val segments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          val fallbackSuppressedSegments: Int,
+          val idleGateSuppressedSegments: Int
+  )
+
+  private fun deriveFallbackCaloriesSegments(
+          primaryActiveCalories: List<HealthConnectModuleInternals.NormalizedSegment>,
+          totalCalories: List<HealthConnectModuleInternals.NormalizedSegment>,
+          basalCalories: List<HealthConnectModuleInternals.NormalizedSegment>,
+          stepsEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          activeTimeEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          distanceEvidenceSegments: List<HealthConnectModuleInternals.NormalizedSegment>
+  ): FallbackDeriveResult {
+    if (totalCalories.isEmpty()) {
+      return FallbackDeriveResult(
+              segments = emptyList(),
+              fallbackSuppressedSegments = 0,
+              idleGateSuppressedSegments = 0
+      )
+    }
+
+    val breakpoints =
+            listOf(
+                            primaryActiveCalories,
+                            totalCalories,
+                            basalCalories,
+                            stepsEvidenceSegments,
+                            activeTimeEvidenceSegments,
+                            distanceEvidenceSegments
+                    )
+                    .flatMap { segments -> segments.flatMap { listOf(it.startMs, it.endMs) } }
+                    .toSortedSet()
+                    .toList()
+
+    if (breakpoints.size < 2) {
+      return FallbackDeriveResult(
+              segments = emptyList(),
+              fallbackSuppressedSegments = 0,
+              idleGateSuppressedSegments = 0
+      )
+    }
+
+    val derived = mutableListOf<HealthConnectModuleInternals.NormalizedSegment>()
+    var fallbackSuppressedSegments = 0
+    var idleGateSuppressedSegments = 0
+    for (index in 0 until breakpoints.lastIndex) {
+      val startMs = breakpoints[index]
+      val endMs = breakpoints[index + 1]
+      if (endMs <= startMs) {
+        continue
+      }
+
+      val totalValue = projectSegmentValue(totalCalories, startMs, endMs)
+      if (totalValue <= 0.0) {
+        continue
+      }
+      if (!hasCoverage(basalCalories, startMs, endMs)) {
+        fallbackSuppressedSegments += 1
+        continue
+      }
+      val basalValue = projectSegmentValue(basalCalories, startMs, endMs)
+      val activeValue = maxOf(totalValue - basalValue, 0.0)
+      if (activeValue <= 0.0) {
+        continue
+      }
+      val projectedDirectActive = projectSegmentValue(primaryActiveCalories, startMs, endMs)
+      val projectedSteps = projectSegmentValue(stepsEvidenceSegments, startMs, endMs)
+      val projectedDistance = projectSegmentValue(distanceEvidenceSegments, startMs, endMs)
+      val projectedActiveTime = projectSegmentValue(activeTimeEvidenceSegments, startMs, endMs)
+      if (projectedDirectActive == 0.0 &&
+                      projectedSteps == 0.0 &&
+                      projectedDistance == 0.0 &&
+                      projectedActiveTime == 0.0
+      ) {
+        idleGateSuppressedSegments += 1
+        continue
+      }
+
+      derived.add(
+              HealthConnectModuleInternals.NormalizedSegment(
+                      startMs = startMs,
+                      endMs = endMs,
+                      value = activeValue,
+                      sourceType = HealthConnectInternalsConstants.SOURCE_FALLBACK,
+                      packageName = HealthConnectInternalsConstants.PACKAGE_FALLBACK_TOTAL_MINUS_BASAL,
+                      deviceModel = ""
+              )
+      )
+    }
+
+    return FallbackDeriveResult(
+            segments = derived,
+            fallbackSuppressedSegments = fallbackSuppressedSegments,
+            idleGateSuppressedSegments = idleGateSuppressedSegments
+    )
+  }
+
+  private data class FillFallbackResult(
+          val segments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          val fallbackUsedSegments: Int
+  )
+
+  private data class ProjectedSegmentRepresentative(
+          val sourceType: String,
+          val packageName: String,
+          val deviceModel: String
+  )
+
+  private data class WeightedSegmentProjection(
+          val segment: HealthConnectModuleInternals.NormalizedSegment,
+          val projectedValue: Double
+  )
+
+  private fun fillUncoveredIntervals(
+          primarySegments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          fallbackSegments: List<HealthConnectModuleInternals.NormalizedSegment>
+  ): FillFallbackResult {
+    if (primarySegments.isEmpty()) {
+      return FillFallbackResult(
+              segments = fallbackSegments,
+              fallbackUsedSegments = fallbackSegments.size
+      )
+    }
+    if (fallbackSegments.isEmpty()) {
+      return FillFallbackResult(segments = primarySegments, fallbackUsedSegments = 0)
+    }
+
+    val breakpoints =
+            listOf(primarySegments, fallbackSegments)
+                    .flatMap { segments -> segments.flatMap { listOf(it.startMs, it.endMs) } }
+                    .toSortedSet()
+                    .toList()
+    if (breakpoints.size < 2) {
+      return FillFallbackResult(segments = primarySegments, fallbackUsedSegments = 0)
+    }
+
+    val merged = mutableListOf<HealthConnectModuleInternals.NormalizedSegment>()
+    var fallbackUsedSegments = 0
+    for (index in 0 until breakpoints.lastIndex) {
+      val startMs = breakpoints[index]
+      val endMs = breakpoints[index + 1]
+      if (endMs <= startMs) {
+        continue
+      }
+
+      val primaryValue = projectSegmentValue(primarySegments, startMs, endMs)
+      val fallbackValue = projectSegmentValue(fallbackSegments, startMs, endMs)
+      if (primaryValue <= 0.0 && fallbackValue <= 0.0) {
+        continue
+      }
+
+      if (primaryValue <= 0.0 && fallbackValue > 0.0) {
+        fallbackUsedSegments += 1
+        merged.add(
+                HealthConnectModuleInternals.NormalizedSegment(
+                        startMs = startMs,
+                        endMs = endMs,
+                        value = fallbackValue,
+                        sourceType = HealthConnectInternalsConstants.SOURCE_FALLBACK,
+                        packageName = HealthConnectInternalsConstants.PACKAGE_FALLBACK_TOTAL_MINUS_BASAL,
+                        deviceModel = ""
+                )
+        )
+        continue
+      }
+
+      if (primaryValue > 0.0) {
+        val representative = resolveProjectedSegmentRepresentative(primarySegments, startMs, endMs)
+        merged.add(
+                HealthConnectModuleInternals.NormalizedSegment(
+                        startMs = startMs,
+                        endMs = endMs,
+                        value = primaryValue,
+                        sourceType =
+                                representative?.sourceType
+                                        ?: HealthConnectInternalsConstants.SOURCE_UNKNOWN,
+                        packageName = representative?.packageName.orEmpty(),
+                        deviceModel = representative?.deviceModel.orEmpty()
+                )
+        )
+      }
+    }
+
+    return FillFallbackResult(segments = merged, fallbackUsedSegments = fallbackUsedSegments)
+  }
+
+  private fun resolveProjectedSegmentRepresentative(
+          segments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          startMs: Long,
+          endMs: Long
+  ): ProjectedSegmentRepresentative? {
+    return segments
+            .asSequence()
+            .mapNotNull { segment ->
+              val overlapStart = maxOf(startMs, segment.startMs)
+              val overlapEnd = minOf(endMs, segment.endMs)
+              if (overlapEnd <= overlapStart) {
+                return@mapNotNull null
+              }
+              val segmentDuration = (segment.endMs - segment.startMs).toDouble()
+              if (segmentDuration <= 0.0) {
+                return@mapNotNull null
+              }
+              val overlapDuration = (overlapEnd - overlapStart).toDouble()
+              val projectedValue = segment.value * (overlapDuration / segmentDuration)
+              if (projectedValue <= 0.0) {
+                return@mapNotNull null
+              }
+              WeightedSegmentProjection(segment, projectedValue)
+            }
+            .sortedWith(
+                    compareByDescending<WeightedSegmentProjection> { it.projectedValue }
+                            .thenByDescending {
+                              HealthConnectSourceTrust.resolveSourcePriority(it.segment.sourceType)
+                            }
+                            .thenBy { it.segment.packageName }
+                            .thenBy { it.segment.startMs }
+                            .thenBy { it.segment.endMs }
+            )
+            .firstOrNull()
+            ?.let { projection ->
+              ProjectedSegmentRepresentative(
+                      sourceType = projection.segment.sourceType,
+                      packageName = projection.segment.packageName,
+                      deviceModel = projection.segment.deviceModel
+              )
+            }
+  }
+
+  private fun projectSegmentValue(
+          segments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          startMs: Long,
+          endMs: Long
+  ): Double {
+    if (segments.isEmpty() || endMs <= startMs) {
+      return 0.0
+    }
+
+    var total = 0.0
+    segments.forEach { segment ->
+      val overlapStart = maxOf(startMs, segment.startMs)
+      val overlapEnd = minOf(endMs, segment.endMs)
+      if (overlapEnd <= overlapStart) {
+        return@forEach
+      }
+
+      val segmentDuration = (segment.endMs - segment.startMs).toDouble()
+      if (segmentDuration <= 0.0) {
+        return@forEach
+      }
+
+      val overlapDuration = (overlapEnd - overlapStart).toDouble()
+      total += segment.value * (overlapDuration / segmentDuration)
+    }
+
+    return total
+  }
+
+  private fun hasCoverage(
+          segments: List<HealthConnectModuleInternals.NormalizedSegment>,
+          startMs: Long,
+          endMs: Long
+  ): Boolean {
+    return segments.any { segment -> minOf(endMs, segment.endMs) > maxOf(startMs, segment.startMs) }
+  }
+}

package/android/src/main/java/com/carivaexercisesdk/domain/exercise/services/HealthConnectInternalsConstants.kt

@@ -0,0 +1,55 @@
+package com.carivaexercisesdk.domain.exercise.services
+
+internal object HealthConnectInternalsConstants {
+  const val SUPPORTED_HOURLY = "hourly"
+  const val SUPPORTED_DAILY = "daily"
+
+  const val SCOPE_STEPS = "steps"
+  const val SCOPE_ACTIVE_TIMES = "activetimes"
+  const val SCOPE_CALORIES = "calories"
+  const val SCOPE_DISTANCES = "distances"
+
+  const val SOURCE_MANUAL_INPUT = "manual_input"
+  const val SOURCE_DEVICE = "device"
+  const val SOURCE_APP = "app"
+  const val SOURCE_UNKNOWN = "unknown"
+  const val SOURCE_FALLBACK = "fallback"
+
+  const val PACKAGE_FALLBACK_TOTAL_MINUS_BASAL = "fallback_total_minus_basal"
+
+  const val OVERLAP_STRATEGY_SOURCE_PRIORITY = "source_priority"
+  const val OVERLAP_STRATEGY_PROPORTIONAL = "proportional"
+
+  const val WARNING_CALORIES_FALLBACK_USED = "calories_fallback_total_minus_basal_used"
+  const val WARNING_CALORIES_FALLBACK_ONLY_USED = "calories_fallback_only_used"
+  const val WARNING_CALORIES_FALLBACK_PARTIAL_USED = "calories_fallback_partial_used"
+  const val WARNING_BMR_SEED_FROM_LATEST_BEFORE_SINCE_USED =
+          "bmr_seed_from_latest_before_since_used"
+  const val WARNING_BMR_MISSING_FOR_FALLBACK_WINDOW = "bmr_missing_for_fallback_window"
+  const val WARNING_FALLBACK_SUPPRESSED_DUE_TO_MISSING_BASAL =
+          "fallback_suppressed_due_to_missing_basal"
+  const val WARNING_FALLBACK_SUPPRESSED_DUE_TO_IDLE_WINDOW =
+          "fallback_suppressed_due_to_idle_window"
+  const val WARNING_UNKNOWN_SOURCE_TYPE = "unknown_source_type_detected"
+
+  const val TRUST_REASON_ALLOWED = "allowed"
+  const val TRUST_REASON_MANUAL_WITH_DEVICE_LOW_CONFIDENCE =
+          "manual_with_device_low_confidence"
+  const val TRUST_REASON_UNKNOWN_WITH_DEVICE_LOW_CONFIDENCE =
+          "unknown_with_device_low_confidence"
+  const val TRUST_REASON_MANUAL_INPUT = "manual_input"
+  const val TRUST_REASON_UNKNOWN_WITHOUT_DEVICE = "unknown_without_device"
+  const val TRUST_REASON_MALFORMED_METADATA = "malformed_metadata"
+
+  const val TRUST_LEVEL_TRUSTED = "trusted"
+  const val TRUST_LEVEL_LOW_CONFIDENCE = "low_confidence"
+  const val TRUST_LEVEL_REJECTED = "rejected"
+
+  val SOURCE_PRIORITY =
+          mapOf(
+                  SOURCE_DEVICE to 4,
+                  SOURCE_APP to 3,
+                  SOURCE_UNKNOWN to 2,
+                  SOURCE_MANUAL_INPUT to 1
+          )
+}