Merge tickets part 2 into release/v1.42.0

# Conflicts:
#	src/__tests__/i18n-reverse-coverage.test.ts
This commit is contained in:
Marc-André Bombeck committed 2026-10-08 13:07:02 +02:00
commit 9d4a50282e
80 files changed
+3975 -818

No files matched your search

+14 -1
View File
@@ -12,6 +12,11 @@
*/
import { prisma } from "@/lib/db";
import { deriveSeries } from "@/lib/vaccinations/series";
import {
CUSTOM_VACCINE_RESOLVE_SELECT,
customLookupOf,
resolveVaccineEntry,
} from "@/lib/vaccinations/resolve-vaccine-entry";
import { resolveEffectiveReferenceRange } from "@/lib/labs/reference-range";
import { getEvent } from "@/lib/logging/context";
import { decryptAllergyReaction } from "@/lib/doctor-report-helpers";
@@ -298,24 +303,32 @@ export async function loadImmunizations(
doseNumber: true,
site: true,
practitioner: { select: { name: true } },
// v1.42 (#1005) — the person's own definition: its antigens place the
// dose in a series, and its name stands in when the dose has none.
customVaccineId: true,
customVaccine: { select: CUSTOM_VACCINE_RESOLVE_SELECT },
},
});
if (rows.length === 0) return null;
const customs = customLookupOf(rows.map((row) => row.customVaccine));
const series = deriveSeries(
rows.map((row) => ({
id: row.id,
occurredAt: row.occurredAt,
antigenSlug: row.antigenSlug,
customVaccineId: row.customVaccineId,
doseNumber: row.doseNumber,
seriesDoses: row.seriesDoses,
})),
customs,
);
return rows.map((row) => ({
occurredAt: row.occurredAt.toISOString(),
antigenSlug: row.antigenSlug,
vaccineName: row.vaccineName,
vaccineName:
row.vaccineName ?? resolveVaccineEntry(row, customs)?.name ?? null,
lotNumber: row.lotNumber,
site: row.site,
practitionerName: row.practitioner?.name ?? null,
+18 -5
View File
@@ -16,7 +16,11 @@ import type {
DocumentLinkedProcedureDto,
DocumentVaccinationLinkDto,
} from "@/lib/validations/inbound-documents";
import { resolveCatalogEntry } from "@/lib/vaccinations/vaccine-catalog";
import {
CUSTOM_VACCINE_RESOLVE_SELECT,
customLookupOf,
resolveVaccineEntry,
} from "@/lib/vaccinations/resolve-vaccine-entry";
/**
* Load the condition links for a page of documents in ONE grouped query.
@@ -237,20 +241,29 @@ export async function loadDocumentVaccinationLinks(
if (doseIds.length === 0) return map;
const doses = await prisma.vaccinationRecord.findMany({
where: { id: { in: doseIds }, userId },
select: { id: true, antigenSlug: true, vaccineName: true },
select: {
id: true,
antigenSlug: true,
vaccineName: true,
customVaccineId: true,
customVaccine: { select: CUSTOM_VACCINE_RESOLVE_SELECT },
},
});
const doseById = new Map(doses.map((dose) => [dose.id, dose]));
const customs = customLookupOf(doses.map((dose) => dose.customVaccine));
for (const [documentId, targets] of byDocument) {
map.set(
documentId,
targets.map((target) => {
const dose = doseById.get(target.id);
const entry = dose ? resolveVaccineEntry(dose, customs) : null;
return {
vaccinationId: target.id,
occurredAt: target.date,
catalogSlug:
resolveCatalogEntry(dose?.antigenSlug ?? null)?.slug ?? null,
vaccineName: dose?.vaccineName ?? null,
catalogSlug: entry?.slug ?? null,
// A dose logged against the person's own definition and carrying no
// wording of its own is named by that definition.
vaccineName: dose?.vaccineName ?? entry?.name ?? null,
};
}),
);
@@ -413,6 +413,7 @@ function makePrisma() {
encounterLabLink: { findMany: vi.fn().mockResolvedValue([]) },
encounterConditionLink: { findMany: vi.fn().mockResolvedValue([]) },
vaccinationRecord: { findMany: vi.fn().mockResolvedValue([]) },
customVaccine: { findMany: vi.fn().mockResolvedValue([]) },
vaccinationDocumentLink: { findMany: vi.fn().mockResolvedValue([]) },
// The reminder engine tables (v1.37.20, #223 / iOS #68). Empty for the
// same reason as the visit tables above.
@@ -290,6 +290,7 @@ function sourceClient() {
encounterLabLink: { findMany: vi.fn().mockResolvedValue([]) },
encounterConditionLink: { findMany: vi.fn().mockResolvedValue([]) },
vaccinationRecord: { findMany: vi.fn().mockResolvedValue([]) },
customVaccine: { findMany: vi.fn().mockResolvedValue([]) },
vaccinationDocumentLink: { findMany: vi.fn().mockResolvedValue([]) },
// The reminder engine tables (v1.37.20, #223 / iOS #68). Empty for the
// same reason as the visit tables above.
+1 -2
View File
@@ -378,6 +378,7 @@ export const TWO_ENDED_MODELS = [
// from anywhere else.
"VaccinationRecord",
"VaccinationDocumentLink",
"CustomVaccine",
// The Vorsorge reminders, off the debt register at last (v1.37.20, #223 /
// iOS #68), and the completion ledger carried with them from the release
// that introduces it. The pairing is deliberate: the ledger arriving is
@@ -589,8 +590,6 @@ export const STRUCTURALLY_UNATTRIBUTABLE: Readonly<Record<string, string>> = {
* rather than by what is cheapest to write.
*/
export const COVERAGE_PENDING: Readonly<Record<string, string>> = {
CustomVaccine:
"The person's own vaccine definitions (v1.42, #1005). Until both ends land, a restored dose that pointed at one comes back as its bare `vaccineName`: no antigens, no series position, no booster rule.",
WorkoutRoute:
"GPS traces. Deliberately absent from the payload today and DISCLOSED as absent in the file's own manifest, which is why this is a documented exclusion rather than a silent one — but it is still a loss for a self-hoster with no other copy.",
WorkoutSamples:
+1
View File
@@ -180,6 +180,7 @@ const SUMMARY_COUNTS = [
"encounterLinks",
"vaccinations",
"vaccinationLinks",
"customVaccines",
"measurementReminders",
"measurementReminderEvents",
"coachConversations",
+3
View File
@@ -179,6 +179,7 @@ export interface RestoreResponse {
encounterLinks: number;
vaccinations: number;
vaccinationLinks: number;
customVaccines: number;
measurementReminders: number;
measurementReminderEvents: number;
coachConversations: number;
@@ -2646,6 +2647,7 @@ export async function restoreBackup(
encounterLinks: visitsCleared.encounterLinks,
vaccinations: vaccinationsCleared.vaccinations,
vaccinationLinks: vaccinationsCleared.vaccinationLinks,
customVaccines: vaccinationsCleared.customVaccines,
measurementReminders: remindersCleared.measurementReminders,
measurementReminderEvents: remindersCleared.measurementReminderEvents,
coachConversations: coachCleared.coachConversations,
@@ -2905,6 +2907,7 @@ export async function restoreBackup(
encounterLinks: summary.encounterLinks,
vaccinations: summary.vaccinations,
vaccinationLinks: summary.vaccinationLinks,
customVaccines: summary.customVaccines,
measurementReminders: summary.measurementReminders,
measurementReminderEvents: summary.measurementReminderEvents,
},
+131 -15
View File
@@ -6,8 +6,9 @@
* greps only the restore ROUTE gets a false negative because the route
* delegates.
*
* Two models ride: the dose and the link that keeps the scanned Impfpass page
* beside it. Both are carried rather than owed. `DocumentConditionLink` on the
* Three models ride: the dose, the link that keeps the scanned Impfpass page
* beside it, and since v1.42 (#1005) the person's own vaccine definitions a
* dose may name. Both are carried rather than owed. `DocumentConditionLink` on the
* debt register says what the alternative costs — documents and conditions
* both restore, the filing between them does not — and an immunization history
* is the record with the least chance of being reconstructed from anywhere
@@ -29,6 +30,9 @@
* the same way, and resolves to NULL, with the drop reported, only when
* the file genuinely lacks the reminder — a portable export omits
* tombstoned ones.
* - `customVaccineId` points at a definition restored by this same section
* first. It drops to NULL, with the drop named, when the file lacks the
* definition; the dose then keeps its own `vaccineName`.
* - `antigenSlug` is restored verbatim with no validation against the
* current catalogue. A slug this release no longer resolves must still
* come back; the renderer degrades to the free-text arm, which is the
@@ -76,6 +80,8 @@ export interface VaccinationBackupEntry {
* lacks the reminder.
*/
reminderId: string | null;
/** The person's own definition the dose names (v1.42, #1005). */
customVaccineId: string | null;
/** Base64 ciphertext; disaster-recovery payloads only. */
noteEncrypted?: string | null;
/** The note readable; portable payloads only. */
@@ -85,6 +91,22 @@ export interface VaccinationBackupEntry {
deletedAt?: string | null;
}
/**
* One of the person's own vaccine definitions (v1.42, #1005). `components`
* travels verbatim, never checked against the antigen list this release
* ships, for the same reason a dose's `antigenSlug` does.
*/
export interface CustomVaccineBackupEntry {
id: string;
name: string;
components: string[];
typicalSeriesDoses: number | null;
boosterIntervalMonths: number | null;
createdAt: string;
updatedAt: string;
deletedAt?: string | null;
}
/** One edge from a dose to the page it was transcribed from. */
export interface VaccinationDocumentLinkBackupEntry {
vaccinationId: string;
@@ -93,11 +115,13 @@ export interface VaccinationDocumentLinkBackupEntry {
}
export interface VaccinationsBackupSection {
customVaccines: CustomVaccineBackupEntry[];
vaccinations: VaccinationBackupEntry[];
vaccinationDocumentLinks: VaccinationDocumentLinkBackupEntry[];
}
export interface VaccinationsBackupCounts {
customVaccines: number;
vaccinations: number;
vaccinationLinks: number;
}
@@ -119,12 +143,24 @@ const VACCINATION_BACKUP_SELECT = {
practitionerId: true,
encounterId: true,
reminderId: true,
customVaccineId: true,
noteEncrypted: true,
createdAt: true,
updatedAt: true,
deletedAt: true,
} as const;
const CUSTOM_VACCINE_BACKUP_SELECT = {
id: true,
name: true,
components: true,
typicalSeriesDoses: true,
boosterIntervalMonths: true,
createdAt: true,
updatedAt: true,
deletedAt: true,
} as const;
const VACCINATION_DOCUMENT_LINK_BACKUP_SELECT = {
vaccinationId: true,
documentId: true,
@@ -140,26 +176,47 @@ const VACCINATION_DOCUMENT_LINK_BACKUP_SELECT = {
* back as itself.
*/
export async function buildVaccinationsBackupSection(
prisma: Pick<PrismaClient, "vaccinationRecord" | "vaccinationDocumentLink">,
prisma: Pick<
PrismaClient,
"vaccinationRecord" | "vaccinationDocumentLink" | "customVaccine"
>,
userId: string,
options: VaccinationsBackupOptions = {},
): Promise<VaccinationsBackupSection> {
const disasterRecovery = options.purpose === "disaster-recovery";
const [vaccinationRows, documentLinkRows] = await Promise.all([
prisma.vaccinationRecord.findMany({
where: disasterRecovery ? { userId } : { userId, deletedAt: null },
orderBy: { occurredAt: "desc" },
select: VACCINATION_BACKUP_SELECT,
}),
prisma.vaccinationDocumentLink.findMany({
where: { userId },
orderBy: { createdAt: "asc" },
select: VACCINATION_DOCUMENT_LINK_BACKUP_SELECT,
}),
]);
const [customVaccineRows, vaccinationRows, documentLinkRows] =
await Promise.all([
prisma.customVaccine.findMany({
where: disasterRecovery ? { userId } : { userId, deletedAt: null },
orderBy: [{ name: "asc" }, { id: "asc" }],
select: CUSTOM_VACCINE_BACKUP_SELECT,
}),
prisma.vaccinationRecord.findMany({
where: disasterRecovery ? { userId } : { userId, deletedAt: null },
orderBy: { occurredAt: "desc" },
select: VACCINATION_BACKUP_SELECT,
}),
prisma.vaccinationDocumentLink.findMany({
where: { userId },
orderBy: { createdAt: "asc" },
select: VACCINATION_DOCUMENT_LINK_BACKUP_SELECT,
}),
]);
return {
customVaccines: customVaccineRows.map((row) => ({
id: row.id,
name: row.name,
components: [...row.components],
typicalSeriesDoses: row.typicalSeriesDoses,
boosterIntervalMonths: row.boosterIntervalMonths,
createdAt: row.createdAt.toISOString(),
updatedAt: row.updatedAt.toISOString(),
...(disasterRecovery
? { deletedAt: row.deletedAt?.toISOString() ?? null }
: {}),
})),
vaccinations: vaccinationRows.map((row) => ({
id: row.id,
occurredAt: row.occurredAt.toISOString(),
@@ -172,6 +229,7 @@ export async function buildVaccinationsBackupSection(
practitionerId: row.practitionerId,
encounterId: row.encounterId,
reminderId: row.reminderId,
customVaccineId: row.customVaccineId,
...(disasterRecovery
? { noteEncrypted: encodeSealedBytes(row.noteEncrypted) }
: {
@@ -199,6 +257,7 @@ export function countVaccinationsBackupSection(
section: VaccinationsBackupSection,
): VaccinationsBackupCounts {
return {
customVaccines: section.customVaccines.length,
vaccinations: section.vaccinations.length,
vaccinationLinks: section.vaccinationDocumentLinks.length,
};
@@ -206,6 +265,7 @@ export function countVaccinationsBackupSection(
/** Counts the immunization restore wiped, for the audit trail. */
export interface VaccinationsRestoreCleared {
customVaccines: number;
vaccinations: number;
vaccinationLinks: number;
}
@@ -219,10 +279,22 @@ export interface VaccinationsRestoreCleared {
* times and reports success.
*/
export interface VaccinationsRestoreInput {
customVaccines: RestoredCustomVaccine[];
vaccinations: RestoredVaccination[];
vaccinationDocumentLinks: VaccinationDocumentLinkBackupEntry[];
}
/** A definition as the parsed file presents it. */
export type RestoredCustomVaccine = Pick<
CustomVaccineBackupEntry,
"id" | "name" | "createdAt" | "updatedAt"
> & {
components?: string[] | undefined;
typicalSeriesDoses?: number | null | undefined;
boosterIntervalMonths?: number | null | undefined;
deletedAt?: string | null | undefined;
};
/**
* What the restore reads, as the parsed file actually presents it — a wider
* set than what this release writes: a portable export omits the tombstone,
@@ -246,6 +318,7 @@ export type RestoredVaccination = Pick<
| "practitionerId"
| "encounterId"
| "reminderId"
| "customVaccineId"
| "noteEncrypted"
| "note"
>
@@ -276,6 +349,32 @@ export async function restoreVaccinationsData(
const clearedVaccinations = await tx.vaccinationRecord.deleteMany({
where: { userId: ownerId },
});
// After the doses that point at them, so neither count reads short.
const clearedCustomVaccines = await tx.customVaccine.deleteMany({
where: { userId: ownerId },
});
// The definitions first: a dose addresses one by id.
if (payload.customVaccines.length > 0) {
await tx.customVaccine.createMany({
data: payload.customVaccines.map((entry) => ({
id: entry.id,
userId: ownerId,
name: entry.name,
// Verbatim, like a dose's slug: an antigen this release does not know
// still says what the person meant, and the resolver skips it.
components: entry.components ?? [],
typicalSeriesDoses: entry.typicalSeriesDoses ?? null,
boosterIntervalMonths: entry.boosterIntervalMonths ?? null,
createdAt: new Date(entry.createdAt),
updatedAt: new Date(entry.updatedAt),
deletedAt: entry.deletedAt ? new Date(entry.deletedAt) : null,
})),
});
}
const restoredCustomVaccines = new Set(
payload.customVaccines.map((entry) => entry.id),
);
// All three far sides are restored by other branches of the same
// transaction, so the check is against the database rather than against the
@@ -308,6 +407,7 @@ export async function restoreVaccinationsData(
const droppedPractitioners: string[] = [];
const droppedEncounters: string[] = [];
const droppedReminders: string[] = [];
const droppedCustomVaccines: string[] = [];
// Sealed notes this host's keys do not open, by file path.
const unopened: string[] = [];
@@ -336,6 +436,14 @@ export async function restoreVaccinationsData(
if (entry.reminderId && reminderId === null) {
droppedReminders.push(entry.reminderId);
}
const customVaccineId =
entry.customVaccineId &&
restoredCustomVaccines.has(entry.customVaccineId)
? entry.customVaccineId
: null;
if (entry.customVaccineId && customVaccineId === null) {
droppedCustomVaccines.push(entry.customVaccineId);
}
return {
id: entry.id,
userId: ownerId,
@@ -352,6 +460,7 @@ export async function restoreVaccinationsData(
practitionerId,
encounterId,
reminderId,
customVaccineId,
noteEncrypted: sealBytesForRestore(
entry.noteEncrypted,
entry.note,
@@ -384,6 +493,12 @@ export async function restoreVaccinationsData(
[...new Set(droppedReminders)],
droppedReminders,
);
recordUnknownKeys(
skips,
"vaccinationReference",
[...new Set(droppedCustomVaccines)],
droppedCustomVaccines,
);
recordUnknownKeys(skips, "vaccinationCiphertext", unopened, unopened);
const restoredVaccinations = new Set(
@@ -433,6 +548,7 @@ export async function restoreVaccinationsData(
);
return {
customVaccines: clearedCustomVaccines.count,
vaccinations: clearedVaccinations.count,
vaccinationLinks: clearedLinks.count,
};
-21
View File
@@ -1,21 +0,0 @@
/**
* The answer a route gives while its contract exists and its body does not.
*
* A release built in parallel packages lands every new route as a stub first,
* registered in the OpenAPI table with its final shape, so the route-coverage
* and contract checks hold in every package's worktree from the start. The
* stub authenticates exactly as the finished route will and then answers 501.
*
* Nothing may ship with a stub in it: the error-code catalogue check fails on
* a listed code no route emits, so the code leaves the catalogue, and this
* file with it, once the last stub is implemented.
*/
import { apiError } from "@/lib/api-response";
export const NOT_IMPLEMENTED_ERROR_CODE = "not_implemented";
export function notImplemented() {
return apiError("Not implemented", 501, {
errorCode: NOT_IMPLEMENTED_ERROR_CODE,
});
}
+44 -2
View File
@@ -19,8 +19,9 @@
* would count a step the phone and the watch both saw twice.
* - Heart rate: per-minute samples of the last 90 days as raw rows, older
* ones as hourly means (min and max kept), one app per hour by the vitals
* priority. The Apple Health retention fold only folds Apple Health rows,
* so this import folds its own history as it writes it.
* priority. The nightly retention fold folds the raw samples into the
* same hourly `stats:` rows once they age past 90 days, and a raw sample
* whose hour is already folded is left out (`folded_window`).
* - Sleep: one row per stage (`sleep-stage-map.ts`), a session without
* stages as one asleep row; of two overlapping sessions from different
* apps the higher-ranked app's is kept.
@@ -58,6 +59,12 @@ import {
valuesMatch,
} from "@/lib/measurements/cross-source-merge";
import { reconcileExternalMeasurement } from "@/lib/measurements/reconcile-external-measurement";
import {
FOLDED_WINDOW_REASON,
findFoldedWindowDuplicates,
isFoldedWindowCandidate,
loadFoldTimezone,
} from "@/lib/measurements/folded-window";
import { canonicalDailyTimestamp } from "@/lib/measurements/consolidation-tz";
import { validateMeasurementRange } from "@/lib/validations/measurement";
import { isModuleEnabled } from "@/lib/modules/gate";
@@ -214,6 +221,8 @@ class ImportRun {
private readonly userId: string;
private readonly tz: string;
private readonly now: Date;
/** The account zone the fold keys its hours in, read once on first need. */
private foldTz: string | undefined;
private readonly apps = new Map<number, string>();
private readonly leftOutApps = new Set<number>();
private readonly devices = new Map<number, string | null>();
@@ -1335,6 +1344,7 @@ class ImportRun {
});
if (sameReadingCheck) batch = await this.withoutOtherSourceTwins(batch);
if (hourlyPulse) batch = await this.withoutRawPulseHours(batch);
else batch = await this.withoutFoldedHours(batch);
if (batch.length === 0) return;
const inserted = await insertNewMeasurementRows(
@@ -1521,6 +1531,38 @@ class ImportRun {
});
}
/**
* A raw sample of a folded type is left out when the nightly fold has
* already turned its hour into a `stats:` mean under this source. The fold
* deletes the samples it summarises, so without this a later import of an
* export that still holds them would put them back beside their own mean.
* Same rule as the Apple Health batch route and ZIP import
* (`folded-window.ts`); rows too young to have been folded cost no query.
*/
private async withoutFoldedHours(rows: PendingRow[]): Promise<PendingRow[]> {
if (rows.length === 0) return rows;
const candidates = rows.map((row) => ({
type: row.type,
source: SOURCE,
externalId: row.externalId,
measuredAt: row.measuredAt,
}));
if (!candidates.some((row) => isFoldedWindowCandidate(row))) return rows;
this.foldTz ??= await loadFoldTimezone(this.prisma, this.userId);
const folded = await findFoldedWindowDuplicates(
this.prisma,
this.userId,
candidates,
{ tz: this.foldTz },
);
if (folded.size === 0) return rows;
return rows.filter((row, index) => {
if (!folded.has(index)) return true;
this.skip(FOLDED_WINDOW_REASON, 1, row.type);
return false;
});
}
/** Called by the collapse when two apps write the same instant. */
noteCollision(type: string): void {
this.skip("same_instant_other_app", 1, type);
+4 -3
View File
@@ -25,6 +25,7 @@ import {
runDenseIntradayRetention,
DENSE_INTRADAY_RETENTION_TYPES,
DENSE_INTRADAY_RETENTION_DAYS,
DENSE_INTRADAY_FOLD_SOURCES,
} from "@/lib/measurements/dense-intraday-retention";
export const DENSE_INTRADAY_RETENTION_QUEUE = "dense-intraday-retention";
@@ -140,8 +141,8 @@ export async function runDenseIntradayRetentionForUser(
/**
* Boot-time discovery. Finds every user holding at least one LIVE
* per-sample dense-tier row (an `APPLE_HEALTH` row of a
* `DENSE_INTRADAY_RETENTION_TYPES` type whose externalId does NOT start
* per-sample dense-tier row (a row of a `DENSE_INTRADAY_FOLD_SOURCES` source
* and a `DENSE_INTRADAY_RETENTION_TYPES` type whose externalId does NOT start
* with the daily-stats prefix, that is not tombstoned, AND whose
* `measuredAt` is older than the retention window) and enqueues one
* retention job per account.
@@ -187,7 +188,7 @@ export async function enqueueBootTimeDenseIntradayRetention(): Promise<{
const users = await prisma.measurement.groupBy({
by: ["userId"],
where: {
source: "APPLE_HEALTH",
source: { in: [...DENSE_INTRADAY_FOLD_SOURCES] },
type: { in: types },
deletedAt: null,
NOT: { externalId: { startsWith: "stats:" } },
+50 -6
View File
@@ -66,7 +66,11 @@ import { listTargets } from "@/lib/links";
import type { LinkedTarget } from "@/lib/links/link-service";
import { isModuleEnabled, type ModuleKey } from "@/lib/modules/gate";
import { DEFAULT_TIMEZONE, userDayKey } from "@/lib/tz/format";
import { resolveCatalogEntry } from "@/lib/vaccinations/vaccine-catalog";
import {
CUSTOM_VACCINE_RESOLVE_SELECT,
customLookupOf,
resolveVaccineEntry,
} from "@/lib/vaccinations/resolve-vaccine-entry";
// ── Bounds ───────────────────────────────────────────────────────────
@@ -430,8 +434,8 @@ function vaccineCatalogName(
slug: string | null,
locale: Locale,
): string | null {
const entry = resolveCatalogEntry(slug);
if (!entry) return null;
const entry = resolveVaccineEntry({ antigenSlug: slug });
if (!entry?.slug) return null;
return getServerTranslator(locale).t(`vaccinations.catalog.${entry.slug}`);
}
@@ -646,8 +650,27 @@ const VACCINATION_SELECT = {
lotNumber: true,
site: true,
practitioner: PRACTITIONER_SELECT,
// v1.42 (#1005) — the person's own definition, for its name and antigens.
customVaccineId: true,
customVaccine: { select: CUSTOM_VACCINE_RESOLVE_SELECT },
} as const;
/**
* The person's own vaccine definition a dose names, when it is the answer
* (the catalogue wins when the dose also carries a slug). Its name is user
* text and is scrubbed or fenced by the caller.
*/
function ownVaccine(row: {
antigenSlug: string | null;
customVaccineId: string | null;
customVaccine: Parameters<typeof customLookupOf>[0][number];
}): { name: string; components: readonly string[] } | null {
const entry = resolveVaccineEntry(row, customLookupOf([row.customVaccine]));
return entry?.kind === "custom" && entry.name
? { name: entry.name, components: entry.components }
: null;
}
async function conditionCandidates(
userId: string,
owner: Owner,
@@ -858,10 +881,15 @@ async function vaccinationCandidates(
});
return rows.map((row) => {
const practitioner = livePractitioner(row.practitioner);
const entry = resolveCatalogEntry(row.antigenSlug);
const entry = resolveVaccineEntry({ antigenSlug: row.antigenSlug });
const own = ownVaccine(row);
const catalogEn = vaccineCatalogName(row.antigenSlug, "en");
const name =
row.vaccineName ?? catalogEn ?? row.antigenSlug ?? "Vaccination";
row.vaccineName ??
catalogEn ??
own?.name ??
row.antigenSlug ??
"Vaccination";
const dose = row.doseNumber ? `dose ${row.doseNumber}, ` : "";
const day = dateOnly(row.occurredAt);
return {
@@ -881,6 +909,10 @@ async function vaccinationCandidates(
? enumWords(row.antigenSlug.replace(/-/g, "_"))
: "",
...(entry?.synonyms ?? []),
own?.name ?? "",
...(own?.components ?? []).map((antigen) =>
enumWords(antigen.replace(/-/g, "_")),
),
].join(" "),
weight: WEIGHT.primary,
},
@@ -1072,6 +1104,8 @@ async function fetchVisit(
vaccineName: true,
antigenSlug: true,
occurredAt: true,
customVaccineId: true,
customVaccine: { select: CUSTOM_VACCINE_RESOLVE_SELECT },
},
orderBy: [{ occurredAt: "asc" }, { id: "asc" }],
})
@@ -1087,6 +1121,7 @@ async function fetchVisit(
label: scrubFenceMarkers(
dose.vaccineName ??
vaccineCatalogName(dose.antigenSlug, "en") ??
ownVaccine(dose)?.name ??
dose.antigenSlug ??
"Vaccination",
),
@@ -1377,7 +1412,9 @@ async function fetchVaccination(
]);
const catalog = vaccineCatalogName(row.antigenSlug, "en");
const name = row.vaccineName ?? catalog ?? row.antigenSlug ?? "Vaccination";
const own = ownVaccine(row);
const name =
row.vaccineName ?? catalog ?? own?.name ?? row.antigenSlug ?? "Vaccination";
const practitioner = livePractitioner(row.practitioner);
const day = dateOnly(row.occurredAt);
const dose =
@@ -1388,6 +1425,13 @@ async function fetchVaccination(
const sentences = [
`Vaccination ${fenceUserText(name)} on ${day}, ${dose}.`,
catalog && row.vaccineName ? `Catalogue entry: ${catalog}.` : null,
own
? `Logged against the person's own vaccine ${fenceUserText(own.name)}${
own.components.length > 0
? `, which protects against ${own.components.join(", ")}`
: ""
}.`
: null,
practitioner
? `Given by ${fenceUserText(practitioner.name)}.`
: "No practitioner recorded.",
@@ -84,8 +84,12 @@ function buildPrismaMock(opts: {
};
// Top-level client.
const findMany = vi.fn(async (args: { where: { type: string } }) =>
args.where.type === "PULSE" ? opts.pulseRows : [],
// The seeded rows are Apple Health's; the Health Connect walk finds none.
const findMany = vi.fn(
async (args: { where: { type: string; source: string } }) =>
args.where.type === "PULSE" && args.where.source === "APPLE_HEALTH"
? opts.pulseRows
: [],
);
// Native-resting probe is the only top-level `findFirst` call.
const topFindFirst = vi
@@ -106,8 +106,13 @@ function buildPrismaMock(existingResting: Array<{ source: string }>) {
.mockResolvedValue([{ id: "user-1", timezone: "Europe/Berlin" }]),
},
measurement: {
findMany: vi.fn(async (args: { where: { type: string } }) =>
args.where.type === "PULSE" ? pulseRows() : [],
// The seeded rows are Apple Health's; the Health Connect walk
// finds none.
findMany: vi.fn(
async (args: { where: { type: string; source: string } }) =>
args.where.type === "PULSE" && args.where.source === "APPLE_HEALTH"
? pulseRows()
: [],
),
findFirst: probeFindFirst,
upsert,
@@ -62,9 +62,12 @@ function buildPrismaMock(
);
const updateMany = vi.fn().mockResolvedValue({ count: 0 });
const deleteMany = vi.fn().mockResolvedValue({ count: 0 });
// The seeded rows are Apple Health's; the Health Connect walk finds none.
const findManyMeasurement = vi.fn(
async (args: { where: { type: string } }) =>
rowsByType[args.where.type] ?? [],
async (args: { where: { type: string; source: string } }) =>
args.where.source === "APPLE_HEALTH"
? (rowsByType[args.where.type] ?? [])
: [],
);
const tx = {
measurement: {
@@ -140,20 +143,21 @@ describe("runDenseIntradayRetention — retention bound", () => {
}
});
it("scans exactly the dense-tier types, source-scoped to APPLE_HEALTH", async () => {
it("scans exactly the dense-tier types, once per fold source, Apple Health first", async () => {
const { mock, findManyMeasurement } = buildPrismaMock({});
await runDenseIntradayRetention(mock, { log: () => {} });
const scannedTypes = findManyMeasurement.mock.calls.map(
(c) => (c[0] as { where: { type: string } }).where.type,
);
expect(scannedTypes.sort()).toEqual(
Array.from(DENSE_INTRADAY_RETENTION_TYPES).sort(),
);
for (const call of findManyMeasurement.mock.calls) {
const where = (call[0] as unknown as { where: { source: string } }).where;
expect(where.source).toBe("APPLE_HEALTH");
}
const scans = findManyMeasurement.mock.calls.map((c) => {
const where = (c[0] as { where: { type: string; source: string } }).where;
return `${where.source}:${where.type}`;
});
const types = Array.from(DENSE_INTRADAY_RETENTION_TYPES);
// One walk per source, each scoped to its one source: two sources
// never share a mean, and manual or Withings rows are never scanned.
expect(scans).toEqual([
...types.map((type) => `APPLE_HEALTH:${type}`),
...types.map((type) => `HEALTH_CONNECT:${type}`),
]);
});
});
@@ -75,8 +75,13 @@ function buildPrismaMock(opts: { spo2Rows: PerSampleRow[] }) {
},
};
const findMany = vi.fn(async (args: { where: { type: string } }) =>
args.where.type === "OXYGEN_SATURATION" ? opts.spo2Rows : [],
// The seeded rows are Apple Health's; the Health Connect walk finds none.
const findMany = vi.fn(
async (args: { where: { type: string; source: string } }) =>
args.where.type === "OXYGEN_SATURATION" &&
args.where.source === "APPLE_HEALTH"
? opts.spo2Rows
: [],
);
// Native-resting probe + derived-resting upsert: PULSE-only surfaces.
const topFindFirst = vi.fn().mockResolvedValue(null);
@@ -226,3 +226,80 @@ describe("findCompactionTombstones", () => {
expect(found.size).toBe(0);
});
});
/**
* Health Connect folds its raw heart-rate history the way Apple Health does:
* past the 90-day window into one `stats:` row per local hour, under its own
* source. The mean-day rule stays Apple Health only, because the nightly
* mean consolidation never reads another source.
*/
describe("Health Connect", () => {
const old = new Date("2026-03-01T10:15:00.000Z");
const hc = (
type: string,
at: Date,
overrides: Record<string, unknown> = {},
) =>
raw(type, at, {
source: "HEALTH_CONNECT",
externalId: "hc:00000000-0000-0000-0000-000000000001:1",
...overrides,
});
/** A lookup that answers per source, as the database does. */
function sourceAwareClient(
live: Array<{ type: string; source: string; externalId: string }>,
) {
const findMany = vi.fn(async (args: { where: { source: string } }) =>
live.filter((row) => row.source === args.where.source),
);
return {
findMany,
client: {
measurement: { findMany },
} as unknown as Parameters<typeof findFoldedWindowDuplicates>[0],
};
}
it("takes a raw dense sample past the window, and not a mean-type one", () => {
expect(isFoldedWindowCandidate(hc("PULSE", old), NOW)).toBe(true);
expect(
isFoldedWindowCandidate(
hc("PULSE", new Date(NOW.getTime() - 89 * DAY)),
NOW,
),
).toBe(false);
expect(isFoldedWindowCandidate(hc("RESPIRATORY_RATE", old), NOW)).toBe(
false,
);
expect(
isFoldedWindowCandidate(
hc("PULSE", old, {
externalId: "stats:HKQuantityTypeIdentifierHeartRate:2026-03-01T10",
}),
NOW,
),
).toBe(false);
});
it("is covered only by a `stats:` row of its own source", async () => {
const hour = "stats:HKQuantityTypeIdentifierHeartRate:2026-03-01T10";
const { client: c, findMany } = sourceAwareClient([
{ type: "PULSE", source: "HEALTH_CONNECT", externalId: hour },
]);
const found = await findFoldedWindowDuplicates(
c,
"u1",
[hc("PULSE", old), raw("PULSE", old)],
{ now: NOW, tz: "UTC" },
);
// The Health Connect sample is a duplicate; the Apple Health sample of
// the same hour is not, because no Apple Health `stats:` row covers it.
expect([...found]).toEqual([0]);
const sources = findMany.mock.calls.map(
(call) =>
(call as unknown as [{ where: { source: string } }])[0].where.source,
);
expect(sources.sort()).toEqual(["APPLE_HEALTH", "HEALTH_CONNECT"]);
});
});
+277 -239
View File
@@ -50,6 +50,7 @@
*/
import { holdAccountAgainstRestore } from "@/lib/export/restore-lock";
import type {
MeasurementSource,
MeasurementType,
Prisma,
PrismaClient,
@@ -154,6 +155,23 @@ export const DENSE_INTRADAY_RETENTION_TYPES: ReadonlySet<MeasurementType> =
*/
export const DENSE_INTRADAY_RETENTION_DAYS = 90;
/**
* The sources whose raw dense samples fold (v1.42). Apple Health from the
* start; Health Connect because its importer writes the samples of the last
* 90 days raw, exactly like an Apple Health sync, and without a fold every
* new export would add another quarter of minute-by-minute heart rate that
* never ages into hourly means. Each source folds into its OWN `stats:` rows,
* so an hour two sources both covered keeps one mean per source, the same
* way the raw samples kept their source.
*/
export const DENSE_INTRADAY_FOLD_SOURCES = [
"APPLE_HEALTH",
"HEALTH_CONNECT",
] as const satisfies readonly MeasurementSource[];
export type DenseIntradayFoldSource =
(typeof DENSE_INTRADAY_FOLD_SOURCES)[number];
/** The stats externalId prefix marks an already-collapsed row. */
const DAILY_STATS_PREFIX = "stats:";
@@ -249,10 +267,13 @@ export async function adoptOrMintHourlyRows(
input: {
userId: string;
type: MeasurementType;
/** The source the folded samples carry; the hourly rows carry it too. */
source?: DenseIntradayFoldSource;
unit: string;
slots: readonly HourlySlot[];
},
): Promise<string[]> {
const source = input.source ?? "APPLE_HEALTH";
if (input.slots.length === 0) return [];
// Every row that either index could put in the way, lowest id first — the
@@ -263,7 +284,7 @@ export async function adoptOrMintHourlyRows(
where: {
userId: input.userId,
type: input.type,
source: "APPLE_HEALTH",
source,
OR: [
{ externalId: { in: input.slots.map((slot) => slot.externalId) } },
{
@@ -338,7 +359,7 @@ export async function adoptOrMintHourlyRows(
type: input.type,
value: slot.value,
unit: input.unit,
source: "APPLE_HEALTH" as const,
source,
measuredAt: slot.anchor,
externalId: slot.externalId,
})),
@@ -538,263 +559,280 @@ export async function runDenseIntradayRetention(
// for the dry-run hourly fan-out estimate (writeDay never runs on dry-run).
let currentTz = DEFAULT_TIMEZONE;
const walk = await runConsolidation<MeasurementType>({
prismaClient,
options: { ...options, cutoffHours },
types: DENSE_INTRADAY_RETENTION_TYPES,
hkIdentifierForType,
dailyStatsExternalId,
statsPrefix: DAILY_STATS_PREFIX,
// The base's per-day reducedValue is the day MEAN; the hourly fold
// recomputes per-hour means itself (same `meanBucketValue` reducer, so
// the two surfaces can never drift), and the day-level value only
// feeds the summary/dry-run reporting.
reduce: meanBucketValue,
// Live per-sample rows for the type, source-scoped to APPLE_HEALTH so
// manual + Withings spot rows survive. The minted hourly stats rows are
// excluded by the NOT-startsWith predicate so they are never re-folded;
// soft-deleted rows are excluded so a re-run converges. `cutoffAt` is
// the retention boundary — rows newer than it (inside the window) are
// NOT scanned, so the dense intra-day shape is preserved.
buildScanWhere: ({ userId, type, cutoffAt, statsPrefix }) => ({
userId,
source: "APPLE_HEALTH",
type,
deletedAt: null,
NOT: { externalId: { startsWith: statsPrefix } },
...(cutoffAt ? { measuredAt: { lt: cutoffAt } } : {}),
}),
scanSelect: {
id: true,
type: true,
value: true,
measuredAt: true,
externalId: true,
unit: true,
},
writeDay: async ({
prismaClient: pc,
userId,
type,
externalId,
canonicalTimestamp,
dayRows,
sourceRowIds,
tz,
dateKey,
}): Promise<DayWriteOutcome> => {
const unit = dayRows[0]?.unit ?? "unknown";
const isPulse = type === "PULSE";
const hkIdentifier = hkIdentifierForType(type);
// Unreachable: the base skips types without an HK identifier before
// scanning; asserted so a future type-set edit fails loud, not by
// minting a malformed externalId.
if (!hkIdentifier) {
throw new Error(`no HK identifier for dense-tier type ${type}`);
}
// Awaited inside, not returned bare: the restore-lock guard finds the
// consolidation passes by their `await runConsolidation`.
const walkSource = async (source: DenseIntradayFoldSource) =>
await runConsolidation<MeasurementType>({
prismaClient,
options: { ...options, cutoffHours },
types: DENSE_INTRADAY_RETENTION_TYPES,
hkIdentifierForType,
dailyStatsExternalId,
statsPrefix: DAILY_STATS_PREFIX,
// The base's per-day reducedValue is the day MEAN; the hourly fold
// recomputes per-hour means itself (same `meanBucketValue` reducer, so
// the two surfaces can never drift), and the day-level value only
// feeds the summary/dry-run reporting.
reduce: meanBucketValue,
// Live per-sample rows for the type, scoped to the one source this walk
// folds so manual + Withings spot rows survive and two sources never
// share a mean. The minted hourly stats rows are
// excluded by the NOT-startsWith predicate so they are never re-folded;
// soft-deleted rows are excluded so a re-run converges. `cutoffAt` is
// the retention boundary — rows newer than it (inside the window) are
// NOT scanned, so the dense intra-day shape is preserved.
buildScanWhere: ({ userId, type, cutoffAt, statsPrefix }) => ({
userId,
source,
type,
deletedAt: null,
NOT: { externalId: { startsWith: statsPrefix } },
...(cutoffAt ? { measuredAt: { lt: cutoffAt } } : {}),
}),
scanSelect: {
id: true,
type: true,
value: true,
measuredAt: true,
externalId: true,
unit: true,
},
writeDay: async ({
prismaClient: pc,
userId,
type,
externalId,
canonicalTimestamp,
dayRows,
sourceRowIds,
tz,
dateKey,
}): Promise<DayWriteOutcome> => {
const unit = dayRows[0]?.unit ?? "unknown";
const isPulse = type === "PULSE";
const hkIdentifier = hkIdentifierForType(type);
// Unreachable: the base skips types without an HK identifier before
// scanning; asserted so a future type-set edit fails loud, not by
// minting a malformed externalId.
if (!hkIdentifier) {
throw new Error(`no HK identifier for dense-tier type ${type}`);
}
// DAY-rollup fidelity — mean AND min/max (all dense-tier types). The
// persistent `MeasurementRollup` DAY bucket aggregates LIVE rows;
// recomputing it AFTER the fold would aggregate the hourly means: the
// min/max collapse to the extreme hourly MEANS (for SpO2 hiding the
// overnight-desaturation nadir; for PULSE the resting floor + workout
// peak) and the mean becomes an unweighted mean-of-hourly-means that
// drifts whenever per-hour sample counts differ. So the DAY bucket is
// recomputed from the RAW rows BEFORE the fold, while they are still
// live, and the post-fold DAY recompute is skipped entirely. The
// WEEK/MONTH/YEAR recomputes this call enqueues run post-commit
// against whatever is live then, as before.
await recomputeBucketsForMeasurement(userId, type, canonicalTimestamp);
// DAY-rollup fidelity — mean AND min/max (all dense-tier types). The
// persistent `MeasurementRollup` DAY bucket aggregates LIVE rows;
// recomputing it AFTER the fold would aggregate the hourly means: the
// min/max collapse to the extreme hourly MEANS (for SpO2 hiding the
// overnight-desaturation nadir; for PULSE the resting floor + workout
// peak) and the mean becomes an unweighted mean-of-hourly-means that
// drifts whenever per-hour sample counts differ. So the DAY bucket is
// recomputed from the RAW rows BEFORE the fold, while they are still
// live, and the post-fold DAY recompute is skipped entirely. The
// WEEK/MONTH/YEAR recomputes this call enqueues run post-commit
// against whatever is live then, as before.
await recomputeBucketsForMeasurement(userId, type, canonicalTimestamp);
// Fold the day into per-LOCAL-HOUR mean rows, anchored at local
// HH:30. Sorted for a deterministic write order across runs.
const byHour = [...bucketRowsByLocalHour(dayRows, tz).entries()].sort(
(a, b) => a[0] - b[0],
);
// Fold the day into per-LOCAL-HOUR mean rows, anchored at local
// HH:30. Sorted for a deterministic write order across runs.
const byHour = [...bucketRowsByLocalHour(dayRows, tz).entries()].sort(
(a, b) => a[0] - b[0],
);
const foldOnce = async (): Promise<{
removed: number;
retiredDaily: boolean;
}> => {
let removed = 0;
let retiredDaily = false;
await pc.$transaction(async (tx) => {
// First, before any reading is touched: see `restore-lock.ts`.
await holdAccountAgainstRestore(tx, userId);
const canonicalRowIds = await adoptOrMintHourlyRows(tx, {
userId,
type,
unit,
slots: byHour.map(([hour, hourRows]) => ({
externalId: hourlyStatsExternalId(hkIdentifier, dateKey, hour),
anchor: canonicalHourlyTimestamp(dateKey, hour, tz),
value: meanBucketValue(hourRows),
})),
});
// Retire a live pre-hourly DAILY `stats:` row for this day (the
// late-sync path: raw samples arriving for a day folded to the
// daily grain before v1.28.31). Same transaction as the hourly
// mint — an AVG-over-live-rows reader must never see the daily
// row and the hourly rows live at once (double count).
const dailyRow = await tx.measurement.findFirst({
where: {
const foldOnce = async (): Promise<{
removed: number;
retiredDaily: boolean;
}> => {
let removed = 0;
let retiredDaily = false;
await pc.$transaction(async (tx) => {
// First, before any reading is touched: see `restore-lock.ts`.
await holdAccountAgainstRestore(tx, userId);
const canonicalRowIds = await adoptOrMintHourlyRows(tx, {
userId,
type,
source: "APPLE_HEALTH",
externalId,
deletedAt: null,
},
select: { id: true },
orderBy: { id: "asc" },
});
if (dailyRow && !canonicalRowIds.includes(dailyRow.id)) {
await tx.measurement.update({
where: { id: dailyRow.id },
data: { deletedAt: new Date() },
source,
unit,
slots: byHour.map(([hour, hourRows]) => ({
externalId: hourlyStatsExternalId(hkIdentifier, dateKey, hour),
anchor: canonicalHourlyTimestamp(dateKey, hour, tz),
value: meanBucketValue(hourRows),
})),
});
retiredDaily = true;
}
// Delete the out-of-window per-sample rows in the same
// transaction. EXCLUDE the adopted canonical rows: a per-sample row
// that happened to fall on an hourly anchor is the row just adopted
// as that hour's mean, so removing it would erase the fold.
//
// v1.42 — deleted outright, like the cumulative drain's rows,
// where they used to be tombstoned for the 75-day retention. No
// client ever pulled these rows, so the tombstone told nobody
// anything; it only held the re-upload of a folded sample off,
// and the `folded_window` ingest guard (`folded-window.ts`) does
// that now from the live hourly row. The tombstones made up most
// of the table and its indexes.
const del = await tx.measurement.deleteMany({
where: {
id: { in: sourceRowIds, notIn: canonicalRowIds },
deletedAt: null,
},
// Retire a live pre-hourly DAILY `stats:` row for this day (the
// late-sync path: raw samples arriving for a day folded to the
// daily grain before v1.28.31). Same transaction as the hourly
// mint — an AVG-over-live-rows reader must never see the daily
// row and the hourly rows live at once (double count).
const dailyRow = await tx.measurement.findFirst({
where: {
userId,
type,
source,
externalId,
deletedAt: null,
},
select: { id: true },
orderBy: { id: "asc" },
});
if (dailyRow && !canonicalRowIds.includes(dailyRow.id)) {
await tx.measurement.update({
where: { id: dailyRow.id },
data: { deletedAt: new Date() },
});
retiredDaily = true;
}
// Delete the out-of-window per-sample rows in the same
// transaction. EXCLUDE the adopted canonical rows: a per-sample row
// that happened to fall on an hourly anchor is the row just adopted
// as that hour's mean, so removing it would erase the fold.
//
// v1.42 — deleted outright, like the cumulative drain's rows,
// where they used to be tombstoned for the 75-day retention. No
// client ever pulled these rows, so the tombstone told nobody
// anything; it only held the re-upload of a folded sample off,
// and the `folded_window` ingest guard (`folded-window.ts`) does
// that now from the live hourly row. The tombstones made up most
// of the table and its indexes.
const del = await tx.measurement.deleteMany({
where: {
id: { in: sourceRowIds, notIn: canonicalRowIds },
deletedAt: null,
},
});
removed = del.count;
});
removed = del.count;
});
return { removed, retiredDaily };
};
return { removed, retiredDaily };
};
let foldResult: { removed: number; retiredDaily: boolean };
try {
foldResult = await foldOnce();
} catch (err) {
if (!isUniqueConstraintViolation(err)) throw err;
// A concurrent writer won a slot mid-transaction. Retry once: the
// deterministic lookup now resolves the winning row and adopts it,
// so this pass cannot create a duplicate.
foldResult = await foldOnce();
}
// Counters mutate OUTSIDE the retryable transaction so a P2002 retry
// cannot double-count.
summary.totals.hourlyRowsUpserted += byHour.length;
if (foldResult.retiredDaily) summary.totals.dailyRowsRetired += 1;
let foldResult: { removed: number; retiredDaily: boolean };
try {
foldResult = await foldOnce();
} catch (err) {
if (!isUniqueConstraintViolation(err)) throw err;
// A concurrent writer won a slot mid-transaction. Retry once: the
// deterministic lookup now resolves the winning row and adopts it,
// so this pass cannot create a duplicate.
foldResult = await foldOnce();
}
// Counters mutate OUTSIDE the retryable transaction so a P2002 retry
// cannot double-count.
summary.totals.hourlyRowsUpserted += byHour.length;
if (foldResult.retiredDaily) summary.totals.dailyRowsRetired += 1;
// iOS#34 — preserve the resting signal for PROXY users. For a user
// with zero native `RESTING_HEART_RATE` rows, the read-path resolver
// derives resting from the 20th-percentile of each day's RAW PULSE; the
// fold has just deleted those rows, so that day's resting figure would
// vanish (the hourly means flatten the low tail the percentile reads).
// Mint one derived `RESTING_HEART_RATE` row from the same percentile,
// sourced `COMPUTED` (distinct from Apple's own resting rows on both
// unique indexes), so the day reads back as the clean resting series
// the resolver prefers. Skipped for users WITH native resting rows
// (the resolver ignores the proxy entirely for them, so a derived row
// would only double-count).
if (isPulse) {
const restingValue = deriveDailyRestingFromPulse(dayRows);
if (restingValue !== null && !(await userHasNativeResting(userId))) {
const restingExternalId = dailyStatsExternalId(
RESTING_HK_IDENTIFIER,
// The fold's canonical timestamp is local-noon of the day; reuse
// its UTC date for the resting row's `stats:` key so a re-run
// upserts the same row instead of minting a sibling.
// eslint-disable-next-line healthlog/no-utc-day-key -- UTC by design: stable stats: externalId key; changing it would mint a sibling row on re-run
canonicalTimestamp.toISOString().slice(0, 10),
);
await pc.measurement.upsert({
where: {
userId_type_source_externalId: {
// iOS#34 — preserve the resting signal for PROXY users. For a user
// with zero native `RESTING_HEART_RATE` rows, the read-path resolver
// derives resting from the 20th-percentile of each day's RAW PULSE; the
// fold has just deleted those rows, so that day's resting figure would
// vanish (the hourly means flatten the low tail the percentile reads).
// Mint one derived `RESTING_HEART_RATE` row from the same percentile,
// sourced `COMPUTED` (distinct from Apple's own resting rows on both
// unique indexes), so the day reads back as the clean resting series
// the resolver prefers. Skipped for users WITH native resting rows
// (the resolver ignores the proxy entirely for them, so a derived row
// would only double-count).
if (isPulse) {
const restingValue = deriveDailyRestingFromPulse(dayRows);
if (restingValue !== null && !(await userHasNativeResting(userId))) {
const restingExternalId = dailyStatsExternalId(
RESTING_HK_IDENTIFIER,
// The fold's canonical timestamp is local-noon of the day; reuse
// its UTC date for the resting row's `stats:` key so a re-run
// upserts the same row instead of minting a sibling.
// eslint-disable-next-line healthlog/no-utc-day-key -- UTC by design: stable stats: externalId key; changing it would mint a sibling row on re-run
canonicalTimestamp.toISOString().slice(0, 10),
);
await pc.measurement.upsert({
where: {
userId_type_source_externalId: {
userId,
type: "RESTING_HEART_RATE",
source: "COMPUTED",
externalId: restingExternalId,
},
},
create: {
userId,
type: "RESTING_HEART_RATE",
value: restingValue,
unit: "bpm",
source: "COMPUTED",
measuredAt: canonicalTimestamp,
externalId: restingExternalId,
},
},
create: {
update: { value: restingValue, deletedAt: null },
});
summary.totals.derivedRestingRowsUpserted += 1;
// The derived row is its own (type, day); recompute its DAY bucket
// so the rollup tier serves it on a covered read.
await recomputeBucketsForMeasurement(
userId,
type: "RESTING_HEART_RATE",
value: restingValue,
unit: "bpm",
source: "COMPUTED",
measuredAt: canonicalTimestamp,
externalId: restingExternalId,
},
update: { value: restingValue, deletedAt: null },
});
summary.totals.derivedRestingRowsUpserted += 1;
// The derived row is its own (type, day); recompute its DAY bucket
// so the rollup tier serves it on a covered read.
await recomputeBucketsForMeasurement(
userId,
"RESTING_HEART_RATE",
canonicalTimestamp,
);
"RESTING_HEART_RATE",
canonicalTimestamp,
);
}
}
}
// No post-fold DAY recompute for ANY dense-tier type — it would
// overwrite the true raw-derived mean/min/max the pre-fold recompute
// above captured with hourly-mean-derived approximations (see the
// fidelity note there).
// No post-fold DAY recompute for ANY dense-tier type — it would
// overwrite the true raw-derived mean/min/max the pre-fold recompute
// above captured with hourly-mean-derived approximations (see the
// fidelity note there).
return { kind: "written", sourceRowsRemoved: foldResult.removed };
},
recordBucket: ({ dayRows, outcome }) => {
summary.totals.daysConsolidated += 1;
if (outcome === null) {
// Dry-run: writeDay never ran, so estimate the hourly fan-out here
// from the same bucketing the real fold would use.
summary.totals.hourlyRowsUpserted += bucketRowsByLocalHour(
dayRows,
currentTz,
).size;
}
summary.totals.perSampleRowsSoftDeleted +=
outcome?.kind === "written"
? outcome.sourceRowsRemoved
: dayRows.length;
},
onUserStart: ({ tz }) => {
currentTz = tz;
},
onUserComplete: ({ userId, tz, dryRun }) => {
log(
`[dense-intraday-retention] user=${userId} tz=${tz}${dryRun ? " (dry-run)" : ""}`,
);
},
// Per-day failure boundary (v1.18.10 lesson). A day whose fold throws —
// e.g. a residual unique-index collision the adopt-in-place path could
// not absorb, or a derived-resting upsert that races a native row — is
// logged and STEPPED OVER so the global walk keeps draining every other
// user / type / day. The failed day keeps its raw rows live (the fold
// deletes only on a committed transaction), so the next nightly run
// retries it. Without this, one poisoned day aborted the whole walk and
// stranded every later account.
onBucketError: ({ userId, type, dateKey, error }) => {
const reason = error instanceof Error ? error.message : String(error);
log(
`[dense-intraday-retention] user=${userId} type=${type} day=${dateKey} failed — ${reason}; continuing with the next bucket`,
);
},
});
return { kind: "written", sourceRowsRemoved: foldResult.removed };
},
recordBucket: ({ dayRows, outcome }) => {
summary.totals.daysConsolidated += 1;
if (outcome === null) {
// Dry-run: writeDay never ran, so estimate the hourly fan-out here
// from the same bucketing the real fold would use.
summary.totals.hourlyRowsUpserted += bucketRowsByLocalHour(
dayRows,
currentTz,
).size;
}
summary.totals.perSampleRowsSoftDeleted +=
outcome?.kind === "written"
? outcome.sourceRowsRemoved
: dayRows.length;
},
onUserStart: ({ tz }) => {
currentTz = tz;
},
onUserComplete: ({ userId, tz, dryRun }) => {
log(
`[dense-intraday-retention] user=${userId} source=${source} tz=${tz}${dryRun ? " (dry-run)" : ""}`,
);
},
// Per-day failure boundary (v1.18.10 lesson). A day whose fold throws —
// e.g. a residual unique-index collision the adopt-in-place path could
// not absorb, or a derived-resting upsert that races a native row — is
// logged and STEPPED OVER so the global walk keeps draining every other
// user / type / day. The failed day keeps its raw rows live (the fold
// deletes only on a committed transaction), so the next nightly run
// retries it. Without this, one poisoned day aborted the whole walk and
// stranded every later account.
onBucketError: ({ userId, type, dateKey, error }) => {
const reason = error instanceof Error ? error.message : String(error);
log(
`[dense-intraday-retention] user=${userId} source=${source} type=${type} day=${dateKey} failed — ${reason}; continuing with the next bucket`,
);
},
});
summary.totals.usersScanned = walk.usersScanned;
summary.stoppedEarly = walk.stoppedEarly;
// One walk per source, Apple Health first so its behaviour and its order
// are exactly what they were before Health Connect folded too. A walk that
// stopped early stops the pass: the next run resumes where it left off.
for (const source of DENSE_INTRADAY_FOLD_SOURCES) {
const walk = await walkSource(source);
summary.totals.usersScanned = Math.max(
summary.totals.usersScanned,
walk.usersScanned,
);
if (walk.stoppedEarly) {
summary.stoppedEarly = true;
break;
}
}
log(
`[dense-intraday-retention] done — usersScanned=${summary.totals.usersScanned} daysConsolidated=${summary.totals.daysConsolidated} perSampleRowsSoftDeleted=${summary.totals.perSampleRowsSoftDeleted} hourlyRowsUpserted=${summary.totals.hourlyRowsUpserted} dailyRowsRetired=${summary.totals.dailyRowsRetired} derivedRestingRowsUpserted=${summary.totals.derivedRestingRowsUpserted}${options.dryRun ? " (dry-run)" : ""}`,
+71 -34
View File
@@ -1,14 +1,13 @@
/**
* The `folded_window` ingest guard and the compaction-tombstone class (v1.42).
*
* The dense-intraday consolidation folds the raw Apple Health samples of a
* DENSE type into one `stats:` row per local hour once they are older than
* The dense-intraday consolidation folds the raw samples of a DENSE type into one `stats:` row per local hour once they are older than
* the retention window, and a MEAN type into one `stats:` row per local day
* once the consolidation grace has passed. Since v1.42 the folded raw rows are
* deleted outright rather than left as tombstones, so a client that re-uploads
* an old sample after losing its anchor would put it back beside the hour or
* day that already accounts for it. A raw (non-`stats:`) Apple Health value of
* such a type, old enough to have been folded, is therefore a duplicate when a
* day that already accounts for it. A raw (non-`stats:`) value of such a source
* and type, old enough to have been folded, is therefore a duplicate when a
* live `stats:` row covers its hour or day. The batch route and the ZIP import
* apply the same rule.
*
@@ -29,8 +28,12 @@
* the other zone; such a row is then simply not recognised, which is the
* pre-v1.42 behaviour, never a wrong refusal.
*
* Health Connect does not use this: its importer writes the folded shape
* itself.
* Health Connect folds its raw heart-rate history the same way under its own
* source (the importer writes samples of the last 90 days raw, and the
* nightly pass folds them once they age out), so the hour rule covers both
* sources and a covering row is always looked up under the sample's own
* source. The day rule stays Apple Health only: the nightly mean
* consolidation reads no other source.
*/
import type {
MeasurementSource,
@@ -49,6 +52,7 @@ import {
hourOfDayForUserTz,
} from "@/lib/measurements/consolidation-tz";
import {
DENSE_INTRADAY_FOLD_SOURCES,
DENSE_INTRADAY_RETENTION_DAYS,
DENSE_INTRADAY_RETENTION_TYPES,
hourlyStatsExternalId,
@@ -60,15 +64,17 @@ export const FOLDED_WINDOW_REASON: FoldedWindowReason = "folded_window";
const HOUR_MS = 3_600_000;
/** Which types fold into which window, and from what age. */
/** Which sources and types fold into which window, and from what age. */
export const FOLDED_WINDOW_RULES = [
{
window: "hour",
sources: DENSE_INTRADAY_FOLD_SOURCES,
types: DENSE_INTRADAY_RETENTION_TYPES,
foldedAfterMs: DENSE_INTRADAY_RETENTION_DAYS * 24 * HOUR_MS,
},
{
window: "day",
sources: ["APPLE_HEALTH"] as const,
types: HIGH_FREQUENCY_MEAN_TYPES,
foldedAfterMs: CONSOLIDATION_GRACE_CUTOFF_HOURS * HOUR_MS,
},
@@ -98,7 +104,6 @@ export function isFoldedWindowCandidate(
row: FoldedWindowCandidateRow,
now: Date = new Date(),
): boolean {
if (row.source !== "APPLE_HEALTH") return false;
if (row.externalId === null) return false;
if (row.externalId.startsWith("stats:")) return false;
// A collision retirement (`reconcile-external-measurement.ts`) parks the
@@ -106,7 +111,10 @@ export function isFoldedWindowCandidate(
if (row.externalId.startsWith("retired:")) return false;
const age = now.getTime() - row.measuredAt.getTime();
return FOLDED_WINDOW_RULES.some(
(rule) => rule.types.has(row.type) && age > rule.foldedAfterMs,
(rule) =>
(rule.sources as readonly MeasurementSource[]).includes(row.source) &&
rule.types.has(row.type) &&
age > rule.foldedAfterMs,
);
}
@@ -153,8 +161,9 @@ export async function loadFoldTimezone(
}
/**
* Indexes (into `rows`) whose covering `stats:` row is live. One query over
* the unique `(user_id, type, source, external_id)` index for the whole set.
* Indexes (into `rows`) whose covering `stats:` row is live under the row's
* own source. One query per source present, each over the unique
* `(user_id, type, source, external_id)` index for the whole set.
*/
async function coveredIndexes(
client: Pick<LookupClient, "measurement">,
@@ -163,35 +172,49 @@ async function coveredIndexes(
rows: ReadonlyArray<{
index: number;
type: MeasurementType;
source: MeasurementSource;
measuredAt: Date;
}>,
): Promise<Set<number>> {
const covered = new Set<number>();
if (rows.length === 0) return covered;
const keyOf = new Map<number, string>();
const ids = new Set<string>();
const types = new Set<MeasurementType>();
const bySource = new Map<
MeasurementSource,
{
keyOf: Map<number, string>;
ids: Set<string>;
types: Set<MeasurementType>;
}
>();
for (const row of rows) {
const id = coveringStatsExternalId(row, tz);
if (!id) continue;
keyOf.set(row.index, `${row.type}|${id}`);
ids.add(id);
types.add(row.type);
let group = bySource.get(row.source);
if (!group) {
group = { keyOf: new Map(), ids: new Set(), types: new Set() };
bySource.set(row.source, group);
}
group.keyOf.set(row.index, `${row.type}|${id}`);
group.ids.add(id);
group.types.add(row.type);
}
if (ids.size === 0) return covered;
const live = await client.measurement.findMany({
where: {
userId,
type: { in: [...types] },
source: "APPLE_HEALTH",
externalId: { in: [...ids] },
deletedAt: null,
},
select: { type: true, externalId: true },
});
const liveKeys = new Set(live.map((row) => `${row.type}|${row.externalId}`));
for (const [index, key] of keyOf) {
if (liveKeys.has(key)) covered.add(index);
for (const [source, group] of bySource) {
const live = await client.measurement.findMany({
where: {
userId,
type: { in: [...group.types] },
source,
externalId: { in: [...group.ids] },
deletedAt: null,
},
select: { type: true, externalId: true },
});
const liveKeys = new Set(
live.map((row) => `${row.type}|${row.externalId}`),
);
for (const [index, key] of group.keyOf) {
if (liveKeys.has(key)) covered.add(index);
}
}
return covered;
}
@@ -211,7 +234,14 @@ export async function findFoldedWindowDuplicates(
const now = options.now ?? new Date();
const candidates = rows.flatMap((row, index) =>
isFoldedWindowCandidate(row, now)
? [{ index, type: row.type, measuredAt: row.measuredAt }]
? [
{
index,
type: row.type,
source: row.source,
measuredAt: row.measuredAt,
},
]
: [],
);
if (candidates.length === 0) return new Set();
@@ -230,7 +260,7 @@ export interface TombstoneCandidateRow extends FoldedWindowCandidateRow {
/**
* Indexes (into `rows`) of the compaction tombstones ("class A"): soft-deleted
* raw Apple Health samples of a folded type that were already past the fold
* raw samples of a folded source and type that were already past the fold
* threshold when they were deleted, and whose hour or day a live `stats:` row
* covers. Everything else, in particular a person's own deletions of recent
* samples, is class B and keeps the 75-day tombstone retention.
@@ -243,7 +273,14 @@ export async function findCompactionTombstones(
): Promise<Set<number>> {
const candidates = rows.flatMap((row, index) =>
row.deletedAt !== null && isFoldedWindowCandidate(row, row.deletedAt)
? [{ index, type: row.type, measuredAt: row.measuredAt }]
? [
{
index,
type: row.type,
source: row.source,
measuredAt: row.measuredAt,
},
]
: [],
);
return coveredIndexes(client, userId, tz, candidates);
+4 -1
View File
@@ -389,6 +389,10 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
"vaccination.booster-invalid",
"vaccination.booster-no-antigen",
"vaccination.booster-out-of-scope",
"vaccination.custom-vaccine-not-found",
"vaccination.custom.invalid",
"vaccination.custom.name-taken",
"vaccination.custom.not-found",
"vaccination.encounter-not-found",
"vaccination.identity-required",
"vaccination.invalid",
@@ -419,7 +423,6 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
"modules_conflict",
"mood_tag_layout_conflict",
"not_configured",
"not_implemented",
"notification_prefs_conflict",
"oidc_only",
"private_origin_not_approved",
+1 -7
View File
@@ -9,12 +9,7 @@ import { z } from "zod/v4";
import type { ZodOpenApiObject } from "zod-openapi";
import { inviteCreateSchema } from "@/lib/validations/invite";
import { adminReminderCheckSchema } from "@/lib/validations/notifications";
import {
dataEnvelope,
errorEnvelope,
notImplementedResponse,
stdResponses,
} from "./shared";
import { dataEnvelope, errorEnvelope, stdResponses } from "./shared";
// v1.4.48 H-APNs-1 — admin diagnostic endpoint for the notification
// subsystem. Mirrors the runtime types in
@@ -371,7 +366,6 @@ export const adminDiagnosticPaths: NonNullable<ZodOpenApiObject["paths"]> = {
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
...notImplementedResponse,
},
},
},
-15
View File
@@ -269,21 +269,6 @@ export const malformedJsonResponse = {
},
};
/**
* The 501 a route answers while its contract is published ahead of its
* implementation on a release branch. Every stub carries it; the owner of the
* route drops it with the stub. No tagged release answers it: the error-code
* catalogue check fails once `not_implemented` is listed and nothing emits
* it, and fails while something still does and it is not listed.
*/
export const notImplementedResponse = {
"501": {
description:
"Not implemented yet: the contract is published ahead of the implementation on a release branch. `meta.errorCode: not_implemented`.",
content: { "application/json": { schema: errorEnvelope } },
},
} as const;
// ── Standard 401 / 422 / 429 responses ───────────────────────────────
export const stdResponses = {
+79 -56
View File
@@ -29,6 +29,8 @@ import {
vaccinationSiteEnum,
vaccinationBoosterSchema,
vaccinationSuggestQuerySchema,
customVaccineCreateSchema,
customVaccineUpdateSchema,
} from "@/lib/validations/vaccinations";
import { measurementReminderDto } from "@/lib/validations/measurement-reminders";
@@ -37,7 +39,6 @@ import {
errorEnvelope,
idempotencyKeyParameter,
idempotentWrite,
notImplementedResponse,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
@@ -49,13 +50,13 @@ import {
const createVaccinationRequest = vaccinationCreateSchema.meta({
id: "CreateVaccinationRequest",
description:
"Log one administered dose. `occurredAt` is required and must not be in the future — a vaccination is recorded after the fact, and a planned booster is a reminder rather than a record. Exactly one identity arm is required: either `antigenSlug` (a slug the catalogue offers) or `vaccineName` (whatever the person's own record says, verbatim, which may be a trade name). Everything else is optional, so a decades-old paper entry with nothing but a date and a name is loggable. `note` is encrypted at rest. `documentIds` pre-links the scanned pages; an id naming nothing the caller owns is dropped rather than refused, so a link never blocks a save. Logging a dose satisfies any booster reminder keyed to one of its component antigens.",
"Log one administered dose. `occurredAt` is required and must not be in the future — a vaccination is recorded after the fact, and a planned booster is a reminder rather than a record. At least one identity arm is required: `antigenSlug` (a slug the catalogue offers), `customVaccineId` (one of the record's own vaccine definitions, see `/api/vaccinations/custom`; an id the record does not hold live is a 404 `vaccination.custom-vaccine-not-found`) or `vaccineName` (whatever the person's own record says, verbatim, which may be a trade name). When both a slug and a definition are given, the catalogue is the answer. Everything else is optional, so a decades-old paper entry with nothing but a date and a name is loggable. `note` is encrypted at rest. `documentIds` pre-links the scanned pages; an id naming nothing the caller owns is dropped rather than refused, so a link never blocks a save. Logging a dose satisfies any booster reminder keyed to one of its component antigens, the antigens of an own definition included.",
});
const updateVaccinationRequest = vaccinationUpdateSchema.meta({
id: "UpdateVaccinationRequest",
description:
"Partial edit of a dose; an omitted key leaves the column untouched, and a body naming nothing is a 422. `occurredAt` is editable because a transcription typo is the common case — and editing it deliberately does NOT re-run the booster satisfaction, so correcting a date can never move a reminder's due date. An edit that would leave the record with neither identity arm is refused. A present `documentIds` array replaces the links, empty array included.",
"Partial edit of a dose; an omitted key leaves the column untouched, and a body naming nothing is a 422. `occurredAt` is editable because a transcription typo is the common case — and editing it deliberately does NOT re-run the booster satisfaction, so correcting a date can never move a reminder's due date. An edit that would leave the record with no identity arm (slug, own definition or name) is refused. `customVaccineId: null` unlinks the dose from its own definition. A present `documentIds` array replaces the links, empty array included.",
});
const listVaccinationsQuery = vaccinationListQuerySchema.meta({
@@ -150,6 +151,55 @@ const practitioner = z
"The practice that administered the dose, resolved rather than an id. Null when the record names none.",
});
// v1.42 (#1005) — the record's own vaccine definitions.
const customVaccine = z
.object({
id: z.string(),
name: z.string(),
components: z
.array(z.string())
.describe(
"Catalogue antigen slugs the product protects against, only ones this release knows.",
),
typicalSeriesDoses: z.number().int().nullable(),
boosterIntervalMonths: z.number().int().nullable(),
createdAt: z.iso.datetime({ offset: true }),
updatedAt: z.iso.datetime({ offset: true }),
})
.meta({
id: "CustomVaccine",
description:
"A vaccine the record's owner defined for a product the shipped catalogue does not list, in the shape a catalogue entry resolves to. A dose logged against it counts into the series of each listed antigen, settles a booster reminder keyed to one of them and offers one from `boosterIntervalMonths`, exactly as a catalogue pick does. `name` is the person's own wording.",
});
const customVaccineCreateRequest = customVaccineCreateSchema.meta({
id: "CreateCustomVaccineRequest",
description:
"A new definition. `components` lists one to all of the catalogue's antigen slugs, each once — a disease outside that list is logged as a free-text dose instead. `typicalSeriesDoses` (1–10) and `boosterIntervalMonths` (1–600) are optional; the interval prefills the booster offer after a dose.",
});
const customVaccineUpdateRequest = customVaccineUpdateSchema.meta({
id: "UpdateCustomVaccineRequest",
description:
"Partial edit; an omitted key is left untouched and an empty body is a 422. The change applies to every dose logged against the definition, because the series is derived on read; it never re-runs booster satisfaction.",
});
const customVaccineNotFound = {
"404": {
description:
"No live definition with this id on the record (`vaccination.custom.not-found`).",
content: { "application/json": { schema: errorEnvelope } },
},
} as const;
const customVaccineNameTaken = {
"409": {
description:
"A live definition on the record already carries this name, compared without case (`vaccination.custom.name-taken`).",
content: { "application/json": { schema: errorEnvelope } },
},
} as const;
const vaccination = z
.object({
id: z.string(),
@@ -161,6 +211,14 @@ const vaccination = z
lotNumber: z.string().nullable(),
site: vaccinationSiteEnum.nullable(),
catalogEntry: catalogEntry.nullable(),
customVaccineId: z.string().nullable().meta({
description:
"The record's own vaccine definition the dose names (v1.42), verbatim.",
}),
customVaccine: customVaccine.nullable().meta({
description:
"That definition, resolved, or null when the dose names none or it was removed. When `catalogEntry` is also set, the catalogue is the answer.",
}),
series: z.array(seriesPosition),
practitioner: practitioner.nullable(),
encounter: vaccinationEncounter.nullable(),
@@ -244,43 +302,15 @@ const vaccinationNotFound = {
const idPath = { path: z.object({ id: z.string() }) };
// v1.42 (#1005) — the record's own vaccine definitions.
const customVaccine = z
.object({
id: z.string(),
name: z.string(),
components: z
.array(z.string())
.describe("Catalogue antigen slugs the product covers."),
typicalSeriesDoses: z.number().int().nullable(),
boosterIntervalMonths: z.number().int().nullable(),
createdAt: z.iso.datetime({ offset: true }),
updatedAt: z.iso.datetime({ offset: true }),
})
.meta({ id: "CustomVaccine" });
const customVaccineCreateRequest = z
.object({
name: z.string(),
components: z.array(z.string()),
typicalSeriesDoses: z.number().int().nullable().optional(),
boosterIntervalMonths: z.number().int().nullable().optional(),
})
.strict()
.meta({ id: "CreateCustomVaccineRequest" });
const customVaccineUpdateRequest = customVaccineCreateRequest
.partial()
.meta({ id: "UpdateCustomVaccineRequest" });
export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/vaccinations/custom": {
get: {
tags: ["Records"],
summary: "List the record's own vaccines",
description:
"Vaccine definitions the record's owner added for products the shipped catalogue does not list. Soft-deleted definitions are excluded.",
"The vaccine definitions the record's owner added for products the shipped catalogue does not list, by name. Removed definitions are excluded. Readable under a `profile` grant like the dose list.",
responses: {
...recordRefusal(),
"200": {
description: "The definitions, by name.",
content: {
@@ -293,19 +323,19 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...stdResponses,
...notImplementedResponse,
},
},
post: {
tags: ["Records"],
summary: "Add an own vaccine",
description:
"Defines a vaccine in the same shape a catalogue entry resolves to, so series and booster logic treat both alike. Names are unique per record.",
"Defines a vaccine in the same shape a catalogue entry resolves to, so the series and booster logic treat both alike. Names are unique per record, compared without case; adding a name the person removed earlier brings that definition back with the new values (its doses were let go on removal and stay so). Audits as `vaccination.custom.create`.",
requestBody: {
required: true,
content: { "application/json": { schema: customVaccineCreateRequest } },
},
responses: {
...recordRefusal(),
"201": {
description: "Created.",
content: {
@@ -317,13 +347,9 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"409": {
description: "A live definition with this name already exists.",
content: { "application/json": { schema: errorEnvelope } },
},
...customVaccineNameTaken,
...stdResponses,
...recordWriteRateLimitResponse,
...notImplementedResponse,
},
},
},
@@ -331,13 +357,15 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
patch: {
tags: ["Records"],
summary: "Edit an own vaccine",
description: "Changes one definition. Owner-scoped; an unknown id 404s.",
description:
"Changes one definition; every dose logged against it reads the change. Owner-scoped; an unknown or removed id 404s. Audits as `vaccination.custom.update`, naming a rename without quoting it.",
requestParams: idPath,
requestBody: {
required: true,
content: { "application/json": { schema: customVaccineUpdateRequest } },
},
responses: {
...recordRefusal(),
"200": {
description: "Updated.",
content: {
@@ -349,25 +377,19 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"404": {
description: "No such definition on this record.",
content: { "application/json": { schema: errorEnvelope } },
},
"409": {
description: "A live definition with this name already exists.",
content: { "application/json": { schema: errorEnvelope } },
},
...customVaccineNotFound,
...customVaccineNameTaken,
...stdResponses,
...notImplementedResponse,
},
},
delete: {
tags: ["Records"],
summary: "Remove an own vaccine",
description:
"Soft-deletes one definition. Doses logged against it stay, on their `vaccineName`.",
"Soft-deletes one definition and lets go of every dose that named it. A dose keeps a name: one without wording of its own takes the definition's name as its `vaccineName` first. Removing twice succeeds. Audits as `vaccination.custom.delete` with the number of doses let go.",
requestParams: idPath,
responses: {
...recordRefusal(),
"200": {
description: "Removed.",
content: {
@@ -379,12 +401,8 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"404": {
description: "No such definition on this record.",
content: { "application/json": { schema: errorEnvelope } },
},
...customVaccineNotFound,
...stdResponses,
...notImplementedResponse,
},
},
},
@@ -421,6 +439,11 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
responses: {
...idempotentWrite(),
...recordRefusal(),
"404": {
description:
"A practice, visit or own vaccine the body names is not the record's (`vaccination.practitioner-not-found`, `vaccination.encounter-not-found`, `vaccination.custom-vaccine-not-found`).",
content: { "application/json": { schema: errorEnvelope } },
},
"201": {
description: "Dose logged.",
content: {
+9
View File
@@ -52,4 +52,13 @@ export const vaccinationKeys = {
vaccinationRestore: () => ["vaccinations", "restore"] as const,
vaccinationBooster: () => ["vaccinations", "booster"] as const,
vaccinationLink: () => ["vaccinations", "link"] as const,
/**
* v1.42 (#1005) — the record's own vaccine definitions. Under the
* `["vaccinations"]` root on purpose: editing or removing a definition
* re-reads every dose that names it, and the root eviction repaints both.
*/
customVaccines: () => ["vaccinations", "custom"] as const,
customVaccineCreate: () => ["vaccinations", "custom", "create"] as const,
customVaccineUpdate: () => ["vaccinations", "custom", "update"] as const,
customVaccineDelete: () => ["vaccinations", "custom", "delete"] as const,
} as const;
+6
View File
@@ -78,6 +78,8 @@ export function recordActivityVerbLine(
return t("recordSharing.activityVerb.encounterVisitCreate", { name });
case "vaccination.record.create":
return t("recordSharing.activityVerb.vaccinationRecordCreate", { name });
case "vaccination.custom.create":
return t("recordSharing.activityVerb.customVaccineCreate", { name });
case "practitioner.contact.create":
return t("recordSharing.activityVerb.practitionerContactCreate", {
name,
@@ -218,6 +220,10 @@ export function recordActivityVerbLine(
return t("recordSharing.activityVerb.vaccinationRecordDelete", { name });
case "vaccination.record.restore":
return t("recordSharing.activityVerb.vaccinationRecordRestore", { name });
case "vaccination.custom.update":
return t("recordSharing.activityVerb.customVaccineUpdate", { name });
case "vaccination.custom.delete":
return t("recordSharing.activityVerb.customVaccineDelete", { name });
case "vaccination.booster.planned":
return t("recordSharing.activityVerb.vaccinationBoosterPlanned", {
name,
@@ -23,10 +23,10 @@ import {
ANTIGEN_SLUGS,
VACCINE_CATALOG,
VACCINE_CATALOG_SLUGS,
componentsForSlug,
resolveCatalogEntry,
type AntigenSlug,
} from "@/lib/vaccinations/vaccine-catalog";
import { componentsForDose } from "@/lib/vaccinations/resolve-vaccine-entry";
const MONOVALENT = new Set<string>(ANTIGEN_SLUGS);
@@ -193,8 +193,10 @@ describe("a slug the catalogue no longer knows degrades to the free text", () =>
it("matches no antigen at all rather than guessing from the name", () => {
// The consequence that matters: an unresolvable dose must not clear a
// booster reminder. No components means no match.
expect(componentsForSlug(ORPHANED_RECORD.antigenSlug)).toEqual([]);
expect(componentsForSlug(null)).toEqual([]);
expect(
componentsForDose({ antigenSlug: ORPHANED_RECORD.antigenSlug }),
).toEqual([]);
expect(componentsForDose({ antigenSlug: null })).toEqual([]);
});
it("still resolves a slug it does have, so the check above is not vacuous", () => {
@@ -0,0 +1,138 @@
/**
* v1.42 (#1005) — the one resolver every consumer asks, and what the
* person's own vaccine definitions do through it: count into each listed
* antigen's series, take their own series length, and lose all of that the
* moment the definition is removed, falling back to the dose's name.
*/
import { describe, expect, it } from "vitest";
import {
componentsForDose,
customLookupOf,
knownAntigens,
resolveVaccineEntry,
type CustomVaccineDefinition,
} from "@/lib/vaccinations/resolve-vaccine-entry";
import { deriveSeries } from "@/lib/vaccinations/series";
const MONTH_MS = 30 * 24 * 60 * 60 * 1000;
const monthsAgo = (months: number) => new Date(Date.now() - months * MONTH_MS);
const dtp: CustomVaccineDefinition = {
id: "cv-dtp",
name: "DTP from abroad",
components: ["diphtheria", "tetanus", "pertussis"],
typicalSeriesDoses: 3,
boosterIntervalMonths: 120,
};
const customs = customLookupOf([dtp]);
describe("resolveVaccineEntry", () => {
it("resolves a catalogue slug, with its citation", () => {
const entry = resolveVaccineEntry({ antigenSlug: "tdap" });
expect(entry?.kind).toBe("catalog");
expect(entry?.slug).toBe("tdap");
expect(entry?.source).not.toBeNull();
expect(entry?.components).toEqual(["tetanus", "diphtheria", "pertussis"]);
});
it("resolves the person's own definition in the same shape, uncited", () => {
const entry = resolveVaccineEntry({ customVaccineId: "cv-dtp" }, customs);
expect(entry).toMatchObject({
kind: "custom",
slug: null,
customVaccineId: "cv-dtp",
name: "DTP from abroad",
atc: null,
category: null,
source: null,
typicalSeriesDoses: 3,
boosterIntervalMonths: 120,
});
expect(entry?.components).toEqual(["diphtheria", "tetanus", "pertussis"]);
});
it("lets the catalogue win when a dose carries both", () => {
const entry = resolveVaccineEntry(
{ antigenSlug: "influenza", customVaccineId: "cv-dtp" },
customs,
);
expect(entry?.kind).toBe("catalog");
expect(entry?.components).toEqual(["influenza"]);
});
it("answers null for nothing it knows: no arm, a dead slug, an unknown or removed definition", () => {
expect(resolveVaccineEntry({})).toBeNull();
expect(resolveVaccineEntry({ antigenSlug: "no-such-slug" })).toBeNull();
expect(
resolveVaccineEntry({ customVaccineId: "cv-missing" }, customs),
).toBeNull();
expect(resolveVaccineEntry({ customVaccineId: "cv-dtp" })).toBeNull();
const removed = customLookupOf([{ ...dtp, deletedAt: new Date() }]);
expect(
resolveVaccineEntry({ customVaccineId: "cv-dtp" }, removed),
).toBeNull();
});
it("drops antigens the catalogue does not know, and duplicates, but keeps the rest", () => {
expect(
knownAntigens(["tetanus", "unicorn-pox", "tetanus", "rabies"]),
).toEqual(["tetanus", "rabies"]);
const odd = customLookupOf([
{ ...dtp, id: "cv-odd", components: ["unicorn-pox", "cholera"] },
]);
expect(componentsForDose({ customVaccineId: "cv-odd" }, odd)).toEqual([
"cholera",
]);
});
});
describe("a dose logged against an own definition, in the series", () => {
it("counts into each listed antigen, at that antigen's own position", () => {
const history = [
// Two catalogue tetanus doses first, then the DTP definition.
{
id: "t1",
occurredAt: monthsAgo(48),
antigenSlug: "tetanus",
doseNumber: null,
seriesDoses: null,
},
{
id: "t2",
occurredAt: monthsAgo(36),
antigenSlug: "tetanus",
doseNumber: null,
seriesDoses: null,
},
{
id: "own",
occurredAt: monthsAgo(12),
antigenSlug: null,
customVaccineId: "cv-dtp",
doseNumber: null,
seriesDoses: null,
},
];
const series = deriveSeries(history, customs).get("own");
expect(series).toEqual([
{ antigen: "diphtheria", position: 1, total: 3, booster: false },
{ antigen: "tetanus", position: 3, total: 3, booster: false },
{ antigen: "pertussis", position: 1, total: 3, booster: false },
]);
});
it("places nothing once the definition is gone from the lookup", () => {
const series = deriveSeries([
{
id: "own",
occurredAt: monthsAgo(1),
antigenSlug: null,
customVaccineId: "cv-dtp",
doseNumber: null,
seriesDoses: null,
},
]);
expect(series.get("own")).toEqual([]);
});
});
+19 -5
View File
@@ -28,7 +28,10 @@
import type { Prisma } from "@/generated/prisma/client";
import { computeReminderNextDueAt } from "@/lib/measurement-reminders/scheduling";
import { componentsForSlug } from "@/lib/vaccinations/vaccine-catalog";
import {
componentsForDose,
loadCustomVaccineLookup,
} from "@/lib/vaccinations/resolve-vaccine-entry";
/** What the confirm carries. All three are the user's edited-or-accepted values. */
export interface BoosterMintInput {
@@ -80,14 +83,25 @@ export async function mintOrReanchorBooster(
): Promise<BoosterMintResult> {
const record = await tx.vaccinationRecord.findFirst({
where: { id: input.vaccinationId, userId, deletedAt: null },
select: { id: true, antigenSlug: true, occurredAt: true },
select: {
id: true,
antigenSlug: true,
customVaccineId: true,
occurredAt: true,
},
});
if (!record) return { outcome: "unknown-record" };
// The reminder keys on the dose's PRIMARY component antigen — for a Tdap that
// is tetanus. A person who tracks the components separately can mint further
// reminders by hand; the offer covers the one the interval belongs to.
const [antigen] = componentsForSlug(record.antigenSlug);
// is tetanus, for the person's own definition the first antigen it lists. A
// person who tracks the components separately can mint further reminders by
// hand; the offer covers the one the interval belongs to.
const [antigen] = componentsForDose(
record,
record.customVaccineId
? await loadCustomVaccineLookup(tx, userId)
: undefined,
);
if (!antigen) return { outcome: "no-antigen" };
const notifyHour = input.notifyHour ?? 9;
+69
View File
@@ -0,0 +1,69 @@
/**
* What the custom-vaccine routes share (v1.42, #1005): the columns they
* publish, the name-clash probe and the removal.
*/
import type { Prisma } from "@/generated/prisma/client";
/** The columns a definition is published with. */
export const CUSTOM_VACCINE_SELECT = {
id: true,
name: true,
components: true,
typicalSeriesDoses: true,
boosterIntervalMonths: true,
createdAt: true,
updatedAt: true,
} as const satisfies Prisma.CustomVaccineSelect;
/**
* A live definition on the record whose name equals `name` ignoring case,
* other than `exceptId`. "Dukoral" and "dukoral" are one product to the
* person reading the picker, even though the unique index tells them apart.
*/
export async function findLiveNameClash(
tx: Prisma.TransactionClient,
userId: string,
name: string,
exceptId?: string,
): Promise<boolean> {
const clash = await tx.customVaccine.findFirst({
where: {
userId,
deletedAt: null,
name: { equals: name, mode: "insensitive" },
...(exceptId ? { id: { not: exceptId } } : {}),
},
select: { id: true },
});
return clash !== null;
}
/**
* Remove a definition and let go of every dose that named it.
*
* The definition is tombstoned; the doses are not touched beyond the link.
* A dose that carried no wording of its own takes the definition's name as
* its `vaccineName` first, so it keeps a name — the same thing the foreign
* key's `ON DELETE SET NULL` promises for a hard delete, done by hand because
* a tombstone does not fire it. Runs in the caller's transaction so the name
* and the unlink land together. Returns how many doses were unlinked.
*/
export async function removeCustomVaccine(
tx: Prisma.TransactionClient,
userId: string,
definition: { id: string; name: string },
): Promise<number> {
await tx.vaccinationRecord.updateMany({
where: { userId, customVaccineId: definition.id, vaccineName: null },
data: { vaccineName: definition.name },
});
const unlinked = await tx.vaccinationRecord.updateMany({
where: { userId, customVaccineId: definition.id },
data: { customVaccineId: null },
});
await tx.customVaccine.update({
where: { id: definition.id },
data: { deletedAt: new Date() },
});
return unlinked.count;
}
+8 -1
View File
@@ -89,6 +89,9 @@ export async function suggestVaccinationForDate(
occurredAt: true,
antigenSlug: true,
vaccineName: true,
// v1.42 (#1005) — a dose named only by the person's own definition is
// offered under that definition's name.
customVaccine: { select: { name: true, deletedAt: true } },
},
});
@@ -96,7 +99,11 @@ export async function suggestVaccinationForDate(
id: row.id,
occurredAt: row.occurredAt.toISOString(),
antigenSlug: row.antigenSlug,
vaccineName: row.vaccineName,
vaccineName:
row.vaccineName ??
(row.customVaccine && row.customVaccine.deletedAt === null
? row.customVaccine.name
: null),
}));
if (vaccinations.length === 0) return { kind: "none" };
+61 -5
View File
@@ -19,6 +19,7 @@
import { decryptFromBytes } from "@/lib/ai/coach/bytes-codec";
import { getEvent } from "@/lib/logging/context";
import type {
CustomVaccine,
Encounter,
Practitioner,
VaccinationRecord,
@@ -28,7 +29,10 @@ import {
toPractitionerDTO,
type PractitionerDTO,
} from "@/lib/practitioners/dto";
import { resolveCatalogEntry } from "@/lib/vaccinations/vaccine-catalog";
import {
knownAntigens,
resolveVaccineEntry,
} from "@/lib/vaccinations/resolve-vaccine-entry";
import type { SeriesPosition } from "@/lib/vaccinations/series";
import type { VaccinationRenewalDTO } from "@/lib/vaccinations/renewal";
@@ -56,6 +60,43 @@ export interface VaccinationCatalogDTO {
category: string;
}
/**
* One of the record's own vaccine definitions (v1.42, #1005). `components`
* lists only antigens the catalogue knows, so a client can name each one.
*/
export interface CustomVaccineDTO {
id: string;
name: string;
components: string[];
typicalSeriesDoses: number | null;
boosterIntervalMonths: number | null;
createdAt: string;
updatedAt: string;
}
export type CustomVaccineRow = Pick<
CustomVaccine,
| "id"
| "name"
| "components"
| "typicalSeriesDoses"
| "boosterIntervalMonths"
| "createdAt"
| "updatedAt"
>;
export function toCustomVaccineDTO(row: CustomVaccineRow): CustomVaccineDTO {
return {
id: row.id,
name: row.name,
components: knownAntigens(row.components),
typicalSeriesDoses: row.typicalSeriesDoses,
boosterIntervalMonths: row.boosterIntervalMonths,
createdAt: row.createdAt.toISOString(),
updatedAt: row.updatedAt.toISOString(),
};
}
/** The visit this dose was given at, enough to recognise it by. */
export interface VaccinationEncounterDTO {
id: string;
@@ -80,6 +121,13 @@ export interface VaccinationDTO {
* not know the slug. Null is the signal to render `vaccineName` instead.
*/
catalogEntry: VaccinationCatalogDTO | null;
/** The person's own definition the dose names, verbatim. */
customVaccineId: string | null;
/**
* That definition, resolved, or `null` when the dose names none or it was
* removed. When `catalogEntry` is also set, the catalogue is the answer.
*/
customVaccine: CustomVaccineDTO | null;
/**
* Where this dose sits in each of its antigen series, resolved server-side.
*
@@ -123,6 +171,7 @@ function decryptNote(value: Uint8Array | null): string | null {
export type VaccinationWithRelations = VaccinationRecord & {
practitioner?: Practitioner | null;
encounter?: Pick<Encounter, "id" | "occurredAt" | "kind"> | null;
customVaccine?: (CustomVaccineRow & Pick<CustomVaccine, "deletedAt">) | null;
};
export function toVaccinationDTO(
@@ -130,7 +179,11 @@ export function toVaccinationDTO(
series: SeriesPosition[],
documents?: VaccinationDocumentDTO[],
): VaccinationDTO {
const entry = resolveCatalogEntry(row.antigenSlug);
const custom =
row.customVaccine && row.customVaccine.deletedAt === null
? row.customVaccine
: null;
const entry = resolveVaccineEntry({ antigenSlug: row.antigenSlug });
return {
id: row.id,
occurredAt: row.occurredAt.toISOString(),
@@ -140,9 +193,12 @@ export function toVaccinationDTO(
seriesDoses: row.seriesDoses,
lotNumber: row.lotNumber,
site: row.site,
catalogEntry: entry
? { slug: entry.slug, atc: entry.atc, category: entry.category }
: null,
catalogEntry:
entry?.slug && entry.atc && entry.category
? { slug: entry.slug, atc: entry.atc, category: entry.category }
: null,
customVaccineId: row.customVaccineId,
customVaccine: custom ? toCustomVaccineDTO(custom) : null,
series,
practitioner: row.practitioner ? toPractitionerDTO(row.practitioner) : null,
encounter: row.encounter
@@ -0,0 +1,191 @@
/**
* The one answer to "what was this dose", catalogue or the person's own.
*
* Since v1.42 (#1005) a dose can name a vaccine the shipped catalogue does
* not list: the person defines it once (`CustomVaccine`: a name, the
* antigens it protects against, a series length, a booster interval) and
* logs doses against it. Every consumer that used to ask the catalogue —
* the series derivation, the booster satisfy matcher, the booster mint, the
* DTO, the doctor report, the document links, MCP search, the picker's info
* sentences and the booster offer — asks this module instead, so a custom
* vaccine counts into a series, clears a booster and offers one exactly the
* way a catalogue entry does.
*
* ── Precedence ─────────────────────────────────────────────────────────────
*
* The catalogue wins when both resolve. A catalogue slug is the shipped,
* sourced answer; a definition is the person's own. A dose carries one or
* the other in practice, and the rule only decides the rare row that
* carries both (an edit that picked a catalogue entry without clearing the
* definition).
*
* A definition that is soft-deleted does not resolve, and neither does an
* antigen it lists that the catalogue does not know: storage is tolerant (a
* restore writes what the file held), the answer is not. A dose with nothing
* that resolves falls back to its `vaccineName`, the same degrade a dead
* catalogue slug has always had.
*
* Pure apart from {@link loadCustomVaccineLookup}, which takes the client it
* reads through, so the client components can import the resolver itself.
*/
import type { Prisma } from "@/generated/prisma/client";
import {
ANTIGEN_SLUGS,
resolveCatalogEntry,
type AntigenSlug,
type VaccineCategory,
} from "@/lib/vaccinations/vaccine-catalog";
/** A definition as the resolver reads it. */
export interface CustomVaccineDefinition {
id: string;
name: string;
components: readonly string[];
typicalSeriesDoses: number | null;
boosterIntervalMonths: number | null;
/** Absent on a DTO, which only ever carries live definitions. */
deletedAt?: Date | null;
}
/** The record's definitions, by id. */
export type CustomVaccineLookup = ReadonlyMap<string, CustomVaccineDefinition>;
/** The fields of a dose the resolver reads. */
export interface VaccineIdentity {
antigenSlug?: string | null;
customVaccineId?: string | null;
}
/** The resolved entry, in the shape a catalogue seed has. */
export interface ResolvedVaccineEntry {
kind: "catalog" | "custom";
/** The catalogue slug, or null for a definition. */
slug: string | null;
/** The definition's id, or null for a catalogue entry. */
customVaccineId: string | null;
/**
* The definition's own name. Null for a catalogue entry, whose name
* resolves through i18n (`vaccinations.catalog.<slug>`).
*/
name: string | null;
/** WHO ATC code; a definition has none. */
atc: string | null;
/** The antigens a dose counts into. */
components: readonly AntigenSlug[];
typicalSeriesDoses: number | null;
boosterIntervalMonths: number | null;
/** Picker grouping; a definition has none. */
category: VaccineCategory | null;
/** The citation for the numbers; a definition is the person's, not cited. */
source: string | null;
/** Generic search aliases; a definition has its name and nothing else. */
synonyms: readonly string[];
}
const KNOWN_ANTIGENS: ReadonlySet<string> = new Set(ANTIGEN_SLUGS);
/** The listed antigens the catalogue knows, deduplicated, in stored order. */
export function knownAntigens(raw: readonly string[]): AntigenSlug[] {
const seen = new Set<string>();
const out: AntigenSlug[] = [];
for (const value of raw) {
if (!KNOWN_ANTIGENS.has(value) || seen.has(value)) continue;
seen.add(value);
out.push(value as AntigenSlug);
}
return out;
}
/**
* Resolve a dose to its entry, catalogue first. Null when neither arm
* resolves — the caller then falls back to the dose's `vaccineName`.
*/
export function resolveVaccineEntry(
record: VaccineIdentity,
customs?: CustomVaccineLookup,
): ResolvedVaccineEntry | null {
const catalog = resolveCatalogEntry(record.antigenSlug);
if (catalog) {
return {
kind: "catalog",
slug: catalog.slug,
customVaccineId: null,
name: null,
atc: catalog.atc,
components: catalog.components,
typicalSeriesDoses: catalog.typicalSeriesDoses,
boosterIntervalMonths: catalog.boosterIntervalMonths,
category: catalog.category,
source: catalog.source,
synonyms: catalog.synonyms ?? [],
};
}
if (!record.customVaccineId || !customs) return null;
const custom = customs.get(record.customVaccineId);
if (!custom || custom.deletedAt) return null;
return {
kind: "custom",
slug: null,
customVaccineId: custom.id,
name: custom.name,
atc: null,
components: knownAntigens(custom.components),
typicalSeriesDoses: custom.typicalSeriesDoses,
boosterIntervalMonths: custom.boosterIntervalMonths,
category: null,
source: null,
synonyms: [],
};
}
/**
* The antigens a dose counts into. Empty for a free-text-only dose and for
* one whose arms no longer resolve: a name string is not evidence about
* which antigens were given, and guessing from one is how a booster reminder
* would be cleared by a dose that never contained it.
*/
export function componentsForDose(
record: VaccineIdentity,
customs?: CustomVaccineLookup,
): readonly AntigenSlug[] {
return resolveVaccineEntry(record, customs)?.components ?? [];
}
/** A lookup over the definitions a list of rows carries. */
export function customLookupOf(
definitions: ReadonlyArray<CustomVaccineDefinition | null | undefined>,
): CustomVaccineLookup {
const map = new Map<string, CustomVaccineDefinition>();
for (const definition of definitions) {
if (definition) map.set(definition.id, definition);
}
return map;
}
/** The columns a definition is resolved from. */
export const CUSTOM_VACCINE_RESOLVE_SELECT = {
id: true,
name: true,
components: true,
typicalSeriesDoses: true,
boosterIntervalMonths: true,
deletedAt: true,
createdAt: true,
updatedAt: true,
} as const satisfies Prisma.CustomVaccineSelect;
/**
* The record's live definitions, by id. An Impfpass names a handful at most,
* so the whole set is read rather than the ids a page happens to need.
*/
export async function loadCustomVaccineLookup(
client: Pick<Prisma.TransactionClient, "customVaccine">,
userId: string,
): Promise<CustomVaccineLookup> {
const rows = await client.customVaccine.findMany({
where: { userId, deletedAt: null },
select: CUSTOM_VACCINE_RESOLVE_SELECT,
});
return customLookupOf(rows);
}
+15 -4
View File
@@ -21,7 +21,9 @@
*
* A free-text-only dose matches nothing. Nothing here reads `vaccineName`: a
* name string is not evidence about which antigens were in the syringe, and a
* booster cleared by a guess is worse than a booster not cleared at all.
* booster cleared by a guess is worse than a booster not cleared at all. A
* dose logged against the person's own vaccine definition (v1.42, #1005)
* counts its listed antigens, the same way a catalogue combination does.
*
* ── Cold path only ─────────────────────────────────────────────────────────
*
@@ -50,7 +52,11 @@ import {
satisfyReminder,
type SatisfiableReminder,
} from "@/lib/measurement-reminders/satisfy";
import { componentsForSlug } from "@/lib/vaccinations/vaccine-catalog";
import {
componentsForDose,
loadCustomVaccineLookup,
type VaccineIdentity,
} from "@/lib/vaccinations/resolve-vaccine-entry";
/** What the create route needs back: which reminders moved, and the first. */
export interface BoosterSatisfyResult {
@@ -82,11 +88,16 @@ const EMPTY: BoosterSatisfyResult = {
export async function satisfyBoostersForDose(
tx: Prisma.TransactionClient,
userId: string,
antigenSlug: string | null,
identity: VaccineIdentity,
occurredAt: Date,
timezone: string,
): Promise<BoosterSatisfyResult> {
const components = componentsForSlug(antigenSlug);
const components = componentsForDose(
identity,
identity.customVaccineId
? await loadCustomVaccineLookup(tx, userId)
: undefined,
);
if (components.length === 0) return EMPTY;
const reminders = await tx.measurementReminder.findMany({
+17 -11
View File
@@ -28,11 +28,11 @@
* medical-device boundary starts, and it is a separate venture's territory.
* What this function reports is arithmetic on what a person wrote down.
*/
import type { AntigenSlug } from "@/lib/vaccinations/vaccine-catalog";
import {
componentsForSlug,
resolveCatalogEntry,
type AntigenSlug,
} from "@/lib/vaccinations/vaccine-catalog";
resolveVaccineEntry,
type CustomVaccineLookup,
} from "@/lib/vaccinations/resolve-vaccine-entry";
/** One antigen's view of one dose. */
export interface SeriesPosition {
@@ -46,7 +46,8 @@ export interface SeriesPosition {
position: number;
/**
* How long the series is: the record's own override first, then the
* catalogue's typical value, then null when neither knows. Null is honest —
* catalogue's (or the person's own definition's) typical value, then null
* when neither knows. Null is honest —
* a seasonal vaccine has no "of M".
*/
total: number | null;
@@ -62,6 +63,8 @@ export interface SeriesInputRecord {
id: string;
occurredAt: Date;
antigenSlug: string | null;
/** The person's own definition (v1.42, #1005), resolved after the slug. */
customVaccineId?: string | null;
doseNumber: number | null;
seriesDoses: number | null;
}
@@ -80,6 +83,7 @@ export interface SeriesInputRecord {
*/
export function deriveSeries(
records: readonly SeriesInputRecord[],
customs?: CustomVaccineLookup,
): Map<string, SeriesPosition[]> {
const result = new Map<string, SeriesPosition[]>();
for (const record of records) result.set(record.id, []);
@@ -97,13 +101,14 @@ export function deriveSeries(
for (const record of chronological) {
// A free-text-only record — and a record whose slug the catalogue no
// longer resolves — yields nothing. Guessing an antigen from a name string
// is how a booster gets cleared by a dose that never contained it.
const components = componentsForSlug(record.antigenSlug);
// longer resolves, or whose own definition was removed — yields nothing.
// Guessing an antigen from a name string is how a booster gets cleared by
// a dose that never contained it.
const entry = resolveVaccineEntry(record, customs);
const components = entry?.components ?? [];
if (components.length === 0) continue;
const catalogTotal =
resolveCatalogEntry(record.antigenSlug)?.typicalSeriesDoses ?? null;
const catalogTotal = entry?.typicalSeriesDoses ?? null;
// The record's own override wins: it is what the person's actual schedule
// was, and the catalogue only knows the typical one.
const total = record.seriesDoses ?? catalogTotal;
@@ -140,6 +145,7 @@ export function deriveSeries(
export function seriesForRecord(
recordId: string,
history: readonly SeriesInputRecord[],
customs?: CustomVaccineLookup,
): SeriesPosition[] {
return deriveSeries(history).get(recordId) ?? [];
return deriveSeries(history, customs).get(recordId) ?? [];
}
+30 -2
View File
@@ -17,6 +17,10 @@ import {
deriveSeries,
type SeriesInputRecord,
} from "@/lib/vaccinations/series";
import {
CUSTOM_VACCINE_RESOLVE_SELECT,
loadCustomVaccineLookup,
} from "@/lib/vaccinations/resolve-vaccine-entry";
import { DEFAULT_TIMEZONE } from "@/lib/tz/format";
/** Matches the visits service: the fallback when an account never set one. */
@@ -25,6 +29,9 @@ import { DEFAULT_TIMEZONE } from "@/lib/tz/format";
export const VACCINATION_INCLUDE = {
practitioner: true,
encounter: { select: { id: true, occurredAt: true, kind: true } },
// v1.42 (#1005) — the person's own definition, resolved onto the DTO so no
// client needs a second read to name the dose or count its antigens.
customVaccine: { select: CUSTOM_VACCINE_RESOLVE_SELECT },
} as const satisfies Prisma.VaccinationRecordInclude;
/** What the series derivation needs, and nothing more. */
@@ -32,6 +39,7 @@ export const SERIES_SELECT = {
id: true,
occurredAt: true,
antigenSlug: true,
customVaccineId: true,
doseNumber: true,
seriesDoses: true,
} as const satisfies Prisma.VaccinationRecordSelect;
@@ -56,12 +64,20 @@ export async function loadSeriesHistory(
});
}
/** Every record's resolved series positions, keyed by record id. */
/**
* Every record's resolved series positions, keyed by record id. The record's
* own vaccine definitions are read beside the history, so a dose logged
* against one counts into the antigens it lists.
*/
export async function resolveSeriesFor(
tx: Prisma.TransactionClient,
userId: string,
) {
return deriveSeries(await loadSeriesHistory(tx, userId));
const [history, customs] = await Promise.all([
loadSeriesHistory(tx, userId),
loadCustomVaccineLookup(tx, userId),
]);
return deriveSeries(history, customs);
}
/**
@@ -152,6 +168,18 @@ export async function resolveOwnerTimezone(userId: string): Promise<string> {
return row?.timezone || DEFAULT_TIMEZONE;
}
/** Does the record own a live vaccine definition with this id? */
export async function resolveOwnedCustomVaccine(
tx: Prisma.TransactionClient,
userId: string,
customVaccineId: string,
): Promise<{ id: string } | null> {
return tx.customVaccine.findFirst({
where: { id: customVaccineId, userId, deletedAt: null },
select: { id: true },
});
}
/** Does the caller own a live visit with this id? */
export async function resolveOwnedEncounter(
tx: Prisma.TransactionClient,
+5 -15
View File
@@ -28,8 +28,11 @@
* A record stores `antigenSlug` verbatim, backups restore it without
* validation, and a slug this file has stopped listing must still describe
* what someone was given. {@link resolveCatalogEntry} is the ONLY lookup path
* and it returns `null` rather than throwing; every consumer answers `null` by
* falling back to the record's own `vaccineName`. That degrade is a tested
* into this file and it returns `null` rather than throwing. Consumers do not
* call it directly: since v1.42 (#1005) they ask
* `src/lib/vaccinations/resolve-vaccine-entry.ts`, which tries the catalogue
* first and the person's own vaccine definitions second, and every consumer
* answers `null` by falling back to the record's own `vaccineName`. That degrade is a tested
* guarantee, not an accident — see
* `src/lib/vaccinations/__tests__/catalog-integrity.test.ts`.
*
@@ -546,16 +549,3 @@ export function resolveCatalogEntry(
if (!slug) return null;
return BY_SLUG.get(slug) ?? null;
}
/**
* The antigens a dose with this slug counts into.
*
* Empty for an unknown slug and for a free-text-only record: a name string is
* not evidence about which antigens were given, and guessing from one is how
* a booster reminder would be cleared by a dose that never contained it.
*/
export function componentsForSlug(
slug: string | null | undefined,
): readonly AntigenSlug[] {
return resolveCatalogEntry(slug)?.components ?? [];
}
@@ -183,13 +183,23 @@ describe("an edit names what it changes", () => {
).toBe(true);
});
it("refuses an edit that clears both identity arms at once", () => {
it("refuses an edit that clears every identity arm at once", () => {
expect(
vaccinationUpdateSchema.safeParse({
antigenSlug: null,
vaccineName: null,
customVaccineId: null,
}).success,
).toBe(false);
});
it("leaves clearing the slug and the name to the merged-row check, because an own vaccine may remain", () => {
expect(
vaccinationUpdateSchema.safeParse({
antigenSlug: null,
vaccineName: null,
}).success,
).toBe(false);
).toBe(true);
});
it("allows clearing one arm, because the other may still be there", () => {
+3
View File
@@ -85,6 +85,8 @@ export interface BackupSummary {
vaccinations: number;
/** v1.37.19 (A6-8) — vaccination↔document links. */
vaccinationLinks: number;
/** v1.42 (#1005) — the person's own vaccine definitions. */
customVaccines: number;
/** v1.37.20 (#223 / iOS #68) — Vorsorge reminder cadences. */
measurementReminders: number;
/** v1.37.20 (#223 / iOS #68) — completion-ledger rows across every reminder. */
@@ -176,6 +178,7 @@ export function summarizeBackup(payload: BackupPayload): BackupSummary {
payload.encounterConditionLinks.length,
vaccinations: payload.vaccinations.length,
vaccinationLinks: payload.vaccinationDocumentLinks.length,
customVaccines: payload.customVaccines.length,
// v1.37.20 (#223 / iOS #68) — counted from the release that carries them,
// so the admin's "what did I just restore" answer never under-counts a
// file with reminders the way it once did for visits.
+21
View File
@@ -1311,6 +1311,24 @@ const vaccinationBackupSchema = z
})
.passthrough();
/**
* One of the person's own vaccine definitions (v1.42, #1005). `components`
* is a list of free strings rather than the antigen enum, for the reason
* `antigenSlug` is: a file the app wrote must restore.
*/
const customVaccineBackupSchema = z
.object({
id: z.string().min(1),
name: z.string().min(1),
components: z.array(z.string()).optional(),
typicalSeriesDoses: z.number().int().nullable().optional(),
boosterIntervalMonths: z.number().int().nullable().optional(),
createdAt: isoDateTime,
updatedAt: isoDateTime,
deletedAt: isoDateTime.nullable().optional(),
})
.passthrough();
const vaccinationLinkBackupSchema = z
.object({
vaccinationId: z.string().min(1),
@@ -2081,6 +2099,9 @@ export const backupPayloadSchema = z
// for the same reason as the sections above: a file written before the
// tables existed carries no key, and an account with an empty Impfpass
// writes [].
// v1.42 (#1005) — defaulted: a file written before definitions
// travelled carries no key, and its doses name none.
customVaccines: z.array(customVaccineBackupSchema).default([]),
vaccinations: z.array(vaccinationBackupSchema).default([]),
vaccinationDocumentLinks: z.array(vaccinationLinkBackupSchema).default([]),
// The Vorsorge reminders and their completion ledger (v1.37.20, #223 /
+66 -6
View File
@@ -25,7 +25,10 @@
*/
import { z } from "zod/v4";
import { VACCINE_CATALOG_SLUGS } from "@/lib/vaccinations/vaccine-catalog";
import {
ANTIGEN_SLUGS,
VACCINE_CATALOG_SLUGS,
} from "@/lib/vaccinations/vaccine-catalog";
const KNOWN_SLUGS: ReadonlySet<string> = new Set(VACCINE_CATALOG_SLUGS);
@@ -99,7 +102,7 @@ const linkIds = z.array(id).max(100).optional();
* rather than leaving the person guessing which of the two the server meant.
*/
const IDENTITY_MESSAGE =
"name the vaccine: pick one from the catalogue or type what the record says";
"name the vaccine: pick one from the catalogue or your own vaccines, or type what the record says";
export const vaccinationCreateSchema = z
.object({
@@ -114,13 +117,18 @@ export const vaccinationCreateSchema = z
site: vaccinationSiteEnum.nullable().optional(),
practitionerId: id.nullable().optional(),
encounterId: id.nullable().optional(),
/**
* v1.42 (#1005) — one of the record's own vaccine definitions, the third
* identity arm. Re-narrowed to the resolved record in the route.
*/
customVaccineId: id.nullable().optional(),
/** Becomes `noteEncrypted`. Impfreaktionen live here. */
note: z.string().max(2000).nullable().optional(),
documentIds: linkIds,
})
.strict()
.superRefine((body, ctx) => {
if (body.antigenSlug || body.vaccineName) return;
if (body.antigenSlug || body.vaccineName || body.customVaccineId) return;
for (const path of ["antigenSlug", "vaccineName"] as const) {
ctx.addIssue({ code: "custom", path: [path], message: IDENTITY_MESSAGE });
}
@@ -151,6 +159,7 @@ export const vaccinationUpdateSchema = z
site: vaccinationSiteEnum.nullable().optional(),
practitionerId: id.nullable().optional(),
encounterId: id.nullable().optional(),
customVaccineId: id.nullable().optional(),
note: z.string().max(2000).nullable().optional(),
documentIds: linkIds,
})
@@ -160,9 +169,13 @@ export const vaccinationUpdateSchema = z
})
.refine(
(body) =>
// Only when the edit clears BOTH arms in one call. Clearing one while
// the other stays is legal and the route checks the merged row.
!(body.antigenSlug === null && body.vaccineName === null),
// Only when the edit clears EVERY arm in one call. Clearing one while
// another stays is legal and the route checks the merged row.
!(
body.antigenSlug === null &&
body.vaccineName === null &&
body.customVaccineId === null
),
{ path: ["antigenSlug"], message: IDENTITY_MESSAGE },
);
@@ -190,6 +203,53 @@ export const vaccinationListQuerySchema = z
export type VaccinationListQuery = z.infer<typeof vaccinationListQuerySchema>;
/* ── the record's own vaccines (v1.42, #1005) ─────────────────────── */
/**
* The antigens a definition protects against: only from the catalogue's
* closed antigen list, because the series derivation and the booster match
* both key on those slugs. A disease the list does not carry is a free-text
* dose, not a definition.
*/
export const customVaccineComponentsSchema = z
.array(z.enum(ANTIGEN_SLUGS))
.min(1)
.max(ANTIGEN_SLUGS.length)
.refine((list) => new Set(list).size === list.length, {
message: "name each antigen once",
});
/** The definition's name: what the person calls the product. */
const customVaccineName = z.string().trim().min(1).max(100);
export const customVaccineCreateSchema = z
.object({
name: customVaccineName,
components: customVaccineComponentsSchema,
typicalSeriesDoses: z.number().int().min(1).max(10).nullable().optional(),
/** Months; a decade booster is 120, bounded like the booster confirm. */
boosterIntervalMonths: z
.number()
.int()
.min(1)
.max(600)
.nullable()
.optional(),
})
.strict();
export type CustomVaccineCreate = z.infer<typeof customVaccineCreateSchema>;
/** Edit a definition; an omitted field is left untouched, an empty body 422s. */
export const customVaccineUpdateSchema = customVaccineCreateSchema
.partial()
.strict()
.refine((body) => Object.keys(body).length > 0, {
message: "name at least one field to change",
});
export type CustomVaccineUpdate = z.infer<typeof customVaccineUpdateSchema>;
/* ── links ────────────────────────────────────────────────────────── */
/**