Files
HealthLog/src/lib/insights/status-shared.ts
T
Marc-André Bombeck 6f60812132 fix(ai): accept every app language on the chat and status requests
The Coach chat, the document chat and the fenced chat declared their
locale field as de/en, so a body naming French, Korean, Brazilian
Portuguese or any other shipped language was refused with 422 before
resolveServerLocale, which carries every locale, ever saw it. The same
pair sat on the profile update, so an account could not store any other
language there either, and the stored language is what the cookie-blind
background work (the Coach nudge, notification texts) writes in.

All four now take z.enum(locales), and the published contract for the
metric, insight and biomarker status queries and the profile update
lists every UI locale instead of two.
2026-10-29 09:19:56 +01:00

408 lines
15 KiB
TypeScript

/**
* Shared helpers for the seven per-card status generators.
*
* Every `src/lib/insights/*-status.ts` generator carried byte-identical
* copies of `round`, `normalizeSummaryText`, `normalizeLocale`, and (in
* six of seven) `summarizeSeries`, plus an identical "parse the model's
* `{summary}` envelope" block and an identical persist block. This module is the single source of truth so a change
* to the rounding precision, the chart-token scrub, or the cache-row
* shape lands once rather than seven times.
*
* `SupportedLocale` is the full UI locale union. The status prompts
* compose one of two reviewed instruction bodies (de / en) but name the
* reader's own language in an explicit output directive, so the reader's
* locale must survive the whole pipeline rather than being collapsed to a
* binary on the way in. The
* medication-compliance generator stores per-medication lines next to its
* summary, so it shares `round`, `normalizeSummaryText`, `normalizeLocale`,
* and `parseSummaryFromContent` but writes its note through `writeStatusNote`
* directly.
*/
import { writeStatusNote } from "@/lib/insights/status-cache";
import { locales, type Locale } from "@/lib/i18n/config";
import { extractJsonObject } from "@/lib/ai/json-extract";
import { stripChartTokens } from "@/lib/insights/chart-tokens";
import {
screenModelOutput,
INSIGHTS_CONTRACTS,
type OutboundReason,
} from "@/lib/ai/safety/outbound-screen";
/**
* The locales the assessment pipeline carries end-to-end — every one the UI
* ships. Aliased to the i18n `Locale` so adding a UI locale widens the
* pipeline in one place rather than needing a second edit here.
*/
export type SupportedLocale = Locale;
const SUPPORTED_LOCALES: ReadonlySet<string> = new Set(locales);
/**
* The presentation contract shared by assessment producers and consumers.
*
* `kind` is the only branch discriminator. In particular, provider
* availability is metadata: it must never hide safe deterministic text.
* Provider/error details deliberately do not belong in this envelope.
*/
export type AssessmentStatus =
| {
kind: "generated";
text: string;
hasProvider: true;
updatedAt: string | null;
retryable: false;
}
| {
kind: "screened-fallback";
text: string;
hasProvider: boolean;
updatedAt: null;
retryable: true;
reason: OutboundReason | "unparseable_output" | "ungrounded_output";
}
| {
kind: "no-provider";
text: null;
hasProvider: false;
updatedAt: null;
retryable: false;
}
| {
kind: "preparing";
text: null;
hasProvider: true;
updatedAt: null;
retryable: true;
}
| {
kind: "revalidating";
text: string;
hasProvider: true;
updatedAt: string | null;
retryable: true;
}
| {
kind: "timeout" | "error";
text: null;
hasProvider: true;
updatedAt: null;
retryable: true;
}
| {
kind: "exhausted";
text: null;
hasProvider: true;
updatedAt: null;
retryable: false;
};
/** Round to `digits` decimal places. */
export function round(value: number, digits = 1): number {
const factor = 10 ** digits;
return Math.round(value * factor) / factor;
}
/** Scrub chart tokens and collapse whitespace out of a model summary. */
export function normalizeSummaryText(value: string): string {
return stripChartTokens(value).replace(/\s+/g, " ").trim();
}
/**
* Validate an arbitrary locale string against every locale the UI ships.
*
* A recognised locale passes through UNCHANGED — that is the whole point:
* the former `value === "de" ? "de" : "en"` binary erased a French reader's
* locale before any prompt saw it, so the output-language directive could
* never fire. An unrecognised or missing value defaults to ENGLISH, never
* German; a German default is the bug class this replaces.
*/
export function normalizeLocale(
value: string | null | undefined,
): SupportedLocale {
return typeof value === "string" && SUPPORTED_LOCALES.has(value)
? (value as SupportedLocale)
: "en";
}
export interface SeriesSummary {
points: number;
start: number;
end: number;
delta: number;
mean: number;
min: number;
max: number;
}
/**
* Fold a value series into a single start/end/delta/mean/min/max
* summary. Returns null for an empty series.
*
* v1.4.33 — fold sum/min/max into a single walk. The previous
* `Math.min(...series.map(...))` / `Math.max(...series.map(...))`
* spread tripped V8's ~125 000-arg ceiling on the bound /api/analytics
* path; see `.planning/round-v1433-analytics-500-report.md` §"Carry-
* over". These helpers are fed bounded windows today so the crash
* never reached them, but the spread allocates a transient args array
* on every call — the fold is both stack-safe and cheaper.
*/
export function summarizeSeries(
series: Array<{ value: number }>,
): SeriesSummary | null {
if (series.length === 0) return null;
const first = series[0].value;
const last = series[series.length - 1].value;
let sum = 0;
let minVal = series[0].value;
let maxVal = series[0].value;
for (const entry of series) {
sum += entry.value;
if (entry.value < minVal) minVal = entry.value;
if (entry.value > maxVal) maxVal = entry.value;
}
return {
points: series.length,
start: round(first, 2),
end: round(last, 2),
delta: round(last - first, 2),
mean: round(sum / series.length, 2),
min: round(minVal, 2),
max: round(maxVal, 2),
};
}
/**
* Strip a Markdown code fence and isolate the JSON object body.
*
* The Anthropic and local providers have no native JSON mode (only the
* OpenAI-family clients send `response_format: json_object`), so a
* compliant model still routinely wraps its `{ "summary": ... }` reply in a
* ```json ... ``` fence or prefixes it with a sentence. `JSON.parse` then
* throws and the caller would surface the raw fenced string as the
* user-facing assessment. The extraction itself lives in
* `src/lib/ai/json-extract.ts`, where the Anthropic client applies it on the
* way out; this name stays for the insights callers.
*/
export function stripJsonFences(content: string): string {
return extractJsonObject(content);
}
/**
* Outcome of reading a status completion for its user-facing summary.
*
* - `summary` — a `{ "summary": "…" }` envelope parsed to a non-empty
* string. Render it.
* - `prose` — the model ignored the JSON contract and returned a plain
* sentence. Render it verbatim (back-compat with non-JSON-mode providers).
* - `unparseable` — the model ATTEMPTED the structured envelope but it came
* back malformed, truncated, or summary-less. There is NO safe text to
* render: the caller must fall back to its deterministic stub. This is the
* state that stops a partial `{ "summary": "…` (braces, property name,
* quotes, literal `\n`) from ever reaching the card — the class of bug
* reported against the resting-pulse Assessment.
*/
export type SummaryExtraction =
| { kind: "summary"; text: string }
| { kind: "prose"; text: string }
| { kind: "unparseable" };
/**
* Parse a candidate string as a `{ summary }` object. Reports whether the
* string was valid JSON *object* at all (`parsed`) separately from whether it
* carried a usable non-empty `summary` — so the caller can tell a malformed /
* truncated envelope apart from a well-formed object that simply lacks the
* field.
*/
function parseSummaryObject(candidate: string): {
parsed: boolean;
summary: string | null;
} {
try {
const obj = JSON.parse(candidate) as unknown;
if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
const value = (obj as { summary?: unknown }).summary;
if (typeof value === "string" && value.trim().length > 0) {
return { parsed: true, summary: value };
}
// Well-formed object, but no usable summary (e.g. `{}` or `{summary:""}`).
return { parsed: true, summary: null };
}
// Valid JSON, but not a summary object (array / number / bare string).
return { parsed: false, summary: null };
} catch {
return { parsed: false, summary: null };
}
}
/**
* Did the completion OPEN like a JSON object? A genuine prose sentence never
* starts with `{` (a stray brace mid-sentence does not count), so a `{`-led
* payload that failed both parse attempts above is a malformed / truncated
* envelope — never surfaced raw. Strips a leading code fence first so a
* fenced-but-truncated object is caught too.
*/
function looksLikeJsonObjectAttempt(content: string): boolean {
const afterFence = content.replace(/^```(?:json)?\s*/i, "").trimStart();
return afterFence.startsWith("{");
}
/**
* Read a model completion for its user-facing summary and classify the result.
*
* Tries the content as-is first (the common, fence-free case), then a
* fence-stripped retry for providers without a native JSON mode. A completion
* that attempted the `{ summary }` envelope but came back malformed / truncated
* / summary-less resolves to `unparseable` rather than falling through as raw
* text — the caller then serves its deterministic fallback. Only a completion
* that never attempted the envelope (genuine prose) passes through verbatim.
*/
export function extractAssessmentSummary(content: string): SummaryExtraction {
const trimmed = content.trim();
// Attempt 1 — the content is itself a JSON object.
const direct = parseSummaryObject(trimmed);
if (direct.parsed) {
return direct.summary
? { kind: "summary", text: direct.summary }
: { kind: "unparseable" };
}
// Attempt 2 — strip a code fence / surrounding prose and retry.
const stripped = stripJsonFences(trimmed);
if (stripped !== trimmed) {
const viaFence = parseSummaryObject(stripped);
if (viaFence.parsed) {
return viaFence.summary
? { kind: "summary", text: viaFence.summary }
: { kind: "unparseable" };
}
}
// Neither parse produced a summary object. If the payload OPENED like an
// object, the model attempted the envelope and it came back malformed or
// truncated — resolve to the controlled fallback, never the raw braces /
// property name / quotes / literal `\n`. Genuine prose falls through.
if (looksLikeJsonObjectAttempt(trimmed)) {
return { kind: "unparseable" };
}
return { kind: "prose", text: content };
}
/**
* Pull the `summary` string out of a model completion. The status prompts
* return a `{ "summary": "…" }` envelope; a model that ignores the contract and
* returns bare prose falls back to the raw content. A malformed / truncated /
* summary-less structured envelope resolves to an EMPTY string (never the raw
* JSON) so no caller can surface partial structured output.
*
* Prefer `extractAssessmentSummary` in new code: it distinguishes an
* unparseable envelope from genuinely empty prose, which this thin wrapper
* collapses to `""`.
*/
export function parseSummaryFromContent(content: string): string {
const extracted = extractAssessmentSummary(content);
return extracted.kind === "unparseable" ? "" : extracted.text;
}
/**
* Store one status note (`InsightStatusCache`, encrypted) for today and return
* when it was written. The medication-compliance generator also stores its
* per-medication lines and goes through `writeStatusNote` directly.
*/
export async function persistStatusInsight(args: {
userId: string;
cacheAction: string;
todayKey: string;
text: string;
/**
* Fingerprint of the data snapshot this note was written from (see
* `snapshot-hash.ts`). The regeneration gate compares the next snapshot's
* hash against it and skips the provider call when nothing changed.
*/
snapshotHash?: string;
/**
* Cheap fingerprint of the SALIENT INPUTS (per-type count + newest
* measuredAt) for slow-moving metrics. The input gate compares a freshly
* probed fingerprint against it BEFORE the heavy snapshot build.
*/
inputHash?: string;
}): Promise<string> {
const generatedAt = await writeStatusNote({
userId: args.userId,
cacheAction: args.cacheAction,
todayKey: args.todayKey,
text: args.text,
snapshotHash: args.snapshotHash,
inputHash: args.inputHash,
});
return generatedAt.toISOString();
}
/**
* Outcome of turning one status-card completion into a shippable assessment.
* `blocked` carries the tripped contract so the caller can annotate before it
* withholds.
*/
export type StatusSummaryOutcome =
| { ok: true; kind: "generated"; text: string }
| {
ok: false;
kind: "screened-fallback";
reason: OutboundReason | "unparseable_output";
};
/**
* The single finalize step every per-metric / biomarker / derived-score status
* generator runs on its completion: parse the `{ summary }` envelope, scrub
* chart tokens and whitespace, then SCREEN the prose against the insights
* safety contracts.
*
* Why the screen belongs here. Before this existed, the only transform between
* a provider and a persisted status assessment was `normalizeSummaryText`,
* which is whitespace-only — so a dose-change imperative or a fabricated
* clinical risk score written onto a metric card persisted as that day's cached
* assessment while the identical sentence in the Coach was caught and replaced.
* Every generator shares this chokepoint, so a card cannot be added that
* silently skips the screen.
*
* SURFACE POLICY — WITHHOLD. Unlike the Coach, a status card is generated in
* the background and read from cache; nobody is waiting on the turn. Persisting
* a refusal is wrong (it would pin "I can't advise on doses" to the user's
* Weight card for the day, which is noise on a surface they did not ask a
* question on) and persisting the screened prose is obviously wrong. So the
* caller serves its existing deterministic stub — the same signal-grounded line
* the card shows when no provider is configured — and persists no model text.
* The card degrades to a state the UI already renders honestly, and the short
* negative-cache window lets the next run try again.
*
* The contracts include `causal` here: GROUND RULE 12 declares surface
* `insights`, and these cards are that surface.
*/
export function finalizeStatusSummary(
content: string,
locale: SupportedLocale,
): StatusSummaryOutcome {
const extracted = extractAssessmentSummary(content);
// A malformed / truncated / summary-less structured envelope has no safe
// text to render. WITHHOLD — the caller serves its deterministic stub. Only
// the `unparseable` discriminator is logged, never the assessment content.
if (extracted.kind === "unparseable") {
return {
ok: false,
kind: "screened-fallback",
reason: "unparseable_output",
};
}
const text = normalizeSummaryText(extracted.text);
if (!text) return { ok: true, kind: "generated", text: "" };
const decision = screenModelOutput(text, locale, INSIGHTS_CONTRACTS);
if (decision.block && decision.reason) {
return {
ok: false,
kind: "screened-fallback",
reason: decision.reason,
};
}
return { ok: true, kind: "generated", text };
}