Export confirmed naps to Apple Health (iOS) as daytime sleep segments + 3 h nap cap

.coderabbit.yaml

@@ -25,3 +25,5 @@ reviews:
     # and they are the least likely place for a shipped bug. Re-include them
     # for a PR that is mostly test work.
     - "!test/**"
+  auto_review:
+    drafts: true

ios/Runner/HealthKitSleepWriter.swift

@@ -15,58 +15,156 @@ enum HealthKitSleepWriter {
   private static let channelName = "openstrap/healthkit_sleep"
   private static let store = HKHealthStore()
   private static let queue = DispatchQueue(label: "wtf.openstrap.healthkit.sleep")
+  // Nap calls carry a monotonic `seq` from Dart. A native call that outlives
+  // its Dart-side timeout can still land later; dropping any nap call whose
+  // seq is not newer than the last applied one keeps a late replaceNap from
+  // overwriting a newer deleteNapRange for the same window. Guarded by queue.
+  private static var lastNapSeq = 0
 
   static func register(messenger: FlutterBinaryMessenger) {
     let channel = FlutterMethodChannel(name: channelName, binaryMessenger: messenger)
     channel.setMethodCallHandler { call, result in
-      guard call.method == "replaceSleepSession" else {
+      guard call.method == "replaceSleepSession"
+          || call.method == "replaceNap"
+          || call.method == "deleteNapRange" else {
         result(FlutterMethodNotImplemented)
         return
       }
       let args = call.arguments as? [String: Any] ?? [:]
       queue.async {
-        replace(args) { ok in
-          DispatchQueue.main.async { result(ok) }
+        switch call.method {
+        case "replaceNap":
+          replaceNap(args) { ok in
+            DispatchQueue.main.async { result(ok) }
+          }
+        case "deleteNapRange":
+          deleteRange(args) { ok in
+            DispatchQueue.main.async { result(ok) }
+          }
+        default:
+          replace(args) { ok in
+            DispatchQueue.main.async { result(ok) }
+          }
         }
       }
     }
   }
 
-  private static func replace(_ args: [String: Any], completion: @escaping (Bool) -> Void) {
+  // A confirmed nap: delete OUR overlapping sleepAnalysis samples in the nap
+  // window, then write one inBed envelope plus one asleep sample. HealthKit
+  // has no nap value (HKCategoryValueSleepAnalysis offers no nap case), so the
+  // nap appears in Apple Health as an ordinary daytime sleep segment — never
+  // labelled as a nap. No stage samples: a nap has no hypnogram, and writing
+  // asleepCore/Deep/REM would fabricate stages. The cleanup window is the nap
+  // window itself, NOT the noon-to-noon night window — it must never touch
+  // the exported main sleep.
+  private static func replaceNap(_ args: [String: Any], completion: @escaping (Bool) -> Void) {
+    guard let seq = napSeq(args) else {
+      completion(false)
+      return
+    }
+    if staleNapCallDropped(seq, completion: completion) { return }
     guard HKHealthStore.isHealthDataAvailable() else {
       completion(true) // iPad / simulator: no store, not an export failure
       return
     }
-    guard let sleepType = HKObjectType.categoryType(forIdentifier: .sleepAnalysis) else {
+    guard let sleepType = HKObjectType.categoryType(forIdentifier: .sleepAnalysis),
+          let start = dateMs(args["startTime"]),
+          let end = dateMs(args["endTime"]),
+          start < end else {
       completion(false)
       return
     }
-    guard let cleanupStart = dateMs(args["cleanupStartTime"]),
-          let cleanupEnd = dateMs(args["cleanupEndTime"]),
-          cleanupStart < cleanupEnd else {
+    let asleepValue: HKCategoryValueSleepAnalysis
+    if #available(iOS 16.0, *) {
+      asleepValue = .asleepUnspecified
+    } else {
+      asleepValue = .asleep // deprecated pre-16 name for asleepUnspecified
+    }
+    let samples: [HKCategorySample] = [
+      HKCategorySample(type: sleepType, value: HKCategoryValueSleepAnalysis.inBed.rawValue, start: start, end: end),
+      HKCategorySample(type: sleepType, value: asleepValue.rawValue, start: start, end: end),
+    ]
+    deleteAndSave(samples: samples, type: sleepType, cleanupStart: start, cleanupEnd: end, seq: napSeq(args), completion: completion)
+  }
+
+  // A nap removed/rejected in Edge: delete OUR sleepAnalysis samples
+  // overlapping the window so the export does not outlive the decision.
+  // `protectWindows` (list of {startMs, endMs}) marks the CURRENT main-sleep
+  // windows: if a night shifted onto a previously exported nap, samples
+  // overlapping any of those windows are kept — deleting them would remove
+  // the user's night from Apple Health. Each window is protected separately;
+  // a union span would also cover a nap lying BETWEEN two nights and the
+  // delete would silently keep everything.
+  private static func deleteRange(_ args: [String: Any], completion: @escaping (Bool) -> Void) {
+    guard let seq = napSeq(args) else {
       completion(false)
       return
     }
-
-    let samples: [HKCategorySample]
-    do {
-      samples = try buildSamples(args, type: sleepType)
-    } catch {
+    if staleNapCallDropped(seq, completion: completion) { return }
+    guard HKHealthStore.isHealthDataAvailable() else {
+      completion(true)
+      return
+    }
+    guard let sleepType = HKObjectType.categoryType(forIdentifier: .sleepAnalysis),
+          let start = dateMs(args["startTime"]),
+          let end = dateMs(args["endTime"]),
+          start < end else {
       completion(false)
       return
     }
+    var protect: [(Date, Date)] = []
+    for raw in (args["protectWindows"] as? [Any] ?? []) {
+      if let m = raw as? [String: Any],
+         let ps = dateMs(m["startMs"]),
+         let pe = dateMs(m["endMs"]), ps < pe {
+        protect.append((ps, pe))
+      }
+    }
+    deleteRange(samples: [], type: sleepType, start: start, end: end,
+                protect: protect, seq: seq, completion: completion)
+  }
 
-    let datePred = HKQuery.predicateForSamples(
-      withStart: cleanupStart, end: cleanupEnd, options: []
-    )
+  private static func napSeq(_ args: [String: Any]) -> Int? {
+    (args["seq"] as? NSNumber)?.intValue
+  }
+
+  // Runs on `queue`. Returns true when the call is stale and was dropped
+  // (completed with false — a dropped call never claims success).
+  private static func staleNapCallDropped(_ seq: Int, completion: @escaping (Bool) -> Void) -> Bool {
+    if seq <= lastNapSeq {
+      completion(false)
+      return true
+    }
+    lastNapSeq = seq
+    return false
+  }
+
+  // Delete-then-save. [seq] (nap calls only) is re-checked in the delete's
+  // completion callback: a newer nap call that started while this delete was
+  // in flight has already bumped lastNapSeq, so this call must NOT save its
+  // samples afterwards — otherwise a removed nap reappears after the newer
+  // deletion. Nil seq (replaceSleepSession) skips the re-check.
+  private static func deleteAndSave(
+    samples: [HKCategorySample],
+    type: HKCategoryType,
+    cleanupStart: Date,
+    cleanupEnd: Date,
+    seq: Int?,
+    completion: @escaping (Bool) -> Void
+  ) {
+    let datePred = HKQuery.predicateForSamples(withStart: cleanupStart, end: cleanupEnd, options: [])
     let sourcePred = HKQuery.predicateForObjects(from: HKSource.default())
     let pred = NSCompoundPredicate(andPredicateWithSubpredicates: [datePred, sourcePred])
-
-    store.deleteObjects(of: sleepType, predicate: pred) { _, _, error in
+    store.deleteObjects(of: type, predicate: pred) { _, _, error in
       if error != nil {
         completion(false)
         return
       }
+      if let seq, seq != lastNapSeq {
+        completion(false) // superseded while the delete was in flight
+        return
+      }
       guard !samples.isEmpty else {
         completion(true)
         return
@@ -77,6 +175,80 @@ enum HealthKitSleepWriter {
     }
   }
 
+  // Delete OUR sleepAnalysis samples overlapping [start, end), except those
+  // overlapping [protectStart, protectEnd) (the current main-sleep window) —
+  // a night that shifted onto a previously exported nap must not be deleted
+  // with it. The seq re-check happens before the delete lands.
+  private static func deleteRange(
+    samples: [HKCategorySample],
+    type: HKCategoryType,
+    start: Date,
+    end: Date,
+    protect: [(Date, Date)],
+    seq: Int,
+    completion: @escaping (Bool) -> Void
+  ) {
+    let datePred = HKQuery.predicateForSamples(withStart: start, end: end, options: [])
+    let sourcePred = HKQuery.predicateForObjects(from: HKSource.default())
+    let pred = NSCompoundPredicate(andPredicateWithSubpredicates: [datePred, sourcePred])
+    let query = HKSampleQuery(sampleType: type, predicate: pred, limit: HKObjectQueryNoLimit, sortDescriptors: nil) { _, results, error in
+      guard let found = results as? [HKCategorySample], error == nil else {
+        completion(false)
+        return
+      }
+      if seq != lastNapSeq {
+        completion(false) // superseded while the query was in flight
+        return
+      }
+      // Samples overlapping ANY protected main-sleep window are kept.
+      let doomed = found.filter { s in
+        !protect.contains { ps, pe in s.startDate < pe && s.endDate > ps }
+      }
+      guard !doomed.isEmpty else {
+        completion(true)
+        return
+      }
+      store.delete(doomed) { success, error in
+        completion(success && error == nil)
+      }
+    }
+    store.execute(query)
+  }
+
+  private static func replace(_ args: [String: Any], completion: @escaping (Bool) -> Void) {
+    guard HKHealthStore.isHealthDataAvailable() else {
+      completion(true) // iPad / simulator: no store, not an export failure
+      return
+    }
+    guard let sleepType = HKObjectType.categoryType(forIdentifier: .sleepAnalysis) else {
+      completion(false)
+      return
+    }
+    guard let cleanupStart = dateMs(args["cleanupStartTime"]),
+          let cleanupEnd = dateMs(args["cleanupEndTime"]),
+          cleanupStart < cleanupEnd else {
+      completion(false)
+      return
+    }
+
+    let samples: [HKCategorySample]
+    do {
+      samples = try buildSamples(args, type: sleepType)
+    } catch {
+      completion(false)
+      return
+    }
+
+    deleteAndSave(
+      samples: samples,
+      type: sleepType,
+      cleanupStart: cleanupStart,
+      cleanupEnd: cleanupEnd,
+      seq: nil, // sleep sessions carry no seq — unchanged behavior
+      completion: completion
+    )
+  }
+
   private static func buildSamples(
     _ args: [String: Any],
     type: HKCategoryType

lib/compute/derivation_engine.dart

@@ -1852,7 +1852,12 @@ import 'vendor_sleep.dart';
 // more than the windowed live/phone sources, instead of only when they counted
 // nothing, so a short tracked walk no longer hides the day's chip total.
 // gen4 (no counter) is unchanged. Edge-only.
-const int kAlgoVersion = 120;
+// 120 → 121 (nap cap 3 h): naps are capped at kMaxNapSec on every path —
+// detected bouts via dropOversizedNaps AND stored edits replayed through
+// applyNapEdits — so a pre-cap manual nap longer than 3 h no longer counts
+// into naps/nap_min. Days derived at v120 keep their stale naps without this
+// bump.
+const int kAlgoVersion = 121;
 /// The sibling SHAs this version was derived against, asserted against
 /// pubspec.yaml in test/db_serve_version_and_reads_test.dart.
 ///
@@ -10082,7 +10087,9 @@ class DerivationEngine {
     List<NapEdit> napEdits,
     String note,
   ) {
-    final merged = applyNapEdits(const [], napEdits);
+    // Cap stored edits too: a manual nap logged before the 3 h cap must not
+    // survive a re-derive as a counted nap.
+    final merged = dropOversizedNaps(applyNapEdits(const [], napEdits));
     if (merged.isEmpty) {
       _writeUnknownNaps(bundle, note);
       return null;
@@ -10269,9 +10276,17 @@ class DerivationEngine {
             'confidence': nap.confidence,
           },
       ];
-      candidates?.addAll(detected.where((n) => !napEdits.any((e) =>
+      // A nap longer than kMaxNapSec (3 h) is a sleep, not a nap — drop it
+      // before it can reach the suggestions, `nap_min`, sleep need or the
+      // timeline. Entry-time paths share the same constant via
+      // manualNapWindowIsValid; stored edits are capped again at the merge
+      // below so pre-cap rows cannot survive a re-derive.
+      final capped = dropOversizedNaps(detected);
+      candidates?.addAll(capped.where((n) => !napEdits.any((e) =>
         e.overlaps(n['start'] as int, n['end'] as int))));
-      final merged = applyNapEdits(const [], napEdits);
+      // Cap stored edits too: a manual nap logged before the 3 h cap must not
+    // survive a re-derive as a counted nap.
+    final merged = dropOversizedNaps(applyNapEdits(const [], napEdits));
 
       bundle['naps'] = <String, dynamic>{
         'value': merged,

lib/compute/nap_edits.dart

@@ -54,9 +54,14 @@ typedef NapMap = Map<String, dynamic>;
 /// scatter of two-minute entries would swamp the real ones in every total.
 const int kMinManualNapSec = 5 * 60;
 
-/// Maximum. Anything longer is a sleep, not a nap, and belongs in the main
-/// sleep window where the stager can actually say something about its stages.
-const int kMaxManualNapSec = 6 * 60 * 60;
+/// Maximum length of anything counted as a nap: 3 hours. Anything longer is a
+/// sleep, not a nap, and belongs in the main sleep window where the stager can
+/// actually say something about its stages. Applies to detected AND manually
+/// logged naps alike — one cap, one place.
+const int kMaxNapSec = 3 * 60 * 60;
+
+/// Maximum for a manually logged nap — the same cap as detected naps.
+const int kMaxManualNapSec = kMaxNapSec;
 
 /// Whether a window can be logged as a nap.
 bool manualNapWindowIsValid(int startSec, int endSec) {
@@ -129,6 +134,16 @@ List<NapMap> applyNapEdits(List<NapMap> detected, List<NapEdit> edits) {
   return out;
 }
 
+/// Drops every nap whose window exceeds [kMaxNapSec]. A detected bout longer
+/// than 3 h is a sleep fragment the detector misfiled as a nap; crediting it
+/// into `nap_min` would count a night's sleep as daytime rest. The filter is
+/// pure so the rule is testable without a derivation run.
+List<NapMap> dropOversizedNaps(List<NapMap> naps) => [
+      for (final n in naps)
+        if ((n['end'] as num).toInt() - (n['start'] as num).toInt() <= kMaxNapSec)
+          n,
+    ];
+
 /// Total asleep minutes across [naps] — the `nap_min` scalar.
 ///
 /// Always a number, including 0 for an empty list. The absent-versus-zero

lib/data/activity_store.dart

@@ -177,6 +177,17 @@ class ActivityStore {
         final start = ((c['start_ts'] ?? c['start']) as num).toInt();
         final end = ((c['end_ts'] ?? c['end']) as num).toInt();
         if (end <= start) continue;
+        // A nap candidate over kMaxNapSec (3 h) is a sleep fragment, not a
+        // nap: never offer it for review — retire any pending rows it
+        // overlaps instead of keeping or re-creating them.
+        if (kind == ActivityKind.nap && end - start > kMaxNapSec) {
+          await tx.rawUpdate(
+            "UPDATE activity_suggestions SET status = 'superseded' "
+            "WHERE kind = ? AND status = 'pending' AND start_ts < ? AND end_ts > ?",
+            [kind.name, end, start],
+          );
+          continue;
+        }
         final matches = await tx.query(
           'activity_suggestions',
           where:
@@ -329,6 +340,28 @@ class ActivityStore {
     return false;
   }
 
+  /// The main-sleep windows (epoch ms) of the nights around [s, e) — the
+  /// night ending on [s]'s date and the one beginning that evening. Used to
+  /// PROTECT night samples when a nap window is deleted from the health
+  /// store after the night shifted onto it.
+  static Future<List<({int onsetMs, int offsetMs})>> mainSleepWindowsAround(
+    DatabaseExecutor tx,
+    int s,
+    int e,
+  ) async {
+    final out = <({int onsetMs, int offsetMs})>[];
+    for (final b in await _nightsAround(tx, s, e)) {
+      final w = ((b['sleep'] as Map?)?['window'] as Map?)?['value'];
+      if (w is Map) {
+        final on = w['onset_ms'], off = w['offset_ms'];
+        if (on is num && off is num && off > on) {
+          out.add((onsetMs: on.toInt(), offsetMs: off.toInt()));
+        }
+      }
+    }
+    return out;
+  }
+
   static Future<List<Map>> _nightsAround(
     DatabaseExecutor tx,
     int s,
@@ -465,7 +498,7 @@ class ActivityStore {
     } else {
       if (!manualNapWindowIsValid(startTs, endTs)) {
         throw const ActivityReviewException(
-          'A nap must last between 5 minutes and 6 hours.',
+          'A nap must last between 5 minutes and 3 hours.',
         );
       }
       if (await _overlapsSleep(tx, startTs, endTs)) {