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:

{
  "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:

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.