docs(import): say what the origin marker is for and who reads it

The comment claimed the app's own sync filters by the marker. It does not:
the app's echo check is HKExternalUUID plus the sample's authoring source
being the app itself, and the marker exists for the deletion path, where
the source is not visible. Say so, and say why the export import reads the
marker and the row id instead.
This commit is contained in:
Marc-André Bombeck committed 2026-10-04 14:34:37 +02:00
1 parent fbd639d9f1
commit 8add851fb7
1 file changed
+13 -5
+13 -5
View File
@@ -1,13 +1,21 @@
/**
* The marker HealthLog's iOS app stamps on every HealthKit sample it writes
* itself (a manual entry, or a Withings or import row it mirrors into Apple
* Health). The sample also carries the HealthLog measurement id as
* `HKExternalUUID`.
* itself, next to `HKExternalUUID` (the HealthLog row id): a manual entry saved
* from the app, and any Withings, import or manual row the server-to-Health
* mirror writes. Builds from before the marker existed wrote the id alone.
*
* Such a sample is already in the database under its own source. When the same
* sample comes back through an Apple Health export it is a second copy of that
* reading, so the export import leaves it out. This is the same predicate the
* app's own sync filter uses, and a stable contract with the app.
* reading, so the export import leaves it out.
*
* This is not the predicate the app's own sync uses. The app decides "our own
* echo" from `HKExternalUUID` plus the sample's authoring source being the app
* itself (`HealthKitSampleOwnership.isOwnEcho`); it keeps this marker for the
* deletion path, where a deleted object exposes its metadata but no source. An
* export names its source only by a display name, so the import cannot repeat
* the source check and reads the marker instead, and for samples from before
* the marker, `HKExternalUUID` against the account's own row ids. The key and
* value are a stable contract with the app.
*/
export const HEALTHLOG_ORIGIN_METADATA_KEY = "dev.healthlog.app.origin";
export const HEALTHLOG_ORIGIN_METADATA_VALUE = "healthlog";