Merge v189/ill into release/v1.18.9

Defer illness recovery-gap correlation to an opt-in detail expansion; gate the
typical-gap insight behind signal-density thresholds; align the illness settings
page to the canonical SettingsCard pattern.
This commit is contained in:
Marc-André Bombeck committed 2026-06-20 12:00:00 +02:00
commit b27d8509cd
16 files changed
+363 -101

No files matched your search

@@ -2,13 +2,17 @@
* v1.18.1 P3 — illness retrospective summary aggregation.
*
* Asserts the count/byMonth/byType tallies, the CHRONIC_ONGOING gap exclusion,
* and the thin-data gate: the "typical recovery gap" is WITHHELD below the
* min-sample floor (never a "typical" claim from one episode).
* and the v1.18.9 signal-density gates: the "typical recovery gap" is WITHHELD
* unless enough episodes EACH clear the per-episode measurement floor AND the
* resulting median magnitude is non-trivial (a 0/±1-day gap is coincidental
* noise, not a finding).
*/
import { describe, expect, it } from "vitest";
import {
summarizeIllnessRetrospective,
MIN_EPISODES_FOR_TYPICAL_GAP,
MIN_GAP_MEASUREMENT_DAYS,
MIN_TYPICAL_GAP_MAGNITUDE_DAYS,
type RetrospectiveEpisode,
} from "../retrospective";
@@ -19,6 +23,9 @@ function ep(over: Partial<RetrospectiveEpisode>): RetrospectiveEpisode {
onsetDay: "2026-01-10",
resolved: true,
recoveryGapDays: 2,
// Default to a well-covered episode so the gap-magnitude / sample-count
// tests aren't masked by the per-episode measurement floor.
gapMeasurementDays: MIN_GAP_MEASUREMENT_DAYS + 2,
lifecycle: "ACUTE",
...over,
};
@@ -76,4 +83,60 @@ describe("summarizeIllnessRetrospective", () => {
expect(out.gapSampleSize).toBe(3);
expect(out.typicalRecoveryGapDays).toBe(4);
});
it("drops episodes below the per-episode measurement floor", () => {
// Three computed gaps, but only one episode is well-covered — the other
// two ride on a couple of coincidental readings and must not count.
const out = summarizeIllnessRetrospective([
ep({ id: "a", recoveryGapDays: 4, gapMeasurementDays: 8 }),
ep({
id: "b",
recoveryGapDays: 5,
gapMeasurementDays: MIN_GAP_MEASUREMENT_DAYS - 1,
}),
ep({ id: "c", recoveryGapDays: 6, gapMeasurementDays: 0 }),
]);
expect(out.gapSampleSize).toBe(1);
expect(out.typicalRecoveryGapDays).toBeNull();
});
it("treats a missing gapMeasurementDays as non-qualifying", () => {
const bare = (id: string): RetrospectiveEpisode => ({
id,
type: "INFECTION",
onsetDay: "2026-01-10",
resolved: true,
recoveryGapDays: 4,
lifecycle: "ACUTE",
});
const out = summarizeIllnessRetrospective([
bare("a"),
bare("b"),
bare("c"),
]);
expect(out.gapSampleSize).toBe(0);
expect(out.typicalRecoveryGapDays).toBeNull();
});
it("withholds a trivial (sub-threshold) median gap as noise", () => {
// Enough well-covered episodes, but the gaps cluster at 0/±1 — the
// coincidental-data baseline. No speculative gap is surfaced.
const out = summarizeIllnessRetrospective([
ep({ id: "a", recoveryGapDays: 0 }),
ep({ id: "b", recoveryGapDays: 1 }),
ep({ id: "c", recoveryGapDays: -1 }),
]);
expect(MIN_TYPICAL_GAP_MAGNITUDE_DAYS).toBe(2);
expect(out.gapSampleSize).toBe(3); // they qualified on coverage…
expect(out.typicalRecoveryGapDays).toBeNull(); // …but the magnitude is noise
});
it("surfaces a negative gap once its magnitude clears the floor", () => {
const out = summarizeIllnessRetrospective([
ep({ id: "a", recoveryGapDays: -2 }),
ep({ id: "b", recoveryGapDays: -3 }),
ep({ id: "c", recoveryGapDays: -4 }),
]);
expect(out.typicalRecoveryGapDays).toBe(-3);
});
});
+58 -6
View File
@@ -15,9 +15,36 @@
*/
import { median } from "@/lib/insights/derived/baseline";
/** Minimum resolved-with-gap episodes before a "typical gap" is asserted. */
/**
* Minimum episodes that each clear the per-episode signal floor before a
* "typical recovery gap" is asserted. A gap is only honest once several
* episodes independently back it, so one or two coincidental gaps never
* become a "typical" claim.
*/
export const MIN_EPISODES_FOR_TYPICAL_GAP = 3;
/**
* Minimum distinct episode days carrying a real measurement before an
* episode's recovery-gap may feed the typical-gap median. Below this an
* episode's window holds too few genuine vitals for its computed gap to mean
* anything — a couple of readings happening to surround the onset/recovery
* markers produce a spurious gap. The correlation engine's own
* `MIN_EPISODE_COVERAGE_DAYS` floor (4) is the engine-side gate; this is the
* aggregate-side reinforcement so a barely-covered episode does not tip the
* median. Sourced from `Derived.coverage.historyDays`.
*/
export const MIN_GAP_MEASUREMENT_DAYS = 4;
/**
* Minimum absolute magnitude (days) the typical gap must reach before it is
* surfaced. A median gap of 0 — and the ±1-day jitter around it — is the
* dominant outcome of coincidental data (numbers and feeling settle on the
* same day), so it carries no signal worth a headline. Only a gap that
* genuinely separates the felt-better marker from the physiological return
* is shown.
*/
export const MIN_TYPICAL_GAP_MAGNITUDE_DAYS = 2;
/** One episode's contribution to the summary. */
export interface RetrospectiveEpisode {
id: string;
@@ -28,6 +55,13 @@ export interface RetrospectiveEpisode {
resolved: boolean;
/** The computed recovery-gap in days, or null when ungated/unavailable. */
recoveryGapDays: number | null;
/**
* Distinct episode days that carried a real measurement (the correlation
* engine's coverage `historyDays`). Drives the per-episode signal floor:
* an episode below `MIN_GAP_MEASUREMENT_DAYS` contributes no gap even if
* the engine computed one. Absent/0 → does not qualify.
*/
gapMeasurementDays?: number;
/** Lifecycle — CHRONIC_ONGOING never contributes a gap. */
lifecycle: string;
}
@@ -56,9 +90,17 @@ export interface IllnessRetrospectiveSummary {
}
/**
* Aggregate the per-episode figures into the retrospective summary. Pure. The
* typical-gap is withheld (null) below the min-sample floor so a single
* episode never becomes a "typical" claim.
* Aggregate the per-episode figures into the retrospective summary. Pure.
*
* The typical-gap is withheld (null) unless ALL THREE signal-density gates
* hold, so coincidental data never surfaces a speculative "Erholungslücke":
* 1. each contributing episode cleared the per-episode measurement floor
* (`gapMeasurementDays >= MIN_GAP_MEASUREMENT_DAYS`),
* 2. at least `MIN_EPISODES_FOR_TYPICAL_GAP` such episodes qualify, and
* 3. the resulting median magnitude reaches
* `MIN_TYPICAL_GAP_MAGNITUDE_DAYS` (a 0/±1-day gap is noise).
* `gapSampleSize` reports the count of episodes that cleared gates 1–2 (the
* transparency figure), independent of the magnitude gate.
*/
export function summarizeIllnessRetrospective(
episodes: RetrospectiveEpisode[],
@@ -76,17 +118,27 @@ export function summarizeIllnessRetrospective(
if (
e.lifecycle !== "CHRONIC_ONGOING" &&
e.recoveryGapDays !== null &&
Number.isFinite(e.recoveryGapDays)
Number.isFinite(e.recoveryGapDays) &&
// Per-episode signal floor: a barely-covered episode contributes no
// gap even if the engine computed one.
(e.gapMeasurementDays ?? 0) >= MIN_GAP_MEASUREMENT_DAYS
) {
gaps.push(e.recoveryGapDays);
}
}
const typicalRecoveryGapDays =
const medianGap =
gaps.length >= MIN_EPISODES_FOR_TYPICAL_GAP
? Math.round(median(gaps))
: null;
// Magnitude gate: a 0/±1-day gap is the coincidental-data baseline and
// carries no signal worth a headline.
const typicalRecoveryGapDays =
medianGap !== null && Math.abs(medianGap) >= MIN_TYPICAL_GAP_MAGNITUDE_DAYS
? medianGap
: null;
return {
episodeCount: episodes.length,
resolvedCount,
+1 -1
View File
@@ -93,7 +93,7 @@ const illnessDayLogGetQuery = z
illnessInsightsQuerySchema.meta({
id: "IllnessInsightsQuery",
description:
"Cross-episode retrospective window query: optional `windowDays` (30–1095, default 365). Retrospective only — the engine summarises past episodes, never forecasts.",
"Cross-episode retrospective window query: optional `windowDays` (30–1095, default 365) and optional `includeRecoveryGap` (default false). With `includeRecoveryGap` off the response carries the count breakdown and a null typical recovery gap on a single fast query; set it true to pay for the per-episode correlation that computes the recovery gap. Retrospective only — the engine summarises past episodes, never forecasts.",
});
const illnessSymptom = z
+8 -2
View File
@@ -35,7 +35,13 @@ export const illnessKeys = {
/**
* v1.18.1 P3 — the cross-episode retrospective summary ("sick N times ·
* typical recovery gap X days") over a trailing window in days.
*
* v1.18.9 — `includeRecoveryGap` is part of the key: the lightweight
* count-only read (list load) and the heavy recovery-gap read (the
* "Analyse" expansion) hit the same endpoint with a different response
* shape, so they MUST cache under distinct keys (same-key + different
* payload silently poisons the cache).
*/
illnessInsights: (windowDays: number) =>
["illness", "insights", windowDays] as const,
illnessInsights: (windowDays: number, includeRecoveryGap: boolean) =>
["illness", "insights", windowDays, includeRecoveryGap] as const,
};
+10
View File
@@ -182,7 +182,17 @@ export type IllnessDayLogListQuery = z.infer<
* The retrospective-insight window query: `GET /api/illness/insights?
* windowDays=365`. Bounded 30..1095 days; defaults to a trailing year.
* Retrospective only — the engine summarises past episodes, never forecasts.
*
* `includeRecoveryGap` (default false) gates the EXPENSIVE per-episode
* correlation fan-out. The illness LIST loads with it off so the page paints
* on a single fast count query; only the explicit "Analyse" expansion sets it
* true and pays for the recovery-gap computation. Withholding it leaves the
* typical-gap null (the surface shows the calm "still learning" line).
*/
export const illnessInsightsQuerySchema = z.object({
windowDays: z.coerce.number().int().min(30).max(1095).optional(),
includeRecoveryGap: z
.enum(["true", "false"])
.transform((v) => v === "true")
.optional(),
});