> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Baselines facade

> Typed observable snapshot of the user's wearable-baseline state — latest scores + reference view + recent-scores ring.

## Overview

`Baselines` is the **host-facing read facade** for wearable baselines. Apps subscribe to a reactive snapshot stream and get a fully-typed view of the user's most recent sleep / recovery / readiness scores plus the current [`WearableReferenceView`](/synheart-core/srm#wearablereferenceview); no JSON parsing, no FFI.

It does NOT compute scores or own ingest pipelines — it caches whatever the host SDK feeds in. The full Flutter `Baselines.ingestVendorSleep` orchestration (Whoop / Garmin / Apple Health / Health Connect → score → snapshot) lives only on the Flutter SDK at this time. On Kotlin / Swift, hosts wire vendor ingest themselves and call the `cache*` setters.

## Surface

Process-wide singleton (`Baselines.shared`) with:

| Surface                                                             | Description                                                                                                                       |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `updates`                                                           | Observable stream of `BaselinesSnapshot` — emits after every `cache*` call. Replays the current snapshot to late subscribers.     |
| `latestSleepScore` / `latestRecoveryScore` / `latestReadinessScore` | Sync getters for the most recent score in each pipeline.                                                                          |
| `reference`                                                         | The most recent `WearableReferenceView` from the SRM (see [Self-Reference Model](/synheart-core/srm)).                            |
| `lastSource`                                                        | Provider id of whoever produced the latest sleep score (`whoop`, `garmin`, `apple_health`, `health_connect`, `self_report`, ...). |
| `cacheSleepScore(result, source)`                                   | Push a new sleep score, roll into the recent-scores ring (cap 7), emit.                                                           |
| `cacheRecoveryScore(result)`                                        | Push a new recovery score, emit.                                                                                                  |
| `cacheReadinessScore(result)`                                       | Push a new readiness score, emit.                                                                                                 |
| `cacheReference(view)`                                              | Push a new wearable reference, emit.                                                                                              |
| `reset()`                                                           | Forget everything (logout / user switch).                                                                                         |
| `current()`                                                         | Synchronous snapshot read.                                                                                                        |

## BaselinesSnapshot

```text theme={null}
reference: WearableReferenceView?
latestSleepScore: SleepScoreResult?
latestRecoveryScore: RecoveryScoreResult?
latestReadinessScore: ReadinessScoreResult?
recentSleepScores: [Int]      // recent-scores ring; oldest → newest; cap 7
capturedAtMs: Int64
```

Derived properties (computed without storage):

* `isEmpty` — nothing has been ingested and the engine hasn't produced a reference yet
* `isReady` — true when the reference reports `READY` status, i.e. all five primary SRM dimensions are mature enough for personalized scoring (see [SRM maturity states](/synheart-core/srm#maturity-states)).
* `priorNightCount` — what the scorer saw (nil if no score)
* `nightsLoggedCount` — items in the recent-scores ring (capped at 7)
* `recentMedian` — median of the ring when populated; falls back to `reference.recentSleepScoreMedian`

## Kotlin

```kotlin theme={null}
import ai.synheart.core.modules.baselines.Baselines
import ai.synheart.core.modules.baselines.BaselinesSnapshot

// Subscribe (Flow<BaselinesSnapshot>)
viewModelScope.launch {
    Baselines.shared.updates.collect { snap ->
        snap.latestSleepScore?.let { render(it.score) }
        snap.latestRecoveryScore?.let { render(it.score) }
        snap.latestReadinessScore?.let { render(it.score) }
    }
}

// Push (from your vendor-ingest code)
Baselines.shared.cacheSleepScore(result = sleepScore, source = "whoop")
Baselines.shared.cacheReference(reference = wearableRefView)
```

## Swift

```swift theme={null}
import SynheartCore

var cancellables = Set<AnyCancellable>()

// Subscribe (Combine — CurrentValueSubject, late subs get current snapshot)
Baselines.shared.updates
    .sink { snap in
        if let s = snap.latestSleepScore { render(s.score) }
        if let r = snap.latestRecoveryScore { render(r.score) }
        if let rd = snap.latestReadinessScore { render(rd.score) }
    }
    .store(in: &cancellables)

// Push
Baselines.shared.cacheSleepScore(sleepScore, source: "whoop")
Baselines.shared.cacheReference(wearableRefView)
```

## Recent-scores ring semantics

`cacheSleepScore` pushes the score (if non-nil) onto a FIFO ring capped at 7. This is the "nights logged" surface for the user — it reflects cumulative ingests in the current session, not what the scorer saw (`priorNightCount` gives you that). The median of the ring is available after the 3rd attach, regardless of HSI window state.

## Cross-language parity

The shape is identical across Flutter / Kotlin / Swift. The stream type differs by platform idiom (Dart `Stream`, Kotlin `Flow`, Swift `AnyPublisher`) but the snapshot content is byte-equivalent.

* Flutter: `lib/src/modules/baselines/baselines_snapshot.dart` + (full ingest) `baselines.dart`
* Kotlin: `synheart-core/src/main/kotlin/ai/synheart/core/modules/baselines/{Baselines,BaselinesSnapshot}.kt`
* Swift: `SynheartCore/Modules/Baselines/{Baselines,BaselinesSnapshot}.swift`

## Related

* [Self-Reference Model (SRM)](/synheart-core/srm) — the longitudinal engine that produces `reference`; defines dimensions, maturity states, and snapshot lifecycle
* [Scoring models](/synheart-core/scoring) — produces the inputs to `cacheSleepScore` / `cacheRecoveryScore` / `cacheReadinessScore`
* [Health Connect / HealthKit backfill](/synheart-core/health-backfill) — populates the SRM that backs `reference`