# HealthProbe – Multi-Model Development Guide

## Overview

HealthProbe is built by multiple AI models, each owning a distinct domain.  
This document defines boundaries, interfaces, and handoff contracts.

**Agentic reality:** The repo is developed largely via agents (Codex CLI, Claude, and dedicated model sessions). When updating product scope, update docs first, then implement behind flags, and add tests for the new behavior.

---

## Model Allocation

| Domain | Owner | Tools |
|--------|-------|-------|
| **UI / SwiftUI Views** | Claude Code | Xcode, SwiftUI, CLAUDE.md |
| **Archive Store** | Dedicated model session | SQLite/local archive format, HealthKit metadata mapping |
| **Data Models (SwiftData)** | Dedicated model session | Xcode, Swift; derived UI/cache/settings/log models only |
| **HealthKit Integration** | Dedicated model session | Xcode, HealthKit docs |
| **Anomaly Detection Algorithms** | Dedicated model session | Swift, statistical references |
| **Context Monitoring** | Dedicated model session | Xcode; logs Health/iCloud state as context only |
| **Documentation** | Claude Code + dedicated session | Markdown |
| **Tests** | Dedicated model session | XCTest, Swift Testing |

---

## Directory Ownership

```
HealthProbe/
├── Views/           ← Claude Code (UI)
├── ViewModels/      ← Claude Code (UI)
├── Utilities/       ← Claude Code (shared helpers, mocks)
├── Models/          ← Models agent (SwiftData UI/cache schemas)
├── Services/        ← Services agent (HealthKit, archive store, anomaly, context)
└── Tests/           ← Tests agent
```

**Rule:** Each agent writes only within its owned directories.  
Cross-boundary changes require an explicit interface contract (protocol) first.

**Documentation scope:** `HealthProbe/Doc/` is shared. Keep it consistent with shipped behavior, and add a dated entry when objectives change.

---

## Interface Contracts

All service boundaries are defined as Swift protocols.  
Claude Code (UI) consumes protocols — never concrete implementations.

### HealthMonitorProtocol

```swift
/// Owned by: Services agent
/// Consumed by: UI (DashboardViewModel)
protocol HealthMonitorProtocol {
    var currentStatus: HealthStatus { get }
    var lastChecked: Date? { get }
    func runCheck() async throws
}
```

### AnomalyStoreProtocol

```swift
/// Owned by: Services agent
/// Consumed by: UI (AnomalyListViewModel)
protocol AnomalyStoreProtocol {
    var anomalies: [DetectedAnomaly] { get }
    func markResolved(_ anomaly: DetectedAnomaly) async throws
}
```

### AuditTrailProtocol

```swift
/// Owned by: Services agent
/// Consumed by: UI (AuditTrailView)
protocol AuditTrailProtocol {
    var entries: [AuditTrailEntry] { get }
    func export() async throws -> Data  // JSON
}
```

### ContextMonitorProtocol

```swift
/// Owned by: Services agent
/// Consumed by: UI (ContextViewModel)
protocol ContextMonitorProtocol {
    var iCloudEnabled: Bool { get }
    var lastObservedAt: Date? { get }
    var stateChanges: [ContextStateChange] { get }
}
```

---

## Shared Types (Models Agent)

These types are defined once in `Models/` and shared across all agents:

```swift
// Models/TypeDistributionBin.swift
@Model
final class TypeDistributionBin {
    var bucketStart: Date
    var bucketEnd: Date
    var count: Int
}

// Models/TypeCount.swift
// TypeCount owns zero or more TypeDistributionBin records.
// These bins store sample counts and import anchors, not raw health values.

// Interface updated 2026-05-12 — see AGENTS.md
// Models/HealthRecord.swift
// HealthRecord stores one anonymized HealthKit record fingerprint plus its start/end dates.
// It intentionally does not store raw health values, device identifiers, or source metadata.
// UI may compare HealthRecord fingerprints between adjacent snapshots to expose losses
// that are masked by newly-added records with the same total count.
// High-volume snapshots store these records in TypeCount.recordArchiveData instead of
// creating one SwiftData model per record, avoiding main-thread stalls after import.

// Interface updated 2026-05-13 — see AGENTS.md
// TypeDistributionBin also stores content hashes and HealthKit query anchors.
// Import uses a global anchored query per data type so follow-up snapshots fetch only
// HealthKit deltas instead of scanning calendar blocks with fixed per-query latency.

// Interface updated 2026-05-18 — see AGENTS.md
// SwiftData is not the forensic source of truth. TypeCount and related rows store
// precomputed UI/index data only. Complete HealthKit samples and metadata belong
// in the local archive store, in one schema that can preserve relationships across
// data types, sources, devices, workouts, and metadata.

// Interface updated 2026-05-17 — see AGENTS.md
// Models/TypeCount.detailCacheData stores precomputed detail data for the current
// TypeCount compared with the immediately previous snapshot on the same device.
// The cache contains aggregate added/disappeared counts, capped preview records for
// UI drill-down, and daily change bins for temporal charts. It must be computed when
// snapshots are saved and refreshed for neighboring snapshots when snapshot deletion
// changes chain links. Existing stores are backfilled incrementally with a strict
// per-launch TypeCount cap to avoid decoding many large archives in one run.

// Interface updated 2026-05-17 — see AGENTS.md
// Models/HealthSnapshot.contentEquivalentSnapshotID marks snapshots whose TypeCount
// content is identical to a previous snapshot on the same device. These snapshots are
// retained as temporal labels but behave as aliases to the representative content
// snapshot for expensive detail cache/diff work.

// Interface updated 2026-05-17 — see AGENTS.md
// Models/TypeCount.contentEquivalentTypeCountID marks individual data types whose
// content is identical to the previous snapshot's same TypeCount. This allows a
// snapshot to contain real changes for some metrics while long-stable metrics behave
// as temporal aliases and skip per-type detail cache/diff work.

// Interface updated 2026-05-17 — see AGENTS.md
// Models/HealthSnapshot stores cached overview scalars for UI consumption:
// tracked type count, aggregate record count, and overall oldest/newest record dates.
// These values must be computed during snapshot save while TypeCount data is already
// in memory, so snapshot list/detail screens never recompute them by traversing
// snapshot.typeCounts on the UI thread.

// Interface updated 2026-05-17 — see AGENTS.md
// Models/SnapshotDelta stores cached list/detail summary scalars derived from TypeDelta.
// Overview screens consume these scalars and type-delta summaries directly instead of
// recalculating per-snapshot changes from HealthSnapshot.typeCounts.

// Models/DetectedAnomaly.swift
enum AnomalyType: String, Codable {
    case historicalInsertion = "historical_insertion"
    case silentDeletion      = "silent_deletion"
    case duplicate           = "duplicate"
    case divergence          = "divergence"
}

enum Severity: String, Codable, Comparable {
    case info, warning, critical
}

enum HealthStatus: String {
    case healthy, warning, critical, unknown
}
```

