From 5917bba61c89a0550d7c5c532dbb90675394d2f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Thu, 4 Jun 2026 01:20:57 +0200 Subject: [PATCH] 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. --- knip.json | 3 +- messages/de.json | 10 + messages/en.json | 10 + messages/es.json | 10 + messages/fr.json | 10 + messages/it.json | 10 + messages/pl.json | 10 + .../migration.sql | 43 ++ prisma/schema.prisma | 49 +++ src/app/api/insights/narrative/route.ts | 95 +++++ src/app/insights/page.tsx | 23 + .../insights/period-narrative-card.tsx | 212 ++++++++++ .../period-narrative-generate.test.ts | 274 ++++++++++++ .../narrative/period-narrative-generate.ts | 393 ++++++++++++++++++ .../__tests__/period-narrative-warm.test.ts | 167 ++++++++ src/lib/jobs/period-narrative-shared.ts | 75 ++++ src/lib/jobs/period-narrative-warm.ts | 236 +++++++++++ src/lib/jobs/reminder-worker.ts | 43 ++ src/lib/query-keys.ts | 7 + 19 files changed, 1678 insertions(+), 2 deletions(-) create mode 100644 prisma/migrations/0113_v1110_insight_narratives/migration.sql create mode 100644 src/app/api/insights/narrative/route.ts create mode 100644 src/components/insights/period-narrative-card.tsx create mode 100644 src/lib/insights/narrative/__tests__/period-narrative-generate.test.ts create mode 100644 src/lib/insights/narrative/period-narrative-generate.ts create mode 100644 src/lib/jobs/__tests__/period-narrative-warm.test.ts create mode 100644 src/lib/jobs/period-narrative-shared.ts create mode 100644 src/lib/jobs/period-narrative-warm.ts diff --git a/knip.json b/knip.json index fb9aa973e..4b0f6accf 100644 --- a/knip.json +++ b/knip.json @@ -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"] } } diff --git a/messages/de.json b/messages/de.json index 527c4e5e2..652dd2153 100644 --- a/messages/de.json +++ b/messages/de.json @@ -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", diff --git a/messages/en.json b/messages/en.json index f3ec7ab62..aecdfcbae 100644 --- a/messages/en.json +++ b/messages/en.json @@ -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", diff --git a/messages/es.json b/messages/es.json index 33323462c..44af26e15 100644 --- a/messages/es.json +++ b/messages/es.json @@ -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", diff --git a/messages/fr.json b/messages/fr.json index 17456de80..8a07a68c9 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -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", diff --git a/messages/it.json b/messages/it.json index c4d7756b4..e25ad9ad5 100644 --- a/messages/it.json +++ b/messages/it.json @@ -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", diff --git a/messages/pl.json b/messages/pl.json index 8efa74dbe..461326124 100644 --- a/messages/pl.json +++ b/messages/pl.json @@ -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", diff --git a/prisma/migrations/0113_v1110_insight_narratives/migration.sql b/prisma/migrations/0113_v1110_insight_narratives/migration.sql new file mode 100644 index 000000000..b4655a390 --- /dev/null +++ b/prisma/migrations/0113_v1110_insight_narratives/migration.sql @@ -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; diff --git a/prisma/schema.prisma b/prisma/schema.prisma index bc7918d87..35bfcc8b9 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -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") +} diff --git a/src/app/api/insights/narrative/route.ts b/src/app/api/insights/narrative/route.ts new file mode 100644 index 000000000..5b48b8868 --- /dev/null +++ b/src/app/api/insights/narrative/route.ts @@ -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, + }); +}); diff --git a/src/app/insights/page.tsx b/src/app/insights/page.tsx index 5e13eae83..8c771c38b 100644 --- a/src/app/insights/page.tsx +++ b/src/app/insights/page.tsx @@ -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: () => ( + + ); +} diff --git a/src/lib/insights/narrative/__tests__/period-narrative-generate.test.ts b/src/lib/insights/narrative/__tests__/period-narrative-generate.test.ts new file mode 100644 index 000000000..20c08b811 --- /dev/null +++ b/src/lib/insights/narrative/__tests__/period-narrative-generate.test.ts @@ -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 { + 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 }) => { + 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"); + }); +}); diff --git a/src/lib/insights/narrative/period-narrative-generate.ts b/src/lib/insights/narrative/period-narrative-generate.ts new file mode 100644 index 000000000..f4589e6a8 --- /dev/null +++ b/src/lib/insights/narrative/period-narrative-generate.ts @@ -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 { + 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 { + 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 { + 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")); +} diff --git a/src/lib/jobs/__tests__/period-narrative-warm.test.ts b/src/lib/jobs/__tests__/period-narrative-warm.test.ts new file mode 100644 index 000000000..52eb46354 --- /dev/null +++ b/src/lib/jobs/__tests__/period-narrative-warm.test.ts @@ -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+\*$/); + }); +}); diff --git a/src/lib/jobs/period-narrative-shared.ts b/src/lib/jobs/period-narrative-shared.ts new file mode 100644 index 000000000..47ffc0e44 --- /dev/null +++ b/src/lib/jobs/period-narrative-shared.ts @@ -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 { + 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. + } +} diff --git a/src/lib/jobs/period-narrative-warm.ts b/src/lib/jobs/period-narrative-warm.ts new file mode 100644 index 000000000..52039bfcd --- /dev/null +++ b/src/lib/jobs/period-narrative-warm.ts @@ -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:`, 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 { + 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 { + 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 { + 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, + }); +} diff --git a/src/lib/jobs/reminder-worker.ts b/src/lib/jobs/reminder-worker.ts index 3656e28f8..7fdf857fb 100644 --- a/src/lib/jobs/reminder-worker.ts +++ b/src/lib/jobs/reminder-worker.ts @@ -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( + 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 diff --git a/src/lib/query-keys.ts b/src/lib/query-keys.ts index 2c61d640e..7d2347dad 100644 --- a/src/lib/query-keys.ts +++ b/src/lib/query-keys.ts @@ -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) =>