# HealthProbe iOS - Specification (MVP)

**Version:** 1.5
**Last Updated:** 2026-05-23
**Status:** MVP iOS local Health DB Time Machine

## Overview

HealthProbe is a read-only iOS app that captures selected HealthKit data into a local archive so the user can revisit how their Health database looked at earlier observation dates.

The MVP is not a cloud sync product and not a cross-device comparator. It is a single-device local timeline:
- capture what HealthKit exposes today
- preserve selected details before they are aggregated, consolidated, or no longer queryable
- show what changed between local observations
- export selected historical views and record tables

The original motivation was data-loss detection. The current objective is broader and calmer: help the user understand the evolution of their local Health database over time. A record-count drop is a change to explain, not automatically an emergency.

## Core Principles

1. **Read-only with respect to HealthKit**
   - Never modify or delete HealthKit data
   - Only observe, archive, compare, and export

2. **Single-device local timeline**
   - Compare only observations captured on this device
   - Do not infer correctness by comparing HealthKit databases from different devices

3. **Local-first storage**
   - HealthProbe data works without network access
   - No HealthProbe CloudKit/iCloud sync for raw samples, digests, reports, or caches

4. **Archive-first design**
   - The local archive is the source of truth
   - SQLite stores differential observations and performs large analyses
   - Core Data stores UI/report/cache/settings/history data that can be rebuilt from the archive

5. **Legacy-device support**
   - Keep iOS 15-era Health collection devices in scope
   - Do not require SwiftData for target architecture
   - Simplify heavy visualizations on legacy devices while preserving capture, reporting, and export

6. **Consolidation-aware interpretation**
   - Apple Health may aggregate or rewrite older high-frequency records
   - Count-only alerts are not reliable evidence of loss
   - UI language should describe additions, removals, consolidation, and uncertainty

7. **Differential storage**
   - Do not append complete periodic snapshots for large datasets
   - Store sample identities, payload versions, observation events/ranges, and aggregates

## MVP Features

### 1. Local HealthKit Capture

Use:
- `HKAnchoredObjectQuery` for incremental capture
- `HKObserverQuery` as a prompt to refresh when iOS wakes the app
- manual capture from the app UI

Track initially:
- workouts
- steps and activity quantities
- heart rate and other high-frequency quantities selected by the user
- sleep and relevant category samples
- additional types through a selected-type registry

Persist differentially in the local SQLite archive where HealthKit exposes it:
- sample UUID hash, type, start/end date, value, and unit
- source and source revision metadata
- HealthKit metadata dictionaries
- device provenance exposed by HealthKit, subject to privacy redaction/hash policy
- first-seen, last-seen, last-verified, disappeared-at observations
- fingerprints for internal matching and explicit user exports
- materialized per-type/per-day aggregates needed by reports and presentation

### 2. Health DB Time Machine

The app must let the user answer:
- "What did my accessible HealthKit data look like on this observation date?"
- "What changed between these two observations?"
- "Which older details can HealthProbe still export even if HealthKit later consolidates them?"

Core views:
- observation timeline
- point-in-time summary
- per-type detail table
- adjacent-observation diff
- selected-record export preview

On legacy/low-memory devices, heavy charts may be replaced with tables, summaries, and generated reports. Export/report correctness is more important than rich visualization.

### 3. Change Explanation

Changes are classified as observations, not accusations:
- **Appeared:** record/fingerprint was absent before and present now
- **Disappeared:** record/fingerprint was present before and absent now
- **Changed representation:** aggregates remain similar but record granularity, intervals, timestamps, or values changed
- **Consolidation likely:** old high-frequency detail appears thinned or intervalized while aggregate totals remain explainable
- **Uncertain:** HealthKit/API/background constraints prevent confident classification

Severity should be used sparingly. The MVP should prefer neutral labels and evidence summaries over alarm language.

### 4. Exports

Exports are a primary product feature. They preserve selected historical evidence and support external analysis.

MVP exports:
- selected point-in-time table as JSON/CSV
- diff report between two observations
- manifest with hashes and observation metadata
- selected disappeared/appeared/changed records

Routine full-database export is not an MVP goal. The archive itself is the local backup; user-facing exports are scoped to what the user is inspecting.

Exports must stream or page from SQLite. The app must not materialize large high-frequency record sets in RAM before writing an export.

### 5. Context Logging

Health/iCloud state may be logged as context only:
- HealthKit permission changes
- app version / iOS version
- local capture start/end/failure
- iCloud sign-in state if available

Context logging must not become HealthProbe cloud sync and must not imply that iCloud state proves why a change happened.

## Out Of Scope

- HealthProbe CloudKit/iCloud sync
- comparing snapshots from different devices
- claiming Apple lost data solely because sample counts changed
- predicting future loss
- modifying HealthKit data
- restoring by patching/transplanting Health database files into iOS backups
- re-publishing archived samples into HealthKit as HealthProbe-owned replacement records
- automatic upload or community reporting

The archive/export format should still preserve enough structure for external recovery tools to use it as input.

## Success Criteria

| Objective | MVP Target |
|-----------|------------|
| Historical inspection | User can select an observation and inspect per-type counts, ranges, and records |
| Change explanation | User can compare adjacent observations with neutral, consolidation-aware labels |
| Preservation | User can export selected records/details that may no longer be available from HealthKit later |
| Legacy support | Capture/report/export works on iOS 15-era devices with simplified visuals where needed |
| Privacy | All HealthProbe data remains local unless the user explicitly exports a file |
| Performance | High-frequency capture streams to the archive without blocking UI |

---

*HealthProbe iOS: a local time machine for HealthKit-accessible data.*
