saksham2001 · ak710 · Aug 2, 2026
@@ -93,9 +93,10 @@ enum CoachContextBuilder {
                 deepMin: s.deepMinutes,
                 lightMin: s.lightMinutes,
                 awakeMin: s.awakeMinutes,
+                remMin: s.hasRemSignal ? s.remMinutes : nil,
                 score: s.session.score,
                 confidence: "medium",
-                decoderNote: DataQualityAnalyzer.sleepDecoderNote
+                decoderNote: DataQualityAnalyzer.sleepDecoderNote(hasREM: s.hasRemSignal)
             )
         }
 
@@ -104,6 +105,7 @@ enum CoachContextBuilder {
                 profileCompleteness: completeness,
                 daysAvailable: daysAvailable,
                 hasSleep: sleep != nil,
+                sleepHasREM: summary.sleep?.hasRemSignal ?? false,
                 lastSyncAt: device?.lastSyncAt,
                 isDemo: summary.isDemo
             ),

@@ -95,6 +95,9 @@ struct CoachContextPacket: Encodable {
         var deepMin: Int
         var lightMin: Int
         var awakeMin: Int
+        /// Omitted entirely when the ring that recorded this night reported no REM stage, so the
+        /// model sees "this field is absent" rather than "REM was zero minutes".
+        var remMin: Int?
         var score: Int?
         var confidence: String
         var decoderNote: String

@@ -37,7 +37,7 @@ enum CoachPromptBuilder {
 
     Data limitations:
     - The app may currently have only a few days of real data.
-    - Sleep stage decoding is experimental and may only contain light/deep/awake, not REM; awake time may read as zero.
+    - Sleep stages come from the ring's firmware, not a validated classifier. Which stages exist depends on the ring: some report REM, others only light/deep/awake. Trust the stage fields actually present in the data rather than assuming REM is missing; awake time may read as zero.
     - If there is no age/profile, do not calculate personalized HR zones. If no weight, do not calculate BMI or weight-loss calorie targets.
     - Some readings are wellness-grade, not medical-grade.
 

@@ -3,13 +3,34 @@ import Foundation
 /// Builds the first-class data-quality warnings that ride in the context packet,
 /// keeping the spirit of the web app's warnings so the coach never over-claims.
 enum DataQualityAnalyzer {
-    static let sleepDecoderNote =
-        "Sleep stage decoding is experimental — light/deep/awake only, no REM; awake time may read as zero."
+    /// The caveat for a night whose ring reported **no** REM stage — jring's `0x11` timeline is
+    /// light/deep/awake only.
+    static let sleepDecoderNoteWithoutREM =
+        "Sleep stage decoding is experimental — this ring reports light/deep/awake only, with no REM; "
+        + "awake time may read as zero."
+
+    /// The caveat for a night that **does** carry REM (Colmi big-data stage `0x04`, YCBT tag `3`).
+    /// Still hedged — the staging is the ring firmware's, not a validated sleep-lab classifier — but it
+    /// no longer denies data the app actually has.
+    static let sleepDecoderNoteWithREM =
+        "Sleep stages come from the ring's own firmware, not a validated classifier — treat the split as "
+        + "approximate; awake time may read as zero."
+
+    /// Picks the caveat that matches what this night actually contains.
+    ///
+    /// Keyed off the night's own stage blocks rather than the connected ring's capabilities: stored
+    /// nights outlive the ring that recorded them, so a user who switches rings must not have older
+    /// REM data disclaimed away (or newer REM data denied) by whatever happens to be paired today.
+    static func sleepDecoderNote(hasREM: Bool) -> String {
+        hasREM ? sleepDecoderNoteWithREM : sleepDecoderNoteWithoutREM
+    }
 
     struct Inputs {
         var profileCompleteness: String       // empty | partial | complete
         var daysAvailable: Int
         var hasSleep: Bool
+        /// Whether the night behind `hasSleep` carried a REM stage. Ignored when `hasSleep` is false.
+        var sleepHasREM: Bool = false
         var lastSyncAt: Date?
         var isDemo: Bool
     }
@@ -36,7 +57,7 @@ enum DataQualityAnalyzer {
         }
 
         if input.hasSleep {
-            out.append(sleepDecoderNote)
+            out.append(sleepDecoderNote(hasREM: input.sleepHasREM))
         }
 
         if !input.isDemo {

@@ -103,13 +103,17 @@ enum CoachSummaryContextBuilder {
         struct Packet: Encodable {
             let range: String, nightsTracked: Int, expectedNights: Int
             let avgTotalMin: Int?, avgScore: Int?
-            let avgDeepMin: Int?, avgLightMin: Int?, avgAwakeMin: Int?, goalMin: Int?
+            let avgDeepMin: Int?, avgLightMin: Int?, avgAwakeMin: Int?
+            /// Absent when no night in the range reported REM — see `SleepInsights.AverageStages.rem`.
+            let avgRemMin: Int?
+            let goalMin: Int?
             let memories: [CoachContextPacket.MemoryContext]
         }
         let p = Packet(
             range: range.rawValue, nightsTracked: valid.count, expectedNights: summary.expectedNights,
             avgTotalMin: avgMin, avgScore: avgScore,
             avgDeepMin: stages?.deep, avgLightMin: stages?.light, avgAwakeMin: stages?.awake,
+            avgRemMin: stages?.rem,
             goalMin: goalMin, memories: memories
         )
         let sig = signature([

@@ -65,10 +65,18 @@ enum RetrievalTools {
             result["hr"] = encodeStats(CoachDataAccess.stats(hr))
             result["spo2"] = encodeStats(CoachDataAccess.stats(spo2))
             if let sleep {
-                result["sleep"] = [
+                // Resolve the stage split so the note reflects what this night actually holds
+                // instead of asserting REM is missing on rings that do report it.
+                let staged = SleepService.summary(for: sleep, context: ctx.modelContext)
+                var payload: [String: Any] = [
                     "total_min": sleep.totalMinutes, "score": sleep.score as Any,
-                    "confidence": "medium", "note": "experimental decoder (no REM)",
+                    "deep_min": staged.deepMinutes, "light_min": staged.lightMinutes,
+                    "awake_min": staged.awakeMinutes,
+                    "confidence": "medium",
+                    "note": DataQualityAnalyzer.sleepDecoderNote(hasREM: staged.hasRemSignal),
                 ]
+                if staged.hasRemSignal { payload["rem_min"] = staged.remMinutes }
+                result["sleep"] = payload
             }
             return .object(result)
         }
@@ -286,8 +294,14 @@ enum RetrievalTools {
                 "nights_tracked": valid.count,
                 "avg_total_min": SleepInsights.averageDuration(valid) as Any,
                 "avg_score": SleepInsights.averageScore(valid) as Any,
-                "avg_stages_min": stages.map { ["deep": $0.deep, "light": $0.light, "awake": $0.awake] } as Any,
-                "note": DataQualityAnalyzer.sleepDecoderNote,
+                "avg_stages_min": stages.map { s -> [String: Int] in
+                    var out = ["deep": s.deep, "light": s.light, "awake": s.awake]
+                    // Present only when some night in the range actually reported REM, so an absent
+                    // key means "this ring can't see REM", never "you slept none".
+                    if let rem = s.rem { out["rem"] = rem }
+                    return out
+                } as Any,
+                "note": DataQualityAnalyzer.sleepDecoderNote(hasREM: stages?.rem != nil),
             ])
         }
     }

@@ -418,12 +418,27 @@ struct SleepStageSummaryCardsView: View {
     let deep: String
     let light: String
     let awake: String
+    /// REM, when the ring behind this night reported the stage at all. `nil` omits the card
+    /// entirely rather than showing a dash — a jring genuinely has no REM stage, and an empty
+    /// fourth card reads as missing data instead of an absent sensor.
+    var rem: String?
 
     var body: some View {
-        HStack(spacing: 12) {
-            stat("\(prefix)Deep", deep, SleepStageColors.deep)
-            stat("\(prefix)Light", light, SleepStageColors.light)
-            stat("\(prefix)Awake", awake, SleepStageColors.awake)
+        // Four cards across is too cramped on a small phone, so REM promotes the row to a 2×2
+        // grid; without it the original three-across row is unchanged.
+        if let rem {
+            LazyVGrid(columns: [GridItem(.flexible(), spacing: 12), GridItem(.flexible(), spacing: 12)], spacing: 12) {
+                stat("\(prefix)Deep", deep, SleepStageColors.deep)
+                stat("\(prefix)REM", rem, SleepStageColors.rem)
+                stat("\(prefix)Light", light, SleepStageColors.light)
+                stat("\(prefix)Awake", awake, SleepStageColors.awake)
+            }
+        } else {
+            HStack(spacing: 12) {
+                stat("\(prefix)Deep", deep, SleepStageColors.deep)
+                stat("\(prefix)Light", light, SleepStageColors.light)
+                stat("\(prefix)Awake", awake, SleepStageColors.awake)
+            }
         }
     }
 

@@ -91,9 +91,10 @@ enum SeedData {
             let light = blocks.filter { $0.stage == .light }.reduce(0) { $0 + $1.durationMinutes }
             let deep = blocks.filter { $0.stage == .deep }.reduce(0) { $0 + $1.durationMinutes }
             let awake = blocks.filter { $0.stage == .awake }.reduce(0) { $0 + $1.durationMinutes }
+            let rem = blocks.filter { $0.stage == .rem }.reduce(0) { $0 + $1.durationMinutes }
             let summary = SleepSummary(
                 session: SleepSession(date: dayDate, startAt: startAt, endAt: wake, totalMinutes: totalMin),
-                lightMinutes: light, deepMinutes: deep, awakeMinutes: awake, blocks: blocks
+                lightMinutes: light, deepMinutes: deep, awakeMinutes: awake, remMinutes: rem, blocks: blocks
             )
             let score = SleepScore.calculate(summary)
             let session = SleepSession(date: dayDate, startAt: startAt, endAt: wake, totalMinutes: totalMin, score: score.score, syncedAt: wake)
@@ -111,9 +112,10 @@ enum SeedData {
                 let napLight = napBlocks.filter { $0.stage == .light }.reduce(0) { $0 + $1.durationMinutes }
                 let napDeep = napBlocks.filter { $0.stage == .deep }.reduce(0) { $0 + $1.durationMinutes }
                 let napAwake = napBlocks.filter { $0.stage == .awake }.reduce(0) { $0 + $1.durationMinutes }
+                let napRem = napBlocks.filter { $0.stage == .rem }.reduce(0) { $0 + $1.durationMinutes }
                 let napSummary = SleepSummary(
                     session: SleepSession(date: dayDate, startAt: napStart, endAt: napEnd, totalMinutes: nap.minutes),
-                    lightMinutes: napLight, deepMinutes: napDeep, awakeMinutes: napAwake, blocks: napBlocks
+                    lightMinutes: napLight, deepMinutes: napDeep, awakeMinutes: napAwake, remMinutes: napRem, blocks: napBlocks
                 )
                 let napScore = SleepScore.calculate(napSummary)
                 let napSession = SleepSession(date: dayDate, startAt: napStart, endAt: napEnd, totalMinutes: nap.minutes, score: napScore.score, syncedAt: napEnd)

@@ -135,7 +135,20 @@ struct SleepSummary {
     let lightMinutes: Int
     let deepMinutes: Int
     let awakeMinutes: Int
+    /// Minutes the ring tagged as REM. Zero on rings whose firmware has no REM stage (jring's
+    /// `0x11` timeline is light/deep/awake only), so a zero here is genuinely ambiguous between
+    /// "no REM slept" and "this ring can't see REM" — use `hasRemSignal` to tell them apart.
+    let remMinutes: Int
     let blocks: [SleepStageBlock]
+
+    /// Whether this night's own stage timeline carries REM at all.
+    ///
+    /// Deliberately derived from the night's blocks rather than the *connected* ring's
+    /// capabilities: stored nights outlive the ring that recorded them, so a user who switches
+    /// from a Colmi to a jring must not have last week's REM retro-actively disclaimed away.
+    var hasRemSignal: Bool {
+        remMinutes > 0 || blocks.contains { $0.stage == .rem }
+    }
 }
 
 struct SleepRangeSummary {

@@ -632,11 +632,13 @@ enum SleepService {
         let light = blocks.filter { $0.stage == .light }.reduce(0) { $0 + $1.durationMinutes }
         let deep = blocks.filter { $0.stage == .deep }.reduce(0) { $0 + $1.durationMinutes }
         let awake = blocks.filter { $0.stage == .awake }.reduce(0) { $0 + $1.durationMinutes }
+        let rem = blocks.filter { $0.stage == .rem }.reduce(0) { $0 + $1.durationMinutes }
         return SleepSummary(
             session: session,
             lightMinutes: light,
             deepMinutes: deep,
             awakeMinutes: awake,
+            remMinutes: rem,
             blocks: includeStages ? blocks : []
         )
     }

@@ -23,6 +23,9 @@ struct SleepScoreResult {
     let lightPct: Int
     /// nil when there is no usable awake signal.
     let awakePct: Int?
+    /// nil on a night whose ring reported no REM stage at all — distinct from `0`, which would
+    /// claim the user slept no REM. Not yet a scoring contributor (see `calculate`).
+    let remPct: Int?
 }
 
 enum SleepScore {
@@ -65,15 +68,32 @@ enum SleepScore {
         return .needsWork
     }
 
+    /// Scores a night out of 100 from duration (35), deep % (30), light % (20) and awake % (15).
+    ///
+    /// **REM is measured but not yet scored.** `remPct` is reported so the coach and the UI can
+    /// show it, but no points ride on it, and the light-sleep band (ideal 50–60%) still carries
+    /// the weight of a no-REM decoder — where REM minutes land in the light bucket. On a
+    /// REM-capable ring those minutes are tagged separately, so light % reads roughly 20 points
+    /// lower for the same night and the band scores it slightly harsher than it should.
+    ///
+    /// Re-weighting the score is deliberately out of scope here: changing the bands changes every
+    /// stored night's score, which needs the versioned recompute that `ReadinessDaily` does for
+    /// readiness. Tracked as the sleep-score v2 rework; this pass only stops REM being dropped on
+    /// the floor entirely.
     static func calculate(_ sleep: SleepSummary) -> SleepScoreResult {
         let total = sleep.session.totalMinutes > 0 ? Double(sleep.session.totalMinutes) : 0
         let deep = Double(max(0, sleep.deepMinutes))
         let light = Double(max(0, sleep.lightMinutes))
         let awake = Double(max(0, sleep.awakeMinutes))
+        // REM belongs in the coverage sum. This clause asks "did the timeline account for
+        // essentially the whole night?", and on a REM-capable ring (Colmi big-data stage `0x04`,
+        // YCBT tag `3`) REM is typically 20–25% of it — omitting it made a fully-described night
+        // look 75% covered, which failed the 0.95 gate below and cost the night its awake
+        // sub-score. jring rings, whose `0x11` timeline has no REM stage, are unaffected.
         let coveredStageMin = sleep.blocks.reduce(0.0) { sum, block in
             switch block.stage {
-            case .deep, .light, .awake: return sum + Double(max(0, block.durationMinutes))
-            default: return sum
+            case .deep, .light, .awake, .rem: return sum + Double(max(0, block.durationMinutes))
+            case .unknown: return sum
             }
         }
         let hasAwakeSignal =
@@ -85,6 +105,9 @@ enum SleepScore {
         let deepPct = total > 0 ? (deep / total) * 100 : 0
         let lightPct = total > 0 ? (light / total) * 100 : 0
         let awakePct: Double? = (total > 0 && hasAwakeSignal) ? (awake / total) * 100 : nil
+        let remPct: Double? = (total > 0 && sleep.hasRemSignal)
+            ? (Double(max(0, sleep.remMinutes)) / total) * 100
+            : nil
 
         let duration = bandScore(totalHours, idealLow: 7.5, idealHigh: 8.5, softLow: 6, softHigh: 9.5, hardLow: 3, hardHigh: 12, points: 35)
         let deepScore = bandScore(deepPct, idealLow: 13, idealHigh: 23, softLow: 5, softHigh: 35, hardLow: 0, hardHigh: 45, points: 30)
@@ -97,7 +120,8 @@ enum SleepScore {
             label: qualityLabel(score),
             deepPct: Int(deepPct.rounded()),
             lightPct: Int(lightPct.rounded()),
-            awakePct: awakePct.map { Int($0.rounded()) }
+            awakePct: awakePct.map { Int($0.rounded()) },
+            remPct: remPct.map { Int($0.rounded()) }
         )
     }
 }
@@ -177,6 +201,7 @@ enum SleepInsights {
             let lightMinutes = daySessions.reduce(0) { $0 + $1.lightMinutes }
             let deepMinutes = daySessions.reduce(0) { $0 + $1.deepMinutes }
             let awakeMinutes = daySessions.reduce(0) { $0 + $1.awakeMinutes }
+            let remMinutes = daySessions.reduce(0) { $0 + $1.remMinutes }
             let blocks = daySessions.flatMap { $0.blocks }.sorted { $0.startAt < $1.startAt }
 
             let totalMinutes = daySessions.reduce(0) { $0 + $1.session.totalMinutes }
@@ -213,6 +238,7 @@ enum SleepInsights {
                 lightMinutes: lightMinutes,
                 deepMinutes: deepMinutes,
                 awakeMinutes: awakeMinutes,
+                remMinutes: remMinutes,
                 blocks: blocks
             ))
         }
@@ -233,13 +259,30 @@ enum SleepInsights {
         return Int((Double(total) / Double(valid.count)).rounded())
     }
 
-    static func averageStages(_ valid: [SleepSummary]) -> (deep: Int, light: Int, awake: Int)? {
+    /// Mean minutes per stage across the valid nights of a range.
+    ///
+    /// A struct rather than a tuple because adding REM makes it four members, which trips
+    /// SwiftLint's `large_tuple` — the same refactor the rest of this codebase already made.
+    struct AverageStages: Equatable {
+        let deep: Int
+        let light: Int
+        let awake: Int
+        /// nil when **no** night in the range carried a REM stage, so the caller can omit the field
+        /// rather than report an average of zero the ring never measured. Nights that do report REM
+        /// are averaged over the whole range, matching how the other three stages are treated.
+        let rem: Int?
+    }
+
+    static func averageStages(_ valid: [SleepSummary]) -> AverageStages? {
         let valid = collapseByDay(valid)
         guard !valid.isEmpty else { return nil }
         let deep = valid.reduce(0) { $0 + $1.deepMinutes } / valid.count
         let light = valid.reduce(0) { $0 + $1.lightMinutes } / valid.count
         let awake = valid.reduce(0) { $0 + $1.awakeMinutes } / valid.count
-        return (deep, light, awake)
+        let rem = valid.contains { $0.hasRemSignal }
+            ? valid.reduce(0) { $0 + $1.remMinutes } / valid.count
+            : nil
+        return AverageStages(deep: deep, light: light, awake: awake, rem: rem)
     }
 
     /// Population standard deviation of nightly durations (minutes).

@@ -150,7 +150,8 @@ struct SleepView: View {
         SleepStageSummaryCardsView(
             deep: SleepFormat.duration(s.deepMinutes),
             light: SleepFormat.duration(s.lightMinutes),
-            awake: SleepFormat.duration(s.awakeMinutes)
+            awake: SleepFormat.duration(s.awakeMinutes),
+            rem: s.hasRemSignal ? SleepFormat.duration(s.remMinutes) : nil
         )
     }
 
@@ -440,7 +441,8 @@ struct SleepView: View {
             prefix: "Avg ",
             deep: stageAvg.map { SleepFormat.duration($0.deep) } ?? "—",
             light: stageAvg.map { SleepFormat.duration($0.light) } ?? "—",
-            awake: stageAvg.map { SleepFormat.duration($0.awake) } ?? "—"
+            awake: stageAvg.map { SleepFormat.duration($0.awake) } ?? "—",
+            rem: stageAvg?.rem.map { SleepFormat.duration($0) }
         )
         summaryCard(rangeSummary(range), fallback: coach)
     }