# HealthProbe - Export Specification

**Last Updated:** 2026-05-23
**Status:** Target design for recovery-compatible exports

## 1. Purpose

Exports let the user preserve selected point-in-time views, diffs, record tables, and evidence summaries from the local SQLite archive.

HealthProbe does not restore, patch backups, or re-publish HealthKit data. Exports should still preserve enough structure for external recovery/salvage tools to reason about what was observed.

## 2. Export Kinds

Supported target kinds:
- `observation_records_json`;
- `observation_records_csv`;
- `observation_diff_json`;
- `type_summary_json`;
- `archive_manifest_json`.

Large exports must stream/page from SQLite. Do not materialize all records into Swift arrays.

## 3. JSON Envelope

Every JSON export uses a versioned envelope:

```json
{
  "export_format_version": 1,
  "export_id": "UUID",
  "export_kind": "observation_records_json",
  "created_at": "2026-05-23T12:00:00.000Z",
  "app": {
    "name": "HealthProbe",
    "version": "local-build"
  },
  "archive": {
    "schema_version": 2,
    "device_chain_hash": "hex",
    "from_observation_id": 1,
    "to_observation_id": null
  },
  "filters": {
    "sample_type_identifiers": [],
    "date_range": null,
    "include_relationships": true
  },
  "manifest": {
    "record_count": 0,
    "item_hash_algorithm": "sha256",
    "manifest_hash_algorithm": "sha256",
    "manifest_hash": "hex"
  },
  "items": []
}
```

JSON keys are emitted in deterministic sorted order for canonical hashing.

## 4. Export Item Contract

Record items should include:
- sample identity hash;
- HealthKit UUID hash when available;
- strict fingerprint;
- semantic fingerprint when available;
- payload version hash;
- sample type identifier;
- start/end timestamps as ISO 8601 UTC;
- value kind, value, unit, category, workout fields;
- source/provenance hashes or redacted fields allowed by the export scope;
- metadata hash and optional metadata object when allowed;
- relationships when both endpoints are in scope, or unresolved endpoint hashes when explicitly allowed;
- observation visibility fields: first seen, last verified, disappeared evidence when available.

Every item has:
- `item_hash = SHA-256(canonical item JSON)`.

## 5. Manifest Hash

`manifest_hash` is calculated incrementally:

```text
SHA-256(
  canonical_export_metadata_json
  + ordered_item_hashes
  + canonical_counts_json
  + canonical_filter_json
)
```

The manifest hash must cover exported content through item hashes. Counts, first dates, or last dates alone are not sufficient.

Item order:
1. sample type identifier;
2. start date;
3. end date;
4. sample identity hash;
5. payload version hash.

## 6. CSV Contract

CSV exports are flat record tables for spreadsheet and external tooling.

Required column order:
1. `export_id`
2. `observation_id`
3. `sample_type_identifier`
4. `sample_identity_hash`
5. `sample_uuid_hash`
6. `strict_fingerprint`
7. `semantic_fingerprint`
8. `payload_hash`
9. `start_date_utc`
10. `end_date_utc`
11. `value_kind`
12. `numeric_value`
13. `unit`
14. `category_value`
15. `workout_activity_type`
16. `duration_seconds`
17. `source_hash`
18. `device_hash`
19. `metadata_hash`
20. `first_seen_observation_id`
21. `last_verified_observation_id`
22. `disappeared_observation_id`
23. `item_hash`

CSV uses RFC 4180 quoting rules and UTF-8.

Relationships are not flattened into the main CSV row. If needed, export a companion relationships CSV with source/target sample hashes.

## 7. Streaming And Cancellation

Implementation contract:
- page records from SQLite with deterministic cursors;
- write output incrementally;
- update item/manifest hash state as rows stream;
- if the user cancels, mark export status as `cancelled` and do not record a completed manifest;
- failed exports should leave no completed manifest row unless the output is verifiable.

Resume support is optional for v1 exports.

## 8. Provenance Warning

Every user-facing export flow must communicate that:
- exported data is observed evidence from HealthKit-accessible surfaces;
- external re-publication to HealthKit may lose original metadata/provenance;
- HealthProbe itself does not restore or modify HealthKit/iOS backups.

