# 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.