fix(workouts): resolve duplicate clusters the same way on every surface

The cross-source picker anchors each duplicate cluster on its first start,
so which cluster a workout lands in depends on the workouts around it. The
detail route still read the old fixed five-minute clock slot, and every
other reader handed the picker only the rows of its own range. The detail
of a twin that straddled a slot boundary declared itself canonical while
the list hid it, and runs at 09:58, 10:02 and 10:06 were grouped one way by
a read starting at 09:55 and another by a read starting at 10:00.

Every reader that decides which workout is canonical (list, detail and its
previous session, activity calendar, day view, doctor report, Coach,
briefing and correlation blocks, strain, per-sport context, the activity
insight's history, the batch write) now reads through one windowed reader.
It reads a duplicate window past the end of the range and reaches back
until every sport in the range starts at a workout that is an anchor
whatever came before it, then picks over everything read and keeps the
rows that start inside the range. The per-sport baseline and the insight
history leave out the whole cluster of the current session instead of the
row alone, which left its twin behind as a session of its own. The batch
write clusters its rows together with the stored workouts around them and
drops only a row that loses to another row of the same batch.

A property test checks the windowed read against a whole-history read for
random dense histories and ranges; route tests pin list, detail, deep link,
previous session and the batch write against the database.
This commit is contained in:
Marc-André Bombeck committed 2026-10-22 18:21:02 +02:00
1 parent 3decab47a0
commit 466dfb3785
33 files changed
+1486 -472

No files matched your search

@@ -1,7 +1,7 @@
{
"$comment": "Production files over 800 lines and their length. Maintained by src/__tests__/source-size-ratchet.test.ts.",
"count": 124,
"total": 146512,
"count": 123,
"total": 145651,
"entries": {
"app/api/dashboard/summary/route.ts": 1032,
"app/api/documents/inbound/route.ts": 811,
@@ -10,7 +10,7 @@
"app/api/measurements/route.ts": 938,
"app/api/medications/[id]/route.ts": 1281,
"app/api/medications/intake/bulk/route.ts": 1044,
"app/api/workouts/batch/route.ts": 971,
"app/api/workouts/batch/route.ts": 958,
"app/medications/page-client.tsx": 839,
"app/page-client.tsx": 2324,
"components/admin/backups-section.tsx": 1462,
@@ -44,7 +44,7 @@
"lib/ai/coach/coach-prose-grounding.ts": 1079,
"lib/ai/coach/persistence.ts": 1219,
"lib/ai/coach/results/metric-table-tool.ts": 1102,
"lib/ai/coach/snapshot.ts": 1362,
"lib/ai/coach/snapshot.ts": 1347,
"lib/ai/coach/stream-events.ts": 817,
"lib/ai/coach/tools/executor.ts": 1522,
"lib/ai/coach/turn/model.ts": 820,
@@ -65,7 +65,7 @@
"lib/daily/today-overview.ts": 838,
"lib/dashboard-layout.ts": 971,
"lib/dashboard/snapshot.ts": 1550,
"lib/day/records.ts": 1175,
"lib/day/records.ts": 1174,
"lib/doctor-report/collect.ts": 803,
"lib/export/backup-plan.ts": 853,
"lib/export/coach-backup.ts": 1070,
@@ -90,7 +90,6 @@
"lib/insights/mood-aggregates.ts": 1055,
"lib/insights/mood-status.ts": 814,
"lib/insights/status-cache.ts": 812,
"lib/insights/strain-score.ts": 832,
"lib/integrations/status.ts": 1445,
"lib/jobs/apple-health-import-worker.ts": 863,
"lib/jobs/backup-restore.ts": 888,
@@ -1,7 +1,7 @@
{
"$comment": "Production functions over 200 lines, keyed \"file :: name\", and their length. Maintained by src/__tests__/source-size-ratchet.test.ts.",
"count": 411,
"total": 148369,
"total": 148324,
"entries": {
"app/achievements/page.tsx :: AchievementsPage": 206,
"app/api/admin/backups/upload/route.ts :: apiHandler(arg)": 314,
@@ -64,8 +64,8 @@
"app/api/sync/changes/route.ts :: apiHandler(arg)": 427,
"app/api/user/ai-provider/route.ts :: apiHandler(arg) #2": 252,
"app/api/withings/callback/route.ts :: apiHandler(arg)": 247,
"app/api/workouts/[id]/route.ts :: apiHandler(arg)": 313,
"app/api/workouts/batch/route.ts :: postBatch": 722,
"app/api/workouts/[id]/route.ts :: apiHandler(arg)": 297,
"app/api/workouts/batch/route.ts :: postBatch": 709,
"app/auth/login/page.tsx :: LoginPage": 576,
"app/auth/register/page.tsx :: RegisterPage": 285,
"app/coach/conversations/page.tsx :: CoachConversationsBody": 249,
@@ -287,7 +287,7 @@
"lib/ai/anthropic-client.ts :: generateCompletion": 294,
"lib/ai/coach/cycle-snapshot.ts :: buildCycleSnapshotBlock": 218,
"lib/ai/coach/glp1-snapshot.ts :: buildGlp1SnapshotBlock": 218,
"lib/ai/coach/snapshot.ts :: buildCoachSnapshotImpl": 898,
"lib/ai/coach/snapshot.ts :: buildCoachSnapshotImpl": 882,
"lib/ai/coach/tools/loop.ts :: runCoachToolLoop": 438,
"lib/ai/coach/turn/model.ts :: runTurnModel": 560,
"lib/ai/coach/turn/pipeline.ts :: runTurn": 274,
+2 -2
View File
@@ -1,7 +1,7 @@
{
"$comment": "as never casts in tests, per test file under src/. Maintained by src/__tests__/test-realism-ratchet.test.ts.",
"count": 524,
"total": 5496,
"total": 5495,
"entries": {
"__tests__/api/auth/login/mfa-branch.test.ts": 10,
"__tests__/api/auth/mfa/verify.test.ts": 9,
@@ -253,7 +253,7 @@
"app/api/withings/credentials/__tests__/route.test.ts": 4,
"app/api/withings/webhook/__tests__/route.test.ts": 26,
"app/api/withings/webhook/[token]/__tests__/route.test.ts": 8,
"app/api/workouts/__tests__/batch-create.test.ts": 14,
"app/api/workouts/__tests__/batch-create.test.ts": 13,
"app/api/workouts/__tests__/canonical-dedup.test.ts": 20,
"app/api/workouts/batch/__tests__/unstable-external-id.test.ts": 4,
"app/c/[token]/__tests__/report-download.test.ts": 11,
@@ -1,7 +1,7 @@
{
"$comment": "Comment lines that open with a release version, per file under src/. Maintained by src/__tests__/version-stamp-ratchet.test.ts.",
"count": 2959,
"total": 10521,
"total": 10520,
"entries": {
"__tests__/account-payload-consumer-guard.test.ts": 2,
"__tests__/acting-account-boundary-guard.test.ts": 7,
@@ -1710,7 +1710,7 @@
"lib/ai/coach/snapshot-cache.ts": 2,
"lib/ai/coach/snapshot-prelude.ts": 17,
"lib/ai/coach/snapshot-series.ts": 5,
"lib/ai/coach/snapshot.ts": 42,
"lib/ai/coach/snapshot.ts": 41,
"lib/ai/coach/source-measurement-types.ts": 1,
"lib/ai/coach/suggest-action.ts": 1,
"lib/ai/coach/suggest-gate.ts": 1,
@@ -31,11 +31,21 @@ const SRC = join(process.cwd(), "src");
const PICKER = "lib/measurements/pick-canonical-workout-rows.ts";
/**
* Every production call site of the picker, frozen.
* The only module that hands rows to the picker: the windowed reader, which
* picks over rows it read with the duplicate-window margin. Every surface goes
* through it, and its output types make a read without the margin a compile
* error. The strain engine's per-cluster impulse sum lives there too and is
* handed the rows of the engine's own windowed read.
*/
const PICKER_CALLERS = ["lib/workouts/canonical-read.ts"];
/**
* Every production read that decides which workout is canonical, frozen.
*
* Adding a surface that collapses workouts is a deliberate act: it must fetch
* the identity fields or it silently disagrees with every other surface. Adding
* the file here is the acknowledgement.
* Adding a surface that collapses workouts is a deliberate act: it must read
* through `readWorkoutsAroundRange` and fetch the identity fields, or it
* silently disagrees with every other surface. Adding the file here is the
* acknowledgement. The value is the file that owns the read's `select`.
*/
const IDENTITY_OWNER: Record<string, string> = {
"app/api/workouts/[id]/route.ts": "app/api/workouts/[id]/route.ts",
@@ -49,15 +59,15 @@ const IDENTITY_OWNER: Record<string, string> = {
// The activity calendar counts workouts per day; a session two devices
// recorded must count once there, as it does in the list.
"lib/activity/calendar-read.ts": "lib/activity/calendar-read.ts",
// The only indirection in the set. The Coach block is handed rows it does not
// read itself; the snapshot builder fetches them in parallel with every other
// block's data. Recording the owner here rather than assuming the call site
// owns its own select is the whole point of this map.
"lib/ai/coach/snapshot-blocks/workouts-block.ts": "lib/ai/coach/snapshot.ts",
// The write path: the batch route runs the same picker over the rows it is
// about to insert, so a duplicate inside one batch is dropped by the rule
// the list later applies.
"app/api/workouts/batch/route.ts": "app/api/workouts/batch/route.ts",
// The Coach block is handed rows it does not read itself; the snapshot
// builder fetches them through this read in parallel with every other
// block's data.
"lib/ai/coach/snapshot-blocks/workouts-read.ts":
"lib/ai/coach/snapshot-blocks/workouts-read.ts",
// The write path: the batch route clusters the rows it is about to insert
// together with the stored rows around them, so a duplicate is dropped by
// the rule the list later applies.
"lib/workouts/batch-dedup.ts": "lib/workouts/batch-dedup.ts",
// The day-total training impulse, the briefing's workout tally and the day
// view's workout section: each counted a session synced by two services
// twice while the list showed it once.
@@ -72,10 +82,16 @@ const IDENTITY_OWNER: Record<string, string> = {
/**
* How a call site proves its rows carry the duration. A read selects the
* column; the batch route maps it off the row it computed for the insert.
* column; the batch route also maps it off the row it computed for the insert.
*/
const IDENTITY_PROOF: Record<string, string> = {
"app/api/workouts/batch/route.ts": "durationSec: p.row.durationSec",
const IDENTITY_PROOF: Record<string, string[]> = {
// These two select `WORKOUT_PICK_SELECT`, whose duration is checked below.
"lib/day/records.ts": ["select: WORKOUT_PICK_SELECT"],
"lib/insights/correlation-channel-series.ts": ["select: WORKOUT_PICK_SELECT"],
"lib/workouts/batch-dedup.ts": [
"durationSec: true",
"durationSec: p.row.durationSec",
],
};
const EXPECTED_CALL_SITES = Object.keys(IDENTITY_OWNER).sort();
@@ -93,17 +109,13 @@ function read(rel: string): string {
}
/**
* Lines that actually invoke the picker. Comment lines are excluded: a
* docblock that names the picker is documentation rather than a call.
* Lines that actually invoke `call`. Comment lines are excluded: a docblock
* that names the function is documentation rather than a call.
*/
function invokesPicker(source: string): boolean {
function invokes(source: string, call: string): boolean {
return source
.split("\n")
.some(
(line) =>
line.includes("pickCanonicalWorkoutRows(") &&
!/^\s*(\*|\/\/|\/\*)/.test(line),
);
.some((line) => line.includes(call) && !/^\s*(\*|\/\/|\/\*)/.test(line));
}
describe("the picker's call-site set is frozen", () => {
@@ -114,13 +126,29 @@ describe("the picker's call-site set is frozen", () => {
expect(sourceFiles().length).toBeGreaterThan(1500);
});
it("has exactly the call sites this file acknowledges", () => {
it("hands rows to the picker only from the windowed reader", () => {
const found = sourceFiles()
.filter((rel) => rel !== PICKER)
.filter((rel) => invokesPicker(read(rel)));
.filter((rel) => invokes(read(rel), "pickCanonicalWorkoutRows("));
expect(found).toEqual(PICKER_CALLERS);
});
it("has exactly the windowed reads this file acknowledges", () => {
const found = sourceFiles()
.filter((rel) => rel !== "lib/workouts/canonical-read.ts")
.filter((rel) => invokes(read(rel), "readWorkoutsAroundRange("));
expect(found).toEqual(EXPECTED_CALL_SITES);
});
it("scores strain only on the sessions of the windowed range", () => {
// The strain engine sums impulses over the rows of its windowed read; it
// must keep the sessions its range owns, not every cluster the margin read.
expect(read("lib/insights/strain-score.ts")).toContain(
"(at) => startsInRange(workouts.range, at)",
);
});
});
describe("every call site fetches the session identity", () => {
@@ -130,9 +158,20 @@ describe("every call site fetches the session identity", () => {
// rows came from. Coarse in the safe direction — it can only fail to catch
// a second unrelated select in the same file, never pass a caller that
// fetches no duration at all.
expect(read(IDENTITY_OWNER[rel])).toContain(
IDENTITY_PROOF[rel] ?? "durationSec: true",
for (const proof of IDENTITY_PROOF[rel] ?? ["durationSec: true"]) {
expect(read(IDENTITY_OWNER[rel])).toContain(proof);
}
});
});
describe("the shared pick select carries the identity", () => {
it("selects durationSec", () => {
const reader = read("lib/workouts/canonical-read.ts");
const select = reader.slice(
reader.indexOf("export const WORKOUT_PICK_SELECT"),
reader.indexOf("} as const;"),
);
expect(select).toContain("durationSec: true");
});
});