fix(medications): keep an extra Apple Health dose off a slot that already holds one

A HealthKit dose event binds to a slot by window band, and a weekly
schedule's band reaches a day either side of its slot. An extra dose
logged the day after a scheduled one landed on that slot and overwrote it
last-write-wins: the slot's time changed and the extra dose was stored
nowhere. An external dose record whose band slot already carries a
different take is now recorded as its own unscheduled dose.

The dose history now lets the take stored on a slot claim it before an
extra dose stored on its own instant, instead of following the order the
rows were read in, so the extra dose reads as off-schedule.

src/app/api/medications/intake/bulk/__tests__/route.test.ts

@@ -1380,9 +1380,11 @@ describe("POST /api/medications/intake/bulk — v1.28 Apple Health dose events",
   });
 
   it("stamps the externalId onto the pending slot row when the Apple dose converges by band", async () => {
-    // Dedup pre-check first (empty), then the canonical-slot find returns
-    // the worker-minted pending REMINDER row for the 19:00 slot.
+    // Dedup pre-check first (empty), then the held-dose probe (no take on
+    // the slot yet), then the canonical-slot find returns the worker-minted
+    // pending REMINDER row for the 19:00 slot.
     vi.mocked(prisma.medicationIntakeEvent.findMany)
+      .mockResolvedValueOnce([] as never)
       .mockResolvedValueOnce([] as never)
       .mockResolvedValueOnce([
         {

src/app/api/medications/intake/bulk/route.ts

@@ -65,6 +65,7 @@ import {
   resolveForcedSlotForWrite,
   resolveSlotForWriteByBand,
   resolveSlotInstantForWrite,
+  slotHeldByAnotherDose,
 } from "@/lib/medications/scheduling/slot-upsert";
 import { resolveInjectionSiteForWrite } from "@/lib/medications/injection-site-write";
 import {
@@ -338,6 +339,9 @@ async function postBulk(request: NextRequest): Promise<Response> {
   let inserted = 0;
   let updated = 0;
   let duplicates = 0;
+  // External dose records kept as their own unscheduled dose because their
+  // band slot already carried a different one.
+  let extraDosesUnscheduled = 0;
   const skipped: Array<{ index: number; reason: string }> = [];
   const unstableShapes: UnstableExternalIdShape[] = [];
   // v1.4.39 W-MED — collect distinct `(medicationId, dayKey)` pairs
@@ -443,6 +447,9 @@ async function postBulk(request: NextRequest): Promise<Response> {
       // a band decision. Pending echoes / skips carry no decision
       // (undefined → the upsert leaves an existing USER_PIN untouched).
       let attributionSource: "AUTO" | "USER_PIN" | undefined;
+      // Set when the band slot is held by a different dose and this take is
+      // recorded unscheduled; it must not converge onto any slot row below.
+      let heldByAnotherDose = false;
       if (isExplicitTaken && entry.forceSlotInstant !== undefined) {
         canonicalSlot = await resolveForcedSlotForWrite({
           userId: user.id,
@@ -486,6 +493,26 @@ async function postBulk(request: NextRequest): Promise<Response> {
         });
         canonicalSlot = attribution.slotInstant;
         attributionSource = "AUTO";
+        // An external dose record (a HealthKit dose event) whose band slot
+        // already carries a different recorded dose is an extra dose, not a
+        // correction of that one. Converging would overwrite the slot's
+        // take last-write-wins and the extra dose would exist nowhere; it is
+        // recorded as its own unscheduled dose instead.
+        if (
+          canonicalSlot !== null &&
+          entry.externalId !== undefined &&
+          (await slotHeldByAnotherDose({
+            userId: user.id,
+            medicationId: entry.medicationId,
+            canonicalSlot,
+            takenAt: entry.takenAt as Date,
+            externalId: entry.externalId,
+          }))
+        ) {
+          canonicalSlot = null;
+          heldByAnotherDose = true;
+          extraDosesUnscheduled += 1;
+        }
       } else if (isExplicitSkip && entry.scheduledFor === undefined) {
         // v1.16.9 — a slot-less deliberate skip resolves by band
         // membership on the skip moment, exactly like a take does. The
@@ -666,6 +693,7 @@ async function postBulk(request: NextRequest): Promise<Response> {
         // late-morning dose consuming the evening slot). It records
         // standalone (ad-hoc) instead.
         const existingSlotRow =
+          !heldByAnotherDose &&
           entry.scheduledFor !== undefined &&
           mayConvergeOntoSuppliedSlot({
             skipped: entry.skipped,
@@ -878,6 +906,7 @@ async function postBulk(request: NextRequest): Promise<Response> {
       updated,
       duplicates,
       skipped: skipped.length,
+      extra_doses_unscheduled: extraDosesUnscheduled,
       ...(unstableShapes.length > 0
         ? unstableExternalIdMeta("medication.intake.bulk", unstableShapes)
         : {}),

src/lib/medications/scheduling/__tests__/extra-dose.test.ts

@@ -0,0 +1,114 @@
+/**
+ * An extra dose next to a slot that already carries one.
+ *
+ * Two ends: the write path keeps a different external dose record off a slot
+ * that is already taken (`isAnotherDose`), and the read ledger lets the dose
+ * stored on the slot claim it before an extra one stored on its own instant,
+ * whatever order the rows were read in.
+ */
+import { describe, expect, it } from "vitest";
+
+import { buildSlotBands, type SlotWindowInput } from "../attribution";
+import { reconstructDoseHistory, type HistoryIntake } from "../dose-history";
+import { SAME_DOSE_TOLERANCE_MS, isAnotherDose } from "../slot-upsert";
+
+const MIN = 60_000;
+const t0 = new Date("2026-06-09T20:00:00Z");
+const plus = (minutes: number) => new Date(t0.getTime() + minutes * MIN);
+
+describe("isAnotherDose", () => {
+  it("a slot with nothing taken is never held by another dose", () => {
+    expect(
+      isAnotherDose(
+        { takenAt: null, externalId: null },
+        { takenAt: plus(600), externalId: "hk-2" },
+      ),
+    ).toBe(false);
+  });
+
+  it("the same external record is the same dose", () => {
+    expect(
+      isAnotherDose(
+        { takenAt: t0, externalId: "hk-1" },
+        { takenAt: plus(600), externalId: "hk-1" },
+      ),
+    ).toBe(false);
+  });
+
+  it("two external records a day apart are two doses", () => {
+    expect(
+      isAnotherDose(
+        { takenAt: t0, externalId: "hk-1" },
+        { takenAt: plus(24 * 60 + 22), externalId: "hk-2" },
+      ),
+    ).toBe(true);
+  });
+
+  it("two external records within a minute are one dose entered twice", () => {
+    expect(
+      isAnotherDose(
+        { takenAt: t0, externalId: "hk-1" },
+        { takenAt: new Date(t0.getTime() + 30_000), externalId: "hk-2" },
+      ),
+    ).toBe(false);
+  });
+
+  it("a take with no external record merges within the tolerance only", () => {
+    const held = { takenAt: t0, externalId: null };
+    expect(
+      isAnotherDose(held, {
+        takenAt: new Date(t0.getTime() + SAME_DOSE_TOLERANCE_MS),
+        externalId: "hk-2",
+      }),
+    ).toBe(false);
+    expect(isAnotherDose(held, { takenAt: plus(30), externalId: "hk-2" })).toBe(
+      true,
+    );
+  });
+});
+
+describe("reconstructDoseHistory: the slot's own dose claims the slot", () => {
+  const slot: SlotWindowInput = {
+    at: t0,
+    timeOfDay: "22:00",
+    onTimeStart: plus(-60),
+    onTimeEnd: plus(60),
+    lateGraceMs: 180 * MIN,
+  };
+  const bands = buildSlotBands([slot]);
+  const onSlot: HistoryIntake = {
+    id: "on-slot",
+    scheduledFor: t0,
+    takenAt: plus(5),
+    skipped: false,
+  };
+  const extra: HistoryIntake = {
+    id: "extra",
+    scheduledFor: plus(30),
+    takenAt: plus(30),
+    skipped: false,
+  };
+
+  it.each([
+    ["slot row first", [onSlot, extra]],
+    ["extra row first (newest scheduledFor first)", [extra, onSlot]],
+  ])("%s", (_label, intakes) => {
+    const rows = reconstructDoseHistory(bands, intakes, plus(600), null);
+    const slotRow = rows.find((row) => row.kind === "slot");
+    const adHoc = rows.filter((row) => row.kind === "ad_hoc");
+    expect(slotRow?.intake?.id).toBe("on-slot");
+    expect(adHoc.map((row) => row.intake?.id)).toEqual(["extra"]);
+  });
+
+  it("among takes not stored on the slot, the nearer one claims it", () => {
+    const far: HistoryIntake = { ...extra, id: "far" };
+    const near: HistoryIntake = {
+      id: "near",
+      scheduledFor: plus(10),
+      takenAt: plus(10),
+      skipped: false,
+    };
+    const rows = reconstructDoseHistory(bands, [far, near], plus(600), null);
+    expect(rows.find((row) => row.kind === "slot")?.intake?.id).toBe("near");
+  });
+});

src/lib/medications/scheduling/dose-history.ts

@@ -273,8 +273,33 @@ export function reconstructDoseHistory(
     }
   }
 
-  for (const i of taken) {
+  // The best fit claims a slot first, whatever order the caller read the rows
+  // in. A take the write path stored ON the slot it attributes to goes before
+  // one stored on its own instant (an extra dose recorded unscheduled), then
+  // on-time before late, then the nearer take. Processing in the caller's
+  // order (newest `scheduledFor` first on the history route) let an extra dose
+  // logged half an hour after the slot claim it and pushed the slot's own
+  // dose out as the off-schedule one.
+  const ranked = taken.map((i) => {
     const matched = attributeIntakeToSlot(i.takenAt as Date, bands);
+    if (!matched) return { i, matched, key: [2, 0, 0] as const };
+    const storedOnSlot =
+      Math.abs(i.scheduledFor.getTime() - matched.band.at.getTime()) <=
+      ANCHOR_EPSILON_MS;
+    return {
+      i,
+      matched,
+      key: [
+        storedOnSlot ? 0 : 1,
+        matched.status === "on_time" ? 0 : 1,
+        Math.abs((i.takenAt as Date).getTime() - matched.band.at.getTime()),
+      ] as const,
+    };
+  });
+  ranked.sort(
+    (a, b) => a.key[0] - b.key[0] || a.key[1] - b.key[1] || a.key[2] - b.key[2],
+  );
+  for (const { i, matched } of ranked) {
     if (matched && !claim.has(matched.band)) {
       claim.set(matched.band, {
         intake: i,

src/lib/medications/scheduling/slot-upsert.ts

@@ -746,6 +746,79 @@ export async function findPinConflict(input: {
   });
 }
 
+/**
+ * How far apart two recorded takes of one slot may sit and still be the same
+ * dose logged twice (a tap in HealthLog and an entry in another app a few
+ * minutes later). Further apart, they are two doses.
+ */
+export const SAME_DOSE_TOLERANCE_MS = 15 * 60_000;
+
+/**
+ * Is `held` (the take a slot already carries) a different dose from the
+ * incoming external dose record?
+ *
+ * Band attribution maps a take to the slot whose band contains it, and a
+ * weekly schedule's band reaches a day either side of the slot. Without this
+ * check an extra dose logged the day after a Tuesday dose landed on the
+ * Tuesday slot and overwrote it last-write-wins: the Tuesday time was
+ * replaced and the extra dose existed nowhere.
+ *
+ *   - Nothing taken on the slot yet (pending, skipped): not another dose, the
+ *     incoming take is the slot's dose.
+ *   - The same external record: the same dose.
+ *   - Two different external records: different doses, unless they sit within
+ *     a minute of each other, which is a double entry rather than two doses.
+ *   - Otherwise (the held take has no external record): the same dose within
+ *     {@link SAME_DOSE_TOLERANCE_MS}, a different one beyond it.
+ */
+export function isAnotherDose(
+  held: { takenAt: Date | null; externalId: string | null },
+  incoming: { takenAt: Date; externalId: string | null },
+): boolean {
+  if (held.takenAt === null) return false;
+  if (held.externalId !== null && held.externalId === incoming.externalId) {
+    return false;
+  }
+  const gap = Math.abs(held.takenAt.getTime() - incoming.takenAt.getTime());
+  if (held.externalId !== null && incoming.externalId !== null) {
+    return gap > 60_000;
+  }
+  return gap > SAME_DOSE_TOLERANCE_MS;
+}
+
+/**
+ * Does the slot at `canonicalSlot` already carry a recorded take that is a
+ * different dose from the incoming one (see {@link isAnotherDose})? The
+ * caller records the incoming take as its own unscheduled dose instead of
+ * converging onto the slot.
+ */
+export async function slotHeldByAnotherDose(input: {
+  userId: string;
+  medicationId: string;
+  canonicalSlot: Date;
+  takenAt: Date;
+  externalId: string | null;
+  client?: Pick<PrismaClient, "medicationIntakeEvent">;
+}): Promise<boolean> {
+  const client = input.client ?? defaultPrisma;
+  const rows = await client.medicationIntakeEvent.findMany({
+    where: {
+      userId: input.userId,
+      medicationId: input.medicationId,
+      scheduledFor: input.canonicalSlot,
+      deletedAt: null,
+      takenAt: { not: null },
+    },
+    select: { takenAt: true, externalId: true },
+  });
+  return rows.some((row) =>
+    isAnotherDose(row, {
+      takenAt: input.takenAt,
+      externalId: input.externalId,
+    }),
+  );
+}
+
 export interface ResolveForcedSlotInput {
   userId: string;
   medicationId: string;