[WIP] rework GroveHealthKitFHIR

[lukaskollmer]

♻️ Current situation & Problem

#67 replaced the previous HealthKit → FHIR conversion layer (which simply produced FHIR Observations with informal and practically undocumented and non-guaranteed semantics and structure) with a new HealthKit → FHIR API whose output is in compliance with our implementation guide

however, this new API was cumbersome to use and understand, and has significantly worse performance (e.g. w.r.t. HKSample → FHIR resource conversion throughput) than what it was replacing.

this PR aims to rework it again, in a way that keeps the fundamental structure and most of the implementation in place, but simplifies and streamlines the public API around the new conversion layer, and also optimizes the implementation to (vastly) improve performance, to a level that at least matches (and in the best case will hopefully exceed) that of the original implementation both PRs intend to replace.

terminology:

• A: the old HealthKit → FHIR converter, as of prior to both Generate the Swift FHIR Contract from the Implementation Guides #67 and [WIP] rework GroveHealthKitFHIR #118
• B: the new conversion layer as introduced in Generate the Swift FHIR Contract from the Implementation Guides #67
• C: the rework of B, as introduced in this PR ([WIP] rework GroveHealthKitFHIR #118)

new high level API

instead of the TODO TOD OTODO

// 1. Once per installation and account: the producer owns identities and the ledger.
let producer = try ExchangeProducer(
    identityScope: identityScope,          // HMAC key + deployment identifier systems
    subject: subject,                      // the participant (logical or bundled Patient)
    application: application,              // ApplicationDevice snapshot of the app
    host: .current(),
    studies: enrollments,                  // [StudyEnrollment]
    storage: ledgerStorage                 // any ExchangeProducer.Storage
)

// 2. One long-lived exporter on top of it (Sendable, supports concurrent multithreaded usage).
var options = HealthKitFHIRExporter.Options()   // every disclosure defaults to omission
options.nativeIdentifier = .authorized(system: myNativeRecordSystem)
options.maximumConcurrency = nil                // nil = every core; 1 = serial
options.measuresThroughput = false              // opt-in timing, read via exporter.throughput
let exporter = try HealthKitFHIRExporter(
    producer: producer,
    repositoryScope: repositoryScope,
    options: options
)

// 3. Export a batch: one ledger transaction reserves every event, graphs are built concurrently,
//    and propagated back to the caller in input order (on the caller's task)
var report = HealthKitFHIRExporter.WarningReport()
let receipt = try await exporter.export(samples, at: .now) { export in
    report.add(export)
    switch export.outcome {
    case .graph(let graph): store(graph.json)           // validated ExchangeGraph; can be uploaded verbatim
    case .refused(let error): log(error.diagnostic)      // typed, per record; the call continues
    }
}
logger.info("\(report)")
receipt.release()   // only after the bytes are durable; until then a retry reproduces every event byte for byte

// 4. Deletions become retraction graphs the same way.
let retractionReceipt = try await exporter.retract(deletions, at: .now) { retraction in
    // .graph(ExchangeGraph) | .refused(HealthKitConversionError) | .nothingToRetract
}

performance

impl	per sample (single core)	samples/s (single core)	per sample (18 cores)	samples/s (18 cores)
A	94.3 µs	10,602	27.4 µs	36,514
B	3,152.2 µs	317	510.7 µs	1,958
C	426.2 µs	2,346	76.8 µs	13,026
C*	219.2 µs	4,562	51.7 µs	19,338

• measured on an M5 Pro, 5000 heart-rate samples with Watch device and study context
• C*: output validation disabled

overall, A still is by far the most performant implementation: this is because it doesn't perform any validation, and because its output (FHIR Observations) is much smaller and simpler than B and C's output (FHIR Bundles containing a graph of Observations and other, related/referenced data)

⚙️ Release Notes

todo

📚 Documentation

yes

✅ Testing

yes

Code of Conduct & Contributing Guidelines

By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines:

• I agree to follow the Code of Conduct and Contributing Guidelines.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}