mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 07:42:23 +00:00
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:
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);
|
||||
});
|
||||
});
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
@@ -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(),
|
||||
});
|
||||
Reference in new issue
Block a user