refactor(rollups): move medication-compliance-rollups under the umbrella

- src/lib/medications/compliance-rollups.ts → src/lib/rollups/medication-compliance-rollups.ts
- co-located test follows the source file

10 importers updated covering the dashboard summary, every intake CRUD
route (single + bulk + import + Telegram webhook), the ingest endpoint,
the admin backups restore path, and the reminder worker job.

Closes the rollup umbrella restructure — every persistent-rollup
producer + reader now lives under src/lib/rollups/. Pure relocation
across all five batches: zero behaviour or exported-surface change.
This commit is contained in:
Marc-André Bombeck committed 2026-05-21 12:22:48 +02:00
1 parent 63e56f7a2d
commit cc08a43e37
12 files changed
+11 -11

No files matched your search

@@ -0,0 +1,475 @@
/**
* v1.4.39 W-MED — unit tests for the medication-compliance rollup tier.
*
* `prisma` is mocked at the module boundary so the test can pin the
* intake-event fan-out + the rollup upsert / read shape without
* standing up a real Postgres. Integration coverage (real Postgres +
* the FK cascade behaviour) lives next to the route test suite when
* the W-MED phase grows them; this file proves the helpers'
* contract.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
intakeFindMany: vi.fn(),
rollupUpsert: vi.fn(),
rollupDeleteMany: vi.fn(),
rollupFindMany: vi.fn(),
rollupFindFirst: vi.fn(),
queryRaw: vi.fn(),
executeRaw: vi.fn(),
bossSend: vi.fn(),
getGlobalBossMock: vi.fn(),
}));
vi.mock("@/lib/db", () => ({
prisma: {
medicationIntakeEvent: {
findMany: mocks.intakeFindMany,
},
medicationComplianceRollup: {
upsert: mocks.rollupUpsert,
deleteMany: mocks.rollupDeleteMany,
findMany: mocks.rollupFindMany,
findFirst: mocks.rollupFindFirst,
},
$queryRaw: mocks.queryRaw,
$executeRaw: mocks.executeRaw,
},
}));
vi.mock("@/lib/jobs/boss-instance", () => ({
getGlobalBoss: () => mocks.getGlobalBossMock(),
}));
vi.mock("@/lib/logging/context", () => ({
annotate: vi.fn(),
}));
import {
dayKeyForScheduledFor,
recomputeMedicationComplianceForDay,
recomputeMedicationComplianceForEvent,
readMedicationCompliance,
hasMedicationComplianceCoverage,
recomputeUserMedicationCompliance,
enqueueBootTimeMedicationComplianceBackfill,
enqueueUserMedicationComplianceBackfill,
MEDICATION_COMPLIANCE_BACKFILL_QUEUE,
} from "../medication-compliance-rollups";
const {
intakeFindMany,
rollupUpsert,
rollupDeleteMany,
rollupFindMany,
rollupFindFirst,
queryRaw,
executeRaw,
bossSend,
getGlobalBossMock,
} = mocks;
beforeEach(() => {
vi.resetAllMocks();
intakeFindMany.mockResolvedValue([]);
rollupUpsert.mockResolvedValue({});
rollupDeleteMany.mockResolvedValue({ count: 0 });
rollupFindMany.mockResolvedValue([]);
rollupFindFirst.mockResolvedValue(null);
queryRaw.mockResolvedValue([]);
executeRaw.mockResolvedValue(0);
});
afterEach(() => {
vi.useRealTimers();
});
describe("dayKeyForScheduledFor", () => {
it("anchors the dayKey on the user's tz wall clock", () => {
// 2026-05-17T23:30:00Z — Berlin local is 2026-05-18 01:30 (CEST).
const ts = new Date("2026-05-17T23:30:00.000Z");
expect(dayKeyForScheduledFor(ts, "Europe/Berlin")).toBe("2026-05-18");
// Los Angeles is UTC-7 (PDT) — still 2026-05-17 16:30 local.
expect(dayKeyForScheduledFor(ts, "America/Los_Angeles")).toBe("2026-05-17");
});
it("falls back to the server default when tz is null", () => {
const ts = new Date("2026-05-17T22:00:00.000Z");
expect(dayKeyForScheduledFor(ts, null)).toBe(
dayKeyForScheduledFor(ts, "Europe/Berlin"),
);
});
});
describe("recomputeMedicationComplianceForDay", () => {
/**
* Helper: pull the bind-variable values out of a Prisma tagged-template
* call so the test can inspect the user-id / day / window bounds the
* SQL was rendered with. Prisma's `$executeRaw` tag passes the
* template strings as the first arg and the substituted values as the
* remaining positional args.
*/
function bindValues(call: unknown[]): unknown[] {
return call.slice(1);
}
it("runs an atomic INSERT … ON CONFLICT upsert with the (user, medication, day) tuple", async () => {
// QA F-H-02 (v1.4.39): the recompute is now a single SQL statement
// that re-aggregates inside the upsert; the JS pre-fold from the
// previous tier is gone so the test inspects the bind values
// instead of the intake fold.
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
// Two statements fire: the INSERT … ON CONFLICT upsert and the
// companion DELETE for the "all events removed" branch.
expect(executeRaw).toHaveBeenCalledTimes(2);
const insertBinds = bindValues(executeRaw.mock.calls[0]);
expect(insertBinds).toContain("user-1");
expect(insertBinds).toContain("med-1");
expect(insertBinds).toContain("2026-05-18");
const deleteBinds = bindValues(executeRaw.mock.calls[1]);
expect(deleteBinds).toContain("user-1");
expect(deleteBinds).toContain("med-1");
expect(deleteBinds).toContain("2026-05-18");
});
it("emits a paired DELETE so a fully-cleared day removes its row", async () => {
// The DELETE fires unconditionally and gates on NOT EXISTS — when
// the day still has events the predicate matches zero rows. The
// test pins that the DELETE statement was issued so a future
// refactor that drops the second statement breaks here.
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
expect(executeRaw).toHaveBeenCalledTimes(2);
});
it("is idempotent across repeated invocations", async () => {
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
expect(executeRaw).toHaveBeenCalledTimes(4);
expect(bindValues(executeRaw.mock.calls[0])).toEqual(
bindValues(executeRaw.mock.calls[2]),
);
expect(bindValues(executeRaw.mock.calls[1])).toEqual(
bindValues(executeRaw.mock.calls[3]),
);
});
it("binds a tz-anchored UTC window into the upsert", async () => {
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
const insertBinds = bindValues(executeRaw.mock.calls[0]);
const insertDates = insertBinds.filter((b): b is Date => b instanceof Date);
// Berlin 2026-05-18 00:00 → UTC 2026-05-17 22:00 (CEST is UTC+2).
expect(insertDates[0].toISOString()).toBe("2026-05-17T22:00:00.000Z");
// Window closes 24h later — Berlin 2026-05-19 00:00 → UTC 2026-05-18 22:00.
expect(insertDates[1].toISOString()).toBe("2026-05-18T22:00:00.000Z");
});
it("buckets the same UTC instant on different days for Berlin vs LA", async () => {
await recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
);
const berlinInsert = bindValues(executeRaw.mock.calls[0]).filter(
(b): b is Date => b instanceof Date,
);
executeRaw.mockClear();
await recomputeMedicationComplianceForDay(
"user-2",
"med-2",
"2026-05-17",
"America/Los_Angeles",
);
const laInsert = bindValues(executeRaw.mock.calls[0]).filter(
(b): b is Date => b instanceof Date,
);
// Berlin 2026-05-18 starts at UTC 2026-05-17 22:00.
expect(berlinInsert[0].toISOString()).toBe("2026-05-17T22:00:00.000Z");
// LA 2026-05-17 starts at UTC 2026-05-17 07:00 (PDT is UTC-7).
expect(laInsert[0].toISOString()).toBe("2026-05-17T07:00:00.000Z");
});
it("commits the strictest aggregate under concurrent recompute calls", async () => {
// QA F-H-02 race pin: two concurrent recomputes for the same
// (user, medication, day) must both go through the atomic SQL
// path. The earlier `findMany`-then-`upsert` pattern could
// interleave A-SELECT → B-SELECT → B-UPSERT (correct) → A-UPSERT
// (stale N-1); the atomic upsert serialises on the row lock so
// each statement re-aggregates a snapshot taken after the prior
// commit. The mock can't reproduce real Postgres concurrency, but
// the test pins that BOTH callers issue the atomic statement (not
// the legacy read-aggregate-then-upsert) so a regression to the
// racy pattern would fail this assertion.
await Promise.all([
recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
),
recomputeMedicationComplianceForDay(
"user-1",
"med-1",
"2026-05-18",
"Europe/Berlin",
),
]);
// 2 callers × 2 statements (INSERT + DELETE) each.
expect(executeRaw).toHaveBeenCalledTimes(4);
// No legacy intake-findMany was issued — the atomic path replaces it.
expect(intakeFindMany).not.toHaveBeenCalled();
// No legacy rollupUpsert / rollupDeleteMany either.
expect(rollupUpsert).not.toHaveBeenCalled();
expect(rollupDeleteMany).not.toHaveBeenCalled();
});
});
describe("recomputeMedicationComplianceForEvent", () => {
it("derives the dayKey from scheduledFor + tz then dispatches", async () => {
// 2026-05-17T23:30:00Z → Berlin day 2026-05-18.
await recomputeMedicationComplianceForEvent({
userId: "user-1",
medicationId: "med-1",
scheduledFor: new Date("2026-05-17T23:30:00.000Z"),
tz: "Europe/Berlin",
});
// The atomic upsert binds the dayKey as one of the positional
// arguments; assert "2026-05-18" reached the SQL layer.
const insertBinds = executeRaw.mock.calls[0].slice(1);
expect(insertBinds).toContain("2026-05-18");
});
it("swallows recompute errors so the parent write never blocks", async () => {
executeRaw.mockRejectedValueOnce(new Error("DB melted"));
await expect(
recomputeMedicationComplianceForEvent({
userId: "user-1",
medicationId: "med-1",
scheduledFor: new Date("2026-05-17T12:00:00.000Z"),
tz: "Europe/Berlin",
}),
).resolves.toBeUndefined();
});
});
describe("readMedicationCompliance", () => {
it("returns a trailing-window zero-filled bucket array", async () => {
rollupFindMany.mockResolvedValue([
{ day: "2026-05-18", scheduled: 2, taken: 1, skipped: 1 },
]);
const now = new Date("2026-05-18T12:00:00.000Z");
const buckets = await readMedicationCompliance(
"user-1",
3,
"Europe/Berlin",
now,
);
expect(buckets).toHaveLength(3);
expect(buckets[buckets.length - 1]).toEqual({
date: "2026-05-18",
scheduled: 2,
taken: 1,
});
expect(buckets[0].scheduled).toBe(0);
expect(buckets[0].taken).toBe(0);
expect(buckets.map((b) => b.date)).toEqual([
"2026-05-16",
"2026-05-17",
"2026-05-18",
]);
});
it("folds per-medication rows into one per-day total", async () => {
rollupFindMany.mockResolvedValue([
{ day: "2026-05-18", scheduled: 1, taken: 1, skipped: 0 },
{ day: "2026-05-18", scheduled: 2, taken: 0, skipped: 1 },
]);
const now = new Date("2026-05-18T12:00:00.000Z");
const buckets = await readMedicationCompliance(
"user-1",
1,
"Europe/Berlin",
now,
);
expect(buckets[0].scheduled).toBe(3);
expect(buckets[0].taken).toBe(1);
});
});
describe("hasMedicationComplianceCoverage", () => {
it("returns true when rolled-day count meets the event-day count in window", async () => {
queryRaw.mockResolvedValue([
{ rolled_days: BigInt(7), event_days: BigInt(7) },
]);
await expect(
hasMedicationComplianceCoverage(
"user-1",
7,
"Europe/Berlin",
new Date("2026-05-18T12:00:00.000Z"),
),
).resolves.toBe(true);
});
it("returns true when the user has zero events in window (trivially covered)", async () => {
// Zero events → the read path returns a trailing-window zero-fill
// from an empty rollup table; covered semantically.
queryRaw.mockResolvedValue([
{ rolled_days: BigInt(0), event_days: BigInt(0) },
]);
await expect(
hasMedicationComplianceCoverage("user-1", 7, "Europe/Berlin"),
).resolves.toBe(true);
});
it("returns false on partial coverage (boot backfill mid-fold)", async () => {
// QA F-H-01 (v1.4.39): the legacy "any row exists" probe would
// flip true here and serve zero-filled buckets for days N..days-1
// that the backfill hasn't reached yet. With the tightened probe
// partial coverage forces the route into the legacy aggregator
// until the fold completes.
queryRaw.mockResolvedValue([
{ rolled_days: BigInt(2), event_days: BigInt(7) },
]);
await expect(
hasMedicationComplianceCoverage(
"user-1",
7,
"Europe/Berlin",
new Date("2026-05-18T12:00:00.000Z"),
),
).resolves.toBe(false);
});
it("returns false on zero rollups when events exist (legacy account cold start)", async () => {
queryRaw.mockResolvedValue([
{ rolled_days: BigInt(0), event_days: BigInt(7) },
]);
await expect(
hasMedicationComplianceCoverage("user-1", 7, "Europe/Berlin"),
).resolves.toBe(false);
});
});
describe("recomputeUserMedicationCompliance", () => {
it("upserts one rollup per (medication, day) pair returned by discovery", async () => {
queryRaw.mockResolvedValue([
{ medication_id: "med-1", day: "2026-05-17" },
{ medication_id: "med-1", day: "2026-05-18" },
{ medication_id: "med-2", day: "2026-05-18" },
]);
const result = await recomputeUserMedicationCompliance(
"user-1",
30,
"Europe/Berlin",
);
expect(result.rowsUpserted).toBe(3);
// Each (medication, day) pair issues two atomic SQL statements:
// the INSERT … ON CONFLICT upsert and the companion DELETE that
// gates on `NOT EXISTS`.
expect(executeRaw).toHaveBeenCalledTimes(6);
});
});
describe("enqueueBootTimeMedicationComplianceBackfill", () => {
it("is a no-op when no boss is attached", async () => {
getGlobalBossMock.mockReturnValue(null);
const result = await enqueueBootTimeMedicationComplianceBackfill();
expect(result).toEqual({ enqueued: 0, skipped: 0, error: null });
expect(queryRaw).not.toHaveBeenCalled();
});
it("enqueues one job per uncovered user", async () => {
getGlobalBossMock.mockReturnValue({ send: bossSend });
queryRaw.mockResolvedValue([{ id: "user-1" }, { id: "user-2" }]);
bossSend.mockResolvedValueOnce("job-1");
bossSend.mockResolvedValueOnce(null); // coalesced
const result = await enqueueBootTimeMedicationComplianceBackfill();
expect(result.enqueued).toBe(1);
expect(result.skipped).toBe(1);
expect(result.error).toBeNull();
expect(bossSend).toHaveBeenCalledWith(
MEDICATION_COMPLIANCE_BACKFILL_QUEUE,
expect.objectContaining({ userId: "user-1" }),
expect.objectContaining({
singletonKey: "medication-compliance-boot-backfill|user-1",
}),
);
});
});
describe("enqueueUserMedicationComplianceBackfill", () => {
it("is a no-op when no boss is attached", async () => {
getGlobalBossMock.mockReturnValue(null);
const result = await enqueueUserMedicationComplianceBackfill("user-1");
expect(result).toEqual({ enqueued: false, error: null });
// Critically: no `$queryRaw` cluster-wide LEFT JOIN scan.
expect(queryRaw).not.toHaveBeenCalled();
});
it("enqueues exactly one job for the caller's user and never touches the cluster-wide LEFT JOIN", async () => {
// QA F-SEC-M-01 (v1.4.39): pre-fix the request-path coverage-miss
// path called `enqueueBootTimeMedicationComplianceBackfill` which
// issued a cluster-wide `LEFT JOIN medication_intake_events ×
// medication_compliance_rollups` on every hit. The user-scoped
// helper sends one targeted job and never runs the discovery scan.
getGlobalBossMock.mockReturnValue({ send: bossSend });
bossSend.mockResolvedValueOnce("job-1");
const result = await enqueueUserMedicationComplianceBackfill("user-1");
expect(result).toEqual({ enqueued: true, error: null });
expect(queryRaw).not.toHaveBeenCalled();
expect(bossSend).toHaveBeenCalledTimes(1);
expect(bossSend).toHaveBeenCalledWith(
MEDICATION_COMPLIANCE_BACKFILL_QUEUE,
expect.objectContaining({ userId: "user-1" }),
expect.objectContaining({
singletonKey: "medication-compliance-boot-backfill|user-1",
}),
);
});
it("reports a coalesced enqueue as `enqueued:false`", async () => {
getGlobalBossMock.mockReturnValue({ send: bossSend });
bossSend.mockResolvedValueOnce(null);
const result = await enqueueUserMedicationComplianceBackfill("user-2");
expect(result).toEqual({ enqueued: false, error: null });
});
});
@@ -0,0 +1,614 @@
/**
* v1.4.39 W-MED — persistent medication-compliance rollup tier.
*
* Replaces the unbounded `MedicationIntakeEvent.findMany` walk on
* `/api/medications/intake?scope=compliance` with a ledger keyed
* `(userId, medicationId, day)` where `day` is `YYYY-MM-DD` anchored
* to the user's IANA timezone.
*
* Write hooks fire from every `MedicationIntakeEvent` mutation site
* (create / update / delete / bulk import) plus the reminder-worker's
* mint path that creates `takenAt:null` rows on RED-phase reminders.
* Reads collapse the trailing N-day window into a single bounded
* `findMany` against `medication_compliance_rollups`; the route-level
* coverage probe falls back to live + fires a boot backfill when a
* user has intake events but zero rollup rows.
*
* Audit anchor: `.planning/round-v1438-perf-analysis.md` §2.5 + §5 P4.
*/
import type { Prisma } from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { annotate } from "@/lib/logging/context";
import {
DEFAULT_TIMEZONE,
isValidTimezone,
userDayKey,
} from "@/lib/tz/format";
import { wallClockInTz } from "@/lib/tz/wall-clock";
/**
* pg-boss queue name for the boot-time medication compliance backfill.
* Mirrors the `rollup-full-backfill` v1.4.35.1 pattern: discovery is
* idempotent across reboots and the worker upserts every
* `(user, medication, day)` row for the trailing window.
*/
export const MEDICATION_COMPLIANCE_BACKFILL_QUEUE =
"medication-compliance-full-backfill";
/** Worker concurrency cap — backfill stays serial to spare the pool. */
export const MEDICATION_COMPLIANCE_BACKFILL_CONCURRENCY = 1;
/** Trailing window the boot backfill folds per uncovered user. */
export const MEDICATION_COMPLIANCE_BACKFILL_DAYS = 90;
/** Payload `boss.send` carries onto the backfill queue. */
export interface MedicationComplianceBackfillPayload {
userId: string;
/** Wall-clock kick-off for debugging only. */
enqueuedAt: string;
}
/** Reader-result row shape — matches `buildComplianceBuckets` output. */
export interface ComplianceBucket {
/** YYYY-MM-DD in the user's tz. */
date: string;
scheduled: number;
taken: number;
}
/**
* Prisma client surface the helpers accept. Either the regular
* `prisma` singleton or a `$transaction(tx)` argument — both expose
* the `medicationIntakeEvent.findMany` + `medicationComplianceRollup.*`
* methods we touch.
*/
type PrismaLike = typeof prisma | Prisma.TransactionClient;
/**
* UTC offset (in minutes) of `tz` at the given instant. Positive east
* of UTC. Honours DST via `Intl.DateTimeFormat`.
*/
function tzOffsetMinutes(date: Date, tz: string): number {
const parts = new Intl.DateTimeFormat("en-US", {
timeZone: tz,
year: "numeric",
month: "2-digit",
day: "2-digit",
hour: "2-digit",
minute: "2-digit",
second: "2-digit",
hour12: false,
}).formatToParts(date);
const get = (type: Intl.DateTimeFormatPartTypes): string =>
parts.find((p) => p.type === type)?.value ?? "0";
let hour = Number(get("hour"));
if (hour === 24) hour = 0;
const asIfUtc = Date.UTC(
Number(get("year")),
Number(get("month")) - 1,
Number(get("day")),
hour,
Number(get("minute")),
Number(get("second")),
);
return Math.round((asIfUtc - date.getTime()) / 60000);
}
/**
* The UTC instant corresponding to local-midnight on `dayKey` in `tz`.
* Two-pass convergence handles DST transitions correctly.
*/
function startOfDayUtcInTz(dayKey: string, tz: string): Date {
const [yearStr, monthStr, dayStr] = dayKey.split("-");
const year = Number(yearStr);
const month = Number(monthStr);
const day = Number(dayStr);
let guess = new Date(Date.UTC(year, month - 1, day, 0, 0, 0, 0));
for (let i = 0; i < 2; i++) {
const offsetMin = tzOffsetMinutes(guess, tz);
guess = new Date(
Date.UTC(year, month - 1, day, 0, 0, 0, 0) - offsetMin * 60_000,
);
}
return guess;
}
/**
* Resolve a safe tz string — fall back to the server default when the
* supplied value is missing or not an IANA zone the host recognises.
*/
function safeTimezone(tz: string | null | undefined): string {
if (tz && isValidTimezone(tz)) return tz;
return DEFAULT_TIMEZONE;
}
/**
* Convert a `scheduledFor` UTC instant to the user's `YYYY-MM-DD`
* day-key. Re-exposed so the write-hook caller can derive the same
* `dayKey` the rollup row is anchored on.
*/
export function dayKeyForScheduledFor(
scheduledFor: Date,
tz: string | null | undefined,
): string {
return userDayKey(scheduledFor, safeTimezone(tz));
}
/**
* Recompute the rollup row for one `(userId, medicationId, dayKey)`
* tuple. Reads every `MedicationIntakeEvent` whose `scheduledFor` lands
* in `[startOfDayInTz, startOfNextDayInTz)` then upserts the
* `medication_compliance_rollups` row.
*
* The hook is idempotent: re-running for the same key produces the
* same row. When the day window holds zero events the row is deleted
* so the read path returns the trailing-window zero-default rather
* than a stale stub.
*
* `tx` accepts the `prisma.$transaction(tx)` client argument when the
* parent write is transactional — passing the transaction client keeps
* the rollup write inside the same transactional boundary.
*/
export async function recomputeMedicationComplianceForDay(
userId: string,
medicationId: string,
dayKey: string,
tz: string | null | undefined,
tx?: PrismaLike,
): Promise<void> {
const client = (tx ?? prisma) as PrismaLike;
const safeTz = safeTimezone(tz);
const start = startOfDayUtcInTz(dayKey, safeTz);
const end = new Date(start.getTime() + 86_400_000);
// Re-derive end via the day-after boundary to honour DST 23 / 25-hour
// days. `start + 86_400_000` is correct for non-transition days; on
// a fall-back day we add one calendar day in the local zone.
const nextDayKey = (() => {
const [y, m, d] = dayKey.split("-").map(Number);
const probe = new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
const probeNext = new Date(probe.getTime() + 86_400_000);
const parts = wallClockInTz(probeNext, safeTz);
return `${String(parts.year).padStart(4, "0")}-${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")}`;
})();
const dstSafeEnd = startOfDayUtcInTz(nextDayKey, safeTz);
const windowEnd = dstSafeEnd.getTime() > start.getTime() ? dstSafeEnd : end;
// v1.4.39 hotfix (QA F-H-02): atomic upsert closes the race window
// between the prior `SELECT … aggregate then UPSERT` pattern. Two
// concurrent writes for the same (user, medication, day) used to
// interleave A-SELECT → B-SELECT → B-UPSERT (correct) → A-UPSERT
// (stale N-1). The INSERT … SELECT re-aggregates inside the upsert
// statement so each write commits with a snapshot taken after the
// prior commit released its row lock; the trailing DELETE handles
// the "all events for the day were removed" case in the same shot.
//
// Both statements key on (user_id, medication_id, day) so they
// serialise behind the row lock the rollup table's primary key
// provides. The DELETE runs second so it cannot clobber a row the
// INSERT just wrote — when the day still has events the
// `WHERE NOT EXISTS` predicate matches zero rows.
await client.$executeRaw`
WITH aggregate AS (
SELECT
COUNT(*)::int AS scheduled,
SUM(CASE WHEN "skipped" THEN 0 WHEN "taken_at" IS NOT NULL THEN 1 ELSE 0 END)::int AS taken,
SUM(CASE WHEN "skipped" THEN 1 ELSE 0 END)::int AS skipped
FROM "medication_intake_events"
WHERE "user_id" = ${userId}
AND "medication_id" = ${medicationId}
AND "scheduled_for" >= ${start}
AND "scheduled_for" < ${windowEnd}
)
INSERT INTO "medication_compliance_rollups"
("user_id", "medication_id", "day", "scheduled", "taken", "skipped", "computed_at")
SELECT
${userId},
${medicationId},
${dayKey},
aggregate.scheduled,
aggregate.taken,
aggregate.skipped,
NOW()
FROM aggregate
WHERE aggregate.scheduled > 0
ON CONFLICT ("user_id", "medication_id", "day") DO UPDATE
SET "scheduled" = EXCLUDED."scheduled",
"taken" = EXCLUDED."taken",
"skipped" = EXCLUDED."skipped",
"computed_at" = EXCLUDED."computed_at"
`;
await client.$executeRaw`
DELETE FROM "medication_compliance_rollups"
WHERE "user_id" = ${userId}
AND "medication_id" = ${medicationId}
AND "day" = ${dayKey}
AND NOT EXISTS (
SELECT 1
FROM "medication_intake_events"
WHERE "user_id" = ${userId}
AND "medication_id" = ${medicationId}
AND "scheduled_for" >= ${start}
AND "scheduled_for" < ${windowEnd}
)
`;
}
/**
* Convenience hook for write-paths that have the `scheduledFor`
* instant in hand. Derives `dayKey` in the user's tz then dispatches
* to `recomputeMedicationComplianceForDay`. Best-effort: surfaces
* failures through `annotate` + `console.error` so a silent populator
* regression shows up in ops without blocking the parent write.
*/
export async function recomputeMedicationComplianceForEvent(input: {
userId: string;
medicationId: string;
scheduledFor: Date;
tz: string | null | undefined;
tx?: PrismaLike;
}): Promise<void> {
const dayKey = dayKeyForScheduledFor(input.scheduledFor, input.tz);
try {
await recomputeMedicationComplianceForDay(
input.userId,
input.medicationId,
dayKey,
input.tz,
input.tx,
);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
annotate({
meta: {
medication_compliance_rollup_failed: true,
medication_compliance_rollup_error: message,
},
});
console.error(
"[medication-compliance-rollups] recompute failed:",
message,
);
}
}
/**
* Read trailing `days` of compliance buckets for the user, oldest day
* first. Returns the same `{date, scheduled, taken}` shape the legacy
* `buildComplianceBuckets` helper produced so the route swap is
* byte-identical.
*
* Days without a rollup row land as zero-filled buckets. The caller's
* cache wrapper carries the user-tz in its key so a tz change forces
* a fresh read.
*/
export async function readMedicationCompliance(
userId: string,
days: number,
tz: string | null | undefined,
now: Date = new Date(),
): Promise<ComplianceBucket[]> {
const safeTz = safeTimezone(tz);
// Build the expected day-key window oldest → newest so the response
// is sorted and zero-filled regardless of which days hold rollups.
const todayKey = userDayKey(now, safeTz);
const expectedKeys: string[] = [];
for (let i = days - 1; i >= 0; i--) {
const probe = new Date(now.getTime() - i * 86_400_000);
expectedKeys.push(userDayKey(probe, safeTz));
}
// Guard against a DST day-of-the-year landing the loop on the same
// dayKey twice — dedup by Map insertion order.
const dedup = new Set<string>();
const orderedKeys: string[] = [];
for (const key of expectedKeys) {
if (!dedup.has(key)) {
dedup.add(key);
orderedKeys.push(key);
}
}
// Always include today even if the trailing window dropped it (e.g.
// days===1 on a DST boundary). Cheap defensive insert.
if (!dedup.has(todayKey)) {
orderedKeys.push(todayKey);
}
const oldestKey = orderedKeys[0];
const newestKey = orderedKeys[orderedKeys.length - 1];
const rows = await prisma.medicationComplianceRollup.findMany({
where: {
userId,
day: { gte: oldestKey, lte: newestKey },
},
select: { day: true, scheduled: true, taken: true, skipped: true },
});
// Fold per-medication rows into one per-day total. The legacy route
// shape was aggregated across all the user's medications; preserving
// that surface keeps the front-end byte-stable.
const totals = new Map<string, { scheduled: number; taken: number }>();
for (const key of orderedKeys) {
totals.set(key, { scheduled: 0, taken: 0 });
}
for (const row of rows) {
const bucket = totals.get(row.day);
if (!bucket) continue;
bucket.scheduled += row.scheduled;
bucket.taken += row.taken;
}
return orderedKeys.map((date) => {
const bucket = totals.get(date) ?? { scheduled: 0, taken: 0 };
return { date, scheduled: bucket.scheduled, taken: bucket.taken };
});
}
/**
* Returns true when the rollup tier covers every day inside the
* trailing `days` window that has at least one intake event. Coverage
* is full when the count of DISTINCT rolled days equals the count of
* DISTINCT days that hold a `medication_intake_events` row in window —
* partial coverage (boot backfill mid-fold on a multi-medication
* account) returns false so the route falls through to the legacy
* aggregator instead of serving zero-filled tiles for un-rolled days.
*
* v1.4.39 hotfix (QA F-H-01): the previous "any row exists" probe
* could short-circuit to the rollup path while only the first few days
* had been backfilled, exposing zero-filled tiles for the un-rolled
* days until the boot fold completed.
*/
export async function hasMedicationComplianceCoverage(
userId: string,
days: number,
tz: string | null | undefined,
now: Date = new Date(),
): Promise<boolean> {
const safeTz = safeTimezone(tz);
const oldestKey = userDayKey(
new Date(now.getTime() - (days - 1) * 86_400_000),
safeTz,
);
const oldestStart = startOfDayUtcInTz(oldestKey, safeTz);
// Single SQL aggregate: count DISTINCT rolled days vs DISTINCT
// event-days in window. The event side is anchored on the same
// user-tz day-key (`to_char(... AT TIME ZONE $tz, 'YYYY-MM-DD')`) so
// the comparison stays apples-to-apples even on DST boundaries.
const result = await prisma.$queryRaw<
Array<{ rolled_days: bigint; event_days: bigint }>
>`
SELECT
(
SELECT COUNT(DISTINCT "day")::bigint
FROM "medication_compliance_rollups"
WHERE "user_id" = ${userId}
AND "day" >= ${oldestKey}
) AS rolled_days,
(
SELECT COUNT(DISTINCT to_char("scheduled_for" AT TIME ZONE ${safeTz}, 'YYYY-MM-DD'))::bigint
FROM "medication_intake_events"
WHERE "user_id" = ${userId}
AND "scheduled_for" >= ${oldestStart}
) AS event_days
`;
if (result.length === 0) return true;
const { rolled_days, event_days } = result[0];
const rolled = Number(rolled_days);
const events = Number(event_days);
// Zero events in window → trivially covered (the read path produces
// a zero-filled trailing window from the empty rollup table).
if (events === 0) return true;
return rolled >= events;
}
/**
* Full-fold helper. Walks every `(medicationId, day)` pair the user
* has logged across the trailing `days` window and upserts each
* rollup row. The boot-time backfill worker calls this once per
* uncovered user; the route's lazy fallback enqueues it when the
* coverage probe returns false.
*
* Bounded SQL: one `DISTINCT (medicationId, dayKey)` $queryRaw scan
* over the trailing window, then one upsert per row. The dayKey is
* computed in Postgres via `to_char(... AT TIME ZONE $tz)` so we
* don't have to ship millions of rows back to Node.
*/
export async function recomputeUserMedicationCompliance(
userId: string,
days: number = MEDICATION_COMPLIANCE_BACKFILL_DAYS,
tz: string | null | undefined = null,
): Promise<{ rowsUpserted: number; durationMs: number }> {
const startedAt = Date.now();
const safeTz = safeTimezone(tz);
const now = new Date();
const oldestKey = userDayKey(
new Date(now.getTime() - (days - 1) * 86_400_000),
safeTz,
);
const oldestStart = startOfDayUtcInTz(oldestKey, safeTz);
// Distinct (medication_id, dayKey) pairs the user has any intake
// event for inside the trailing window. `to_char(... AT TIME ZONE
// $tz)` keeps the day-bucket on the user's wall-clock.
const pairs = await prisma.$queryRaw<
Array<{ medication_id: string; day: string }>
>`
SELECT DISTINCT
"medication_id",
to_char("scheduled_for" AT TIME ZONE ${safeTz}, 'YYYY-MM-DD') AS "day"
FROM "medication_intake_events"
WHERE "user_id" = ${userId}
AND "scheduled_for" >= ${oldestStart}
`;
let rowsUpserted = 0;
for (const pair of pairs) {
await recomputeMedicationComplianceForDay(
userId,
pair.medication_id,
pair.day,
safeTz,
);
rowsUpserted += 1;
}
return { rowsUpserted, durationMs: Date.now() - startedAt };
}
/**
* Fire-and-forget warm-up — kept around for symmetry with
* `ensureUserRollupsFresh` even though the on-write hook fully owns
* coverage in steady state. The route currently doesn't call this
* directly; the coverage-probe + boot-backfill cascade handles the
* cold-mount case.
*/
export async function ensureUserMedicationComplianceFresh(
userId: string,
days: number = MEDICATION_COMPLIANCE_BACKFILL_DAYS,
tz: string | null | undefined = null,
): Promise<{ recomputed: boolean }> {
try {
if (await hasMedicationComplianceCoverage(userId, days, tz)) {
return { recomputed: false };
}
await recomputeUserMedicationCompliance(userId, days, tz);
return { recomputed: true };
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
annotate({
meta: {
medication_compliance_rollup_refresh_failed: true,
medication_compliance_rollup_refresh_error: message,
},
});
console.error(
"[medication-compliance-rollups] ensure-fresh failed:",
message,
);
return { recomputed: false };
}
}
/**
* v1.4.39 hotfix (QA F-SEC-M-01) — user-scoped enqueue helper for the
* request-path coverage-miss fallback.
*
* Mirrors `ensureUserMoodRollupsFresh`: the route fires this when its
* coverage probe returned false so the caller's account picks up a
* targeted boot-backfill job, instead of running a cluster-wide
* `LEFT JOIN` over `medication_intake_events × medication_compliance_rollups`
* on every authenticated coverage-miss request. The cluster-wide scan
* was a soft DoS amplifier — an authenticated user iterating
* coverage-miss requests could drive a multi-tenant table scan on
* every hit.
*
* The boot-time discovery helper below stays cluster-wide (it runs
* once per worker boot, not per request).
*/
export async function enqueueUserMedicationComplianceBackfill(
userId: string,
): Promise<{ enqueued: boolean; error: string | null }> {
const boss = getGlobalBoss();
if (!boss) {
return { enqueued: false, error: null };
}
try {
const payload: MedicationComplianceBackfillPayload = {
userId,
enqueuedAt: new Date().toISOString(),
};
const jobId = await boss.send(
MEDICATION_COMPLIANCE_BACKFILL_QUEUE,
payload,
{
retryLimit: 3,
retryDelay: 60,
retryBackoff: true,
singletonKey: `medication-compliance-boot-backfill|${userId}`,
},
);
return { enqueued: jobId !== null && jobId !== undefined, error: null };
} catch (err) {
return {
enqueued: false,
error: err instanceof Error ? err.message : String(err),
};
}
}
/**
* Boot-time enqueue helper — mirrors v1.4.35.1
* `enqueueBootTimeRollupBackfill`. Finds users with intake events but
* zero compliance-rollup coverage for the trailing window and enqueues
* one full-fold per account onto `MEDICATION_COMPLIANCE_BACKFILL_QUEUE`.
*
* Idempotent across reboots: once an account has at least one rollup
* row inside the trailing window the discovery query drops them.
* pg-boss `singletonKey` coalesces duplicate sends.
*/
export async function enqueueBootTimeMedicationComplianceBackfill(): Promise<{
enqueued: number;
skipped: number;
error: string | null;
}> {
const boss = getGlobalBoss();
if (!boss) {
return { enqueued: 0, skipped: 0, error: null };
}
try {
// Trailing window cutoff for the existence probe — `scheduled_for`
// older than this is not what the read path consults.
const cutoff = new Date(
Date.now() - MEDICATION_COMPLIANCE_BACKFILL_DAYS * 86_400_000,
);
const users = await prisma.$queryRaw<Array<{ id: string }>>`
SELECT DISTINCT mie."user_id" AS id
FROM "medication_intake_events" mie
LEFT JOIN "medication_compliance_rollups" r
ON r."user_id" = mie."user_id"
AND r."medication_id" = mie."medication_id"
WHERE mie."scheduled_for" >= ${cutoff}
AND r."day" IS NULL
`;
if (users.length === 0) {
return { enqueued: 0, skipped: 0, error: null };
}
let enqueued = 0;
let skipped = 0;
for (const { id } of users) {
const payload: MedicationComplianceBackfillPayload = {
userId: id,
enqueuedAt: new Date().toISOString(),
};
const jobId = await boss.send(
MEDICATION_COMPLIANCE_BACKFILL_QUEUE,
payload,
{
retryLimit: 3,
retryDelay: 60,
retryBackoff: true,
singletonKey: `medication-compliance-boot-backfill|${id}`,
},
);
if (jobId) {
enqueued += 1;
} else {
skipped += 1;
}
}
return { enqueued, skipped, error: null };
} catch (err) {
return {
enqueued: 0,
skipped: 0,
error: err instanceof Error ? err.message : String(err),
};
}
}