feat(illness): name the driving vital in the recovery-gap summary

The cross-episode summary already computes per-vital physiological returns
but the card surfaced only one bare line. Thread the dominant returning
vital through the aggregate and the DTO so the copy reads 'you tend to feel
better before your resting heart rate settles' instead of a context-free
gap figure.

The aggregate tallies which vital produced a real return across the
episodes that qualified for the typical-gap median and reports the most
frequent one (deterministic alphabetical tiebreak); the driver is named
only when a gap actually clears the magnitude gate. Zero new compute — the
returns were already in hand. Adds the localized copy in all six locales.

src/app/api/illness/insights/route.ts

@@ -85,7 +85,11 @@ export const GET = apiHandler(async (request: NextRequest) => {
   // out of the typical-gap median by the aggregate's signal-density gates.
   const gapById = new Map<
     string,
-    { recoveryGapDays: number | null; gapMeasurementDays: number }
+    {
+      recoveryGapDays: number | null;
+      gapMeasurementDays: number;
+      gapReturnTypes: string[];
+    }
   >();
   if (includeRecoveryGap) {
     const gapCandidates = rows
@@ -98,7 +102,11 @@ export const GET = apiHandler(async (request: NextRequest) => {
           async (): Promise<
             [
               string,
-              { recoveryGapDays: number | null; gapMeasurementDays: number },
+              {
+                recoveryGapDays: number | null;
+                gapMeasurementDays: number;
+                gapReturnTypes: string[];
+              },
             ]
           > => {
             const derived = await computeEpisodeCorrelation(
@@ -130,6 +138,15 @@ export const GET = apiHandler(async (request: NextRequest) => {
                   derived.status === "ok"
                     ? derived.value.adverseCoverageDays
                     : 0,
+                // The vitals that produced a real physiological return —
+                // tallied across the qualifying episodes to name the dominant
+                // driving vital in the summary copy.
+                gapReturnTypes:
+                  derived.status === "ok"
+                    ? derived.value.returns
+                        .filter((r) => r.gapDays !== null)
+                        .map((r) => String(r.type))
+                    : [],
               },
             ];
           },
@@ -148,6 +165,7 @@ export const GET = apiHandler(async (request: NextRequest) => {
       resolved: r.resolvedAt !== null,
       recoveryGapDays: gap?.recoveryGapDays ?? null,
       gapMeasurementDays: gap?.gapMeasurementDays ?? 0,
+      gapReturnTypes: gap?.gapReturnTypes ?? [],
       lifecycle: r.lifecycle,
     };
   });
@@ -160,6 +178,7 @@ export const GET = apiHandler(async (request: NextRequest) => {
       episode_count: summary.episodeCount,
       gap_sample_size: summary.gapSampleSize,
       typical_gap_days: summary.typicalRecoveryGapDays,
+      gap_driver_type: summary.gapDriverType,
       include_recovery_gap: includeRecoveryGap,
     },
   });

src/components/illness/illness-insights-card.tsx

@@ -87,13 +87,22 @@ export function IllnessInsightsCard({
               <p className="text-muted-foreground">
                 {t("illness.insights.typicalGapLearning")}
               </p>
+            ) : gap.data.typicalRecoveryGapDays === null ? (
+              <p className="text-muted-foreground">
+                {t("illness.insights.typicalGapLearning")}
+              </p>
+            ) : gap.data.gapDriverType ? (
+              <p className="text-muted-foreground">
+                {t("illness.insights.typicalGapWithDriver", {
+                  days: gap.data.typicalRecoveryGapDays,
+                  vital: t(`illness.vital.${gap.data.gapDriverType}`),
+                })}
+              </p>
             ) : (
               <p className="text-muted-foreground">
-                {gap.data.typicalRecoveryGapDays !== null
-                  ? t("illness.insights.typicalGap", {
-                      days: gap.data.typicalRecoveryGapDays,
-                    })
-                  : t("illness.insights.typicalGapLearning")}
+                {t("illness.insights.typicalGap", {
+                  days: gap.data.typicalRecoveryGapDays,
+                })}
               </p>
             )}
           </div>

src/components/illness/types.ts

@@ -149,4 +149,5 @@ export interface IllnessInsightsResponse {
   gapSampleSize: number;
   byMonth: Record<string, number>;
   byType: Record<string, number>;
+  gapDriverType: string | null;
 }

src/lib/illness/__tests__/retrospective.test.ts

@@ -131,6 +131,74 @@ describe("summarizeIllnessRetrospective", () => {
     expect(out.typicalRecoveryGapDays).toBeNull(); // …but the magnitude is noise
   });
 
+  it("names the dominant driving vital when a gap is surfaced", () => {
+    const out = summarizeIllnessRetrospective([
+      ep({
+        id: "a",
+        recoveryGapDays: 4,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+      ep({
+        id: "b",
+        recoveryGapDays: 6,
+        gapReturnTypes: ["RESTING_HEART_RATE", "HEART_RATE_VARIABILITY"],
+      }),
+      ep({
+        id: "c",
+        recoveryGapDays: 5,
+        gapReturnTypes: ["HEART_RATE_VARIABILITY"],
+      }),
+    ]);
+    // RHR returned in 2 of 3 episodes, HRV in 2 as well — tie → deterministic
+    // alphabetical resolution picks HEART_RATE_VARIABILITY.
+    expect(out.typicalRecoveryGapDays).toBe(5);
+    expect(out.gapDriverType).toBe("HEART_RATE_VARIABILITY");
+  });
+
+  it("picks the strictly-most-frequent driver", () => {
+    const out = summarizeIllnessRetrospective([
+      ep({
+        id: "a",
+        recoveryGapDays: 4,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+      ep({
+        id: "b",
+        recoveryGapDays: 6,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+      ep({
+        id: "c",
+        recoveryGapDays: 5,
+        gapReturnTypes: ["HEART_RATE_VARIABILITY"],
+      }),
+    ]);
+    expect(out.gapDriverType).toBe("RESTING_HEART_RATE");
+  });
+
+  it("leaves the driver null when no gap is surfaced", () => {
+    const out = summarizeIllnessRetrospective([
+      ep({
+        id: "a",
+        recoveryGapDays: 0,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+      ep({
+        id: "b",
+        recoveryGapDays: 1,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+      ep({
+        id: "c",
+        recoveryGapDays: -1,
+        gapReturnTypes: ["RESTING_HEART_RATE"],
+      }),
+    ]);
+    // Magnitude gate withholds the gap → no driver is named.
+    expect(out.typicalRecoveryGapDays).toBeNull();
+    expect(out.gapDriverType).toBeNull();
+  });
+
   it("surfaces a negative gap once its magnitude clears the floor", () => {
     const out = summarizeIllnessRetrospective([
       ep({ id: "a", recoveryGapDays: -2 }),

src/lib/illness/retrospective.ts

@@ -62,6 +62,14 @@ export interface RetrospectiveEpisode {
    * the engine computed one. Absent/0 → does not qualify.
    */
   gapMeasurementDays?: number;
+  /**
+   * The vital metric types that produced a non-null physiological-return gap
+   * for this episode (the engine's `returns[]` filtered to a real return).
+   * Tallied across the qualifying episodes to name the dominant driving vital
+   * in the cross-episode summary ("felt better ~X days before resting heart
+   * rate settled"). Absent/empty → contributes no driver.
+   */
+  gapReturnTypes?: string[];
   /** Lifecycle — CHRONIC_ONGOING never contributes a gap. */
   lifecycle: string;
 }
@@ -87,6 +95,13 @@ export interface IllnessRetrospectiveSummary {
   byMonth: Record<number, number>;
   /** Per-type episode counts in the window (retrospective breakdown). */
   byType: Record<string, number>;
+  /**
+   * The dominant vital that drove the typical recovery gap — the metric type
+   * that most often produced a physiological return across the qualifying
+   * episodes — or null when no gap is surfaced or no vital clearly leads. The
+   * card names it ("…before resting heart rate settled"). Retrospective only.
+   */
+  gapDriverType: string | null;
 }
 
 /**
@@ -109,6 +124,10 @@ export function summarizeIllnessRetrospective(
   const byType: Record<string, number> = {};
   let resolvedCount = 0;
   const gaps: number[] = [];
+  // Tally of which vital produced a physiological return, across only the
+  // episodes that qualified for the typical-gap median — the dominant one
+  // names the driving vital in the card.
+  const driverTally: Record<string, number> = {};
 
   for (const e of episodes) {
     const month = Number(e.onsetDay.slice(5, 7));
@@ -124,6 +143,8 @@ export function summarizeIllnessRetrospective(
       (e.gapMeasurementDays ?? 0) >= MIN_GAP_MEASUREMENT_DAYS
     ) {
       gaps.push(e.recoveryGapDays);
+      for (const type of e.gapReturnTypes ?? [])
+        driverTally[type] = (driverTally[type] ?? 0) + 1;
     }
   }
 
@@ -139,6 +160,16 @@ export function summarizeIllnessRetrospective(
       ? medianGap
       : null;
 
+  // Name the driving vital only when a gap is actually surfaced — the most
+  // frequently-returning vital across the qualifying episodes. Ties resolve
+  // deterministically by metric name so the copy is stable across reads.
+  const gapDriverType =
+    typicalRecoveryGapDays !== null
+      ? (Object.entries(driverTally).sort((a, b) =>
+          b[1] !== a[1] ? b[1] - a[1] : a[0] < b[0] ? -1 : 1,
+        )[0]?.[0] ?? null)
+      : null;
+
   return {
     episodeCount: episodes.length,
     resolvedCount,
@@ -146,5 +177,6 @@ export function summarizeIllnessRetrospective(
     gapSampleSize: gaps.length,
     byMonth,
     byType,
+    gapDriverType,
   };
 }

src/lib/openapi/routes/illness.ts

@@ -253,11 +253,12 @@ const illnessInsightsResponse = z
     gapSampleSize: z.number().int(),
     byMonth: z.record(z.string(), z.number().int()),
     byType: z.record(z.string(), z.number().int()),
+    gapDriverType: z.string().nullable(),
   })
   .meta({
     id: "IllnessInsightsResponse",
     description:
-      "Cross-episode retrospective summary over the trailing window: episode + resolved counts, the typical (median) recovery gap (null below the min-sample floor — withholds a thin claim), a recurrence-by-month tally, and a per-type breakdown. Retrospective only.",
+      "Cross-episode retrospective summary over the trailing window: episode + resolved counts, the typical (median) recovery gap (null below the min-sample floor — withholds a thin claim), a recurrence-by-month tally, a per-type breakdown, and the dominant driving vital (`gapDriverType`, null when no gap is surfaced). Retrospective only.",
   });
 
 const episodeNotFound = {