Files
HealthLog/src/lib/signals/registry.ts
T
Marc-André Bombeck f75337e6f2 feat(measurements): record blood ketones and show the glucose-ketone index (#1367)
Ketones had to live in a custom metric, with the glucose-ketone index typed
in by hand beside it, where it drifted from the readings it came from.

- Type: BLOOD_KETONES (beta-hydroxybutyrate, mmol/L, migration 0496),
  plausible from 0 to 10: the blood ketone meters read 0.0 to 8.0 and print
  HI above it, and a venous value off a lab sheet fits under 10. Zero is a
  real reading. No band, no direction, no personal record, off the Coach
  snapshot and the correlations; readable over MCP and owned by the glucose
  module like glucose.
- Entry: choosing blood ketones in the measurement form also takes the
  glucose from the same fingerstick, in the account's glucose unit. Both
  rows go through the array arm of POST /api/measurements with one
  timestamp, so they land in one transaction or not at all.
- Index: glucose (mg/dL / 18.0182, the tree's one factor) over ketones,
  computed at read time and never stored. Each ketone reading above zero
  pairs with the glucose reading at the same instant, else the nearest one
  within 15 minutes either side; a tie goes to the same source, then to the
  earlier reading. Nothing pairs across a wider gap.
- Surfaces: GET /api/measurements/series takes kind=ketones and
  kind=glucoseKetoneIndex (each point names the paired readings), and the
  day carries glucoseKetoneIndex when both reading types are visible. The
  new Ketones page charts the readings with the index beneath; the day view
  shows the index beside the value tiles; the doctor report, its PDF and the
  clinician share print it in the glucose group when both leaves are chosen,
  since beside the ketones it gives the glucose back.
- FHIR: ketone readings export under LOINC 104816-4 (Beta hydroxybutyrate
  [Moles/volume] in Blood). The index is left out: it has no LOINC term,
  and both readings it is built from are in the bundle.
- The measurement form's action row moved into its own component to keep
  the form inside its size budget.

OpenAPI regenerated; all ten locales; the import unit table lists the type.
2026-11-10 19:28:57 +01:00

2164 lines
64 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* v1.25 — the SIGNAL REGISTRY backbone.
*
* One declarative table that describes a health signal ACROSS every surface
* it touches (DB measurement type, detail page, correlation engine, Coach
* snapshot, MCP read tool, FHIR coding). Today a single signal is described
* 8–16 times in independent tables keyed by slightly different vocabularies,
* and nothing fails the build when they disagree. This registry promotes the
* proto-registry in `metric-status-registry.ts` to the canonical definition
* and lets the per-surface tables DERIVE from it (see `./adapters/*`) instead
* of being hand-maintained beside it.
*
* Coexistence, not replacement: the DB enum stays the source of truth for
* persistence. The registry sits ABOVE it. Surfaces are flipped one at a time
* to read from the registry; the registry-invariant test pins every derived
* table byte-for-byte to the values the hand-written tables carry today, so a
* flip is a no-op diff and future drift fails CI.
*
* Adding a NEW signal (the clinical-signals wave): append ONE
* `SignalDefinition` object below, add its i18n keys, and — for a
* `measurement`/`score` — one Prisma enum member + migration. The derived
* tables (FHIR, correlation, …) light up with no further per-surface edits.
*/
import type { MeasurementType } from "@/generated/prisma/client";
import type {
MetricArchetype,
MetricDirection,
MetricNormalRange,
} from "@/lib/insights/metric-status-registry";
import type { FhirObservationCategory } from "@/lib/fhir/loinc-map";
import { FEVER_BAND_C } from "@/lib/clinical-floors";
/**
* Discriminator: a device/manual reading, a lab biomarker, a computed score, or
* an environmental exposure. `environment` (v1.25 W-ENV) is NOT backed by a
* `MeasurementType` — its daily value lives in `EnvironmentContext` and feeds
* the correlation engine through the env channel series builder, not the
* measurement-keyed `BUCKETED_TYPES`. It registers here so the env signals get
* a stable key + display metadata in the one cross-surface table.
*/
/** Reuse the assessment registry's direction vocabulary verbatim. */
export type SignalDirection = MetricDirection;
/** Coarse population placement band; the user's own baseline still leads. */
export type SignalBand = MetricNormalRange;
/**
* FHIR R4 coding facet. Field names align with `loinc-map.ts`'s `LoincMapping`
* (`unit` is the UCUM string, also used as the `code`) so the FHIR adapter is a
* straight projection with no renaming.
*/
export interface SignalFhirCoding {
/** LOINC code, or null when no stable LOINC applies (local text fallback). */
loinc: string | null;
display: string;
/** UCUM unit string (also used as the FHIR `code`). */
unit: string;
category: FhirObservationCategory;
}
/** Chart-overlay facet. Typed loosely (string overlayKey) to keep the backbone free of the dashboard-layout runtime dep. */
export interface SignalChart {
overlayKey: string;
color?: string;
yAxisUnit?: string;
/** Display rescale (e.g. m/s → km/h); applied at the chart edge only. */
valueScale?: number;
}
/**
* Per-surface eligibility — declarative flags, not branches scattered across
* files. `coachSnapshot.scope` is the Coach scope-source token (typed as a
* string here so the backbone does not depend on the coach module; the coach
* flip will tighten it to `CoachScopeSource`).
*/
export interface SignalSurfaces {
/** Mount the generic HealthKit/biomarker detail template. */
detailPage: boolean;
/** Feed the FDR correlation channels (⇒ `BUCKETED_TYPES`). */
correlationEligible: boolean;
/** Coach snapshot inclusion + its scope token, or `false` to opt out. */
coachSnapshot: false | { scope: string };
/** Exposed to the MCP `get_metric_series` / search inventory. */
mcp: boolean;
}
interface SignalCommon {
/** Stable signal key — the ONE vocabulary every surface speaks. */
key: string;
/** i18n key prefix resolving `.title`/`.description`/`.chartTitle`/`.emptyState.*`. Optional until the clinical-signals wave fills it per signal. */
i18nPrefix?: string;
/** Stable English display name (the model localises its own prose). */
displayName: string;
/** Canonical storage unit (matches the DB column semantics). */
unit: string;
direction: SignalDirection;
archetype: MetricArchetype;
normalRange?: SignalBand;
/** Single-reading fever band line (°C) for temperature signals. */
feverBandC?: number;
/** Richer clinical bands defer to a `reference-ranges.ts` entry by key. */
referenceMetric?: string;
/** Cross-source dedup ladder key; omit ⇒ not cross-source-deduped. */
sourcePriorityKey?: string;
chart?: SignalChart;
surfaces: SignalSurfaces;
fhir?: SignalFhirCoding;
}
/** How a `measurement`/`score` signal is sourced from the DB enum. */
export interface MeasurementSignalSource {
measurementType: MeasurementType;
/** Fallback measurement type (e.g. an SDNN→RMSSD HRV proxy). */
fallbackMeasurementType?: MeasurementType;
}
/** How a `biomarker` signal is sourced from the labs catalog. */
export interface BiomarkerSignalSource {
biomarkerKey: string;
}
/**
* How an `environment` signal is sourced (v1.25 W-ENV). The value is a daily
* `EnvironmentContext` column, surfaced to the correlation engine under
* `environmentChannelKey` (the `ENV_*` channel key from
* `@/lib/environment/fields`). No `MeasurementType` — env data is never a
* Measurement row.
*/
export interface EnvironmentSignalSource {
environmentChannelKey: string;
}
/**
* The canonical cross-surface signal definition, discriminated on `kind`.
* `measurement` and `score` both resolve to a `MeasurementType`; `biomarker`
* resolves to a labs-catalog key.
*/
export type SignalDefinition =
| (SignalCommon & { kind: "measurement"; source: MeasurementSignalSource })
| (SignalCommon & { kind: "score"; source: MeasurementSignalSource })
| (SignalCommon & { kind: "biomarker"; source: BiomarkerSignalSource })
| (SignalCommon & { kind: "environment"; source: EnvironmentSignalSource });
/** Convenience: build a Coach-snapshot facet from a scope token. */
function coachScope(scope: string): { scope: string } {
return { scope };
}
/**
* The registry. Keyed by stable signal key. Generic HealthKit signals key by
* their `metric-status-registry` id (STEPS, RESTING_HEART_RATE, …); the six
* specialised signals (WEIGHT/BMI/PULSE/BODY_FAT/BP_SYS/BP_DIA) key by their
* `MeasurementType` and carry `detailPage:false` so the generic template never
* double-renders them — they still appear in the cross-surface indices (FHIR,
* correlation, Coach, MCP).
*
* Every value here is the value the hand-written per-surface table carries
* today; the registry-invariant test pins them byte-for-byte.
*/
export const SIGNALS: Record<string, SignalDefinition> = {
// ── physiological-vital ──────────────────────────────────────────────
RESTING_HEART_RATE: {
key: "RESTING_HEART_RATE",
kind: "measurement",
source: { measurementType: "RESTING_HEART_RATE" },
sourcePriorityKey: "restingHeartRate",
i18nPrefix: "insights.restingHr",
displayName: "Resting heart rate",
unit: "bpm",
direction: "lower-better",
archetype: "physiological-vital",
normalRange: { low: 50, high: 100 },
referenceMetric: "RESTING_HEART_RATE",
chart: {
overlayKey: "restingHr",
color: "var(--destructive)",
yAxisUnit: "bpm",
},
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("resting_hr"),
mcp: true,
},
fhir: {
loinc: "40443-4",
display: "Heart rate --resting",
unit: "/min",
category: "vital-signs",
},
},
HEART_RATE_VARIABILITY: {
key: "HEART_RATE_VARIABILITY",
kind: "measurement",
source: { measurementType: "HEART_RATE_VARIABILITY" },
sourcePriorityKey: "hrv",
displayName: "Heart-rate variability (SDNN)",
unit: "ms",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("hrv"),
mcp: true,
},
fhir: {
loinc: "80404-7",
display: "R-R interval.standard deviation (Heart rate variability)",
unit: "ms",
category: "vital-signs",
},
},
// v1.44 — RMSSD, the heart-rate-variability statistic rings and bands
// report (Oura, WHOOP, Polar, Fitbit, Google Health). Registered for its FHIR
// coding only: every other surface reads it through its own tables today, so
// all surface flags stay off and nothing else derives from this entry.
// LOINC publishes an SDNN term (80404-7, above) and none for RMSSD, so the
// coding is text-only rather than borrowing SDNN's code for a different
// statistic.
HRV_RMSSD: {
key: "HRV_RMSSD",
kind: "measurement",
source: { measurementType: "HRV_RMSSD" },
displayName: "Heart-rate variability (RMSSD)",
unit: "ms",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: null,
display: "Heart rate variability RMSSD",
unit: "ms",
category: "vital-signs",
},
},
OXYGEN_SATURATION: {
key: "OXYGEN_SATURATION",
kind: "measurement",
source: { measurementType: "OXYGEN_SATURATION" },
sourcePriorityKey: "spo2",
displayName: "Blood oxygen (SpO₂)",
unit: "%",
direction: "higher-better",
archetype: "physiological-vital",
normalRange: { low: 95, high: 100 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("spo2"),
mcp: true,
},
fhir: {
loinc: "59408-5",
display: "Oxygen saturation in Arterial blood by Pulse oximetry",
unit: "%",
category: "vital-signs",
},
},
RESPIRATORY_RATE: {
key: "RESPIRATORY_RATE",
kind: "measurement",
source: { measurementType: "RESPIRATORY_RATE" },
sourcePriorityKey: "respiratoryRate",
displayName: "Respiratory rate",
unit: "breaths/min",
direction: "target-band",
archetype: "physiological-vital",
normalRange: { low: 12, high: 20 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("respiratory_rate"),
mcp: true,
},
fhir: {
loinc: "9279-1",
display: "Respiratory rate",
unit: "/min",
category: "vital-signs",
},
},
BODY_TEMPERATURE: {
key: "BODY_TEMPERATURE",
kind: "measurement",
source: { measurementType: "BODY_TEMPERATURE" },
sourcePriorityKey: "bodyTemperature",
displayName: "Body temperature",
unit: "°C",
direction: "target-band",
archetype: "physiological-vital",
normalRange: { low: 36.1, high: 37.2 },
feverBandC: FEVER_BAND_C,
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("body_temp"),
mcp: true,
},
fhir: {
loinc: "8310-5",
display: "Body temperature",
unit: "Cel",
category: "vital-signs",
},
},
SKIN_TEMPERATURE: {
key: "SKIN_TEMPERATURE",
kind: "measurement",
source: { measurementType: "SKIN_TEMPERATURE" },
sourcePriorityKey: "skinTemperature",
displayName: "Wrist skin temperature",
unit: "°C",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("skin_temp"),
mcp: true,
},
},
BLOOD_GLUCOSE: {
key: "BLOOD_GLUCOSE",
kind: "measurement",
source: { measurementType: "BLOOD_GLUCOSE" },
displayName: "Blood glucose",
unit: "mg/dL",
direction: "target-band",
archetype: "physiological-vital",
normalRange: { low: 70, high: 140 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("glucose"),
mcp: true,
},
},
// Blood ketones (#1367). Beta-hydroxybutyrate from a fingerstick meter,
// typed by hand. No band: what a ketone reading should be depends on the
// plan a clinician sets, so the value is shown as recorded. Off the Coach
// snapshot and the correlations, readable over MCP.
BLOOD_KETONES: {
key: "BLOOD_KETONES",
kind: "measurement",
source: { measurementType: "BLOOD_KETONES" },
displayName: "Blood ketones (BHB)",
unit: "mmol/L",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: true,
},
// LOINC 104816-4 "Beta hydroxybutyrate [Moles/volume] in Blood": the
// quantitative, method-less blood term. A typed value does not say
// whether it came from a strip or a venous draw, and the strip term
// (66441-7) is semi-quantitative, which a numeric mmol/L reading is not.
fhir: {
loinc: "104816-4",
display: "Beta hydroxybutyrate [Moles/volume] in Blood",
unit: "mmol/L",
category: "laboratory",
},
},
WALKING_HEART_RATE_AVERAGE: {
key: "WALKING_HEART_RATE_AVERAGE",
kind: "measurement",
source: { measurementType: "WALKING_HEART_RATE_AVERAGE" },
displayName: "Walking heart rate",
unit: "bpm",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_hr"),
mcp: true,
},
},
PULSE_WAVE_VELOCITY: {
key: "PULSE_WAVE_VELOCITY",
kind: "measurement",
source: { measurementType: "PULSE_WAVE_VELOCITY" },
displayName: "Pulse-wave velocity",
unit: "m/s",
direction: "lower-better",
archetype: "physiological-vital",
normalRange: { low: 0, high: 10 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("pulse_wave_velocity"),
mcp: true,
},
},
VASCULAR_AGE: {
key: "VASCULAR_AGE",
kind: "measurement",
source: { measurementType: "VASCULAR_AGE" },
displayName: "Vascular age",
unit: "years",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("vascular_age"),
mcp: true,
},
},
CARDIO_RECOVERY: {
key: "CARDIO_RECOVERY",
kind: "measurement",
source: { measurementType: "CARDIO_RECOVERY" },
displayName: "Cardio recovery",
unit: "bpm",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierHeartRateRecoveryOneMinute",
display: "Cardio recovery (1-minute heart-rate recovery)",
unit: "/min",
category: "vital-signs",
},
},
WRIST_TEMPERATURE: {
key: "WRIST_TEMPERATURE",
kind: "measurement",
source: { measurementType: "WRIST_TEMPERATURE" },
displayName: "Wrist temperature",
unit: "°C",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierAppleSleepingWristTemperature",
display: "Sleeping wrist temperature",
unit: "Cel",
category: "vital-signs",
},
},
ANS_CHARGE: {
key: "ANS_CHARGE",
kind: "measurement",
source: { measurementType: "ANS_CHARGE" },
displayName: "ANS charge",
unit: "score",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
AVERAGE_HEART_RATE: {
key: "AVERAGE_HEART_RATE",
kind: "measurement",
source: { measurementType: "AVERAGE_HEART_RATE" },
displayName: "Average heart rate",
unit: "bpm",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
MAX_HEART_RATE: {
key: "MAX_HEART_RATE",
kind: "measurement",
source: { measurementType: "MAX_HEART_RATE" },
displayName: "Max heart rate",
unit: "bpm",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
// ── activity-fitness ─────────────────────────────────────────────────
STEPS: {
key: "STEPS",
kind: "measurement",
source: { measurementType: "ACTIVITY_STEPS" },
sourcePriorityKey: "steps",
displayName: "Steps",
unit: "steps/day",
direction: "higher-better",
archetype: "activity-fitness",
normalRange: { low: 8000, high: 15000 },
surfaces: {
detailPage: true,
correlationEligible: true,
coachSnapshot: coachScope("steps"),
mcp: true,
},
fhir: {
loinc: "41950-7",
display: "Number of steps in 24 hour Measured",
unit: "{steps}",
category: "activity",
},
},
ACTIVE_ENERGY: {
key: "ACTIVE_ENERGY",
kind: "measurement",
source: { measurementType: "ACTIVE_ENERGY_BURNED" },
sourcePriorityKey: "activeEnergy",
displayName: "Active energy",
unit: "kcal/day",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("active_energy"),
mcp: true,
},
fhir: {
loinc: "41981-2",
display: "Calories burned",
unit: "kcal",
category: "activity",
},
},
// Resting energy (#1340). Stored, charted and exported; read
// through MCP like active energy, but kept off the Coach snapshot and the
// correlations, and no score or total is built from it.
BASAL_ENERGY: {
key: "BASAL_ENERGY",
kind: "measurement",
source: { measurementType: "BASAL_ENERGY_BURNED" },
displayName: "Resting energy",
unit: "kcal/day",
direction: "target-band",
archetype: "activity-fitness",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierBasalEnergyBurned",
display: "Resting energy",
unit: "kcal",
category: "activity",
},
},
FLIGHTS_CLIMBED: {
key: "FLIGHTS_CLIMBED",
kind: "measurement",
source: { measurementType: "FLIGHTS_CLIMBED" },
sourcePriorityKey: "flightsClimbed",
displayName: "Flights climbed",
unit: "flights/day",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("flights"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierFlightsClimbed",
display: "Flights climbed",
unit: "{flights}",
category: "activity",
},
},
WALKING_RUNNING_DISTANCE: {
key: "WALKING_RUNNING_DISTANCE",
kind: "measurement",
source: { measurementType: "WALKING_RUNNING_DISTANCE" },
sourcePriorityKey: "walkingRunningDistance",
displayName: "Walking + running distance",
unit: "m/day",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("distance"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierDistanceWalkingRunning",
display: "Distance walking/running",
unit: "m",
category: "activity",
},
},
TIME_IN_DAYLIGHT: {
key: "TIME_IN_DAYLIGHT",
kind: "measurement",
source: { measurementType: "TIME_IN_DAYLIGHT" },
displayName: "Time in daylight",
unit: "min/day",
direction: "higher-better",
archetype: "activity-fitness",
normalRange: { low: 30, high: 120 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("daylight"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierTimeInDaylight",
display: "Time in daylight",
unit: "min",
category: "activity",
},
},
VO2_MAX: {
key: "VO2_MAX",
kind: "measurement",
source: { measurementType: "VO2_MAX" },
sourcePriorityKey: "vo2Max",
displayName: "VO₂ max (cardio fitness)",
unit: "mL/(kg·min)",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("vo2_max"),
mcp: true,
},
fhir: {
// 96402-2, used before, does not exist in LOINC. The watch estimate is
// not a measured exercise-test VO2 peak (94122-9), so the HealthKit
// identifier rides the custom system.
loinc: "HKQuantityTypeIdentifierVO2Max",
display: "VO2 max (estimated)",
unit: "mL/min/kg",
category: "vital-signs",
},
},
DAY_STRAIN: {
key: "DAY_STRAIN",
kind: "measurement",
source: { measurementType: "DAY_STRAIN" },
displayName: "Day strain",
unit: "score",
direction: "target-band",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
WORKOUT_STRAIN: {
key: "WORKOUT_STRAIN",
kind: "measurement",
source: { measurementType: "WORKOUT_STRAIN" },
displayName: "Workout strain",
unit: "score",
direction: "target-band",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
// ── Garmin day scores and the bridged training figures ──
BODY_BATTERY: {
key: "BODY_BATTERY",
kind: "measurement",
source: { measurementType: "BODY_BATTERY" },
displayName: "Body Battery",
unit: "score",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
STRESS_LEVEL: {
key: "STRESS_LEVEL",
kind: "measurement",
source: { measurementType: "STRESS_LEVEL" },
displayName: "Stress level",
unit: "score",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
TRAINING_READINESS: {
key: "TRAINING_READINESS",
kind: "measurement",
source: { measurementType: "TRAINING_READINESS" },
displayName: "Training readiness",
unit: "score",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
ACUTE_TRAINING_LOAD: {
key: "ACUTE_TRAINING_LOAD",
kind: "measurement",
source: { measurementType: "ACUTE_TRAINING_LOAD" },
displayName: "Acute training load",
unit: "load",
direction: "target-band",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
CARDIO_LOAD: {
key: "CARDIO_LOAD",
kind: "measurement",
source: { measurementType: "CARDIO_LOAD" },
displayName: "Cardio load",
unit: "score",
direction: "target-band",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
ENERGY_EXPENDITURE_KJ: {
key: "ENERGY_EXPENDITURE_KJ",
kind: "measurement",
source: { measurementType: "ENERGY_EXPENDITURE_KJ" },
displayName: "Energy expenditure",
unit: "kJ",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
// ── body-composition ─────────────────────────────────────────────────
TOTAL_BODY_WATER: {
key: "TOTAL_BODY_WATER",
kind: "measurement",
source: { measurementType: "TOTAL_BODY_WATER" },
displayName: "Total body water",
unit: "kg",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("total_body_water"),
mcp: true,
},
fhir: {
// 73704-9, used before, is a nasogastric fluid output.
loinc: "101683-1",
display: "Body water mass",
unit: "kg",
category: "vital-signs",
},
},
BONE_MASS: {
key: "BONE_MASS",
kind: "measurement",
source: { measurementType: "BONE_MASS" },
displayName: "Bone mass",
unit: "kg",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("bone_mass"),
mcp: true,
},
fhir: {
// 73708-0, used before, is "Body fat [Mass] Calculated".
loinc: "101685-6",
display: "Body bone mass",
unit: "kg",
category: "vital-signs",
},
},
FAT_FREE_MASS: {
key: "FAT_FREE_MASS",
kind: "measurement",
source: { measurementType: "FAT_FREE_MASS" },
displayName: "Fat-free mass",
unit: "kg",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("fat_free_mass"),
mcp: true,
},
fhir: {
loinc: null,
display: "Fat-free mass",
unit: "kg",
category: "vital-signs",
},
},
FAT_MASS: {
key: "FAT_MASS",
kind: "measurement",
source: { measurementType: "FAT_MASS" },
displayName: "Fat mass",
unit: "kg",
direction: "lower-better",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("fat_mass"),
mcp: true,
},
fhir: {
loinc: null,
display: "Fat mass",
unit: "kg",
category: "vital-signs",
},
},
MUSCLE_MASS: {
key: "MUSCLE_MASS",
kind: "measurement",
source: { measurementType: "MUSCLE_MASS" },
displayName: "Muscle mass",
unit: "kg",
direction: "higher-better",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("muscle_mass"),
mcp: true,
},
fhir: {
loinc: null,
display: "Muscle mass",
unit: "kg",
category: "vital-signs",
},
},
LEAN_BODY_MASS: {
key: "LEAN_BODY_MASS",
kind: "measurement",
source: { measurementType: "LEAN_BODY_MASS" },
displayName: "Lean body mass",
unit: "kg",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("lean_body_mass"),
mcp: true,
},
fhir: {
loinc: null,
display: "Lean body mass",
unit: "kg",
category: "vital-signs",
},
},
VISCERAL_FAT: {
key: "VISCERAL_FAT",
kind: "measurement",
source: { measurementType: "VISCERAL_FAT" },
displayName: "Visceral fat rating",
unit: "rating",
direction: "lower-better",
archetype: "body-composition",
normalRange: { low: 1, high: 12 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("visceral_fat"),
mcp: true,
},
fhir: {
loinc: null,
display: "Visceral fat",
unit: "1",
category: "vital-signs",
},
},
// ── mobility-gait ────────────────────────────────────────────────────
WALKING_STEADINESS: {
key: "WALKING_STEADINESS",
kind: "measurement",
source: { measurementType: "WALKING_STEADINESS" },
displayName: "Walking steadiness",
unit: "%",
direction: "higher-better",
archetype: "mobility-gait",
normalRange: { low: 50, high: 100 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_steadiness"),
mcp: true,
},
},
WALKING_ASYMMETRY: {
key: "WALKING_ASYMMETRY",
kind: "measurement",
source: { measurementType: "WALKING_ASYMMETRY" },
displayName: "Walking asymmetry",
unit: "%",
direction: "lower-better",
archetype: "mobility-gait",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_asymmetry"),
mcp: true,
},
fhir: {
// 91557-1, used before, does not exist in LOINC.
loinc: "HKQuantityTypeIdentifierWalkingAsymmetryPercentage",
display: "Walking asymmetry percentage",
unit: "%",
category: "vital-signs",
},
},
WALKING_DOUBLE_SUPPORT: {
key: "WALKING_DOUBLE_SUPPORT",
kind: "measurement",
source: { measurementType: "WALKING_DOUBLE_SUPPORT" },
displayName: "Double-support time",
unit: "%",
direction: "lower-better",
archetype: "mobility-gait",
normalRange: { low: 20, high: 40 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_double_support"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierWalkingDoubleSupportPercentage",
display: "Walking double support percentage",
unit: "%",
category: "vital-signs",
},
},
WALKING_STEP_LENGTH: {
key: "WALKING_STEP_LENGTH",
kind: "measurement",
source: { measurementType: "WALKING_STEP_LENGTH" },
displayName: "Step length",
unit: "m",
direction: "higher-better",
archetype: "mobility-gait",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_step_length"),
mcp: true,
},
fhir: {
// 41955-6, used before, is "Distance walked in 1 week"; LOINC has no
// step-length term, so the HealthKit identifier rides the custom system.
loinc: "HKQuantityTypeIdentifierWalkingStepLength",
display: "Walking step length",
unit: "m",
category: "vital-signs",
},
},
WALKING_SPEED: {
key: "WALKING_SPEED",
kind: "measurement",
source: { measurementType: "WALKING_SPEED" },
displayName: "Walking speed",
unit: "m/s",
direction: "higher-better",
archetype: "mobility-gait",
normalRange: { low: 1.2, high: 1.4 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("walking_speed"),
mcp: true,
},
fhir: {
// 41957-2, used before, is a 24-hour mean walking speed; the value
// here is a HealthKit walking-speed reading.
loinc: "HKQuantityTypeIdentifierWalkingSpeed",
display: "Walking speed",
unit: "m/s",
category: "vital-signs",
},
},
FALL_COUNT: {
key: "FALL_COUNT",
kind: "measurement",
source: { measurementType: "FALL_COUNT" },
displayName: "Falls",
unit: "falls/day",
direction: "lower-better",
archetype: "mobility-gait",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierNumberOfTimesFallen",
display: "Number of times fallen",
unit: "{falls}",
category: "activity",
},
},
SIX_MINUTE_WALK_DISTANCE: {
key: "SIX_MINUTE_WALK_DISTANCE",
kind: "measurement",
source: { measurementType: "SIX_MINUTE_WALK_DISTANCE" },
displayName: "Six-minute walk distance",
unit: "m",
direction: "higher-better",
archetype: "mobility-gait",
normalRange: { low: 400, high: 700 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierSixMinuteWalkTestDistance",
display: "Six-minute walk test distance",
unit: "m",
category: "activity",
},
},
STAIR_ASCENT_SPEED: {
key: "STAIR_ASCENT_SPEED",
kind: "measurement",
source: { measurementType: "STAIR_ASCENT_SPEED" },
displayName: "Stair ascent speed",
unit: "m/s",
direction: "higher-better",
archetype: "mobility-gait",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierStairAscentSpeed",
display: "Stair ascent speed",
unit: "m/s",
category: "vital-signs",
},
},
STAIR_DESCENT_SPEED: {
key: "STAIR_DESCENT_SPEED",
kind: "measurement",
source: { measurementType: "STAIR_DESCENT_SPEED" },
displayName: "Stair descent speed",
unit: "m/s",
direction: "higher-better",
archetype: "mobility-gait",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierStairDescentSpeed",
display: "Stair descent speed",
unit: "m/s",
category: "vital-signs",
},
},
// ── environmental-exposure ───────────────────────────────────────────
AUDIO_EXPOSURE_ENV: {
key: "AUDIO_EXPOSURE_ENV",
kind: "measurement",
source: { measurementType: "AUDIO_EXPOSURE_ENV" },
displayName: "Environmental sound exposure",
unit: "dBA",
direction: "lower-better",
archetype: "environmental-exposure",
normalRange: { low: 0, high: 80 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("audio_env"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierEnvironmentalAudioExposure",
display: "Environmental audio exposure",
unit: "dB[A]",
category: "vital-signs",
},
},
AUDIO_EXPOSURE_HEADPHONE: {
key: "AUDIO_EXPOSURE_HEADPHONE",
kind: "measurement",
source: { measurementType: "AUDIO_EXPOSURE_HEADPHONE" },
displayName: "Headphone audio exposure",
unit: "dBA",
direction: "lower-better",
archetype: "environmental-exposure",
normalRange: { low: 0, high: 80 },
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("audio_headphone"),
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierHeadphoneAudioExposure",
display: "Headphone audio exposure",
unit: "dB[A]",
category: "vital-signs",
},
},
AUDIO_EXPOSURE_EVENT: {
key: "AUDIO_EXPOSURE_EVENT",
kind: "measurement",
source: { measurementType: "AUDIO_EXPOSURE_EVENT" },
displayName: "Loud-exposure events",
unit: "events",
direction: "lower-better",
archetype: "environmental-exposure",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: coachScope("audio_event"),
mcp: true,
},
},
// ── sleep (dedicated template) ───────────────────────────────────────
SLEEP_DURATION: {
key: "SLEEP_DURATION",
kind: "measurement",
source: { measurementType: "SLEEP_DURATION" },
sourcePriorityKey: "sleep",
displayName: "Sleep duration",
unit: "min",
direction: "target-band",
archetype: "sleep",
normalRange: { low: 420, high: 540 },
surfaces: {
detailPage: true,
correlationEligible: true,
coachSnapshot: coachScope("sleep"),
mcp: true,
},
fhir: {
loinc: "93832-4",
display: "Sleep duration",
unit: "h",
category: "activity",
},
},
BREATHING_DISTURBANCES: {
key: "BREATHING_DISTURBANCES",
kind: "measurement",
source: { measurementType: "BREATHING_DISTURBANCES" },
displayName: "Sleep breathing disturbances",
unit: "count",
direction: "lower-better",
archetype: "sleep",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierAppleSleepingBreathingDisturbances",
display: "Sleeping breathing disturbances",
unit: "{count}",
category: "vital-signs",
},
},
SLEEP_SCORE: {
key: "SLEEP_SCORE",
kind: "measurement",
source: { measurementType: "SLEEP_SCORE" },
displayName: "Sleep score",
unit: "score",
direction: "higher-better",
archetype: "sleep",
surfaces: {
detailPage: true,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
// ── specialised metrics (bespoke status files; detailPage:false) ──────
// These keep their dedicated scopes + status generators; they register
// only so the cross-surface indices (FHIR, correlation, Coach, MCP) see
// them without routing them through the generic detail template.
WEIGHT: {
key: "WEIGHT",
kind: "measurement",
source: { measurementType: "WEIGHT" },
sourcePriorityKey: "weight",
displayName: "Weight",
unit: "kg",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: coachScope("weight"),
mcp: true,
},
fhir: {
loinc: "29463-7",
display: "Body weight",
unit: "kg",
category: "vital-signs",
},
},
BODY_MASS_INDEX: {
key: "BODY_MASS_INDEX",
kind: "measurement",
source: { measurementType: "BODY_MASS_INDEX" },
displayName: "Body mass index",
unit: "kg/m²",
direction: "target-band",
archetype: "body-composition",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: coachScope("bmi"),
mcp: true,
},
fhir: {
loinc: "39156-5",
display: "Body mass index (BMI) [Ratio]",
unit: "kg/m2",
category: "vital-signs",
},
},
PULSE: {
key: "PULSE",
kind: "measurement",
source: { measurementType: "PULSE" },
sourcePriorityKey: "pulse",
displayName: "Pulse",
unit: "bpm",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: coachScope("pulse"),
mcp: true,
},
fhir: {
loinc: "8867-4",
display: "Heart rate",
unit: "/min",
category: "vital-signs",
},
},
BODY_FAT: {
key: "BODY_FAT",
kind: "measurement",
source: { measurementType: "BODY_FAT" },
sourcePriorityKey: "bodyFat",
displayName: "Body fat",
unit: "%",
direction: "lower-better",
archetype: "body-composition",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: coachScope("body_fat"),
mcp: true,
},
fhir: {
loinc: "41982-0",
display: "Percentage of body fat Measured",
unit: "%",
category: "vital-signs",
},
},
BLOOD_PRESSURE_SYS: {
key: "BLOOD_PRESSURE_SYS",
kind: "measurement",
source: { measurementType: "BLOOD_PRESSURE_SYS" },
sourcePriorityKey: "bloodPressure",
displayName: "Blood pressure (systolic)",
unit: "mmHg",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: coachScope("bp"),
mcp: true,
},
},
BLOOD_PRESSURE_DIA: {
key: "BLOOD_PRESSURE_DIA",
kind: "measurement",
source: { measurementType: "BLOOD_PRESSURE_DIA" },
sourcePriorityKey: "bloodPressure",
displayName: "Blood pressure (diastolic)",
unit: "mmHg",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: coachScope("bp"),
mcp: true,
},
},
// ── v1.25 clinical-signals wave — validated mental-health screeners ──────
// PHQ-9 / GAD-7 totals. Opt-in, beside mood tracking. Deliberately kept OFF
// the Coach snapshot + MCP surfaces (`coachSnapshot:false` ⇒ `mcp:false`):
// mental-health item content is excluded from AI by construction, and the
// score trend stays a quiet local signal. FHIR rides the `survey` category
// with the instrument total-score LOINC.
PHQ9_SCORE: {
key: "PHQ9_SCORE",
kind: "score",
source: { measurementType: "PHQ9_SCORE" },
displayName: "PHQ-9 depression screen (total)",
unit: "score",
direction: "lower-better",
archetype: "physiological-vital",
normalRange: { low: 0, high: 4 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "44261-6",
display:
"Patient Health Questionnaire 9 item (PHQ-9) total score [Reported]",
unit: "{score}",
category: "survey",
},
},
GAD7_SCORE: {
key: "GAD7_SCORE",
kind: "score",
source: { measurementType: "GAD7_SCORE" },
displayName: "GAD-7 anxiety screen (total)",
unit: "score",
direction: "lower-better",
archetype: "physiological-vital",
normalRange: { low: 0, high: 4 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "70274-6",
display:
"Generalized anxiety disorder 7 item (GAD-7) total score [Reported.PHQ]",
unit: "{score}",
category: "survey",
},
},
// ── v1.27.9 — WHO-5 well-being + Sleep Condition Indicator totals ───────
// Same privacy posture as PHQ-9 / GAD-7 (off Coach snapshot + MCP; item
// content never rides a Measurement row). Direction inverts: HIGHER is
// better for both. No verified total-score LOINC exists for either, so both
// carry the `loinc: null` text-only survey concept the physical signals
// already use — an uncoded finding a clinician can read, never an invented
// code. Without a `fhir` facet the FHIR adapter drops a signal entirely,
// which is how a total the PDF and the share view show went missing from
// every FHIR output.
WHO5_SCORE: {
key: "WHO5_SCORE",
kind: "score",
source: { measurementType: "WHO5_SCORE" },
displayName: "WHO-5 well-being index (0–100)",
unit: "score",
direction: "higher-better",
archetype: "physiological-vital",
// "Below 50" is the WHO-suggested cut-off; achievable totals are
// multiples of 4, so ≥ 52 is the good side.
normalRange: { low: 52, high: 100 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// No verified total-score LOINC — local text concept, `{score}` UCUM.
loinc: null,
display: "WHO-5 well-being index total score",
unit: "{score}",
category: "survey",
},
},
SCI_SCORE: {
key: "SCI_SCORE",
kind: "score",
source: { measurementType: "SCI_SCORE" },
displayName: "Sleep Condition Indicator (total)",
unit: "score",
direction: "higher-better",
archetype: "physiological-vital",
// > 16 identified "no insomnia disorder" in Espie et al. 2014.
normalRange: { low: 17, high: 32 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// No verified total-score LOINC — local text concept, `{score}` UCUM.
loinc: null,
display: "Sleep Condition Indicator total score",
unit: "{score}",
category: "survey",
},
},
// ── v1.25 clinical-signals wave — physical / clinical measurements ──────
GRIP_STRENGTH: {
key: "GRIP_STRENGTH",
kind: "measurement",
source: { measurementType: "GRIP_STRENGTH" },
displayName: "Grip strength",
unit: "kg",
direction: "higher-better",
archetype: "activity-fitness",
// Coarse population floor; the EWGSOP2 cut-off is sex-specific (men < 27,
// women < 16 kg) and resolved at the display edge by the sex-aware band
// resolver (`norms.ts` GRIP_STRENGTH table) the detail-page assessment
// threads through `lookupNormalRange`.
normalRange: { low: 16, high: 60 },
surfaces: {
detailPage: true,
correlationEligible: false,
// Off the Coach snapshot, but reachable over MCP: the `mcp` facet is
// independent of `coachSnapshot`. The MCP rich reads expose it through
// the rollup-backed baseline / compare / change-point reads.
coachSnapshot: false,
mcp: true,
},
fhir: {
// NEEDS-VERIFY: no hand-grip-strength LOINC confirmed this pass —
// emits a local text concept until a stable LOINC is checked on loinc.org.
loinc: null,
display: "Hand grip strength",
unit: "kg",
category: "vital-signs",
},
},
PAIN_NRS: {
key: "PAIN_NRS",
kind: "measurement",
source: { measurementType: "PAIN_NRS" },
displayName: "Pain (0–10 NRS)",
unit: "score",
direction: "lower-better",
archetype: "physiological-vital",
normalRange: { low: 0, high: 3 },
surfaces: {
detailPage: true,
correlationEligible: false,
// Off the Coach snapshot, reachable over MCP (independent facets).
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "72514-3",
display: "Pain severity - 0-10 verbal numeric rating [Score] - Reported",
unit: "{score}",
category: "survey",
},
},
WAIST_CIRCUMFERENCE: {
key: "WAIST_CIRCUMFERENCE",
kind: "measurement",
source: { measurementType: "WAIST_CIRCUMFERENCE" },
sourcePriorityKey: "waist",
displayName: "Waist circumference",
unit: "cm",
direction: "lower-better",
archetype: "body-composition",
// WHO European-origin increased-risk threshold (men > 94); the sex-aware
// resolver (`norms.ts` WAIST_CIRCUMFERENCE table: men 94 / women 80)
// sharpens it at the display edge via `lookupNormalRange`.
normalRange: { low: 0, high: 94 },
surfaces: {
detailPage: true,
correlationEligible: false,
// Off the Coach snapshot, reachable over MCP (independent facets).
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "8280-0",
display: "Waist circumference at umbilicus by Tape measure",
unit: "cm",
category: "vital-signs",
},
},
WAIST_TO_HEIGHT: {
key: "WAIST_TO_HEIGHT",
kind: "measurement",
source: { measurementType: "WAIST_TO_HEIGHT" },
displayName: "Waist-to-height ratio",
unit: "ratio",
direction: "lower-better",
archetype: "body-composition",
// NICE: keep waist under half your height — WHtR ≥ 0.5 flags increased
// risk, so the last in-range value sits just below the 0.5 threshold
// (`high: 0.49`) and a 0.50 reading classifies as increased, not normal.
normalRange: { low: 0, high: 0.49 },
surfaces: {
detailPage: true,
correlationEligible: false,
// Off the Coach snapshot, reachable over MCP (independent facets).
coachSnapshot: false,
mcp: true,
},
fhir: {
// NEEDS-VERIFY: WHtR LOINC not confirmed this pass — local text concept.
loinc: null,
display: "Waist to height ratio",
unit: "1",
category: "vital-signs",
},
},
// ── v1.25 clinical-signals wave — longevity lab panel (kind:"biomarker") ─
// Registered through the registry to prove the labs path under one definition
// shape. The lab FHIR/UCUM coding lives in `fhir/lab-loinc.ts`; the
// biomarker-detail rail renders these via the labs catalog. Off Coach/MCP
// here (the labs surface has its own `get_labs` MCP tool).
APOB: {
key: "APOB",
kind: "biomarker",
source: { biomarkerKey: "apob" },
displayName: "Apolipoprotein B",
unit: "mg/dL",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
LPA: {
key: "LPA",
kind: "biomarker",
source: { biomarkerKey: "lp-a" },
displayName: "Lipoprotein(a)",
unit: "nmol/L",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
HS_CRP: {
key: "HS_CRP",
kind: "biomarker",
source: { biomarkerKey: "hs-crp" },
displayName: "hs-CRP",
unit: "mg/L",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
HBA1C: {
key: "HBA1C",
kind: "biomarker",
source: { biomarkerKey: "hba1c" },
displayName: "HbA1c",
unit: "%",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
FASTING_GLUCOSE: {
key: "FASTING_GLUCOSE",
kind: "biomarker",
source: { biomarkerKey: "fasting-glucose" },
displayName: "Fasting glucose",
unit: "mg/dL",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
FASTING_INSULIN: {
key: "FASTING_INSULIN",
kind: "biomarker",
source: { biomarkerKey: "fasting-insulin" },
displayName: "Fasting insulin",
unit: "µIU/mL",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
EGFR: {
key: "EGFR",
kind: "biomarker",
source: { biomarkerKey: "egfr" },
displayName: "eGFR (CKD-EPI 2021)",
unit: "mL/min/1.73m²",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
GGT: {
key: "GGT",
kind: "biomarker",
source: { biomarkerKey: "ggt" },
displayName: "GGT",
unit: "U/L",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
FERRITIN: {
key: "FERRITIN",
kind: "biomarker",
source: { biomarkerKey: "ferritin" },
displayName: "Ferritin",
unit: "ng/mL",
direction: "target-band",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
OMEGA3_INDEX: {
key: "OMEGA3_INDEX",
kind: "biomarker",
source: { biomarkerKey: "omega-3-index" },
displayName: "Omega-3 index",
unit: "%",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
},
// ── v1.25 (W-ENV) environmental-context module — exposure signals ─────────
// Daily weather/daylight, fetched server-side from Open-Meteo for the user's
// coarse home (or a travel override) and stored in `EnvironmentContext`. NOT
// `MeasurementType`-backed: `correlationEligible:true` declares intent, but
// the wiring runs through the env channel series builder, not the
// measurement-keyed `BUCKETED_TYPES` (the correlation adapter skips
// `kind:"environment"`). Off the Coach snapshot + MCP surfaces in v1
// (`coachSnapshot:false ⇒ mcp:false`); no FHIR facet (env observations are
// not Measurement rows, so they never enter `MEASUREMENT_LOINC`). Direction is
// `target-band` — a neutral exposure, not a "better/worse" vital.
ENV_TEMP_MEAN: {
key: "ENV_TEMP_MEAN",
kind: "environment",
source: { environmentChannelKey: "ENV_TEMP_MEAN" },
i18nPrefix: "environment.fields.tempMean",
displayName: "Daily temperature",
unit: "°C",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_TEMP_MIN: {
key: "ENV_TEMP_MIN",
kind: "environment",
source: { environmentChannelKey: "ENV_TEMP_MIN" },
i18nPrefix: "environment.fields.tempMin",
displayName: "Overnight low temperature",
unit: "°C",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_SUNSHINE: {
key: "ENV_SUNSHINE",
kind: "environment",
source: { environmentChannelKey: "ENV_SUNSHINE" },
i18nPrefix: "environment.fields.sunshine",
displayName: "Sunshine duration",
unit: "h",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_DAYLIGHT: {
key: "ENV_DAYLIGHT",
kind: "environment",
source: { environmentChannelKey: "ENV_DAYLIGHT" },
i18nPrefix: "environment.fields.daylight",
displayName: "Daylight length",
unit: "h",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_PRECIP: {
key: "ENV_PRECIP",
kind: "environment",
source: { environmentChannelKey: "ENV_PRECIP" },
i18nPrefix: "environment.fields.precip",
displayName: "Precipitation",
unit: "mm",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_PRESSURE_MEAN: {
key: "ENV_PRESSURE_MEAN",
kind: "environment",
source: { environmentChannelKey: "ENV_PRESSURE_MEAN" },
i18nPrefix: "environment.fields.pressureMean",
displayName: "Barometric pressure",
unit: "hPa",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_PRESSURE_DELTA: {
key: "ENV_PRESSURE_DELTA",
kind: "environment",
source: { environmentChannelKey: "ENV_PRESSURE_DELTA" },
i18nPrefix: "environment.fields.pressureDelta",
displayName: "Pressure swing",
unit: "hPa",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
}, // ── v1.42 (#615) air-quality exposure channels ───────────────────────────
// Three correlation channels out of the air-quality feed: fine particles,
// the ozone 8-hour high, and the day's highest pollen count. UV, NO2 and
// dust are display and Coach context only. Same surface flags as the weather
// channels above; the channel series builder carries the wiring.
ENV_PM25: {
key: "ENV_PM25",
kind: "environment",
source: { environmentChannelKey: "ENV_PM25" },
i18nPrefix: "environment.fields.pm25",
displayName: "Fine particles (PM2.5)",
unit: "µg/m³",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_OZONE_8H: {
key: "ENV_OZONE_8H",
kind: "environment",
source: { environmentChannelKey: "ENV_OZONE_8H" },
i18nPrefix: "environment.fields.ozone8h",
displayName: "Ozone (8-hour high)",
unit: "µg/m³",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
ENV_POLLEN_MAX: {
key: "ENV_POLLEN_MAX",
kind: "environment",
source: { environmentChannelKey: "ENV_POLLEN_MAX" },
i18nPrefix: "environment.fields.pollenMax",
displayName: "Pollen (highest)",
unit: "grains/m³",
direction: "target-band",
archetype: "environmental-exposure",
surfaces: {
detailPage: false,
correlationEligible: true,
coachSnapshot: false,
mcp: false,
},
},
// ── v1.44 — Apple Health activity rings, mindfulness, State of Mind, AFib ──
// The three ring metrics are read through MCP like steps and daylight. The
// mindful minutes, the State of Mind valence and AFib burden stay off every
// AI-facing surface (Coach, MCP, correlations): mental-health self-reports
// and an AFib awareness signal are shared only where the person asks.
EXERCISE_MINUTES: {
key: "EXERCISE_MINUTES",
kind: "measurement",
source: { measurementType: "EXERCISE_MINUTES" },
displayName: "Exercise minutes",
unit: "min/day",
direction: "higher-better",
archetype: "activity-fitness",
// Apple's exercise ring default and the WHO weekly 150 minutes / 7.
normalRange: { low: 22, high: 60 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierAppleExerciseTime",
display: "Exercise time",
unit: "min",
category: "activity",
},
},
STAND_MINUTES: {
key: "STAND_MINUTES",
kind: "measurement",
source: { measurementType: "STAND_MINUTES" },
displayName: "Standing minutes",
unit: "min/day",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "HKQuantityTypeIdentifierAppleStandTime",
display: "Stand time",
unit: "min",
category: "activity",
},
},
STAND_HOURS: {
key: "STAND_HOURS",
kind: "measurement",
source: { measurementType: "STAND_HOURS" },
displayName: "Stand hours",
unit: "h/day",
direction: "higher-better",
archetype: "activity-fitness",
// Apple's stand-ring goal is 12 hours.
normalRange: { low: 12, high: 24 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: true,
},
fhir: {
loinc: "HKCategoryTypeIdentifierAppleStandHour",
display: "Stand hours",
unit: "h",
category: "activity",
},
},
MINDFUL_MINUTES: {
key: "MINDFUL_MINUTES",
kind: "measurement",
source: { measurementType: "MINDFUL_MINUTES" },
displayName: "Mindful minutes",
unit: "min/day",
direction: "higher-better",
archetype: "activity-fitness",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKCategoryTypeIdentifierMindfulSession",
display: "Mindful session",
unit: "min",
category: "activity",
},
},
STATE_OF_MIND_VALENCE: {
key: "STATE_OF_MIND_VALENCE",
kind: "score",
source: { measurementType: "STATE_OF_MIND_VALENCE" },
displayName: "State of mind (valence)",
unit: "valence",
direction: "higher-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// A self-report on HealthKit's −1..1 scale; no LOINC concept.
loinc: null,
display: "State of mind valence",
unit: "1",
category: "survey",
},
},
AFIB_BURDEN: {
key: "AFIB_BURDEN",
kind: "measurement",
source: { measurementType: "AFIB_BURDEN" },
displayName: "AFib burden",
unit: "%",
direction: "lower-better",
archetype: "physiological-vital",
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
loinc: "HKQuantityTypeIdentifierAtrialFibrillationBurden",
display: "Atrial fibrillation burden",
unit: "%",
category: "vital-signs",
},
},
// ── v1.44 — room climate pushed through the ingest token ──
// Bands are the usual comfort guidance (CO2 under 1000 ppm as the long-
// standing ventilation threshold, 18–24 °C, 40–60 % RH); placement only.
INDOOR_CO2: {
key: "INDOOR_CO2",
kind: "measurement",
source: { measurementType: "INDOOR_CO2" },
displayName: "Indoor CO2",
unit: "ppm",
direction: "target-band",
archetype: "environmental-exposure",
normalRange: { low: 400, high: 1000 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// A room reading, not a body observation; no LOINC concept applies.
loinc: null,
display: "Indoor carbon dioxide",
unit: "[ppm]",
category: "activity",
},
},
INDOOR_TEMPERATURE: {
key: "INDOOR_TEMPERATURE",
kind: "measurement",
source: { measurementType: "INDOOR_TEMPERATURE" },
displayName: "Indoor temperature",
unit: "°C",
direction: "target-band",
archetype: "environmental-exposure",
normalRange: { low: 18, high: 24 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// A room reading, not a body observation; no LOINC concept applies.
loinc: null,
display: "Indoor air temperature",
unit: "Cel",
category: "activity",
},
},
INDOOR_HUMIDITY: {
key: "INDOOR_HUMIDITY",
kind: "measurement",
source: { measurementType: "INDOOR_HUMIDITY" },
displayName: "Indoor humidity",
unit: "%",
direction: "target-band",
archetype: "environmental-exposure",
normalRange: { low: 40, high: 60 },
surfaces: {
detailPage: false,
correlationEligible: false,
coachSnapshot: false,
mcp: false,
},
fhir: {
// A room reading, not a body observation; no LOINC concept applies.
loinc: null,
display: "Indoor relative humidity",
unit: "%",
category: "activity",
},
},
};
/** Type guard: narrow an arbitrary string to a registered signal key. */
export function isSignalKey(key: string): boolean {
return Object.prototype.hasOwnProperty.call(SIGNALS, key);
}
/** Resolve a signal by its key, or null when unregistered. */
export function getSignal(key: string): SignalDefinition | null {
return isSignalKey(key) ? SIGNALS[key] : null;
}
/** Every registered signal, in declaration order. */
export function allSignals(): SignalDefinition[] {
return Object.values(SIGNALS);
}
/** Reverse index: DB `MeasurementType` → the signal it backs (built once). */
const MEASUREMENT_TYPE_TO_SIGNAL = new Map<MeasurementType, SignalDefinition>(
allSignals()
.filter(
(s): s is Extract<SignalDefinition, { kind: "measurement" | "score" }> =>
s.kind === "measurement" || s.kind === "score",
)
.map((s) => [s.source.measurementType, s]),
);
/** Resolve the signal a `MeasurementType` backs, or null when unregistered. */
export function signalForMeasurementType(
type: MeasurementType,
): SignalDefinition | null {
return MEASUREMENT_TYPE_TO_SIGNAL.get(type) ?? null;
}