refactor(rollups): move WMY and cumulative readers

- src/lib/measurements/rollup-read-wmy.ts → src/lib/rollups/measurement-read-wmy.ts
- src/lib/measurements/rollup-read-cumulative.ts → src/lib/rollups/measurement-read-cumulative.ts
- co-located tests follow the source files
- cumulative module's sibling import of apple-health-mapping promoted to
  the @/lib alias since that mapping stays in src/lib/measurements/

Importers updated: 2 sites for WMY (health-score + summaries-slice),
zero external sites for cumulative (only co-located test reads it).

Pure relocation.
This commit is contained in:
Marc-André Bombeck committed 2026-05-21 12:21:40 +02:00
1 parent b7da526cbb
commit 8cfb1715b4
6 files changed
+5 -5

No files matched your search

@@ -0,0 +1,136 @@
/**
* v1.4.39 W-SUM — unit tests for the cumulative-day-sum reader helpers.
*
* `prisma.measurementRollup.findMany` is mocked so the tests pin the
* exact `where` shape the consumer sends (cumulative type set,
* granularity, since-bound) and the legacy-NULL fallback semantics of
* `resolveBucketSum`.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
findMany: vi.fn(),
}));
vi.mock("@/lib/db", () => ({
prisma: {
measurementRollup: {
findMany: mocks.findMany,
},
},
}));
import { prisma } from "@/lib/db";
import {
isCumulativeType,
readCumulativeDaySums,
resolveBucketSum,
} from "../measurement-read-cumulative";
beforeEach(() => {
mocks.findMany.mockReset();
});
describe("isCumulativeType", () => {
it("recognises the five cumulative HK types", () => {
expect(isCumulativeType("ACTIVITY_STEPS")).toBe(true);
expect(isCumulativeType("ACTIVE_ENERGY_BURNED")).toBe(true);
expect(isCumulativeType("FLIGHTS_CLIMBED")).toBe(true);
expect(isCumulativeType("WALKING_RUNNING_DISTANCE")).toBe(true);
expect(isCumulativeType("TIME_IN_DAYLIGHT")).toBe(true);
});
it("rejects spot metrics", () => {
expect(isCumulativeType("WEIGHT")).toBe(false);
expect(isCumulativeType("BLOOD_PRESSURE_SYS")).toBe(false);
expect(isCumulativeType("PULSE")).toBe(false);
});
});
describe("readCumulativeDaySums", () => {
it("queries the rollup table with the cumulative type + DAY granularity", async () => {
const since = new Date("2026-04-15T00:00:00.000Z");
const rows = [
{
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
sumValue: 8120,
count: 4,
mean: 2030,
},
{
bucketStart: new Date("2026-04-16T00:00:00.000Z"),
sumValue: 12480,
count: 5,
mean: 2496,
},
];
mocks.findMany.mockResolvedValueOnce(rows);
const out = await readCumulativeDaySums("user-1", "ACTIVITY_STEPS", since);
expect(out).toHaveLength(2);
expect(out[0]).toMatchObject({
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
sumValue: 8120,
count: 4,
mean: 2030,
});
// Single round-trip — eliminates the legacy per-type chunked
// findMany loop in analytics A2.
expect(prisma.measurementRollup.findMany).toHaveBeenCalledTimes(1);
const args = mocks.findMany.mock.calls[0][0];
expect(args.where).toMatchObject({
userId: "user-1",
type: "ACTIVITY_STEPS",
granularity: "DAY",
bucketStart: { gte: since },
});
expect(args.orderBy).toEqual({ bucketStart: "asc" });
});
it("propagates legacy NULL sum_value rows so the caller can fall back", async () => {
mocks.findMany.mockResolvedValueOnce([
{
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
sumValue: null,
count: 3,
mean: 1500,
},
]);
const [row] = await readCumulativeDaySums(
"user-1",
"ACTIVITY_STEPS",
new Date("2026-04-15T00:00:00.000Z"),
);
expect(row.sumValue).toBeNull();
// Algebraic fallback parity: pre-v1.4.39 buckets still surface
// a usable daily total during the boot-backfill convergence
// window.
expect(resolveBucketSum(row)).toBe(4500);
});
});
describe("resolveBucketSum", () => {
it("returns sumValue when populated", () => {
expect(
resolveBucketSum({
bucketStart: new Date(),
sumValue: 7500,
count: 3,
mean: 2500,
}),
).toBe(7500);
});
it("falls back to mean * count when sumValue is null (legacy row)", () => {
expect(
resolveBucketSum({
bucketStart: new Date(),
sumValue: null,
count: 3,
mean: 2500,
}),
).toBe(7500);
});
});
@@ -0,0 +1,362 @@
/**
* v1.4.39 W-WMY — unit tests for the WEEK / MONTH / YEAR rollup
* readers and the auto-router that picks the largest granularity
* that still resolves a requested window.
*
* `prisma.measurementRollup.findMany` is mocked at the module level
* so the test pins:
* - each per-granularity reader filters by the correct
* `granularity` literal,
* - empty rollups return `null` so the caller can branch on
* coverage miss,
* - the auto-router walks YEAR → MONTH → WEEK → DAY and stops at
* the first granularity whose floor the window clears AND which
* has coverage,
* - `aggregateWmyBuckets` composes `count / min / max / mean / sum`
* linearly across coarser buckets (the same compositional
* contract `rollup-read.ts:aggregateBuckets` carries for DAY).
*
* Integration coverage against a real Postgres lives outside this
* file — the writer's `STDDEV_POP / REGR_SLOPE` semantics are pinned
* in `tests/integration/measurement-rollups.test.ts` already.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
findMany: vi.fn(),
}));
vi.mock("@/lib/db", () => ({
prisma: {
measurementRollup: {
findMany: mocks.findMany,
},
},
}));
import {
aggregateWmyBuckets,
readBestGranularityRollups,
readMonthRollups,
readWeekRollups,
readYearRollups,
type RollupBucketRow,
} from "../measurement-read-wmy";
const { findMany } = mocks;
function bucket(
bucketStart: string,
partial: Partial<RollupBucketRow> = {},
): RollupBucketRow {
return {
bucketStart: new Date(bucketStart),
count: 10,
mean: 82,
sd: 1,
slope: -0.01,
r2: 0.3,
sumValue: null,
minValue: 80,
maxValue: 84,
...partial,
};
}
beforeEach(() => {
findMany.mockReset();
});
afterEach(() => {
vi.restoreAllMocks();
});
describe("readWeekRollups", () => {
it("returns the WEEK buckets for (userId, type, since)", async () => {
const rows = [
bucket("2026-04-27T00:00:00.000Z"),
bucket("2026-05-04T00:00:00.000Z", { mean: 81 }),
];
findMany.mockResolvedValueOnce(rows);
const since = new Date("2026-04-20T00:00:00.000Z");
const result = await readWeekRollups("user-1", "WEIGHT", since);
expect(result).not.toBeNull();
expect(result).toHaveLength(2);
expect(result?.[0].mean).toBe(82);
expect(result?.[1].mean).toBe(81);
const args = findMany.mock.calls[0][0];
expect(args.where.granularity).toBe("WEEK");
expect(args.where.userId).toBe("user-1");
expect(args.where.type).toBe("WEIGHT");
expect(args.where.bucketStart.gte).toBe(since);
expect(args.orderBy).toEqual({ bucketStart: "asc" });
});
it("returns null when the WEEK window has no coverage", async () => {
findMany.mockResolvedValueOnce([]);
const result = await readWeekRollups(
"user-1",
"WEIGHT",
new Date("2026-04-20T00:00:00.000Z"),
);
expect(result).toBeNull();
});
});
describe("readMonthRollups", () => {
it("returns the MONTH buckets and pins the granularity filter", async () => {
findMany.mockResolvedValueOnce([bucket("2026-04-01T00:00:00.000Z")]);
const result = await readMonthRollups(
"user-2",
"PULSE",
new Date("2026-01-01T00:00:00.000Z"),
);
expect(result).toHaveLength(1);
expect(findMany.mock.calls[0][0].where.granularity).toBe("MONTH");
});
it("returns null on coverage miss", async () => {
findMany.mockResolvedValueOnce([]);
const result = await readMonthRollups(
"user-2",
"PULSE",
new Date("2026-01-01T00:00:00.000Z"),
);
expect(result).toBeNull();
});
});
describe("readYearRollups", () => {
it("returns the YEAR buckets and pins the granularity filter", async () => {
findMany.mockResolvedValueOnce([bucket("2025-01-01T00:00:00.000Z")]);
const result = await readYearRollups(
"user-3",
"WEIGHT",
new Date("2023-01-01T00:00:00.000Z"),
);
expect(result).toHaveLength(1);
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
});
it("returns null on coverage miss", async () => {
findMany.mockResolvedValueOnce([]);
const result = await readYearRollups(
"user-3",
"WEIGHT",
new Date("2023-01-01T00:00:00.000Z"),
);
expect(result).toBeNull();
});
});
describe("readBestGranularityRollups", () => {
it("returns null on a non-positive window", async () => {
expect(await readBestGranularityRollups("user", "WEIGHT", 0)).toBeNull();
expect(await readBestGranularityRollups("user", "WEIGHT", -10)).toBeNull();
expect(await readBestGranularityRollups("user", "WEIGHT", NaN)).toBeNull();
expect(findMany).not.toHaveBeenCalled();
});
it("routes a 90-day window to DAY (every coarser floor is too low)", async () => {
findMany.mockResolvedValueOnce([bucket("2026-04-01T00:00:00.000Z")]);
const result = await readBestGranularityRollups("user", "WEIGHT", 90);
expect(result).not.toBeNull();
expect(result?.granularity).toBe("DAY");
expect(findMany).toHaveBeenCalledTimes(1);
expect(findMany.mock.calls[0][0].where.granularity).toBe("DAY");
});
it("routes a 365-day window to MONTH (clears the 62-day MONTH floor)", async () => {
findMany.mockResolvedValueOnce([bucket("2026-01-01T00:00:00.000Z")]);
const result = await readBestGranularityRollups("user", "WEIGHT", 365);
expect(result).not.toBeNull();
expect(result?.granularity).toBe("MONTH");
expect(findMany).toHaveBeenCalledTimes(1);
expect(findMany.mock.calls[0][0].where.granularity).toBe("MONTH");
});
it("routes a 1095-day window to YEAR (clears the 730-day YEAR floor)", async () => {
findMany.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]);
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
expect(result).not.toBeNull();
expect(result?.granularity).toBe("YEAR");
expect(findMany).toHaveBeenCalledTimes(1);
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
});
it("falls back to MONTH when YEAR has no coverage", async () => {
// 1095-day window asks for YEAR first; coverage miss → MONTH.
findMany
.mockResolvedValueOnce([]) // YEAR miss
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // MONTH hit
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
expect(result?.granularity).toBe("MONTH");
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
expect(findMany.mock.calls[1][0].where.granularity).toBe("MONTH");
});
it("falls all the way through to DAY when every coarser tier misses", async () => {
findMany
.mockResolvedValueOnce([]) // YEAR miss
.mockResolvedValueOnce([]) // MONTH miss
.mockResolvedValueOnce([]) // WEEK miss
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // DAY hit
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
expect(result?.granularity).toBe("DAY");
expect(findMany).toHaveBeenCalledTimes(4);
});
it("returns null when no granularity carries any coverage", async () => {
findMany.mockResolvedValue([]);
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
expect(result).toBeNull();
// YEAR, MONTH, WEEK, DAY all probed.
expect(findMany).toHaveBeenCalledTimes(4);
});
});
describe("aggregateWmyBuckets", () => {
it("returns the empty-window shape on no rows", () => {
expect(aggregateWmyBuckets([])).toEqual({
count: 0,
min: null,
max: null,
mean: null,
sum: null,
});
});
it("sums count + folds min/max + weights mean across MONTH buckets", () => {
// Two MONTH buckets — same compositional contract as DAY because
// `count / min / max / mean` are linearly composable across any
// bucket granularity.
// April: count=10, mean=82, min=79, max=84
// May: count=20, mean=80, min=77, max=83
// ⇒ totalCount=30, min=77, max=84,
// mean = (10×82 + 20×80) / 30 = 80.6666…
const rows: RollupBucketRow[] = [
bucket("2026-04-01T00:00:00.000Z", {
count: 10,
mean: 82,
minValue: 79,
maxValue: 84,
}),
bucket("2026-05-01T00:00:00.000Z", {
count: 20,
mean: 80,
minValue: 77,
maxValue: 83,
}),
];
const result = aggregateWmyBuckets(rows);
expect(result.count).toBe(30);
expect(result.min).toBe(77);
expect(result.max).toBe(84);
expect(result.mean).toBeCloseTo((10 * 82 + 20 * 80) / 30, 5);
});
it("sums cumulative sumValue when every bucket carries one", () => {
const rows: RollupBucketRow[] = [
bucket("2026-04-01T00:00:00.000Z", { sumValue: 12_500 }),
bucket("2026-05-01T00:00:00.000Z", { sumValue: 8_200 }),
];
const result = aggregateWmyBuckets(rows);
expect(result.sum).toBe(20_700);
});
it("returns null sum when no bucket carries sumValue (pre-W-SUM data)", () => {
const rows: RollupBucketRow[] = [
bucket("2026-04-01T00:00:00.000Z", { sumValue: null }),
bucket("2026-05-01T00:00:00.000Z", { sumValue: null }),
];
expect(aggregateWmyBuckets(rows).sum).toBeNull();
});
it("treats sumValue NaN/Infinity as missing", () => {
const rows: RollupBucketRow[] = [
bucket("2026-04-01T00:00:00.000Z", { sumValue: 100 }),
bucket("2026-05-01T00:00:00.000Z", {
// simulate a Postgres NaN slipping through serialisation.
sumValue: Number.NaN,
}),
];
// Only the finite sumValue contributes.
expect(aggregateWmyBuckets(rows).sum).toBe(100);
});
});
/**
* v1.4.40 W-WMY-WIRE — granularity-routing parity across the v1.4.40
* consumers (summaries-slice + health-score-fast-path). Both consumers
* now call `readBestGranularityRollups` for their long-window probes;
* this pins:
* - 90 d → DAY (every coarser floor too high — DAY is canonical
* for the trailing quarter regardless of consumer),
* - 365 d → MONTH (clears MONTH floor 181 d, short of YEAR floor
* 731 d) — the granularity health-score-fast-path's weight long-
* window read and summaries-slice's year-ago baseline both
* consume,
* - 1095 d → YEAR (clears the 731-day YEAR floor) — the v1.5
* multi-year trend card target.
*
* The parity assertion ensures the routing contract is a single
* source of truth: any future floor adjustment forces both consumers
* to re-pin in lock-step rather than silently diverging.
*/
describe("readBestGranularityRollups — cross-consumer routing parity", () => {
it("pins the 90 / 365 / 1095 day routing targets the consumers depend on", async () => {
// Three sequential probes with non-empty results so the router
// stops at the first matching tier per window.
findMany
.mockResolvedValueOnce([bucket("2026-02-15T00:00:00.000Z")]) // 90d → DAY
.mockResolvedValueOnce([bucket("2025-08-01T00:00:00.000Z")]) // 365d → MONTH
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // 1095d → YEAR
const ninety = await readBestGranularityRollups("user", "WEIGHT", 90);
const yearLong = await readBestGranularityRollups("user", "WEIGHT", 365);
const threeYear = await readBestGranularityRollups("user", "WEIGHT", 1095);
expect(ninety?.granularity).toBe("DAY");
expect(yearLong?.granularity).toBe("MONTH");
expect(threeYear?.granularity).toBe("YEAR");
// Each consumer-relevant window only fires one round-trip on the
// happy path; the per-tier walk is reserved for coverage-miss
// scenarios already pinned above.
expect(findMany).toHaveBeenCalledTimes(3);
expect(findMany.mock.calls[0][0].where.granularity).toBe("DAY");
expect(findMany.mock.calls[1][0].where.granularity).toBe("MONTH");
expect(findMany.mock.calls[2][0].where.granularity).toBe("YEAR");
});
it("aggregates MONTH buckets to a byte-identical mean compared to the underlying DAY buckets", async () => {
// The compositional contract `count / mean` are linearly
// composable across granularities — pin it by simulating "MONTH
// routing for a 365-day window" vs "DAY routing for the same
// window" against the same underlying counts/means and asserting
// the count-weighted mean agrees.
//
// MONTH bucket (consolidated): count=30, mean=80
// DAY buckets (per-day refresh): count=10/mean=82 + count=20/mean=79
// ⇒ DAY-derived mean = (10*82 + 20*79) / 30 = 80.0
// Both must agree numerically — the routing helper's choice is a
// performance optimisation, not a math change.
const monthBuckets: RollupBucketRow[] = [
bucket("2025-08-01T00:00:00.000Z", { count: 30, mean: 80 }),
];
const dayBuckets: RollupBucketRow[] = [
bucket("2025-08-05T00:00:00.000Z", { count: 10, mean: 82 }),
bucket("2025-08-20T00:00:00.000Z", { count: 20, mean: 79 }),
];
const monthAgg = aggregateWmyBuckets(monthBuckets);
const dayAgg = aggregateWmyBuckets(dayBuckets);
expect(monthAgg.count).toBe(dayAgg.count);
expect(monthAgg.mean).toBeCloseTo(dayAgg.mean ?? Number.NaN, 5);
});
});
@@ -0,0 +1,120 @@
/**
* v1.4.39 W-SUM — read helpers for cumulative-metric daily sums.
*
* The v1.4.36 read path consumes the rollup table for spot-metric means
* via `rollup-read.ts`. Cumulative HK types (steps, flights, distance,
* daylight, active-energy) need the per-day SUM rather than the MEAN —
* every row is a partial-day slice from HealthKit, so MEAN understates
* the daily total by the per-bucket sample count.
*
* The v1.4.39 schema scaffolding (migration 0072) added `sum_value` to
* `measurement_rollups`. The writer in `rollups.ts` populates it on
* every fold (including for non-cumulative types — the cost is one
* extra `SUM` in the existing aggregator). The legacy-NULL backfill
* runs through `enqueueBootTimeRollupBackfill` so existing rows
* converge on the next worker boot.
*
* Callers fall back to `mean * count` when `sumValue` is null. The
* shortcut is mathematically exact for a single source per day:
*
* sum = mean × count = (Σvalue / count) × count = Σvalue
*
* Multiple sources for the same `(user, type, day)` mix into the same
* bucket today — the source-priority resolution that
* `pickCanonicalSourceRows` runs in JS happens AFTER the rollup
* aggregate is built. The W8c per-source rollup deferred to v1.5 fixes
* that; until then, the cumulative read paths trust the bucket sum as
* the canonical daily total and the iOS drain (which collapses per
* source via `dailyStatsExternalId`) keeps Marc's tenant on the
* single-source-per-day path.
*/
import { prisma } from "@/lib/db";
import type { MeasurementType } from "@/generated/prisma/client";
import { CUMULATIVE_HK_TYPES } from "@/lib/measurements/apple-health-mapping";
/**
* Cumulative measurement types the rollup `sum_value` column serves.
* Re-exported from the canonical Apple Health mapping so the
* consumer-side gate stays in one place.
*
* Audit anchor: `.planning/round-v1438-perf-analysis.md` §3
* "Cumulative daily sums" + §5 P3.
*/
export type CumulativeType =
| "ACTIVITY_STEPS"
| "ACTIVE_ENERGY_BURNED"
| "FLIGHTS_CLIMBED"
| "WALKING_RUNNING_DISTANCE"
| "TIME_IN_DAYLIGHT";
/**
* `true` when `type` is one of the cumulative HK types whose daily
* total the rollup `sum_value` column carries.
*/
export function isCumulativeType(type: MeasurementType): type is CumulativeType {
return CUMULATIVE_HK_TYPES.has(type);
}
/** One DAY-bucket row read from `measurement_rollups`. */
export interface CumulativeDaySumRow {
bucketStart: Date;
/**
* Per-bucket SUM. `null` only when the bucket pre-dates the v1.4.39
* writer change AND the boot-time backfill has not yet converged on
* this user. Callers fall back to `mean * count` for the null case.
*/
sumValue: number | null;
count: number;
mean: number;
}
/**
* Read every DAY bucket for `(userId, type)` since `since`. Returns
* rows ascending by `bucketStart`. Pre-v1.4.39 rows surface here with
* `sumValue = null`; the caller decides whether to fall back to
* `mean * count` or skip them.
*
* Bounded to the cumulative-type set so a misuse (passing a spot
* metric) is a type error rather than a silent SUM on the wrong
* column. The query is a plain `findMany` against the
* `(userId, type, granularity, bucketStart)` composite primary key —
* single round-trip, fully indexed.
*/
export async function readCumulativeDaySums(
userId: string,
type: CumulativeType,
since: Date,
): Promise<CumulativeDaySumRow[]> {
const rows = await prisma.measurementRollup.findMany({
where: {
userId,
type: type as MeasurementType,
granularity: "DAY",
bucketStart: { gte: since },
},
orderBy: { bucketStart: "asc" },
select: {
bucketStart: true,
sumValue: true,
count: true,
mean: true,
},
});
return rows.map((r) => ({
bucketStart: r.bucketStart,
sumValue: r.sumValue,
count: r.count,
mean: r.mean,
}));
}
/**
* Resolve a per-bucket cumulative total. Reads `sumValue` when the
* v1.4.39 writer has populated it; falls back to `mean * count` for
* legacy NULL rows so the chart never paints a hole during the boot-
* backfill convergence window.
*/
export function resolveBucketSum(row: CumulativeDaySumRow): number {
if (row.sumValue !== null) return row.sumValue;
return row.mean * row.count;
}
+290
View File
@@ -0,0 +1,290 @@
/**
* v1.4.39 W-WMY — WEEK / MONTH / YEAR rollup readers.
*
* Background — the read-side gap
* ------------------------------
* Every measurement write fans out via `recomputeBucketsForMeasurement`
* into a synchronous DAY upsert plus pg-boss-queued WEEK / MONTH / YEAR
* recomputes. The boot-time backfill (`enqueueBootTimeRollupBackfill`)
* mints the full WEEK / MONTH / YEAR history once per uncovered user.
*
* As of v1.4.38 the only reader that consults `measurement_rollups`
* (`rollup-read.ts`, plus the per-fast-path branches in
* `summaries-slice`, `comprehensive-aggregator`, etc.) caps at DAY and
* a trailing 90-day window. The WEEK / MONTH / YEAR buckets sit in
* Postgres as pure write amplification — populated every write,
* surfaced nowhere on read. The v1.4.38 perf audit
* (`.planning/round-v1438-perf-analysis.md` §2 + §5 P6) calls this out
* as the largest unused investment in the rollup tier.
*
* What this module adds
* ---------------------
* Helpers that read the trailing N-bucket window for a single
* `(userId, type)` pair at a chosen granularity, plus an auto-router
* that picks the largest granularity that still resolves the requested
* window. The shape returned is identical to `readRollupBuckets` so
* callers can interleave WEEK / MONTH / YEAR rows with DAY rows
* downstream without branching on the source granularity.
*
* Compositional contract
* ----------------------
* `count / min / max / mean / sumValue` are linearly composable across
* any granularity — aggregating these stats over WEEK buckets returns
* the same numbers as aggregating the underlying DAY buckets or the
* raw measurements. `sd / slope / r2` are NOT linearly composable; the
* routed callers either fall back to live SQL for those or accept the
* per-bucket stat as-is. The auto-router is a granularity selector
* only — it does not attempt to reconstruct slope across coarser
* buckets.
*
* Coverage-miss semantics
* -----------------------
* Each reader returns `null` when the requested granularity yields
* zero rows for `(userId, type, since)`. The caller decides whether
* that is a real "no data" case (the user has not logged this type in
* the window) or a coverage miss the boot-backfill / worker has not
* caught up on. The default policy is to fall back to a finer
* granularity (MONTH → WEEK → DAY) before giving up — see
* `readBestGranularityRollups`.
*
* Scope vs. `rollup-read.ts`
* --------------------------
* `rollup-read.ts` carries the existing DAY-only aggregator. This
* module is deliberately separate so the WEEK / MONTH / YEAR wiring
* is reviewable in isolation and so the v1.4.39 W-SUM agent's
* concurrent edits to the writer side don't collide with the reader
* additions.
*/
import type {
MeasurementType,
RollupGranularity,
} from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
/**
* Normalised bucket row returned by every WMY reader. Mirrors the
* shape `readRollupBuckets` returns plus the `sumValue` column the
* v1.4.39 W-SUM agent added to `MeasurementRollup`. `sumValue` is
* `null` for rows that pre-date the column's introduction; the boot
* backfill fills it in alongside the other stats.
*/
export interface RollupBucketRow {
bucketStart: Date;
count: number;
mean: number;
sd: number | null;
slope: number | null;
r2: number | null;
sumValue: number | null;
minValue: number;
maxValue: number;
}
/**
* Per-granularity "this is the smallest window the granularity can
* meaningfully resolve" floor. Used by `readBestGranularityRollups`
* to route a requested window into the coarsest tier that still
* carries enough buckets for the caller to do something useful.
*
* - DAY → any window — 90 daily buckets for a 90-day window
* is already trivially cheap and the trend resolution
* is canonical
* - WEEK → > 90 days (~13 weekly buckets for a quarter)
* - MONTH → > 180 days (~6 monthly buckets, enough trend signal
* for a half-year view; smaller windows benefit more
* from DAY-bucket granularity than coarse-grained
* averaging)
* - YEAR → > 730 days (≥ 2 yearly buckets — anything below 2 y
* collapses to one bucket and carries no slope signal)
*
* The pinned routing the v1.5 multi-year trend card relies on:
* 90 d → DAY (90 buckets)
* 365 d → MONTH (12 buckets)
* 1095 d → YEAR (3 buckets)
*
* The floors are conservative on purpose — coarser tiers only
* activate when the row-count savings actually justify trading the
* finer trend resolution.
*/
const GRANULARITY_FLOORS: Array<{
granularity: RollupGranularity;
minWindowDays: number;
}> = [
{ granularity: "YEAR", minWindowDays: 731 },
{ granularity: "MONTH", minWindowDays: 181 },
{ granularity: "WEEK", minWindowDays: 91 },
{ granularity: "DAY", minWindowDays: 0 },
];
/**
* Read the trailing WEEK buckets for `(userId, type)` since `since`.
* Returns `null` when no buckets exist in the window — the caller
* decides whether to fall back to a finer granularity or to live SQL.
*/
export async function readWeekRollups(
userId: string,
type: MeasurementType,
since: Date,
): Promise<RollupBucketRow[] | null> {
return readGranularity(userId, type, "WEEK", since);
}
/**
* Read the trailing MONTH buckets for `(userId, type)` since `since`.
* Returns `null` on coverage miss.
*/
export async function readMonthRollups(
userId: string,
type: MeasurementType,
since: Date,
): Promise<RollupBucketRow[] | null> {
return readGranularity(userId, type, "MONTH", since);
}
/**
* Read the trailing YEAR buckets for `(userId, type)` since `since`.
* Returns `null` on coverage miss.
*/
export async function readYearRollups(
userId: string,
type: MeasurementType,
since: Date,
): Promise<RollupBucketRow[] | null> {
return readGranularity(userId, type, "YEAR", since);
}
/**
* Pick the largest granularity that can still resolve the requested
* `windowDays` window — WEEK for >14 d, MONTH for >62 d, YEAR for
* >730 d. Falls back to a finer granularity on coverage miss so a
* user with WEEK / MONTH coverage but no YEAR buckets (e.g. a tenant
* who joined less than two years ago) still gets a usable trend
* series.
*
* Returns the granularity the helper resolved against plus the row
* shape `readWeekRollups` / `readMonthRollups` / `readYearRollups`
* return. `null` when no granularity yields any buckets in the
* window — the caller is expected to short-circuit to "no data" or
* to live SQL.
*/
export async function readBestGranularityRollups(
userId: string,
type: MeasurementType,
windowDays: number,
): Promise<{
granularity: RollupGranularity;
rows: RollupBucketRow[];
} | null> {
if (!Number.isFinite(windowDays) || windowDays <= 0) return null;
const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1000);
// Walk the floors from coarsest to finest and return the first
// granularity whose floor the window clears AND which has coverage
// for `(userId, type, since)`. The `if rows == null` fall-through
// is what makes the helper resilient to partial coverage.
for (const floor of GRANULARITY_FLOORS) {
if (windowDays < floor.minWindowDays) continue;
const rows = await readGranularity(userId, type, floor.granularity, since);
if (rows && rows.length > 0) {
return { granularity: floor.granularity, rows };
}
}
return null;
}
/**
* Linearly compose `count / min / max / mean / sum` across an array
* of bucket rows. Mirrors `rollup-read.ts:aggregateBuckets` but
* carries `sumValue` so cumulative-metric callers (steps, energy,
* distance) can read the window total without re-deriving from
* `mean * count`. SD / slope / r2 are intentionally omitted — those
* stats do not compose across coarser buckets and the consumers that
* need them stay on live SQL.
*/
export function aggregateWmyBuckets(rows: RollupBucketRow[]): {
count: number;
min: number | null;
max: number | null;
mean: number | null;
sum: number | null;
} {
if (rows.length === 0) {
return { count: 0, min: null, max: null, mean: null, sum: null };
}
let totalCount = 0;
let sumWeighted = 0;
let sumCumulative = 0;
let sawSum = false;
let min = Infinity;
let max = -Infinity;
for (const row of rows) {
totalCount += row.count;
sumWeighted += row.count * row.mean;
if (row.sumValue !== null && Number.isFinite(row.sumValue)) {
sumCumulative += row.sumValue;
sawSum = true;
}
if (row.minValue < min) min = row.minValue;
if (row.maxValue > max) max = row.maxValue;
}
if (totalCount === 0) {
return { count: 0, min: null, max: null, mean: null, sum: null };
}
return {
count: totalCount,
min: Number.isFinite(min) ? min : null,
max: Number.isFinite(max) ? max : null,
mean: sumWeighted / totalCount,
sum: sawSum ? sumCumulative : null,
};
}
/**
* Internal — shared `findMany` projection. Returns `null` when the
* window has zero rows so the caller can branch on coverage miss
* without a separate count round-trip.
*/
async function readGranularity(
userId: string,
type: MeasurementType,
granularity: RollupGranularity,
since: Date,
): Promise<RollupBucketRow[] | null> {
// Bounded `findMany`: `(userId, type, granularity, bucketStart)`
// is the composite primary key so the planner picks the index path
// every time. `bucketStart >= since` is the same shape
// `readRollupBuckets` uses; we don't carry an upper bound because
// the helpers are always reading "trailing window to now".
const rows = await prisma.measurementRollup.findMany({
where: {
userId,
type,
granularity,
bucketStart: { gte: since },
},
orderBy: { bucketStart: "asc" },
select: {
bucketStart: true,
count: true,
mean: true,
sd: true,
slope: true,
r2: true,
sumValue: true,
minValue: true,
maxValue: true,
},
});
if (rows.length === 0) return null;
return rows.map((r) => ({
bucketStart: r.bucketStart,
count: r.count,
mean: r.mean,
sd: r.sd,
slope: r.slope,
r2: r.r2,
sumValue: r.sumValue,
minValue: r.minValue,
maxValue: r.maxValue,
}));
}