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

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

AnomalyStoreProtocol

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

AuditTrailProtocol

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

ContextMonitorProtocol

/// 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:

// 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:

Define the protocol in Services/Protocols/ (services agent)
Implement a mock in Utilities/Mocks.swift (Claude Code)
Build UI against the mock (Claude Code)
Replace mock with real implementation (services agent)
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:

Update this file (AGENTS.md) with the protocol/interface change
Update the relevant protocol in Services/Protocols/
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