Generate the Swift FHIR Contract from the Implementation Guides

[PSchmiedmayer]

♻️ Current situation & Problem

We need one place to define the FHIR structures exchanged across Grove and a deterministic way to keep every language implementation aligned with that contract. The Grove FHIR Implementation Guides are authoritative: mobile carries the shared exchange contract, while healthkit, sensorkit, sensor, and questionnaire define the source-specific claims used by this package.

The previous Swift implementation combined hand-written HealthKit mappings, a partial Questionnaire bridge, and no complete SensorKit producer contract. That made important behavior depend on local conventions: graph identity, exact source evidence, profile membership, and supported source inventories could drift from the Implementation Guides without a failing build.

This change generates the Swift contracts from the catalogs pinned to the current main revision of the Implementation Guides and makes the conversion boundaries validate those contracts. HealthKit, SensorKit, and Questionnaire now publish explicit R4 graphs with deterministic identity and producer conformance fixtures. The legacy ResearchKit bridge remains available only for its existing format and is explicitly deprecated; it does not claim support for the new Questionnaire contract.

⚙️ Release Notes

• Generate GroveFHIRContract and the SensorKit catalog surface from the authoritative Implementation Guide catalogs, with regeneration and drift checks in CI.
• Publish complete R4 exchange graphs with typed identifiers, deterministic entry-node keys, explicit profile membership, closed references, and conversion Provenance.
• Convert HealthKit records through an explicit durable conversion context, including exact DSTU2 and R4 clinical payload preservation inside an R4 exchange graph.
• Advance HealthKit query anchors only after handlers durably accept the complete delta, then run optional cleanup actions after the matching anchor compare-and-exchange succeeds.
• Persist bulk-export completion as ordered, atomic session snapshots before delivering results, fence pending writes during pause and termination, and provide post-persistence cleanup for retry-only state.
• Represent HealthKit and SensorKit recording evidence as complete Recording Documents and return the full conversion Bundle to callers.
• Add persisted SensorKit acquisition coordinates, explicit batch acknowledgement, retry-stable record identity, and lossless ECG and device-usage evidence.
• Map SensorKit ECG guidance to Observation.method, preserve exact point coverage, and omit empty optional FHIR arrays.
• Export profile-conformant patient Questionnaires and validate Questionnaire/QuestionnaireResponse pairs, SDC quantity units, and coded quantity bounds.
• Keep the ResearchKit bridge narrowly compile-compatible while deprecating it for new FHIR Questionnaire formats.
• Scope draft CI to the active FHIR stack plus its HealthKit and Study support packages while retaining an all-package readiness mode on the currently enabled CI platforms; cache the exact guide revision and build shared guide dependencies once.

📚 Documentation

DocC documents the durable conversion inputs, complete exchange graph, retry and acknowledgement responsibilities, post-anchor and post-persistence cleanup boundaries, and the boundaries around exact provider attachments. The contract itself remains in the Implementation Guides rather than being copied into version-specific package prose.

✅ Testing

• Deterministic generation and Python contract tests.
• Unit and UI coverage for the affected HealthKit, SensorKit, Questionnaire, StudyDefinition, and legacy ResearchKit surfaces on their supported Apple platforms.
• Atomic session-snapshot, ordered persistence, failed-write recovery, anchor acknowledgement, and termination-fencing coverage for retry-safe HealthKit processing.
• Official HL7 Validator conformance for 27 HealthKit resources, two Questionnaire resources plus their exact pair rules, and 12 SensorKit resources against the pinned Implementation Guide package closure.
• Strict SwiftLint, Periphery, DocC warning checks, generated-source consistency, canonical hygiene, actionlint, REUSE compliance, and deployment-floor builds for iOS, macOS, and watchOS.

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.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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

---

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