Files
HealthLog/src/lib/insights/derived/dispatch.ts
T
Marc-André Bombeck 0be484c8a3 feat(insights): TRAJECTORY forecasting derived metric with a widening band
Add a short-horizon OLS projection over the DAY-native per-day mean
series, extending the existing trendSlope. The fit, residual standard
error and prediction interval are computed at DAY granularity only — the
rollup invariant forbids composing a slope/sd from WEEK/MONTH buckets.

The projection is gated on fit quality (R squared), in-window history and
staleness: below any floor the engine returns insufficient rather than a
weak line, so noise is never extrapolated. The prediction-interval band
widens with the horizon distance from the data centre, so the fan
visibly communicates uncertainty.

Register TRAJECTORY in the derived registry and dispatch (additive,
iOS-forward-compatible; the capabilities endpoint and drift-guard pick it
up automatically). Surface it on the weight detail page as a forecast
band beneath the chart, labelled a projection with the cited method and
a conditional, range-only headline — never a prediction or a dated
event. i18n across all six locales.
2026-06-04 01:40:27 +02:00

227 lines
8.0 KiB
TypeScript

/**
* v1.10.0 — the route-side dispatcher: `DerivedMetricId` → its pure
* compute function → a wire-flat `Derived<unknown>`.
*
* The generic `/api/insights/derived` route validates `metric` against
* the closed registry enum, then calls `computeDerivedMetric`. Wave 1
* implements `VITALS_BASELINE` end-to-end; every other registered id is
* a metadata stub whose compute lands in W2/W3. A stub routed before its
* compute lands returns `insufficient` with `reason: "not_implemented"`
* — never a fabricated value, never a 500.
*
* Server-only — imports the server-only compute engines.
*/
import type { MeasurementType } from "@/generated/prisma/client";
import { buildInsufficient, nowProvenanceTimestamp } from "./coverage";
import {
getDerivedMetricMeta,
isVitalsBaselineType,
isTrajectoryType,
type DerivedMetricId,
} from "./registry";
import {
computeVitalsBaseline,
type BaselineProfile,
} from "./baseline";
import { computeFitnessAge } from "./fitness-age";
import { computeSixMinuteWalkBand } from "./six-minute-walk";
import { computeVascularAgeDelta } from "./vascular-age";
import { computeHrvBalance } from "./hrv-balance";
import { computeBmi } from "./bmi";
import { computeSleepScore } from "./sleep-score";
import { computeReadiness } from "./readiness";
import { computeCoincidentDeviation } from "./coincident-deviation";
import { computeTrajectory } from "./trajectory";
import {
computeWellnessScore,
type WellnessScoreType,
} from "./wellness-scores";
import type { Derived } from "./types";
export interface DerivedComputeArgs {
metric: DerivedMetricId;
userId: string;
profile: BaselineProfile;
/**
* Optional sub-target for metrics that baseline a single chosen type
* (`VITALS_BASELINE`). Validated against the engine's supported set.
*/
type?: string | null;
/** Trailing window override (days). */
windowDays?: number;
now?: Date;
}
/** A `not_implemented` insufficient — the stub guard for W2/W3 metrics. */
function notImplemented(
inputs: string[],
now: Date,
): Derived<unknown> {
const computedAt = nowProvenanceTimestamp(now);
return buildInsufficient<unknown>({
coverage: { requiredInputs: 1, presentInputs: 0, historyDays: 0, missing: inputs },
provenance: { inputs, source: "none", windowDays: 0, computedAt },
reason: "not_implemented",
});
}
/**
* Dispatch a derived-metric id to its compute function. Returns the flat
* `Derived<unknown>` the route wraps in the standard envelope. The caller
* has already Zod-validated `metric` against the registry enum, so an
* unknown id never reaches here.
*/
export async function computeDerivedMetric(
args: DerivedComputeArgs,
): Promise<Derived<unknown>> {
const now = args.now ?? new Date();
const meta = getDerivedMetricMeta(args.metric);
if (!meta) {
// Defensive — the route validates against the enum first.
return notImplemented([], now);
}
if (!meta.implemented) {
return notImplemented(meta.inputs.map(String), now);
}
switch (args.metric) {
case "VITALS_BASELINE": {
// The baseline engine needs a single chosen vital; default to
// RESTING_HEART_RATE when the caller omits one (the catalogue's
// canonical example).
const requested = args.type ?? "RESTING_HEART_RATE";
if (!isVitalsBaselineType(requested)) {
return buildInsufficient<unknown>({
coverage: {
requiredInputs: 1,
presentInputs: 0,
historyDays: 0,
missing: [requested],
},
provenance: {
inputs: [requested],
source: "none",
windowDays: 0,
computedAt: nowProvenanceTimestamp(now),
},
reason: "unsupported_baseline_type",
});
}
return computeVitalsBaseline(args.userId, args.profile, {
type: requested as MeasurementType,
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
}
case "FITNESS_AGE":
return computeFitnessAge(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "VASCULAR_AGE_DELTA":
return computeVascularAgeDelta(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "HRV_BALANCE":
return computeHrvBalance(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "BMI":
return computeBmi(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "SLEEP_SCORE":
return computeSleepScore(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "READINESS":
return computeReadiness(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "COINCIDENT_DEVIATION":
return computeCoincidentDeviation(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "WRIST_TEMPERATURE_BASELINE":
case "STAIR_ASCENT_SPEED_BASELINE":
case "STAIR_DESCENT_SPEED_BASELINE": {
// v1.10.3 additive HealthKit baselines — each pins ONE fixed type and
// reuses the type-generic baseline engine unchanged (median ± k·MAD).
// Wrist temperature is a personal-DEVIATION band (no illness/cycle
// inference); stair ascent/descent are personal trend bands (no
// population cutoff — stair pace is geometry-confounded). The fixed
// type is the metric's single registered input.
const baselineType: Record<
| "WRIST_TEMPERATURE_BASELINE"
| "STAIR_ASCENT_SPEED_BASELINE"
| "STAIR_DESCENT_SPEED_BASELINE",
MeasurementType
> = {
WRIST_TEMPERATURE_BASELINE: "WRIST_TEMPERATURE",
STAIR_ASCENT_SPEED_BASELINE: "STAIR_ASCENT_SPEED",
STAIR_DESCENT_SPEED_BASELINE: "STAIR_DESCENT_SPEED",
};
return computeVitalsBaseline(args.userId, args.profile, {
type: baselineType[args.metric],
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
}
case "SIX_MINUTE_WALK_BAND":
return computeSixMinuteWalkBand(args.userId, args.profile, {
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
case "TRAJECTORY": {
// Short-horizon OLS projection over a single chosen metric; defaults
// to RESTING_HEART_RATE (the catalogue's canonical example) when the
// caller omits one. Validated against the supported projection set —
// any other type 422s the same way VITALS_BASELINE does.
const requested = args.type ?? "RESTING_HEART_RATE";
if (!isTrajectoryType(requested)) {
return buildInsufficient<unknown>({
coverage: {
requiredInputs: 1,
presentInputs: 0,
historyDays: 0,
missing: [requested],
},
provenance: {
inputs: [requested],
source: "none",
windowDays: 0,
computedAt: nowProvenanceTimestamp(now),
},
reason: "unsupported_trajectory_type",
});
}
return computeTrajectory(args.userId, args.profile, {
type: requested as MeasurementType,
windowDays: args.windowDays,
now,
}) as Promise<Derived<unknown>>;
}
case "RECOVERY_SCORE":
case "STRESS_SCORE":
case "STRAIN_SCORE":
// Passthrough read of the nightly-persisted COMPUTED rows — never a
// recompute. The same `Derived<T>` contract carries the scores.
return computeWellnessScore(
args.metric as WellnessScoreType,
args.userId,
args.profile,
{ windowDays: args.windowDays, now },
) as Promise<Derived<unknown>>;
default:
// Registered + implemented but no dispatch arm — treat as a stub.
return notImplemented(meta.inputs.map(String), now);
}
}