feat(mental-health): record which wording a check-in was answered in

An administration now stores `wording`: `validated` (the published
validated version of the reader's language, the original for English),
`unvalidated_translation` (HealthLog's own translation) or `original_en`
(the English original, chosen by a reader of another language). The
client sends only `englishOriginal`; the server resolves the rest from
the wording registry, so a client cannot claim a validated wording the
registry does not hold. `locale` keeps the reader's language, which
still selects the crisis resources.

Additive migration 0475: a nullable column with no backfill, since which
text earlier rows showed depended on releases since replaced. Every read
returns the field, the OpenAPI contract carries it and `englishOriginal`,
and the disaster-recovery backup carries and restores it (the parity
goldens gain the column; their pinned timestamps move by one step
because the fill writes one more column).

The PHQ-9 item-9 crisis signpost is answered from the answers alone and
is proven in every wording through the real route.
This commit is contained in:
Marc-André Bombeck committed 2026-10-23 08:14:15 +02:00
1 parent 3843705296
commit 02cc0631fa
14 files changed
+347 -66

No files matched your search

@@ -1905,6 +1905,7 @@
"id": "<id:89>",
"instrument": "GAD7",
"locale": "en",
"wording": null,
"version": "standard",
"responsesEncrypted": "<sealed:v1:{\"items\":[1,1,0,1,0,1,0],\"schema\":1}>",
"totalScore": 4,
@@ -1917,13 +1918,14 @@
"externalId": null,
"syncVersion": 0,
"deletedAt": "<tombstone>",
"createdAt": "2026-05-05T13:56:01.000Z",
"updatedAt": "2026-05-05T13:57:01.000Z"
"createdAt": "2026-05-05T13:57:01.000Z",
"updatedAt": "2026-05-05T13:58:01.000Z"
},
{
"id": "<id:90>",
"instrument": "PHQ9",
"locale": "de",
"wording": "unvalidated_translation",
"version": "rt-MentalHealthAssessment-version",
"responsesEncrypted": "<sealed:v1:{\"items\":[2,1,2,2,1,1,2,1,2],\"schema\":1}>",
"totalScore": 14,
@@ -1936,8 +1938,8 @@
"externalId": "rt-MentalHealthAssessment-externalId",
"syncVersion": 3,
"deletedAt": null,
"createdAt": "2026-05-05T13:56:00.000Z",
"updatedAt": "2026-05-05T13:57:00.000Z"
"createdAt": "2026-05-05T13:57:00.000Z",
"updatedAt": "2026-05-05T13:58:00.000Z"
}
],
"consentReceipts": [
@@ -4318,6 +4320,7 @@
"id": "<id:89>",
"instrument": "GAD7",
"locale": "en",
"wording": null,
"version": "standard",
"responsesEncrypted": "<sealed:v1:{\"items\":[1,1,0,1,0,1,0],\"schema\":1}>",
"totalScore": 4,
@@ -4330,13 +4333,14 @@
"externalId": null,
"syncVersion": 0,
"deletedAt": "<tombstone>",
"createdAt": "2026-05-05T13:56:01.000Z",
"updatedAt": "2026-05-05T13:57:01.000Z"
"createdAt": "2026-05-05T13:57:01.000Z",
"updatedAt": "2026-05-05T13:58:01.000Z"
},
{
"id": "<id:90>",
"instrument": "PHQ9",
"locale": "de",
"wording": "unvalidated_translation",
"version": "rt-MentalHealthAssessment-version",
"responsesEncrypted": "<sealed:v1:{\"items\":[2,1,2,2,1,1,2,1,2],\"schema\":1}>",
"totalScore": 14,
@@ -4349,8 +4353,8 @@
"externalId": "rt-MentalHealthAssessment-externalId",
"syncVersion": 3,
"deletedAt": null,
"createdAt": "2026-05-05T13:56:00.000Z",
"updatedAt": "2026-05-05T13:57:00.000Z"
"createdAt": "2026-05-05T13:57:00.000Z",
"updatedAt": "2026-05-05T13:58:00.000Z"
}
],
"consentReceipts": [
@@ -2153,6 +2153,7 @@
"userId": "round-trip-owner",
"instrument": "GAD7",
"locale": "en",
"wording": null,
"version": "standard",
"responsesEncrypted": "<sealed:v1:{\"items\":[1,1,0,1,0,1,0],\"schema\":1}>",
"totalScore": 4,
@@ -2165,14 +2166,15 @@
"externalId": null,
"syncVersion": 0,
"deletedAt": "<tombstone>",
"createdAt": "2026-05-05T13:56:01.000Z",
"updatedAt": "2026-05-05T13:57:01.000Z"
"createdAt": "2026-05-05T13:57:01.000Z",
"updatedAt": "2026-05-05T13:58:01.000Z"
},
{
"id": "<id:99>",
"userId": "round-trip-owner",
"instrument": "PHQ9",
"locale": "de",
"wording": "unvalidated_translation",
"version": "rt-MentalHealthAssessment-version",
"responsesEncrypted": "<sealed:v1:{\"items\":[2,1,2,2,1,1,2,1,2],\"schema\":1}>",
"totalScore": 14,
@@ -2185,8 +2187,8 @@
"externalId": "rt-MentalHealthAssessment-externalId",
"syncVersion": 3,
"deletedAt": null,
"createdAt": "2026-05-05T13:56:00.000Z",
"updatedAt": "2026-05-05T13:57:00.000Z"
"createdAt": "2026-05-05T13:57:00.000Z",
"updatedAt": "2026-05-05T13:58:00.000Z"
}
],
"ConsentReceipt": [
@@ -4800,6 +4802,7 @@
"id": "<id:89>",
"instrument": "GAD7",
"locale": "en",
"wording": null,
"version": "standard",
"responsesEncrypted": "<sealed:v1:{\"items\":[1,1,0,1,0,1,0],\"schema\":1}>",
"totalScore": 4,
@@ -4812,13 +4815,14 @@
"externalId": null,
"syncVersion": 0,
"deletedAt": "<tombstone>",
"createdAt": "2026-05-05T13:56:01.000Z",
"updatedAt": "2026-05-05T13:57:01.000Z"
"createdAt": "2026-05-05T13:57:01.000Z",
"updatedAt": "2026-05-05T13:58:01.000Z"
},
{
"id": "<id:90>",
"instrument": "PHQ9",
"locale": "de",
"wording": "unvalidated_translation",
"version": "rt-MentalHealthAssessment-version",
"responsesEncrypted": "<sealed:v1:{\"items\":[2,1,2,2,1,1,2,1,2],\"schema\":1}>",
"totalScore": 14,
@@ -4831,8 +4835,8 @@
"externalId": "rt-MentalHealthAssessment-externalId",
"syncVersion": 3,
"deletedAt": null,
"createdAt": "2026-05-05T13:56:00.000Z",
"updatedAt": "2026-05-05T13:57:00.000Z"
"createdAt": "2026-05-05T13:57:00.000Z",
"updatedAt": "2026-05-05T13:58:00.000Z"
}
],
"consentReceipts": [
@@ -1780,6 +1780,7 @@
"userId": "round-trip-owner",
"instrument": "GAD7",
"locale": "en",
"wording": null,
"version": "standard",
"responsesEncrypted": "<sealed:v1:{\"items\":[1,1,0,1,0,1,0],\"schema\":1}>",
"totalScore": 4,
@@ -1792,14 +1793,15 @@
"externalId": null,
"syncVersion": 0,
"deletedAt": "<tombstone>",
"createdAt": "2026-05-05T13:56:01.000Z",
"updatedAt": "2026-05-05T13:57:01.000Z"
"createdAt": "2026-05-05T13:57:01.000Z",
"updatedAt": "2026-05-05T13:58:01.000Z"
},
{
"id": "<id:100>",
"userId": "round-trip-owner",
"instrument": "PHQ9",
"locale": "de",
"wording": "unvalidated_translation",
"version": "rt-MentalHealthAssessment-version",
"responsesEncrypted": "<sealed:v1:{\"items\":[2,1,2,2,1,1,2,1,2],\"schema\":1}>",
"totalScore": 14,
@@ -1812,8 +1814,8 @@
"externalId": "rt-MentalHealthAssessment-externalId",
"syncVersion": 3,
"deletedAt": null,
"createdAt": "2026-05-05T13:56:00.000Z",
"updatedAt": "2026-05-05T13:57:00.000Z"
"createdAt": "2026-05-05T13:57:00.000Z",
"updatedAt": "2026-05-05T13:58:00.000Z"
}
],
"ConsentReceipt": [
+2
View File
@@ -1401,6 +1401,8 @@ export const FILL_OVERRIDES: Readonly<Record<string, unknown>> = {
"Biomarker.contextEncrypted": () =>
encryptContextToBytes("fasted, morning draw"),
"MoodEntry.tags": JSON.stringify(["round-trip-tag"]),
// A closed set (ASSESSMENT_WORDINGS); the export carries nothing else.
"MentalHealthAssessment.wording": "unvalidated_translation",
"CorrelationPattern.qValue": 0.04,
"CorrelationPattern.dismissedEvidenceHash": "ab".repeat(32),
// CHECK in migration 0408: the profile is built from samples or from hour buckets.
@@ -0,0 +1,183 @@
/**
* Which text a check-in was answered in, end to end through the real routes
* and the real schema, checked against the published contract by the kit.
*
* The client says only two things: the reader's language and whether they
* switched to the English original. The server resolves the rest from the
* wording registry and stores it on the row, and every read returns it:
* - a language with a validated translation records `validated`;
* - a language with HealthLog's own translation records
* `unvalidated_translation`;
* - the switch records `original_en`;
* - English records `validated` whatever the switch says.
* The PHQ-9 crisis signpost answers item 9 the same way in every wording.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
import {
GET as listAssessments,
POST as createAssessment,
} from "@/app/api/mental-health/assessments/route";
import { GET as readAssessment } from "@/app/api/mental-health/assessments/[id]/route";
import { callRoute } from "../kit/call-route";
import { makeSession, makeUser, type SessionFixture } from "../kit/factories";
import { getPrismaClient, truncateAllTables } from "./setup";
vi.mock("@/lib/db-compat", () => ({
ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
}));
// The reminder satisfy and the rollup tail hand work to pg-boss; the queue is
// not what this file is about.
vi.mock("@/lib/jobs/boss-instance", () => ({
getGlobalBoss: () => ({ send: vi.fn().mockResolvedValue("wording-job") }),
}));
interface Row {
id: string;
instrument: string;
locale: string;
wording: string | null;
item9Flagged: boolean;
}
interface Created {
assessment: Row;
crisis: { emergencyNumber: string } | null;
}
const PHQ9_ITEM9 = [0, 0, 0, 0, 0, 0, 0, 0, 1];
const SCI = [2, 2, 2, 2, 2, 2, 2, 2];
let session: SessionFixture;
beforeEach(async () => {
await truncateAllTables(getPrismaClient());
const user = await makeUser({
locale: "nl",
modulePreferencesJson: { mentalHealth: true },
});
session = await makeSession(user);
});
async function submit(body: Record<string, unknown>) {
const result = await callRoute<Created>(createAssessment, {
method: "POST",
route: "/api/mental-health/assessments",
body,
auth: session,
});
expect(result.status, JSON.stringify(result.body)).toBe(201);
return result.data;
}
describe("the wording a check-in records", () => {
it("records a validated translation, HealthLog's own translation and the English original apart", async () => {
const validated = await submit({
instrument: "PHQ9",
items: PHQ9_ITEM9,
locale: "nl",
});
const translation = await submit({
instrument: "SCI",
items: SCI,
locale: "nl",
});
const original = await submit({
instrument: "SCI",
items: SCI,
locale: "nl",
englishOriginal: true,
});
const english = await submit({
instrument: "SCI",
items: SCI,
locale: "en",
englishOriginal: true,
});
expect(validated.assessment.wording).toBe("validated");
expect(translation.assessment.wording).toBe("unvalidated_translation");
expect(original.assessment.wording).toBe("original_en");
expect(english.assessment.wording).toBe("validated");
const stored = await getPrismaClient().mentalHealthAssessment.findMany({
select: { id: true, locale: true, wording: true },
});
const byId = new Map(stored.map((row) => [row.id, row]));
expect(byId.get(translation.assessment.id)).toMatchObject({
locale: "nl",
wording: "unvalidated_translation",
});
expect(byId.get(original.assessment.id)).toMatchObject({
locale: "nl",
wording: "original_en",
});
const list = await callRoute<{ assessments: Row[] }>(listAssessments, {
method: "GET",
route: "/api/mental-health/assessments",
auth: session,
});
expect(list.status).toBe(200);
expect(
Object.fromEntries(list.data.assessments.map((r) => [r.id, r.wording])),
).toEqual({
[validated.assessment.id]: "validated",
[translation.assessment.id]: "unvalidated_translation",
[original.assessment.id]: "original_en",
[english.assessment.id]: "validated",
});
const detail = await callRoute<{ assessment: Row }>(readAssessment, {
method: "GET",
route: "/api/mental-health/assessments/{id}",
params: { id: translation.assessment.id },
auth: session,
});
expect(detail.status).toBe(200);
expect(detail.data.assessment.wording).toBe("unvalidated_translation");
});
it("defaults to the account's language when the client sends none", async () => {
const created = await submit({ instrument: "SCI", items: SCI });
expect(created.assessment.locale).toBe("nl");
expect(created.assessment.wording).toBe("unvalidated_translation");
});
it("answers PHQ-9 item 9 with the crisis signpost in every wording", async () => {
for (const body of [
{ locale: "nl" },
{ locale: "ko" },
{ locale: "pt-BR" },
{ locale: "de" },
{ locale: "nl", englishOriginal: true },
{ locale: "en" },
]) {
const created = await submit({
instrument: "PHQ9",
items: PHQ9_ITEM9,
...body,
});
expect(created.assessment.item9Flagged, JSON.stringify(body)).toBe(true);
expect(created.crisis, JSON.stringify(body)).not.toBeNull();
}
const quiet = await submit({
instrument: "PHQ9",
items: [3, 3, 3, 3, 3, 3, 3, 3, 0],
locale: "pt-BR",
});
expect(quiet.crisis).toBeNull();
});
it("refuses a switch that is not a boolean", async () => {
const result = await callRoute(createAssessment, {
method: "POST",
route: "/api/mental-health/assessments",
body: { instrument: "SCI", items: SCI, englishOriginal: "yes" },
auth: session,
});
expect(result.status).toBe(422);
expect(await getPrismaClient().mentalHealthAssessment.count()).toBe(0);
});
});