fix(measurements): wire walking step length and walking speed

The iOS team had gated both client-side waiting on the server map.
Both flow raw SI on the wire (metres and metres per second
respectively) — the server-side ×100 scaling the percent gait
metrics use does NOT apply here. The convention block at the top of
apple-health-mapping.ts now spells the split out so a future
gait-metric addition picks the right path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marc-André BombeckandClaude Opus 4.7 committed 2026-05-28 23:38:21 +02:00
1 parent 8d5d039ed1
commit 7f95a2a44f
18 files changed
+332 -3

No files matched your search

@@ -78,6 +78,9 @@ export const MEASUREMENT_TYPE_LABEL_KEYS: Record<string, string> = {
WALKING_HEART_RATE_AVERAGE: "measurements.typeWalkingHeartRateAverage",
WALKING_ASYMMETRY: "measurements.typeWalkingAsymmetry",
WALKING_DOUBLE_SUPPORT: "measurements.typeWalkingDoubleSupport",
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
WALKING_STEP_LENGTH: "measurements.typeWalkingStepLength",
WALKING_SPEED: "measurements.typeWalkingSpeed",
};
export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
@@ -136,6 +139,12 @@ export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
WALKING_HEART_RATE_AVERAGE: HeartPulse,
WALKING_ASYMMETRY: Footprints,
WALKING_DOUBLE_SUPPORT: Footprints,
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
// Footprints carries the stride/length signal; Gauge mirrors
// the velocity-reading shape (same family as VO2_MAX +
// WALKING_STEADINESS).
WALKING_STEP_LENGTH: Footprints,
WALKING_SPEED: Gauge,
};
export const MEASUREMENT_TYPE_COLORS: Record<string, string> = {
@@ -187,4 +196,11 @@ export const MEASUREMENT_TYPE_COLORS: Record<string, string> = {
WALKING_HEART_RATE_AVERAGE: "bg-chart-3/20 text-chart-3",
WALKING_ASYMMETRY: "bg-chart-2/20 text-chart-2",
WALKING_DOUBLE_SUPPORT: "bg-chart-2/20 text-chart-2",
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
// Stay in chart-2 (Dracula green) — the entire Mobility cluster
// (steadiness + asymmetry + double-support + step length + speed)
// shares the activity-family colour so the gait cards read as one
// visual group on Insights.
WALKING_STEP_LENGTH: "bg-chart-2/20 text-chart-2",
WALKING_SPEED: "bg-chart-2/20 text-chart-2",
};
@@ -56,10 +56,13 @@ const EXPECTED_TYPES = [
"WALKING_HEART_RATE_AVERAGE",
"WALKING_ASYMMETRY",
"WALKING_DOUBLE_SUPPORT",
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
"WALKING_STEP_LENGTH",
"WALKING_SPEED",
] as const;
describe("measurementTypeEnum coverage", () => {
it("exposes the 36 canonical measurement types", () => {
it("exposes the 38 canonical measurement types", () => {
expect([...measurementTypeEnum.options].sort()).toEqual(
[...EXPECTED_TYPES].sort(),
);
@@ -123,6 +126,10 @@ describe("measurementTypeEnum coverage", () => {
"WALKING_HEART_RATE_AVERAGE",
"WALKING_ASYMMETRY",
"WALKING_DOUBLE_SUPPORT",
// v1.5.5 iOS-coord follow-up — raw-SI gait pair held under the
// same clinical-layout deferral as the rest of the Mobility set.
"WALKING_STEP_LENGTH",
"WALKING_SPEED",
]);
it("doctor-report PDF vital types cover the canonical enum minus documented exclusions", () => {
+8
View File
@@ -74,6 +74,11 @@ export const ALLOWED_CHART_TOKENS = [
"metric:WALKING_HEART_RATE_AVERAGE",
"metric:WALKING_ASYMMETRY",
"metric:WALKING_DOUBLE_SUPPORT",
// v1.5.5 iOS-coord follow-up — raw-SI gait pair. Same posture:
// the LLM can reference these in prose; the chart components
// ride the existing card-shelf renderer.
"metric:WALKING_STEP_LENGTH",
"metric:WALKING_SPEED",
] as const;
export type ChartToken = (typeof ALLOWED_CHART_TOKENS)[number];
@@ -158,6 +163,9 @@ const ORPHAN_ENUMS = [
"WALKING_HEART_RATE_AVERAGE",
"WALKING_ASYMMETRY",
"WALKING_DOUBLE_SUPPORT",
// v1.5.5 iOS-coord follow-up — raw-SI gait pair, same shape.
"WALKING_STEP_LENGTH",
"WALKING_SPEED",
] as const;
// `\b` boundaries keep ordinary English prose untouched — "weight"
@@ -457,6 +457,75 @@ describe("v1.5.5 iOS-coord additions — six previously-deferred identifiers", (
});
});
describe("v1.5.5 iOS-coord follow-up — raw-SI gait pair", () => {
it("maps walkingStepLength + walkingSpeed to the new MeasurementTypes", () => {
const sl = APPLE_HEALTH_TYPE_MAP.HKQuantityTypeIdentifierWalkingStepLength;
const sp = APPLE_HEALTH_TYPE_MAP.HKQuantityTypeIdentifierWalkingSpeed;
expect(sl).toBeDefined();
expect(sp).toBeDefined();
expect(sl.measurementType).toBe("WALKING_STEP_LENGTH");
expect(sp.measurementType).toBe("WALKING_SPEED");
expect(sl.dbUnit).toBe("m");
expect(sp.dbUnit).toBe("m/s");
});
it("passes raw SI values through unchanged (no ×100 scaling)", () => {
// Crucial convention pin: the percent gait metrics scale ×100
// server-side because Apple ships 0..1 fractions; step length
// and speed are already in metres / metres-per-second and MUST
// round-trip as identity. A future contributor wiring a new
// gait identifier should add to the right bucket — this test
// is the regression sentinel for that decision.
const sl = APPLE_HEALTH_TYPE_MAP.HKQuantityTypeIdentifierWalkingStepLength;
const sp = APPLE_HEALTH_TYPE_MAP.HKQuantityTypeIdentifierWalkingSpeed;
expect(sl.convertToDbUnit(0.72)).toBe(0.72);
expect(sl.convertToDbUnit(1.5)).toBe(1.5);
expect(sp.convertToDbUnit(1.3)).toBe(1.3);
expect(sp.convertToDbUnit(2.1)).toBe(2.1);
});
it("removes both identifiers from the deferred set", () => {
expect(
HK_QUANTITY_TYPE_DEFERRED.has("HKQuantityTypeIdentifierWalkingStepLength"),
).toBe(false);
expect(
HK_QUANTITY_TYPE_DEFERRED.has("HKQuantityTypeIdentifierWalkingSpeed"),
).toBe(false);
});
it("round-trips a walking-step-length sample through mapAppleHealthEntry", () => {
const out = mapAppleHealthEntry({
hkIdentifier: "HKQuantityTypeIdentifierWalkingStepLength",
value: 0.72,
unit: "m",
startDate: "2026-05-28T09:00:00.000Z",
endDate: "2026-05-28T09:00:00.000Z",
});
expect(out).toEqual({
type: "WALKING_STEP_LENGTH",
value: 0.72,
unit: "m",
takenAt: new Date("2026-05-28T09:00:00.000Z"),
});
});
it("round-trips a walking-speed sample through mapAppleHealthEntry", () => {
const out = mapAppleHealthEntry({
hkIdentifier: "HKQuantityTypeIdentifierWalkingSpeed",
value: 1.34,
unit: "m/s",
startDate: "2026-05-28T09:00:00.000Z",
endDate: "2026-05-28T09:00:00.000Z",
});
expect(out).toEqual({
type: "WALKING_SPEED",
value: 1.34,
unit: "m/s",
takenAt: new Date("2026-05-28T09:00:00.000Z"),
});
});
});
describe("v1.4.30 Tier-1 additions (R-F T1.4 + T1.5)", () => {
it("maps appleWalkingSteadiness to WALKING_STEADINESS with × 100 scaling", () => {
const mapping =
+45 -2
View File
@@ -123,6 +123,25 @@ export const APPLE_HEALTH_SLEEP_STAGE_MAP: Record<number, SleepStage> = {
* through the same canonical server-side scaling path. The coord
* note in `.planning/ios-coord/` documents the one-release shim and
* the migration window.
*
* ── Convention split — percent vs raw SI ───────────────────────────
*
* The ×100 scaling applies ONLY to identifiers Apple ships as a
* 0..1 fraction:
*
* - `oxygenSaturation`
* - `bodyFatPercentage`
* - `appleWalkingSteadiness`
* - `walkingAsymmetryPercentage`
* - `walkingDoubleSupportPercentage`
*
* Identifiers that already ride raw SI units on the wire pass
* through `convertToDbUnit` as identity — no scaling, no clamp. The
* v1.5.5 follow-up additions `walkingStepLength` (metres) and
* `walkingSpeed` (metres per second) belong to this second bucket
* and must NOT be scaled. A future contributor adding a new gait
* metric: check Apple's HK unit; percent → ×100 path, m/m·s/kg/etc
* → identity path.
*/
export const APPLE_HEALTH_TYPE_MAP: Record<string, AppleHealthMapping> = {
// ── Body composition ────────────────────────────────────────
@@ -427,6 +446,30 @@ export const APPLE_HEALTH_TYPE_MAP: Record<string, AppleHealthMapping> = {
convertToDbUnit: (v) => v * 100,
aggregation: "latest",
},
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ───────────
// Walking step length — Apple ships raw metres; canonical DB
// unit is metres too. NO scaling — the ×100 convention applies
// ONLY to the percent gait metrics above. See the convention
// block at the top of this file for the split.
HKQuantityTypeIdentifierWalkingStepLength: {
hkIdentifier: "HKQuantityTypeIdentifierWalkingStepLength",
measurementType: "WALKING_STEP_LENGTH",
hkUnit: "m",
dbUnit: "m",
convertToDbUnit: (v) => v,
aggregation: "mean",
},
// Walking speed — Apple ships raw metres-per-second; canonical
// DB unit is m/s too. NO scaling — see the convention block.
HKQuantityTypeIdentifierWalkingSpeed: {
hkIdentifier: "HKQuantityTypeIdentifierWalkingSpeed",
measurementType: "WALKING_SPEED",
hkUnit: "m/s",
dbUnit: "m/s",
convertToDbUnit: (v) => v,
aggregation: "mean",
},
};
/**
@@ -536,8 +579,8 @@ export const HK_QUANTITY_TYPE_DEFERRED = new Set<string>([
"HKQuantityTypeIdentifierAppleStandTime", // implied by Workout rows
"HKCategoryTypeIdentifierAppleStandHour", // implied by Workout rows
// Running / walking form — v1.5+
"HKQuantityTypeIdentifierWalkingSpeed",
"HKQuantityTypeIdentifierWalkingStepLength",
// v1.5.5 — `WalkingStepLength` + `WalkingSpeed` moved into the
// mapping table (raw SI on the wire — metres and m/s respectively).
"HKQuantityTypeIdentifierStairAscentSpeed",
"HKQuantityTypeIdentifierStairDescentSpeed",
"HKQuantityTypeIdentifierSixMinuteWalkTestDistance",
+3
View File
@@ -94,6 +94,9 @@ export const MEASUREMENT_CATEGORIES: ReadonlyMap<
["WALKING_ASYMMETRY", "activity"],
["WALKING_DOUBLE_SUPPORT", "activity"],
["WALKING_HEART_RATE_AVERAGE", "activity"],
// v1.5.5 follow-up — gait raw-SI pair join the same Mobility cluster.
["WALKING_STEP_LENGTH", "activity"],
["WALKING_SPEED", "activity"],
// ── Sleep ──
["SLEEP_DURATION", "sleep"],
+14
View File
@@ -62,6 +62,13 @@ export function getPRDirection(
// v1.5.5 — lean body mass is the muscle-mass-adjacent body-comp
// axis where higher is the goal.
case "LEAN_BODY_MASS":
// v1.5.5 follow-up — walking speed is a well-established
// clinical fitness marker (often called the "sixth vital
// sign" in older-adult medicine); faster gait correlates
// with cardiovascular fitness, sarcopenia recovery, and
// overall mobility resilience. MAX direction matches Apple's
// own Mobility-section framing.
case "WALKING_SPEED":
return PersonalRecordDirection.MAX;
// MIN direction — lower value is the record.
@@ -104,6 +111,13 @@ export function getPRDirection(
case "RESPIRATORY_RATE":
case "WALKING_HEART_RATE_AVERAGE":
case "BODY_MASS_INDEX":
// v1.5.5 follow-up — walking step length is a state metric:
// taller users have longer strides regardless of fitness, and
// there is no clean "higher is better" axis (very long strides
// can also signal an unsafe overstride). Defer to a null PR
// direction; the future worker can still surface trend deltas
// without claiming a record direction.
case "WALKING_STEP_LENGTH":
return null;
}
}
+21
View File
@@ -42,6 +42,11 @@ export const measurementTypeEnum = z.enum([
"WALKING_HEART_RATE_AVERAGE",
"WALKING_ASYMMETRY",
"WALKING_DOUBLE_SUPPORT",
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
// Both ship raw SI on the wire (metres / metres-per-second); see
// the convention block in `apple-health-mapping.ts`.
"WALKING_STEP_LENGTH",
"WALKING_SPEED",
]);
export const glucoseContextEnum = z.enum([
@@ -121,6 +126,12 @@ const unitMap: Record<string, string> = {
// — see the project convention block in `apple-health-mapping.ts`.
WALKING_ASYMMETRY: "%",
WALKING_DOUBLE_SUPPORT: "%",
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
// Step length is metres; speed is metres per second. Both flow
// raw on the wire — no server-side scaling. The unit strings
// match HealthKit's `m` / `m/s` defaults.
WALKING_STEP_LENGTH: "m",
WALKING_SPEED: "m/s",
};
export function getUnitForType(type: string): string {
@@ -218,6 +229,16 @@ const VALUE_RANGES: Record<string, { min: number; max: number }> = {
// the ×100 server-side scaling the canonical band is 0..100.
WALKING_ASYMMETRY: { min: 0, max: 100 },
WALKING_DOUBLE_SUPPORT: { min: 0, max: 100 },
// ── v1.5.5 iOS-coord follow-up — raw-SI gait pair ──
// Step length (metres) — adult walking sits around 0.5–0.8 m; the
// 0.1 floor captures shuffling gait and the 2.0 ceiling covers
// unusually tall sprinters without catching obvious sensor noise.
WALKING_STEP_LENGTH: { min: 0.1, max: 2.0 },
// Walking speed (m/s) — healthy adult casual gait ≈ 1.2–1.4 m/s;
// brisk walking tops out near 2.2 m/s before transitioning to a
// run. The 0.1 floor captures a very slow shuffle; 3.0 covers
// race-walking record territory.
WALKING_SPEED: { min: 0.1, max: 3.0 },
};
export function validateMeasurementRange(