Any model changes must be announced in this file before other agents consume them.

---

## Handoff Process

When a module is ready to be consumed by another agent:

1. **Define the protocol** in `Services/Protocols/` (services agent)
2. **Implement a mock** in `Utilities/Mocks.swift` (Claude Code)
3. **Build UI against the mock** (Claude Code)
4. **Replace mock with real implementation** (services agent)
5. **Integration test** (tests agent)

This allows UI development and service development to proceed in parallel.

---

## Algorithms & Detection Logic

The following modules involve non-trivial logic and should be reviewed carefully:

| Module | File | Description |
|--------|------|-------------|
| **Anomaly Detector** | `Services/AnomalyDetector.swift` | Statistical detection: insertions, deletions, duplicates, divergence |
| **Divergence Engine** | `Services/DivergenceEngine.swift` | Time-series trend analysis, σ comparison |
| **Fingerprinter** | `Services/SampleFingerprinter.swift` | Duplicate detection via sample hashing |
| **Snapshot Comparator** | `Services/SnapshotComparator.swift` | Diff between two HealthKit snapshots |
| **Distribution Comparator** | `Services/SnapshotDiffService.swift` | Daily per-type distribution diff to reveal old-data disappearance masked by new data |

**Guidelines for algorithm modules:**
- Document assumptions explicitly (e.g., "assumes continuous monitoring since install")
- All thresholds (e.g., `age > 7 days`) must be configurable constants, not magic numbers
- Include unit tests for edge cases (empty snapshots, partial data, clock skew)
- No UI code; return plain Swift types only

---

## Privacy Directives — All Agents

**Mandatory across all modules:**
- No credentials, API keys, tokens, or certificates in any file
- No personal data: names, emails, phone numbers, dates of birth
- No device identifiers: UDID, serial number, advertising ID, device name
- No account identifiers: Apple ID, iCloud account info, CloudKit record IDs
- No raw health values in code, tests, previews, logs, or comments
- No location data or patterns enabling re-identification
- Synthetic data only in tests and previews

**Clarification:** “No raw health values” applies to this repository’s contents. The app may optionally store a user's raw HealthKit samples *locally on-device* for forensic backup purposes, but such samples must never appear in source control, logs, or docs.

---

## Communication Between Agents

When one agent needs to communicate a decision or change to another:

1. **Update this file** (`AGENTS.md`) with the protocol/interface change
2. **Update the relevant protocol** in `Services/Protocols/`
3. **Add a comment** in the affected file: `// Interface updated YYYY-MM-DD — see AGENTS.md`

---

## Current Status

| Module | Status | Owner |
|--------|--------|-------|
| SwiftData Models | ✅ Done | Models agent |
| HealthKit Integration | ✅ Done | Services agent |
| Snapshot Diff Service | ✅ Done | Services agent |
| Service Protocols | ⏳ Not started | Services agent |
| Anomaly Detection | ⏳ Not started | Services agent |
| Sync Monitor | ⏳ Not started | Services agent |
| UI – App entry + TabView | ✅ Done | Claude Code |
| UI – Dashboard | ✅ Done (functional, minimal) | Claude Code |
| UI – Snapshots + Detail | ✅ Done | Claude Code |
| UI – Data Types | ✅ Done | Claude Code |
| UI – Settings | ✅ Done | Claude Code |
| Unit Tests | ⏳ Not started | Tests agent |
