Fix Data Loss and Stuck Collection Found in the FHIR Stack Review

[lukaskollmer]

♻️ Current situation & Problem

Stack: 9/9, following #116. Consumed by SchmiedmayerLab/MyHeartCounts-iOS#220 through SchmiedmayerLab/MyHeartCounts-StudyDefinitions#52. A review of the FHIR stack (#67, #94, #104, #116) together with its consumer, SchmiedmayerLab/MyHeartCounts-iOS#204, found problems that lose or distort participant data or leave a collection permanently stuck. This PR fixes the ones that belong in Grove:

• Every HealthKit State of Mind sample was refused. applyEffective rejected any .period contract whose sample has endDate == startDate. State of Mind samples carry a single date, and so do manual point-in-time entries (dietary values, insulin, water, falls, alcoholic beverages). The IG only requires a strictly positive interval for step count and wheelchair push count (grove-step-count-period-1) and, through corpus edge rules, for basal energy and mindful sessions.
• A SensorKit cursor could wedge forever. After an unacknowledged batch, any SensorKit content drift makes the retry throw pendingBatchMismatch on every fetch, and reset() refused to run while a batch was pending. There was no API to recover, so the sensor stopped collecting until reinstall.
• Skipping one optional marked question dropped every extracted reading of the response. For example, a participant who enters their glucose but skips the blood-pressure panel got no Observation at all.
• Sleeping breathing disturbances were divided by the night's length. HealthKit already stores this value per hour, so the wire value was about 7x too small.
• The ECG uniform-timing check measured offsets from the .begin marker instead of the first voltage chunk and compared Doubles exactly, which can reject real sessions.
• Instants in the repeated DST hour were still serialized one hour early on the SensorKit, questionnaire authored, HealthKit ECG and issued paths. Fix HealthKit Export Completion and Retries #104 had fixed this only for HealthKit effective.
• The first -apple15 release would fail. apple15-release.py expects a watchOS 9 floor, but the lowered platforms have been watchOS 8 since Generate the Swift FHIR Contract from the Implementation Guides #67.
• CI pinned grove-fhir to 9c5eff45, a commit that exists only as the head of the squash-merged Align the Producer Contract Across Swift, Kotlin and TypeScript grove-fhir#42.

⚙️ Release Notes

• A zero-length HealthKit sample now converts to an effectivePeriod with equal start and end, unless its measurement requires a non-zero period (step count, wheelchair push count, basal energy, mindful session). Reversed intervals are still refused.
• New SensorKit.discardPendingBatches(for:) abandons delivered-but-unacknowledged batches and keeps the committed cursor. Records fetched afterwards get fresh acquisition coordinates. Consumers call it after pendingBatchMismatch.
• resetQueryAnchors(for:) now succeeds when a batch is pending, abandons it, and no longer aborts at the first pending device partition.
• Questionnaire extraction: an unanswered marked item, or a panel with no answered component, extracts nothing instead of refusing the whole response. This applies even to required items, because enablement is the pair validator's job. A half-answered panel still refuses, now with componentIncomplete. Integer and decimal panel components with a fixed questionnaire-unit now extract.
• appleSleepingBreathingDisturbances is emitted unchanged as events per hour.
• ECG timing is measured from the first voltage chunk, with a 1 µs tolerance for Date representation noise. Real gaps and shifts are still rejected.
• New TimeZone.fixedOffset(at:) in FHIRModelsExtensions, now used by every FHIR date-time Grove builds from a named zone.
• Apple 15 release checks, docs and comments now agree on the watchOS 8 floor. CI validates against grove-fhir eff5af8, the squash commit of grove-fhir#42 on main.

Behavior changes consumers may notice:

• ObservationExtractionError.answerMissing is no longer thrown for unanswered items.
• Breathing-disturbance values are about 7x larger than before.
• An ECG's effectivePeriod.start moves to its first voltage chunk.
• FHIR date-times built by Grove now carry GMT-offset zones instead of named zones. Serialized output only changes inside the repeated DST hour.

📚 Documentation

The SensorKit docs list discardPendingBatches(for:) and link it from pendingBatchMismatch. The ExtractingObservations article and the extractor's doc comments describe the unanswered-item rules. APPLE15_RELEASES.md and the README describe standard targets as the default and lowered targets as opt-in. Inline comments cite the IG invariant and corpus rules behind the non-zero-period set and justify the ECG tolerance.

Follow-up for grove-fhir, not changed here: mobile/input/fsh/terminology.fsh defines #session-rate as "a count of qualifying events divided by the session duration". That reads as if the producer must divide, which is how this bug came about. The definition should allow a platform-computed rate.

✅ Testing

Run locally on macOS (Xcode 27, standard targets, all traits), all passing:

• FHIRModelsExtensions test plan
• GroveHealthKitFHIR test plan (183 tests)
• GroveSensorKitFHIR test plan (83 tests)
• GroveQuestionnaire test plan (218 + 28 + 14 tests)
• Scripts/Tests/test_apple15_release.py

The GroveSensorKit tests only run on iOS. They compile (build-for-testing, generic iOS Simulator), but they were not run locally, so CI runs them. That covers the new reset/discardPendingBatch tests.

The ECG fix has no fixture from a real device yet. If real voltage chunks jitter by more than 1 µs, those sessions will still be rejected.

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.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 2dfc6fd9-5351-4a6e-83c2-2db1c88e1c32

---

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