feat(insights): period-narrative summary on the overview

Add a calm "your week / month in review" summary to the Insights
overview, generated from the period-narrative context (deltas, personal
bands, FDR-controlled associations, coincident days).

- New insight_narratives table (migration 0113): one durable row per
  (user, period, locale); generated prose AES-256-GCM at rest following
  the coach-message precedent; labels-only provenance stays plaintext.
- generatePeriodNarrative feeds the context into the provider chain with
  a tight, descriptive-never-causal prompt; an insufficient context
  yields no narrative, a missing provider no-ops, neither fabricates.
- Nightly warm cron on week (Mon) / month (1st) boundaries, budget-gated
  per user; the read-only GET enqueues a single-user warm on a cold read.
- Read route is stale-while-revalidate and never blocks on the provider;
  the card renders plain text (no markdown), a single provenance
  disclosure, and a fixed footprint (no CLS). i18n in all six locales.
This commit is contained in:
Marc-André Bombeck committed 2026-06-04 01:21:42 +02:00
1 parent 337f024a87
commit 5917bba61c
19 files changed
+1678 -2

No files matched your search

+1 -2
View File
@@ -73,7 +73,6 @@
"ignoreExportsUsedInFile": true,
"ignoreIssues": {
"src/components/ui/**": ["exports", "types"],
"src/lib/validations/**": ["types"],
"src/lib/insights/narrative/**": ["exports"]
"src/lib/validations/**": ["types"]
}
}
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Analyse wurde neu erstellt",
"warmAssessments": "Auswertungen vorbereiten",
"warmStarted": "Auswertungen werden im Hintergrund erstellt",
"narrativeTitle": "Dein Zeitraum im Rückblick",
"narrativeWeek": "Diese Woche",
"narrativeMonth": "Dieser Monat",
"narrativePreparing": "Deine Zusammenfassung wird erstellt…",
"narrativeUpdating": "Wird aktualisiert…",
"narrativeUpdated": "Aktualisiert {time}",
"narrativeProvenanceLabel": "Wie das zustande kam",
"narrativeProvenanceMethod": "Eine Zusammenfassung des Zeitraums in einfacher Sprache, ausschließlich aus deinen erfassten Werten und den Zusammenhängen, die die statistische Mehrfachvergleichskorrektur überstanden haben. Beschreibend, nie eine Ursache.",
"narrativeProvenanceMetrics": "Basierend auf: {metrics}",
"narrativeProvenanceWindow": "Zeitfenster: {from} bis {to}",
"heroFallbackSubtitle": "Täglicher Blick auf deine Trends — direkt aus den Zahlen, die du protokollierst.",
"heroGreetingMorning": "Guten Morgen",
"heroGreetingAfternoon": "Guten Tag",
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Analysis refreshed",
"warmAssessments": "Prepare assessments",
"warmStarted": "Assessments are being prepared in the background",
"narrativeTitle": "Your period in review",
"narrativeWeek": "This week",
"narrativeMonth": "This month",
"narrativePreparing": "Preparing your summary…",
"narrativeUpdating": "Updating…",
"narrativeUpdated": "Updated {time}",
"narrativeProvenanceLabel": "How this was put together",
"narrativeProvenanceMethod": "A plain-language summary of the period, drawn only from your logged numbers and the associations that survived statistical multiple-comparison control. Descriptive, never a cause.",
"narrativeProvenanceMetrics": "Based on: {metrics}",
"narrativeProvenanceWindow": "Window: {from} to {to}",
"heroFallbackSubtitle": "A daily read of your trends, drawn straight from the numbers you've logged.",
"heroGreetingMorning": "Good morning",
"heroGreetingAfternoon": "Good afternoon",
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Análisis regenerado",
"warmAssessments": "Preparar evaluaciones",
"warmStarted": "Las evaluaciones se están preparando en segundo plano",
"narrativeTitle": "Tu período en resumen",
"narrativeWeek": "Esta semana",
"narrativeMonth": "Este mes",
"narrativePreparing": "Preparando tu resumen…",
"narrativeUpdating": "Actualizando…",
"narrativeUpdated": "Actualizado {time}",
"narrativeProvenanceLabel": "Cómo se elaboró esto",
"narrativeProvenanceMethod": "Un resumen del período en lenguaje sencillo, basado únicamente en tus valores registrados y en las asociaciones que superaron el control estadístico de comparaciones múltiples. Descriptivo, nunca una causa.",
"narrativeProvenanceMetrics": "Basado en: {metrics}",
"narrativeProvenanceWindow": "Ventana: del {from} al {to}",
"heroFallbackSubtitle": "Una mirada diaria a tus tendencias — directamente de los datos que registras.",
"heroGreetingMorning": "Buenos días",
"heroGreetingAfternoon": "Buenas tardes",
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Analyse regénérée",
"warmAssessments": "Préparer les évaluations",
"warmStarted": "Les évaluations sont en cours de préparation en arrière-plan",
"narrativeTitle": "Votre période en revue",
"narrativeWeek": "Cette semaine",
"narrativeMonth": "Ce mois-ci",
"narrativePreparing": "Préparation de votre résumé…",
"narrativeUpdating": "Mise à jour…",
"narrativeUpdated": "Mis à jour {time}",
"narrativeProvenanceLabel": "Comment cela a été établi",
"narrativeProvenanceMethod": "Un résumé de la période en langage clair, établi uniquement à partir de vos valeurs enregistrées et des associations ayant survécu au contrôle statistique des comparaisons multiples. Descriptif, jamais une cause.",
"narrativeProvenanceMetrics": "Basé sur : {metrics}",
"narrativeProvenanceWindow": "Fenêtre : du {from} au {to}",
"heroFallbackSubtitle": "Un coup d’œil quotidien sur tes tendances — directement issu des chiffres que tu saisis.",
"heroGreetingMorning": "Bonjour",
"heroGreetingAfternoon": "Bonjour",
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Analisi rigenerata",
"warmAssessments": "Prepara le valutazioni",
"warmStarted": "Le valutazioni vengono preparate in background",
"narrativeTitle": "Il tuo periodo in sintesi",
"narrativeWeek": "Questa settimana",
"narrativeMonth": "Questo mese",
"narrativePreparing": "Preparazione del riepilogo…",
"narrativeUpdating": "Aggiornamento…",
"narrativeUpdated": "Aggiornato {time}",
"narrativeProvenanceLabel": "Come è stato realizzato",
"narrativeProvenanceMethod": "Un riepilogo del periodo in linguaggio semplice, basato esclusivamente sui valori registrati e sulle associazioni che hanno superato il controllo statistico dei confronti multipli. Descrittivo, mai una causa.",
"narrativeProvenanceMetrics": "Basato su: {metrics}",
"narrativeProvenanceWindow": "Finestra: dal {from} al {to}",
"heroFallbackSubtitle": "Uno sguardo quotidiano ai tuoi trend — direttamente dai numeri che registri.",
"heroGreetingMorning": "Buongiorno",
"heroGreetingAfternoon": "Buon pomeriggio",
+10
View File
@@ -1540,6 +1540,16 @@
"regenerateSuccess": "Analiza wygenerowana ponownie",
"warmAssessments": "Przygotuj analizy",
"warmStarted": "Analizy są przygotowywane w tle",
"narrativeTitle": "Twój okres w skrócie",
"narrativeWeek": "Ten tydzień",
"narrativeMonth": "Ten miesiąc",
"narrativePreparing": "Przygotowywanie podsumowania…",
"narrativeUpdating": "Aktualizowanie…",
"narrativeUpdated": "Zaktualizowano {time}",
"narrativeProvenanceLabel": "Jak to powstało",
"narrativeProvenanceMethod": "Podsumowanie okresu w prostym języku, oparte wyłącznie na zarejestrowanych wartościach i powiązaniach, które przeszły statystyczną korektę dla porównań wielokrotnych. Opisowe, nigdy nie przyczynowe.",
"narrativeProvenanceMetrics": "Na podstawie: {metrics}",
"narrativeProvenanceWindow": "Okno: od {from} do {to}",
"heroFallbackSubtitle": "Codzienne spojrzenie na twoje trendy — prosto z liczb, które rejestrujesz.",
"heroGreetingMorning": "Dzień dobry",
"heroGreetingAfternoon": "Dzień dobry",
@@ -0,0 +1,43 @@
-- v1.11.0 — period-narrative cache (Pillar P1).
--
-- One durable, typed row per (user, period, locale) holding the latest
-- generated period summary ("how your week/month went"). Delete +
-- regenerate clean: the unique index on (user_id, period, locale) enforces
-- a single row per slot, so a regeneration upserts in place and there is
-- never a stale duplicate to disambiguate.
--
-- The generated prose is held AES-256-GCM at rest in `encrypted_content`
-- (BYTEA), following the `coach_messages.encrypted_content` precedent. The
-- `provenance_json` envelope is labels-only (metric names, the read window,
-- the FDR footer) and carries no PII, so it stays plaintext for a stable,
-- queryable shape — matching `coach_messages.metric_source_json`.
--
-- Purely additive: one new table, no enum changes, no backfill. Deleting the
-- user cascades every narrative away (clean GDPR-erasure).
CREATE TABLE IF NOT EXISTS "insight_narratives" (
"id" TEXT NOT NULL,
"user_id" TEXT NOT NULL,
"period" TEXT NOT NULL,
"locale" TEXT NOT NULL,
"date_key" TEXT NOT NULL,
"encrypted_content" BYTEA NOT NULL,
"provenance_json" TEXT,
"provider_type" TEXT,
"prompt_version" TEXT,
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updated_at" TIMESTAMP(3) NOT NULL,
CONSTRAINT "insight_narratives_pkey" PRIMARY KEY ("id")
);
CREATE UNIQUE INDEX IF NOT EXISTS "insight_narratives_user_id_period_locale_key"
ON "insight_narratives" ("user_id", "period", "locale");
CREATE INDEX IF NOT EXISTS "insight_narratives_user_id_updated_at_idx"
ON "insight_narratives" ("user_id", "updated_at" DESC);
ALTER TABLE "insight_narratives"
ADD CONSTRAINT "insight_narratives_user_id_fkey"
FOREIGN KEY ("user_id") REFERENCES "users" ("id")
ON DELETE CASCADE ON UPDATE CASCADE;
+49
View File
@@ -428,6 +428,9 @@ model User {
// provider chain entry) so a known-bad credential is negatively cached
// across workers instead of re-burning a 401 every generation.
providerHealth ProviderHealth[]
// v1.11.0 W3 — one durable period-narrative row per (period, locale).
// Delete/regenerate-clean; the generated prose is AES-256-GCM at rest.
insightNarratives InsightNarrative[]
// v1.7.0 profile — optional patient-identity fields surfaced on the
// health-record export cover (PDF) and the FHIR `Patient` resource.
@@ -2830,3 +2833,49 @@ model ClinicianShareLink {
@@index([expiresAt])
@@map("clinician_share_links")
}
// v1.11.0 W3 — period-narrative cache (Pillar P1).
//
// One durable, typed row per (user, period, locale) carrying the latest
// generated period summary ("how your week/month went"). Delete +
// regenerate clean: the unique constraint enforces a single row per slot,
// so a regeneration upserts in place and there is never a stale duplicate
// to disambiguate. The generated prose is held AES-256-GCM at rest in
// `encryptedContent` (Bytes), following the `CoachMessage.encryptedContent`
// precedent — the body is descriptive health narrative and is treated as
// sensitive even though it carries labels-plus-numbers, not raw rows.
//
// `provenanceJson` is the labels-only provenance envelope the surface
// renders as ⓘ chips (metric names + the read window + the FDR footer);
// it carries no PII so it stays plaintext for a stable, queryable shape,
// matching `CoachMessage.metricSourceJson`. `providerType` + `promptVersion`
// mirror the attribution columns so the cross-feature aggregator can slice
// quality per (provider × prompt). `period` is `week` | `month`; `dateKey`
// is the UTC `YYYY-MM-DD` boundary the row was generated for, so the
// stale-while-revalidate read can tell "today's" narrative from an older
// one without decrypting.
model InsightNarrative {
id String @id @default(cuid())
userId String @map("user_id")
/// "week" | "month".
period String
/// Resolved UI locale of the prose ("de" | "en").
locale String
/// UTC YYYY-MM-DD boundary the narrative was generated for.
dateKey String @map("date_key")
/// AES-256-GCM ciphertext of the generated narrative prose.
encryptedContent Bytes @map("encrypted_content")
/// Labels-only provenance envelope (metric names, window, FDR footer).
provenanceJson String? @map("provenance_json")
providerType String? @map("provider_type")
promptVersion String? @map("prompt_version")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
// One row per (user, period, locale) — regeneration upserts in place.
@@unique([userId, period, locale])
@@index([userId, updatedAt(sort: Desc)])
@@map("insight_narratives")
}
+95
View File
@@ -0,0 +1,95 @@
/**
* v1.11.0 W3 — period-narrative read route (Pillar P1).
*
* `GET /api/insights/narrative?period=week|month` serves the latest generated
* period summary for the calling user. Read-only by construction (the v1.8.3
* freeze posture): it NEVER blocks on the provider. It returns the last good
* narrative immediately (stale-while-revalidate) and, when the row is missing
* or stale and a provider is configured, fire-and-forget enqueues a warm so
* the next read reflects the latest period.
*
* `userId` is narrowed from the session/Bearer (never a query field); an
* unknown `period` 422s via the closed enum.
*/
import { NextRequest } from "next/server";
import { z } from "zod/v4";
import { apiSuccess, returnAllZodIssues } from "@/lib/api-response";
import { apiHandler, requireAuth } from "@/lib/api-handler";
import { annotate } from "@/lib/logging/context";
import { resolveServerLocale } from "@/lib/i18n/server-locale";
import { requireAssistantSurface } from "@/lib/feature-flags";
import { hasUsableStatusProvider } from "@/lib/insights/status-provider";
import { readPeriodNarrative } from "@/lib/insights/narrative/period-narrative-generate";
import { PERIOD_DAYS, type NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
import { enqueueNarrativeWarm } from "@/lib/jobs/period-narrative-shared";
export const dynamic = "force-dynamic";
const NARRATIVE_PERIODS = Object.keys(PERIOD_DAYS) as [string, ...string[]];
const narrativeQuerySchema = z.object({
period: z.enum(NARRATIVE_PERIODS),
});
/** A narrative read this recently is considered fresh; no warm is enqueued. */
const NARRATIVE_FRESH_MS = 20 * 60 * 60 * 1000;
function narrowLocale(locale: string): "de" | "en" {
return locale === "en" ? "en" : "de";
}
export const GET = apiHandler(async (request: NextRequest) => {
const { user } = await requireAuth();
await requireAssistantSurface("insightStatus");
const parsed = narrativeQuerySchema.safeParse({
period: request.nextUrl.searchParams.get("period"),
});
if (!parsed.success) {
annotate({
action: { name: "insights.narrative.invalid-period" },
meta: { issue_count: parsed.error.issues.length },
});
return returnAllZodIssues(parsed.error, 422);
}
const period = parsed.data.period as NarrativePeriod;
const resolved = await resolveServerLocale({
request,
userLocale: user.locale ?? null,
override: request.nextUrl.searchParams.get("locale"),
});
const locale = narrowLocale(resolved);
const existing = await readPeriodNarrative(user.id, period, locale);
const isFresh =
existing !== null &&
Date.now() - new Date(existing.updatedAt).getTime() < NARRATIVE_FRESH_MS;
// Read-only: never block on the provider. Warm out of band only when stale
// / missing AND a provider is configured (a provider-less account costs one
// cheap chain-resolve and shows the no-key state instead).
let revalidating = false;
if (!isFresh && (await hasUsableStatusProvider(user.id))) {
void enqueueNarrativeWarm({ userId: user.id, period, locale });
revalidating = true;
}
annotate({
action: { name: "insights.narrative" },
meta: { period, has_narrative: existing !== null, revalidating },
});
return apiSuccess({
period,
locale,
narrative: existing
? {
text: existing.text,
provenance: existing.provenance,
updatedAt: existing.updatedAt,
}
: null,
revalidating,
});
});
+23
View File
@@ -120,6 +120,27 @@ const CoincidentDeviationCard = dynamic(
},
);
// v1.11.0 — period-narrative card (Pillar P1). The calm "your week/month in
// review" summary, drawn from the read-only stale-while-revalidate narrative
// route. Deferred behind `next/dynamic` like the other below-the-hero blocks;
// it owns its own query and un-mounts when no narrative exists. The loader
// skeleton shares the card's `min-h-40` footprint so the page does not shift.
const PeriodNarrativeCard = dynamic(
() =>
import("@/components/insights/period-narrative-card").then((mod) => ({
default: mod.PeriodNarrativeCard,
})),
{
ssr: false,
loading: () => (
<div
aria-hidden="true"
className="bg-card border-border min-h-40 animate-pulse rounded-xl border motion-reduce:animate-none"
/>
),
},
);
/**
* v1.4.25 W4d — Insights mother page.
*
@@ -270,6 +291,8 @@ export default function InsightsPage() {
<CoincidentDeviationCard enabled={isAuthenticated} />
{flags.briefing && <PeriodNarrativeCard enabled={isAuthenticated} />}
<div className="flex justify-end">
<Button
size="sm"
@@ -0,0 +1,212 @@
"use client";
import { useState } from "react";
import { useQuery } from "@tanstack/react-query";
import { Info } from "lucide-react";
import { useTranslations } from "@/lib/i18n/context";
import { queryKeys } from "@/lib/query-keys";
import { cn } from "@/lib/utils";
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover";
/**
* v1.11.0 W3 — period-narrative card (Pillar P1).
*
* A calm, top-of-overview summary of the user's last week / month, drawn from
* the read-only `GET /api/insights/narrative` route. The route is
* stale-while-revalidate: it returns the last good prose instantly and warms a
* fresh one out of band, so this card never blocks on the provider.
*
* Restraint guarantees: plain React text children (NO markdown — the whole
* tree forbids a markdown library for XSS reasons), no score, no chart, a
* single ⓘ provenance disclosure, and a fixed `min-h` footprint shared across
* the loading / preparing / resolved states so the card — and everything below
* it on the overview — never shifts (no CLS).
*/
type NarrativePeriod = "week" | "month";
interface NarrativeProvenance {
metrics: string[];
window: { from: string; to: string };
pairsTested: number;
fdrQ: number;
computedAt: string;
}
interface NarrativeResponse {
period: NarrativePeriod;
locale: string;
narrative: {
text: string;
provenance: NarrativeProvenance | null;
updatedAt: string;
} | null;
revalidating: boolean;
}
interface PeriodNarrativeCardProps {
/** Gate the underlying read (e.g. on the auth flag). */
enabled?: boolean;
className?: string;
}
async function fetchNarrative(
period: NarrativePeriod,
): Promise<NarrativeResponse> {
const res = await fetch(`/api/insights/narrative?period=${period}`);
if (!res.ok) {
throw new Error(`narrative ${res.status}`);
}
return (await res.json()).data as NarrativeResponse;
}
function ProvenanceDisclosure({
provenance,
}: {
provenance: NarrativeProvenance;
}) {
const { t } = useTranslations();
const metrics = provenance.metrics.slice(0, 8).join(", ");
return (
<Popover>
<PopoverTrigger
aria-label={t("insights.narrativeProvenanceLabel")}
className="text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 items-center justify-center rounded-full transition-colors"
>
<Info className="size-3.5" aria-hidden="true" />
</PopoverTrigger>
<PopoverContent className="w-80 text-sm" align="end">
<p className="text-foreground font-medium">
{t("insights.narrativeProvenanceLabel")}
</p>
<p className="text-muted-foreground mt-1">
{t("insights.narrativeProvenanceMethod")}
</p>
{metrics ? (
<p className="text-muted-foreground mt-2 text-xs">
{t("insights.narrativeProvenanceMetrics", { metrics })}
</p>
) : null}
</PopoverContent>
</Popover>
);
}
const SHELL =
"bg-card border-border flex min-h-40 w-full min-w-0 flex-col gap-3 rounded-xl border p-4 md:p-6";
export function PeriodNarrativeCard({
enabled = true,
className,
}: PeriodNarrativeCardProps) {
const { t, locale } = useTranslations();
const [period, setPeriod] = useState<NarrativePeriod>("week");
const query = useQuery({
queryKey: queryKeys.insightsNarrative(period, locale),
queryFn: () => fetchNarrative(period),
enabled,
// The route warms out of band; poll briefly while a refresh is in flight
// so freshly-warmed prose lands without a manual remount.
refetchInterval: (q) =>
q.state.data?.revalidating && !q.state.data.narrative ? 5000 : false,
});
// Loading with nothing to show yet → matched skeleton (CLS-safe).
if (query.isLoading) {
return (
<div
data-slot="period-narrative-card-skeleton"
aria-hidden="true"
className={cn(SHELL, className)}
>
<div className="flex h-7 items-center justify-between gap-2">
<div className="bg-muted/40 h-3 w-32 rounded" />
<div className="bg-muted/40 size-5 rounded-full" />
</div>
<div className="bg-muted/40 h-4 w-full rounded" />
<div className="bg-muted/40 h-4 w-5/6 rounded" />
<div className="bg-muted/40 h-4 w-2/3 rounded" />
</div>
);
}
// The route never errors the page; on a fetch error or a genuinely empty
// account (no narrative ever produced) the card un-mounts itself rather than
// showing an error or an empty husk on the overview.
if (query.isError || (!query.data?.narrative && !query.data?.revalidating)) {
return null;
}
const data = query.data;
const narrative = data?.narrative ?? null;
const preparing = !narrative && data?.revalidating === true;
return (
<div
data-slot="period-narrative-card"
data-period={period}
className={cn(SHELL, className)}
>
<div className="flex items-center justify-between gap-2">
<span className="text-muted-foreground truncate text-xs font-medium tracking-wide uppercase">
{t("insights.narrativeTitle")}
</span>
{narrative?.provenance ? (
<ProvenanceDisclosure provenance={narrative.provenance} />
) : null}
</div>
{/* Week / month toggle. Calm segmented control, no chart. */}
<div className="flex gap-1 self-start" role="tablist">
{(["week", "month"] as const).map((p) => (
<button
key={p}
type="button"
role="tab"
aria-selected={period === p}
onClick={() => setPeriod(p)}
className={cn(
"rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
period === p
? "bg-muted text-foreground"
: "text-muted-foreground hover:text-foreground",
)}
>
{p === "week"
? t("insights.narrativeWeek")
: t("insights.narrativeMonth")}
</button>
))}
</div>
{preparing ? (
<p className="text-muted-foreground text-sm">
{t("insights.narrativePreparing")}
</p>
) : (
// Plain text child — NO markdown renderer (XSS posture, CLAUDE.md).
<p className="text-foreground text-sm leading-relaxed whitespace-pre-line">
{narrative?.text}
</p>
)}
{narrative ? (
<p className="text-muted-foreground mt-auto text-[11px]">
{data?.revalidating
? t("insights.narrativeUpdating")
: t("insights.narrativeUpdated", {
time: new Date(narrative.updatedAt).toLocaleDateString(
locale === "de" ? "de-DE" : undefined,
),
})}
</p>
) : null}
</div>
);
}
@@ -0,0 +1,274 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
// Identity "encryption" so the test asserts on plaintext round-trips without
// an ENCRYPTION_KEYS env. The generator's `encryptToBytes`/`decryptFromBytes`
// wrap these.
vi.mock("@/lib/crypto", () => ({
encrypt: (s: string) => `enc:${s}`,
decrypt: (s: string) => s.replace(/^enc:/, ""),
}));
// Keep the wide-event annotate a no-op.
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
// The default DB import must resolve to something; every test injects its own
// prisma double, so this is only a guard against accidental real-DB use.
vi.mock("@/lib/db", () => ({ prisma: {} }));
import {
generatePeriodNarrative,
readPeriodNarrative,
buildNarrativeUserPrompt,
NARRATIVE_PROMPT_VERSION,
} from "@/lib/insights/narrative/period-narrative-generate";
import type {
PeriodNarrativeContext,
PeriodNarrativeResult,
} from "@/lib/insights/narrative/period-narrative";
function readyContext(
over: Partial<PeriodNarrativeContext> = {},
): PeriodNarrativeContext {
return {
status: "ready",
period: "week",
metricDeltas: [
{
type: "WEIGHT",
unit: "kg",
current: 80,
prior: 81,
delta: -1,
deltaPercent: -1.2,
currentDays: 6,
priorDays: 7,
},
],
bandTransitions: [],
drivers: [
{
behaviour: "ACTIVITY_STEPS",
outcome: "SLEEP_DURATION",
r: 0.4,
qValue: 0.02,
n: 14,
interpretation: "more steps tended to coincide with longer sleep",
},
],
coincidentFlags: [],
pairsTested: 12,
fdrQ: 0.1,
provenance: {
metrics: ["WEIGHT", "ACTIVITY_STEPS", "SLEEP_DURATION"],
window: { from: "2026-05-01T00:00:00.000Z", to: "2026-05-15T00:00:00.000Z" },
computedAt: "2026-05-15T05:00:00.000Z",
},
...over,
};
}
interface FakeRow {
userId: string;
period: string;
locale: string;
dateKey: string;
encryptedContent: Uint8Array;
provenanceJson: string | null;
providerType: string | null;
promptVersion: string | null;
updatedAt: Date;
}
/** Minimal in-memory prisma double for the (user, period, locale) row + user. */
function makePrisma(seedRow?: FakeRow) {
let row: FakeRow | undefined = seedRow;
return {
_get: () => row,
user: {
findUnique: vi.fn(async () => ({ timezone: "Europe/Berlin" })),
},
insightNarrative: {
findUnique: vi.fn(async () => (row ? { ...row } : null)),
upsert: vi.fn(async (args: { create: FakeRow; update: Partial<FakeRow> }) => {
if (row) {
row = { ...row, ...args.update, updatedAt: new Date() };
} else {
row = { ...args.create, updatedAt: new Date() };
}
return { ...row };
}),
},
};
}
beforeEach(() => vi.clearAllMocks());
describe("buildNarrativeUserPrompt", () => {
it("renders metrics, drivers, and the FDR footer with the prompt version", () => {
const prompt = buildNarrativeUserPrompt(readyContext(), "en");
expect(prompt).toContain("WEIGHT");
expect(prompt).toContain("ACTIVITY_STEPS ~ SLEEP_DURATION");
expect(prompt).toContain("12 pairs tested");
expect(NARRATIVE_PROMPT_VERSION).toBe("1.11.0");
});
});
describe("generatePeriodNarrative — descriptive generation", () => {
it("generates a narrative from a seeded ready context and stores it encrypted", async () => {
const prisma = makePrisma();
const runCompletion = vi.fn(async () => ({
kind: "ok" as const,
content: "Your weight eased down slightly this week.",
providerType: "openai",
model: "gpt",
tokensUsed: 50,
}));
const outcome = await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () => readyContext() as PeriodNarrativeResult,
runCompletion,
});
expect(outcome).toEqual({ status: "generated", providerType: "openai" });
expect(prisma.insightNarrative.upsert).toHaveBeenCalledOnce();
const stored = prisma._get();
expect(stored?.promptVersion).toBe(NARRATIVE_PROMPT_VERSION);
// Stored ciphertext is the identity-encoded prose, not plaintext.
expect(Buffer.from(stored!.encryptedContent).toString("utf8")).toBe(
"enc:Your weight eased down slightly this week.",
);
});
it("passes a descriptive-never-causal system prompt to the provider", async () => {
const prisma = makePrisma();
let systemPrompt = "";
const runCompletion = vi.fn(async (args: { systemPrompt: string }) => {
systemPrompt = args.systemPrompt;
return {
kind: "ok" as const,
content: "ok",
providerType: "openai",
model: "m",
tokensUsed: 1,
};
});
await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () => readyContext() as PeriodNarrativeResult,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
runCompletion: runCompletion as any,
});
expect(systemPrompt).toMatch(/never CAUSAL|DESCRIPTIVE/);
expect(systemPrompt).toMatch(/no markdown/i);
});
});
describe("generatePeriodNarrative — honesty floor", () => {
it("writes no narrative when the context is insufficient", async () => {
const prisma = makePrisma();
const runCompletion = vi.fn();
const outcome = await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () =>
({
status: "insufficient",
period: "week",
reason: "not_enough_history",
coverage: { metricsWithData: 1, required: 2 },
}) as PeriodNarrativeResult,
runCompletion,
});
expect(outcome).toEqual({ status: "insufficient" });
expect(runCompletion).not.toHaveBeenCalled();
expect(prisma.insightNarrative.upsert).not.toHaveBeenCalled();
});
it("no-ops without a provider and never fabricates a story", async () => {
const prisma = makePrisma();
const outcome = await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () => readyContext() as PeriodNarrativeResult,
runCompletion: async () => ({ kind: "none" as const }),
});
expect(outcome).toEqual({ status: "skipped", reason: "no-provider" });
expect(prisma.insightNarrative.upsert).not.toHaveBeenCalled();
});
});
describe("generatePeriodNarrative — cache + regenerate", () => {
it("serves a recent row without regenerating", async () => {
const prisma = makePrisma({
userId: "u1",
period: "week",
locale: "en",
dateKey: "2026-05-15",
encryptedContent: new Uint8Array(Buffer.from("enc:old", "utf8")),
provenanceJson: null,
providerType: "openai",
promptVersion: NARRATIVE_PROMPT_VERSION,
updatedAt: new Date(),
});
const runCompletion = vi.fn();
const outcome = await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () => readyContext() as PeriodNarrativeResult,
runCompletion,
});
expect(outcome).toEqual({ status: "cached" });
expect(runCompletion).not.toHaveBeenCalled();
});
it("force regenerates and upserts the single row in place", async () => {
const prisma = makePrisma({
userId: "u1",
period: "week",
locale: "en",
dateKey: "2026-05-15",
encryptedContent: new Uint8Array(Buffer.from("enc:old", "utf8")),
provenanceJson: null,
providerType: "openai",
promptVersion: "0.0.0",
updatedAt: new Date(),
});
const outcome = await generatePeriodNarrative("u1", {
period: "week",
locale: "en",
force: true,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: prisma as any,
buildContext: async () => readyContext() as PeriodNarrativeResult,
runCompletion: async () => ({
kind: "ok" as const,
content: "fresh",
providerType: "anthropic",
model: "m",
tokensUsed: 2,
}),
});
expect(outcome).toEqual({ status: "generated", providerType: "anthropic" });
// Read back the decrypted prose via the public reader.
const read = await readPeriodNarrative(
"u1",
"week",
"en",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma as any,
);
expect(read?.text).toBe("fresh");
expect(read?.providerType).toBe("anthropic");
});
});
@@ -0,0 +1,393 @@
/**
* v1.11.0 W3 — period-narrative GENERATOR (Pillar P1).
*
* A sibling of `generateComprehensiveInsight`: it feeds the W2
* `buildPeriodNarrativeContext` output — a compact, provenance-carrying
* `label + number + source` context — into the user's provider chain with a
* TIGHT, descriptive-never-causal prompt and persists the generated prose in
* the typed `insight_narratives` table (AES-256-GCM at rest).
*
* Honesty floor (inherited verbatim from the W1/W2 layers it consumes):
* - The context is the only ground truth. The prompt forbids inventing any
* number, trend, driver, or threshold not present in the context.
* - Drivers are already BH-FDR survivors with conservative `interpretation`
* strings; the narrative may restate them as associations, NEVER as
* causes.
* - An `insufficient` context (too little history) yields NO narrative — the
* generator returns `{ status: "insufficient" }` and writes nothing, so a
* sparse account never gets a fabricated story.
* - No provider configured → `{ status: "skipped", reason: "no-provider" }`,
* no LLM call. A provider timeout / error is non-fatal and writes nothing.
*
* Cache + stale-while-revalidate mirror the per-status assessments: a fresh
* read serves today's row instantly; a regenerate upserts the single
* (user, period, locale) row in place (delete/regenerate-clean by
* construction — the unique index forbids duplicates).
*/
import type { PrismaClient } from "@/generated/prisma/client";
import { prisma as defaultPrisma } from "@/lib/db";
import { encrypt, decrypt } from "@/lib/crypto";
import { getLocalDateParts } from "@/lib/timezone";
import { annotate } from "@/lib/logging/context";
import { runStatusCompletion } from "@/lib/insights/status-provider";
import {
buildPeriodNarrativeContext,
type NarrativePeriod,
type PeriodNarrativeContext,
} from "@/lib/insights/narrative/period-narrative";
/**
* Stable identifier for the narrative prompt revision. Bumped whenever the
* prompt below changes so the cross-feature attribution aggregator can slice
* quality per (provider × prompt) and a prompt change is observable.
*/
export const NARRATIVE_PROMPT_VERSION = "1.11.0" as const;
/** A narrative cached this recently is served without regenerating. */
const NARRATIVE_FRESH_MS = 20 * 60 * 60 * 1000;
export type NarrativeGenerateOutcome =
| { status: "cached" }
| { status: "generated"; providerType: string }
| { status: "skipped"; reason: "no-provider" }
| { status: "insufficient" }
| { status: "failed"; reason: string };
interface GenerateOptions {
/** Which period to narrate. */
period: NarrativePeriod;
/** Resolved UI locale for the prompt + row. */
locale: "de" | "en";
/** Skip the freshness short-circuit and force a fresh generation. */
force?: boolean;
/** Injected clock for deterministic tests; defaults to now. */
now?: Date;
/** Injected for tests — defaults to the real DB context assembler. */
buildContext?: typeof buildPeriodNarrativeContext;
/** Injected for tests — defaults to the real bounded provider call. */
runCompletion?: typeof runStatusCompletion;
/** Injected for tests — the shared client by default. */
prisma?: PrismaClient;
}
/** The labels-only provenance the surface renders as ⓘ chips. */
export interface NarrativeProvenancePayload {
metrics: string[];
window: { from: string; to: string };
pairsTested: number;
fdrQ: number;
computedAt: string;
}
/** UTC YYYY-MM-DD boundary key for a row, in the user's tz. */
function dateKeyFor(now: Date, tz: string): string {
const { year, month, day } = getLocalDateParts(now, tz);
return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
}
// ── prompt ──────────────────────────────────────────────────────────────
const SYSTEM_PROMPT_EN = `You summarise one person's health-tracking PERIOD (a week or a month) for that person.
Prompt version: ${NARRATIVE_PROMPT_VERSION}.
Hard rules:
- The supplied CONTEXT is the ONLY source of truth. Never state a number, trend, driver, or threshold that is not in it.
- Be DESCRIPTIVE, never CAUSAL. Say "X moved with Y" or "X was associated with Y", never "X caused Y" or "because of X".
- The listed drivers already survived statistical multiple-comparison control; restate them only as associations and keep their conservative meaning.
- No diagnosis, no medical advice, no alarm. Calm, factual, second person ("your").
- 2 to 4 short sentences. Plain text only — no markdown, no headings, no bullet points, no emojis.
- If the context is thin, say plainly that there is little to report this period rather than inventing detail.`;
const SYSTEM_PROMPT_DE = `Du fasst den Gesundheits-Tracking-ZEITRAUM einer Person (eine Woche oder einen Monat) für diese Person zusammen.
Prompt-Version: ${NARRATIVE_PROMPT_VERSION}.
Feste Regeln:
- Der bereitgestellte KONTEXT ist die EINZIGE Wahrheitsquelle. Nenne nie eine Zahl, einen Trend, einen Zusammenhang oder einen Schwellenwert, der nicht darin steht.
- Sei BESCHREIBEND, nie URSÄCHLICH. Sage "X bewegte sich mit Y" oder "X war mit Y assoziiert", nie "X verursachte Y" oder "wegen X".
- Die genannten Zusammenhänge haben bereits die statistische Mehrfachvergleichskorrektur überstanden; gib sie nur als Assoziationen wieder und bewahre ihre vorsichtige Bedeutung.
- Keine Diagnose, kein medizinischer Rat, keine Panik. Ruhig, sachlich, in der zweiten Person ("dein").
- 2 bis 4 kurze Sätze. Nur Klartext — kein Markdown, keine Überschriften, keine Aufzählungen, keine Emojis.
- Wenn der Kontext dünn ist, sage klar, dass es in diesem Zeitraum wenig zu berichten gibt, statt Details zu erfinden.`;
/** Render the typed context into a compact, model-readable block. */
export function buildNarrativeUserPrompt(
context: PeriodNarrativeContext,
locale: "de" | "en",
): string {
const periodLabel =
context.period === "week"
? locale === "de"
? "die letzte Woche (7 Tage)"
: "the last week (7 days)"
: locale === "de"
? "den letzten Monat (30 Tage)"
: "the last month (30 days)";
const lines: string[] = [];
lines.push(
locale === "de"
? `Zeitraum: ${periodLabel}, verglichen mit dem vorherigen gleich langen Zeitraum.`
: `Period: ${periodLabel}, compared with the prior period of equal length.`,
);
if (context.metricDeltas.length > 0) {
lines.push(locale === "de" ? "Veränderungen:" : "Changes:");
for (const d of context.metricDeltas) {
if (d.current === null) continue;
const unit = d.unit ? ` ${d.unit}` : "";
const deltaPart =
d.delta === null
? locale === "de"
? "(kein Vergleich möglich)"
: "(no comparison available)"
: `${d.delta >= 0 ? "+" : ""}${d.delta}${unit}${
d.deltaPercent === null ? "" : ` (${d.deltaPercent}%)`
}`;
lines.push(
`- ${d.type}: ${d.current}${unit} ${deltaPart} [${d.currentDays}d]`,
);
}
}
if (context.bandTransitions.length > 0) {
lines.push(
locale === "de"
? "Persönlicher Normbereich (Median ± Streuung des Vorzeitraums):"
: "Personal typical range (prior-period median ± spread):",
);
for (const b of context.bandTransitions) {
const where =
b.direction === "above"
? locale === "de"
? "über dem Bereich"
: "above the range"
: b.direction === "below"
? locale === "de"
? "unter dem Bereich"
: "below the range"
: locale === "de"
? "im Bereich"
: "in range";
lines.push(
`- ${b.type}: ${b.center} (${b.bandLow}–${b.bandHigh}) → ${where}`,
);
}
}
if (context.drivers.length > 0) {
lines.push(
locale === "de"
? "Statistisch belegte Assoziationen (NICHT kausal):"
: "Statistically supported associations (NOT causal):",
);
for (const dr of context.drivers) {
lines.push(
`- ${dr.behaviour} ~ ${dr.outcome}: r=${dr.r}, q=${dr.qValue}, n=${dr.n} — ${dr.interpretation}`,
);
}
}
if (context.coincidentFlags.length > 0) {
lines.push(
locale === "de"
? `Tage mit mehreren gleichzeitig außerhalb des Normbereichs liegenden Werten: ${context.coincidentFlags.length}.`
: `Days with several vitals outside the typical range together: ${context.coincidentFlags.length}.`,
);
}
lines.push(
locale === "de"
? `(${context.pairsTested} Paare getestet, FDR-Ziel q=${context.fdrQ}.)`
: `(${context.pairsTested} pairs tested, FDR target q=${context.fdrQ}.)`,
);
return lines.join("\n");
}
/**
* Generate + cache the period narrative for one user. Pure pipeline; no
* rate-limit / request concerns (the route + cron add those). Returns a typed
* outcome the caller can log + branch on. Never throws on a provider failure
* (a cron batch loop must continue to the next user).
*/
export async function generatePeriodNarrative(
userId: string,
options: GenerateOptions,
): Promise<NarrativeGenerateOutcome> {
const { locale } = options;
const force = options.force === true;
const now = options.now ?? new Date();
const prisma = options.prisma ?? defaultPrisma;
const buildContext = options.buildContext ?? buildPeriodNarrativeContext;
const runCompletion = options.runCompletion ?? runStatusCompletion;
const period = options.period;
// Freshness short-circuit — a recently-generated row is served as-is.
if (!force) {
const existing = await prisma.insightNarrative.findUnique({
where: { userId_period_locale: { userId, period, locale } },
select: { updatedAt: true },
});
if (
existing &&
now.getTime() - existing.updatedAt.getTime() < NARRATIVE_FRESH_MS
) {
return { status: "cached" };
}
}
const context = await buildContext(userId, { period, now });
if (context.status === "insufficient") {
annotate({
action: { name: "insights.narrative.insufficient" },
meta: { period, reason: context.reason },
});
return { status: "insufficient" };
}
const profile = await prisma.user.findUnique({
where: { id: userId },
select: { timezone: true },
});
const tz = profile?.timezone ?? "Europe/Berlin";
const completion = await runCompletion({
userId,
cacheAction: `insights.narrative.${period}.${locale}`,
systemPrompt: locale === "de" ? SYSTEM_PROMPT_DE : SYSTEM_PROMPT_EN,
userPrompt: buildNarrativeUserPrompt(context, locale),
temperature: 0.3,
maxTokens: 400,
});
if (completion.kind === "none") {
return { status: "skipped", reason: "no-provider" };
}
if (completion.kind === "timeout") {
annotate({
action: { name: "insights.narrative.timeout" },
meta: { period, locale },
});
return { status: "failed", reason: "timeout" };
}
if (completion.kind === "error") {
return { status: "failed", reason: "provider-error" };
}
const text = completion.content.trim();
if (text.length === 0) {
return { status: "failed", reason: "empty" };
}
const provenance: NarrativeProvenancePayload = {
metrics: context.provenance.metrics,
window: context.provenance.window,
pairsTested: context.pairsTested,
fdrQ: context.fdrQ,
computedAt: context.provenance.computedAt,
};
// Upsert the single (user, period, locale) row in place — delete/regenerate
// clean by construction. The prose is held AES-256-GCM at rest.
const encryptedContent = encryptToBytes(text);
const dateKey = dateKeyFor(now, tz);
await prisma.insightNarrative.upsert({
where: { userId_period_locale: { userId, period, locale } },
create: {
userId,
period,
locale,
dateKey,
encryptedContent,
provenanceJson: JSON.stringify(provenance),
providerType: completion.providerType,
promptVersion: NARRATIVE_PROMPT_VERSION,
},
update: {
dateKey,
encryptedContent,
provenanceJson: JSON.stringify(provenance),
providerType: completion.providerType,
promptVersion: NARRATIVE_PROMPT_VERSION,
},
});
annotate({
action: { name: "insights.narrative.generated" },
meta: { period, locale, provider: completion.providerType },
});
return { status: "generated", providerType: completion.providerType };
}
/** The narrative row, decrypted for a read. */
export interface NarrativeRead {
period: NarrativePeriod;
locale: "de" | "en";
text: string;
dateKey: string;
provenance: NarrativeProvenancePayload | null;
providerType: string | null;
promptVersion: string | null;
updatedAt: string;
}
/**
* Read the latest narrative for `(userId, period, locale)`, decrypting the
* prose. Null when none was ever generated. This is the stale-while-revalidate
* source: it returns whatever was last produced, regardless of age, so the
* surface renders prior prose immediately while a refresh warms out of band.
*/
export async function readPeriodNarrative(
userId: string,
period: NarrativePeriod,
locale: "de" | "en",
prisma: PrismaClient = defaultPrisma,
): Promise<NarrativeRead | null> {
const row = await prisma.insightNarrative.findUnique({
where: { userId_period_locale: { userId, period, locale } },
});
if (!row) return null;
let text: string;
try {
text = decryptFromBytes(row.encryptedContent);
} catch {
// A row we cannot decrypt is treated as absent — the caller regenerates.
return null;
}
let provenance: NarrativeProvenancePayload | null = null;
if (row.provenanceJson) {
try {
provenance = JSON.parse(row.provenanceJson) as NarrativeProvenancePayload;
} catch {
provenance = null;
}
}
return {
period: row.period as NarrativePeriod,
locale: row.locale as "de" | "en",
text,
dateKey: row.dateKey,
provenance,
providerType: row.providerType,
promptVersion: row.promptVersion,
updatedAt: row.updatedAt.toISOString(),
};
}
// ── helpers ───────────────────────────────────────────────────────────────
/** Prisma `Bytes` ↔ ciphertext, mirroring the CoachMessage helper. */
function encryptToBytes(plaintext: string): Uint8Array<ArrayBuffer> {
const ciphertext = encrypt(plaintext);
const encoded = Buffer.from(ciphertext, "utf8");
const out = new Uint8Array(new ArrayBuffer(encoded.byteLength));
out.set(encoded);
return out;
}
function decryptFromBytes(buf: Uint8Array): string {
return decrypt(Buffer.from(buf).toString("utf8"));
}
@@ -0,0 +1,167 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
import fs from "node:fs";
import path from "node:path";
const checkRateLimit = vi.fn();
const getAssistantFlags = vi.fn();
vi.mock("@/lib/rate-limit", () => ({
checkRateLimit: (...a: unknown[]) => checkRateLimit(...a),
}));
vi.mock("@/lib/feature-flags", () => ({
getAssistantFlags: (...a: unknown[]) => getAssistantFlags(...a),
}));
// Never reach the real generator (which imports the provider chain).
vi.mock("@/lib/insights/narrative/period-narrative-generate", () => ({
generatePeriodNarrative: vi.fn(),
}));
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
import {
runPeriodNarrativeWarm,
periodsForDay,
findNarrativeCandidates,
PERIOD_NARRATIVE_QUEUE,
PERIOD_NARRATIVE_CRON,
} from "../period-narrative-warm";
function makePrisma(users: Array<{ id: string; locale: string | null }>) {
const findMany = vi.fn().mockResolvedValue(users);
return { prisma: { user: { findMany } }, findMany };
}
// A Monday that is also the 1st of the month — both periods warm.
const MON_FIRST = new Date("2026-06-01T03:05:00.000Z");
// A plain Tuesday mid-month — no boundary.
const TUE_MID = new Date("2026-06-02T03:05:00.000Z");
// A Monday that is not the 1st — week only.
const MON_MID = new Date("2026-06-08T03:05:00.000Z");
beforeEach(() => {
vi.clearAllMocks();
getAssistantFlags.mockResolvedValue({
enabled: true,
briefing: true,
insightStatus: true,
});
checkRateLimit.mockResolvedValue({ allowed: true });
});
describe("periodsForDay — boundary gate", () => {
it("warms week on a Monday", () => {
expect(periodsForDay(MON_MID)).toContain("week");
expect(periodsForDay(MON_MID)).not.toContain("month");
});
it("warms month on the 1st", () => {
expect(periodsForDay(MON_FIRST)).toContain("month");
});
it("warms nothing on a plain mid-week day", () => {
expect(periodsForDay(TUE_MID)).toEqual([]);
});
});
describe("findNarrativeCandidates", () => {
it("filters coach-enabled users, capped", async () => {
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await findNarrativeCandidates(prisma as any, 50);
const arg = findMany.mock.calls[0][0];
expect(arg.where.disableCoach).toBe(false);
expect(arg.take).toBe(50);
});
});
describe("runPeriodNarrativeWarm", () => {
it("is a no-op on a non-boundary night (no generation)", async () => {
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
const generate = vi.fn();
const result = await runPeriodNarrativeWarm(
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma as any,
{ now: TUE_MID, generate },
);
expect(result.periods).toEqual([]);
expect(findMany).not.toHaveBeenCalled();
expect(generate).not.toHaveBeenCalled();
});
it("generates the boundary periods for each candidate, gated by budget", async () => {
const { prisma } = makePrisma([
{ id: "u1", locale: "de" },
{ id: "u2", locale: "en" },
]);
const generate = vi
.fn()
.mockResolvedValue({ status: "generated", providerType: "openai" });
const result = await runPeriodNarrativeWarm(
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma as any,
{ now: MON_FIRST, generate },
);
expect(result.periods.sort()).toEqual(["month", "week"]);
// 2 users × 2 periods.
expect(generate).toHaveBeenCalledTimes(4);
expect(result.generated).toBe(4);
// Budget bucket checked once per user.
expect(checkRateLimit).toHaveBeenCalledTimes(2);
});
it("skips a budget-blocked user without generating", async () => {
const { prisma } = makePrisma([{ id: "u1", locale: "de" }]);
checkRateLimit.mockResolvedValueOnce({ allowed: false });
const generate = vi.fn();
const result = await runPeriodNarrativeWarm(
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma as any,
{ now: MON_MID, generate },
);
expect(result.budgetBlocked).toBe(1);
expect(generate).not.toHaveBeenCalled();
});
it("short-circuits when the briefing surface is disabled", async () => {
getAssistantFlags.mockResolvedValueOnce({
enabled: false,
briefing: false,
insightStatus: false,
});
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
const generate = vi.fn();
const result = await runPeriodNarrativeWarm(
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma as any,
{ now: MON_FIRST, generate },
);
expect(result.periods).toEqual([]);
expect(findMany).not.toHaveBeenCalled();
expect(generate).not.toHaveBeenCalled();
});
});
describe("queue registration", () => {
const workerSrc = fs.readFileSync(
path.resolve(__dirname, "../reminder-worker.ts"),
"utf8",
);
it("registers the queue in the allQueues createQueue loop", () => {
const match = workerSrc.match(/const allQueues\s*=\s*\[([\s\S]*?)\];/);
expect(match).not.toBeNull();
expect(match![1]).toMatch(/\bPERIOD_NARRATIVE_QUEUE\b/);
});
it("schedules the cron in the schedules table", () => {
expect(workerSrc).toMatch(
/\[\s*PERIOD_NARRATIVE_QUEUE\s*,\s*PERIOD_NARRATIVE_CRON\s*\]/,
);
});
it("registers a boss.work handler for the queue", () => {
expect(workerSrc).toMatch(/boss\.work[\s\S]{0,120}PERIOD_NARRATIVE_QUEUE/);
});
it("exposes a sane queue name + nightly cron", () => {
expect(PERIOD_NARRATIVE_QUEUE).toBe("period-narrative-warm");
expect(PERIOD_NARRATIVE_CRON).toMatch(/^\d+\s+\d+\s+\*\s+\*\s+\*$/);
});
});
+75
View File
@@ -0,0 +1,75 @@
/**
* v1.11.0 W3 — generator-free contract for the period-narrative warm queue.
*
* The read-only GET route enqueues a single-user warm here without importing
* the concrete generator (which would pull the provider chain + W2 context
* assembler into the route bundle). The worker-only pipeline
* (`runPeriodNarrativeWarm`) lives in `period-narrative-warm.ts`, which
* re-exports the queue name from here so there is one source of truth.
*
* Mirrors the `insight-pregenerate-shared.ts` split exactly: queue name +
* payload type + cron + enqueue helper here, the concrete dispatch in the
* worker module.
*/
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { annotate } from "@/lib/logging/context";
import type { NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
export const PERIOD_NARRATIVE_QUEUE = "period-narrative-warm";
/**
* Nightly at 05:05 Europe/Berlin — inside the existing maintenance window,
* after the comprehensive insight pre-generation (04:30) and the computed
* scores (04:45–04:55) so the rollup signals it reads are already folded.
* The handler only does real work near a week/month boundary; on every other
* night it short-circuits cheaply.
*/
export const PERIOD_NARRATIVE_CRON = "5 5 * * *";
export interface PeriodNarrativePayload {
/** Set on the nightly scheduled tick (informational). */
triggeredAt?: string;
/** Single-user warm enqueued by the read-only GET on a cold/stale read. */
userId?: string;
/** Period to warm on the single-user path. */
period?: NarrativePeriod;
/** Locale to warm; defaults to "de" when absent. */
locale?: "de" | "en";
}
/**
* Fire-and-forget enqueue used by the read-only GET on a cold/stale read. A
* `singletonKey` per `(user, period, locale)` collapses repeated reads within
* a short window into one queued job. No-ops cleanly when the global boss is
* unavailable (a web process without an embedded worker) — the nightly cron
* remains the catch-net.
*/
export async function enqueueNarrativeWarm(payload: {
userId: string;
period: NarrativePeriod;
locale: "de" | "en";
}): Promise<void> {
const boss = getGlobalBoss();
if (!boss) return;
try {
await boss.send(
PERIOD_NARRATIVE_QUEUE,
{
userId: payload.userId,
period: payload.period,
locale: payload.locale,
} satisfies PeriodNarrativePayload,
{
singletonKey: `warm:${payload.userId}:${payload.period}:${payload.locale}`,
singletonSeconds: 120,
},
);
annotate({
action: { name: "insights.narrative.warm.enqueued" },
meta: { period: payload.period, locale: payload.locale },
});
} catch {
// Best-effort — a failure just means the narrative stays as-is until the
// next read or the nightly cron warms it.
}
}
+236
View File
@@ -0,0 +1,236 @@
/**
* v1.11.0 W3 — nightly period-narrative warm cron + single-user dispatch.
*
* The nightly tick warms the latest week/month narrative for data-bearing,
* coach-enabled users so the Insights overview renders the summary instantly
* the morning after a period boundary, never blocking the first mount on the
* provider. The handler only fans out near a boundary:
* - the WEEK narrative warms on Mondays (the day after a week closes),
* - the MONTH narrative warms on the 1st of the month.
* On every other night it short-circuits to a no-op for cheapness.
*
* Budget gate (mirrors `insight-pregenerate`): a per-user rate-limit bucket
* (`period-narrative:<userId>`, one warm / 20 h) bounds nightly LLM cost, and
* a per-run batch cap bounds a single tick. The generator no-ops cleanly
* without a provider (one cheap chain-resolve, no LLM) and writes nothing on
* an insufficient context, so a provider-less / sparse account is near-free.
*
* Recurring pg-boss task — never runs inside an HTTP request, never shells out
* to `tsx` (CLAUDE.md DO-NOTs).
*/
import type { PrismaClient } from "@/generated/prisma/client";
import { checkRateLimit } from "@/lib/rate-limit";
import { getAssistantFlags } from "@/lib/feature-flags";
import { annotate } from "@/lib/logging/context";
import {
generatePeriodNarrative,
type NarrativeGenerateOutcome,
} from "@/lib/insights/narrative/period-narrative-generate";
import type { NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
import {
PERIOD_NARRATIVE_QUEUE,
PERIOD_NARRATIVE_CRON,
enqueueNarrativeWarm,
type PeriodNarrativePayload,
} from "@/lib/jobs/period-narrative-shared";
export {
PERIOD_NARRATIVE_QUEUE,
PERIOD_NARRATIVE_CRON,
enqueueNarrativeWarm,
};
export type { PeriodNarrativePayload };
/** Per-run cap on the number of users a single tick generates for. */
export const NARRATIVE_BATCH_CAP = 200;
/** Per-user budget bucket window — one warm per 20 h. */
const NARRATIVE_BUDGET_WINDOW_MS = 20 * 60 * 60 * 1000;
export interface NarrativeWarmRunResult {
/** Periods warmed this tick (empty when not on a boundary night). */
periods: NarrativePeriod[];
total: number;
generated: number;
cached: number;
skipped: number;
insufficient: number;
failed: number;
budgetBlocked: number;
}
/**
* Which period narratives a given calendar day should warm. The week
* narrative warms on Mondays (`getDay() === 1`); the month narrative warms on
* the 1st. A day can be both (the 1st falling on a Monday). Returns an empty
* list on a non-boundary day, so the nightly cron is a no-op most nights.
*
* Exported + pure so the cron test can pin the boundary logic without a clock.
*/
export function periodsForDay(now: Date, tz = "Europe/Berlin"): NarrativePeriod[] {
// Resolve the local weekday + day-of-month in the maintenance-window tz so
// the boundary matches the user-facing calendar, not UTC.
const parts = new Intl.DateTimeFormat("en-US", {
timeZone: tz,
weekday: "short",
day: "numeric",
}).formatToParts(now);
const weekday = parts.find((p) => p.type === "weekday")?.value;
const dayOfMonth = Number(parts.find((p) => p.type === "day")?.value);
const periods: NarrativePeriod[] = [];
if (weekday === "Mon") periods.push("week");
if (dayOfMonth === 1) periods.push("month");
return periods;
}
interface NarrativeCandidate {
id: string;
locale: string | null;
}
/**
* Discovery query — coach-enabled users, oldest-narrative-first so the
* staleest users are served before the per-run cap bites. Whether a user has
* a provider / enough history is confirmed inside the generator (skipped /
* insufficient), so a provider-less or sparse account costs at most one cheap
* chain-resolve and no LLM call.
*/
export async function findNarrativeCandidates(
prisma: PrismaClient,
cap: number,
): Promise<NarrativeCandidate[]> {
return prisma.user.findMany({
where: { disableCoach: false },
take: cap,
select: { id: true, locale: true },
});
}
function normalizeLocale(value: string | null): "de" | "en" {
return value === "en" ? "en" : "de";
}
/**
* Run one nightly warm pass. Pure of pg-boss so the unit test can drive it
* directly. Short-circuits to a no-op when (a) the master assistant briefing
* switch is off or (b) the night is not a period boundary. The per-user
* budget gate runs BEFORE the LLM call so a no-op night costs only
* rate-limit upserts.
*/
export async function runPeriodNarrativeWarm(
prisma: PrismaClient,
options: {
now?: Date;
cap?: number;
/** Injected for the test — defaults to the real generator. */
generate?: typeof generatePeriodNarrative;
} = {},
): Promise<NarrativeWarmRunResult> {
const now = options.now ?? new Date();
const cap = options.cap ?? NARRATIVE_BATCH_CAP;
const generate = options.generate ?? generatePeriodNarrative;
const result: NarrativeWarmRunResult = {
periods: [],
total: 0,
generated: 0,
cached: 0,
skipped: 0,
insufficient: 0,
failed: 0,
budgetBlocked: 0,
};
const flags = await getAssistantFlags();
if (!flags.briefing) return result;
const periods = periodsForDay(now);
result.periods = periods;
if (periods.length === 0) return result;
const candidates = await findNarrativeCandidates(prisma, cap);
result.total = candidates.length;
for (const candidate of candidates) {
const budget = await checkRateLimit(
`period-narrative:${candidate.id}`,
1,
NARRATIVE_BUDGET_WINDOW_MS,
);
if (!budget.allowed) {
result.budgetBlocked++;
continue;
}
const locale = normalizeLocale(candidate.locale);
for (const period of periods) {
const outcome = await generate(candidate.id, {
period,
locale,
force: true,
now,
});
tally(result, outcome);
}
}
annotate({
action: { name: "insights.narrative.warm.run" },
meta: {
periods,
total: result.total,
generated: result.generated,
cached: result.cached,
skipped: result.skipped,
insufficient: result.insufficient,
failed: result.failed,
budget_blocked: result.budgetBlocked,
},
});
return result;
}
function tally(
result: NarrativeWarmRunResult,
outcome: NarrativeGenerateOutcome,
): void {
switch (outcome.status) {
case "generated":
result.generated++;
break;
case "cached":
result.cached++;
break;
case "skipped":
result.skipped++;
break;
case "insufficient":
result.insufficient++;
break;
case "failed":
result.failed++;
break;
}
}
/**
* Single-user warm enqueued by the read-only GET on a cold/stale read. Runs
* the generator directly for one (user, period, locale) WITHOUT the nightly
* budget bucket (the enqueue's `singletonKey` is the anti-spam layer). The
* generator no-ops cleanly without a provider and writes nothing on an
* insufficient context, so this is bounded by construction.
*/
export async function warmOneNarrative(
payload: PeriodNarrativePayload,
): Promise<NarrativeGenerateOutcome | null> {
if (!payload.userId || !payload.period) return null;
const flags = await getAssistantFlags();
if (!flags.briefing && !flags.insightStatus) return null;
return generatePeriodNarrative(payload.userId, {
period: payload.period,
locale: payload.locale ?? "de",
force: true,
});
}
+43
View File
@@ -95,6 +95,13 @@ import {
STRAIN_SCORE_CRON,
runStrainScore,
} from "@/lib/jobs/strain-score";
import {
PERIOD_NARRATIVE_QUEUE,
PERIOD_NARRATIVE_CRON,
runPeriodNarrativeWarm,
warmOneNarrative,
type PeriodNarrativePayload,
} from "@/lib/jobs/period-narrative-warm";
import {
DENSE_INTRADAY_RETENTION_QUEUE,
DENSE_INTRADAY_RETENTION_CONCURRENCY,
@@ -2318,6 +2325,10 @@ export async function startReminderWorker() {
// onto the drain-cumulative tick). The queue MUST be registered here or
// the boot enqueue silently never drains.
DENSE_INTRADAY_RETENTION_QUEUE,
// v1.11.0 — nightly period-narrative warm + single-user warm enqueued by
// the read-only narrative GET. The queue MUST be registered here or the
// GET-miss enqueue silently never warms.
PERIOD_NARRATIVE_QUEUE,
];
for (const q of allQueues) {
@@ -2429,6 +2440,10 @@ export async function startReminderWorker() {
// Strain-score compute + store, after the recovery + stress passes so
// the nightly score writes stay ordered.
[STRAIN_SCORE_QUEUE, STRAIN_SCORE_CRON],
// v1.11.0 — nightly 05:05 Europe/Berlin period-narrative warm. The
// handler only fans out on a week (Mon) / month (1st) boundary; every
// other night is a cheap no-op. Budget-gated per user inside the runner.
[PERIOD_NARRATIVE_QUEUE, PERIOD_NARRATIVE_CRON],
];
for (const [name, cron] of schedules) {
@@ -2694,6 +2709,34 @@ export async function startReminderWorker() {
}
},
);
// v1.11.0 — period-narrative warm. A scheduled tick (no `userId`) runs the
// boundary-gated nightly fan-out; a `userId` payload runs a single-user warm
// enqueued by the read-only GET on a cold/stale read. Single-flight so two
// ticks never double-walk the cohort; the per-user budget gate covers the
// fan-out and the enqueue `singletonKey` covers the single-user path.
await boss.work<PeriodNarrativePayload>(
PERIOD_NARRATIVE_QUEUE,
{ localConcurrency: 1 },
async (jobs) => {
for (const job of jobs) {
try {
if (job.data?.userId) {
await warmOneNarrative(job.data);
} else {
const summary = await runPeriodNarrativeWarm(getWorkerPrisma());
workerLog(
"info",
`[period-narrative] periods=${summary.periods.join(",") || "none"} total=${summary.total} generated=${summary.generated} cached=${summary.cached} skipped=${summary.skipped} insufficient=${summary.insufficient} failed=${summary.failed} budget=${summary.budgetBlocked}`,
);
}
} catch (err) {
recordError();
workerLog("error", "[period-narrative] warm failed", err);
throw err;
}
}
},
);
// v1.8.3 — on-demand per-metric status generation enqueued by the
// read-only status route on a cold card. Low concurrency so a first
// visit that cold-misses several cards can't saturate the Prisma pool
+7
View File
@@ -101,6 +101,13 @@ export const queryKeys = {
* without a second LLM round-trip.
*/
insightsAdvisor: () => ["insights", "advisor"] as const,
/**
* v1.11.0 — period-narrative summary (`/api/insights/narrative?period=…`).
* Keyed by period + locale so the week and month summaries cache
* independently and a locale switch fetches the matching prose.
*/
insightsNarrative: (period: string, locale: string) =>
["insights", "narrative", period, locale] as const,
insightsBpStatus: (locale: string) =>
["insights", "blood-pressure-status", locale] as const,
insightsWeightStatus: (locale: string) =>