# Sprint 1 – Apple Health Analytics v2

**Status:** implemented, production-verified and independently approved
**Scope:** canonical Apple Health aggregation, source/overlap safety, local-day semantics, coverage and missingness metadata.

## Motivation

The raw Apple Health import is intentionally lossless and can contain overlapping daily, weekly and yearly exports, several source classes and provisional current-day values. Raw rows are therefore unsuitable for direct summation or medical interpretation.

Analytics v2 keeps `apple_health_records` unchanged and introduces a deterministic read-only canonicalization layer.

## Canonicalization pipeline

1. **Exact observation deduplication**
   - Canonical grouping uses metric, source class, canonical UTC start/end timestamp and canonical unit.
   - Repeated rows from the exact same source are treated as export revisions; across source aliases only equivalent canonical values deduplicate, while different values remain distinct observations.
   - The newest database row is retained; raw rows remain untouched.

2. **Europe/Zurich local-day semantics**
   - Offset-aware timestamps are converted to `Europe/Zurich` before day bucketing.
   - Naive timestamps are explicitly treated as Zurich local time and marked as an assumption.
   - The current local day is excluded by default because it is provisional.

3. **Resolution precedence**
   - Explicit annual/weekly/monthly export names receive deterministic cadence metadata, including interrupted one- or two-row exports.
   - Fine/direct daily observations supersede coarse weekly/monthly fallback rows on overlapping days.
   - Coarse sum rows are converted to daily-equivalent values and marked `coarse_fallback`; they are not represented as direct measurements.

4. **Source precedence**
   - A single deterministic source class is selected per metric/day to prevent Watch, phone and derived-app overlap from being summed together.
   - Priority is composite export, Watch, phone, Health app, other app, unknown; aliases within one selected source class are combined.
   - Raw source names are never emitted by coverage summaries.

5. **Metric-aware aggregation**
   - Sum: activity/energy/distance/duration and selected nutrition quantities.
   - Average: physiological samples such as heart rate, HRV, respiration and SpO₂.
   - Last: body measurements such as weight and BMI.
   - Compatible energy, distance, body-mass, water and duration units are normalized before deduplication and aggregation.

## Public interfaces

- `daily_points(metric, ...)` returns value plus data-quality metadata for each completed local day.
- `daily_series(metric, ...)` remains backward compatible for existing dashboard/report consumers.
- `coverage_summary(metric, ...)` returns counts and quality only:
  - expected calendar days and metric-aware expected observations,
  - daily cadence for continuous metrics and weekly cadence for body measurements,
  - observed/missing observations and coverage ratio,
  - direct versus coarse-fallback days,
  - source/unit conflict days,
  - deduplicated and discarded overlap counts.
- `summary()` returns Analytics-v2 metadata for all available metrics without source names or raw values. It loads only required metadata columns once for all metrics; bounded coverage queries avoid loading raw JSON payloads or unrelated history.

## Dashboard and report integration

- Dashboard trends and physician report continue to consume `daily_series`, now backed by Analytics v2.
- The Dashboard adds a 30-completed-day Apple Health data-quality table.
- Coverage labels assess only data availability/import quality, never health or medical risk.
- Existing medical-safety boundaries remain unchanged: Apple Health trends are contextual data, not diagnosis, alerting or treatment guidance.

## Regression gates

Synthetic tests cover:

- duplicate exports with equivalent offsets/units,
- complete and interrupted grouped-export handling,
- direct-over-coarse precedence,
- source-class precedence and alias combination,
- aware and naive timezone semantics,
- provisional current-day exclusion,
- compatible energy/distance/body-mass/water/duration normalization,
- last-value body-measurement semantics,
- bounded, single-load summary/coverage paths,
- coverage/missingness output without raw values,
- dashboard non-medical quality wording.

No production health values, exports or reports are included in tests or Git.