fix(sync): expire delta cursors issued before a restore or a data wipe

A restore writes rows back with their original updatedAt, behind every
paired client's watermarks, and removes rows without leaving tombstones.
A client that kept its cursor would miss both on its next incremental
pull. The same holds after the person deletes all their data.

`users.sync_reset_at` (migration 0363) records when the record was last
replaced: the restore stamps it as its last write and again right after
the commit, the per-account and the admin wipe stamp it inside their
transactions. Cursors now carry the time they were issued, and
/api/sync/changes answers its existing `cursorExpired` to a cursor issued
before the reset, or one without an issue time on an account that has
one. The comparison is on the issue time, because after a restore a
freshly drained cursor still carries old watermarks.

src/lib/data-wipe/wipe-plan.ts

@@ -469,6 +469,8 @@ export const USER_KEPT_FIELDS: Readonly<Record<string, string>> = {
     "the version of the medical disclaimer the account acknowledged",
   documentQuotaBytes:
     "a per-account storage quota set by the operator, not by the person",
+  syncResetAt:
+    "sync bookkeeping, not record content: the wipe sets it to its own time rather than clearing it, so a paired client's delta cursor from before the wipe is refused and the client starts over",
 };
 
 /**

src/lib/export/__tests__/restore-backup-round-trip.test.ts

@@ -759,7 +759,10 @@ describe("backup round trip — export, wire schema, restore", () => {
       });
 
       const userUpdate = written.find(
-        (w) => w.model === "user" && w.op === "update",
+        (w) =>
+          w.model === "user" &&
+          w.op === "update" &&
+          "insightsCachedText" in w.data,
       );
       expect(
         userUpdate,
@@ -798,8 +801,13 @@ describe("backup round trip — export, wire schema, restore", () => {
       // whether the restore over-invalidates on a genuine no-op.
       const { written: writtenUnchanged } = await roundTrip(liveSeed, payload);
 
+      // The restore also stamps the account's sync reset; only an update
+      // that touches the cached briefing is what this asks about.
       const userUpdate = writtenUnchanged.find(
-        (w) => w.model === "user" && w.op === "update",
+        (w) =>
+          w.model === "user" &&
+          w.op === "update" &&
+          "insightsCachedText" in w.data,
       );
       expect(
         userUpdate,

src/lib/export/restore-backup.ts

@@ -103,6 +103,7 @@ import { restoreEcgData } from "@/lib/export/ecg-backup";
 import { restoredMedicationCreatedAt } from "@/lib/export/medication-created-at";
 import { invalidateUserData } from "@/lib/cache/invalidate";
 import { TOMBSTONE_RETENTION_DAYS } from "@/lib/auth/native-client";
+import { stampSyncReset } from "@/lib/sync/reset";
 import {
   classifyRestoreFailure,
   RESTORE_FAILURE_CAUSE_MESSAGES,
@@ -2412,6 +2413,11 @@ export async function restoreBackup(
           foreignBefore,
           await countForeignReferences(tx, ownerId, tenantEdges),
         );
+        // Paired clients' delta cursors are no longer valid (see
+        // `User.syncResetAt`). Stamped as the last write, so it commits with
+        // the data, and stamped again right after the commit below to cover
+        // a cursor issued while this transaction was still running.
+        await stampSyncReset(tx, ownerId);
         progress.sectionsDone = RESTORE_SECTION_STEPS.length;
         report("sections", true);
         return {
@@ -2479,6 +2485,22 @@ export async function restoreBackup(
     );
   }
 
+  // A pull that started before the commit read the pre-restore rows and may
+  // have been issued a cursor after the stamp inside the transaction. The
+  // second stamp expires that one too; it can only expire more cursors, so a
+  // failure here costs a client at most one extra incremental page.
+  try {
+    await stampSyncReset(prisma, ownerId);
+  } catch (err) {
+    annotate({
+      meta: {
+        restore_sync_reset_failed: true,
+        restore_sync_reset_error:
+          err instanceof Error ? err.message : String(err),
+      },
+    });
+  }
+
   const { cleared, skipped, expiredTombstonesSkipped } = outcome;
   const measurementsRestored =
     streamed.measurementCount - expiredTombstonesSkipped;

src/lib/openapi/routes/sync.ts

@@ -257,7 +257,7 @@ export const syncChangesResponse = z
     cursorExpired: z
       .boolean()
       .describe(
-        "True when the supplied cursor predates tombstone retention — drop the cursor and do a clean initial sync.",
+        "True when the supplied cursor predates tombstone retention, or was issued before the account's data was last restored from a backup or deleted — drop the cursor and do a clean initial sync.",
       ),
     changes: z.object({
       measurements: z.object({

src/lib/sync/__tests__/cursor.test.ts

@@ -3,7 +3,12 @@
  */
 import { describe, it, expect } from "vitest";
 
-import { encodeCursor, decodeCursor, type SyncCursor } from "../cursor";
+import {
+  encodeCursor,
+  decodeCursor,
+  decodeCursorIssuedAt,
+  type SyncCursor,
+} from "../cursor";
 
 describe("sync cursor codec", () => {
   it("round-trips a per-domain keyset map through encode/decode", () => {
@@ -112,3 +117,20 @@ describe("sync cursor codec", () => {
     });
   });
 });
+
+describe("cursor issue time (sync reset)", () => {
+  const cursor: SyncCursor = {
+    measurements: { updatedAtMs: 1_000, id: "clx0m" },
+  };
+
+  it("round-trips the issue time beside the watermarks", () => {
+    const token = encodeCursor(cursor, 1_790_000_000_000);
+    expect(decodeCursorIssuedAt(token)).toBe(1_790_000_000_000);
+    expect(decodeCursor(token)).toEqual(cursor);
+  });
+
+  it("reads no issue time from a token that carries none", () => {
+    expect(decodeCursorIssuedAt(encodeCursor(cursor))).toBeNull();
+    expect(decodeCursorIssuedAt("not a token")).toBeNull();
+  });
+});

src/lib/sync/cursor.ts

@@ -63,14 +63,27 @@ const CURSOR_VERSION = 2;
  *  `cycleDays`/`cycles` domains; they decode as absent (fresh scan). */
 const SUPPORTED_CURSOR_VERSIONS: readonly number[] = [1, 2];
 
-/** Encode a per-domain keyset map into an opaque token. */
-export function encodeCursor(cursor: SyncCursor): string {
+/**
+ * Encode a per-domain keyset map into an opaque token.
+ *
+ * `issuedAtMs` is when the server handed the token out. The watermarks cannot
+ * say that: a restore writes rows back with their original `updatedAt`, so a
+ * cursor drained entirely after a restore can still carry watermarks older
+ * than it. The issue time is what `/api/sync/changes` compares against the
+ * account's `syncResetAt`. Additive inside the v2 envelope: a token without
+ * it decodes as before and counts as issued before any reset.
+ */
+export function encodeCursor(cursor: SyncCursor, issuedAtMs?: number): string {
   const d: Record<string, { u: number; i: string }> = {};
   for (const domain of SYNC_DOMAINS) {
     const wm = cursor[domain];
     if (wm) d[domain] = { u: wm.updatedAtMs, i: wm.id };
   }
-  const json = JSON.stringify({ v: CURSOR_VERSION, d });
+  const json = JSON.stringify(
+    issuedAtMs === undefined
+      ? { v: CURSOR_VERSION, d }
+      : { v: CURSOR_VERSION, t: issuedAtMs, d },
+  );
   return Buffer.from(json, "utf-8").toString("base64url");
 }
 
@@ -117,3 +130,18 @@ export function decodeCursor(token: string): SyncCursor | null {
     return null;
   }
 }
+
+/**
+ * When a token was issued (see {@link encodeCursor}), or null for a token
+ * that does not say: one from before the field existed, or one that does not
+ * parse.
+ */
+export function decodeCursorIssuedAt(token: string): number | null {
+  try {
+    const json = Buffer.from(token, "base64url").toString("utf-8");
+    const t = (JSON.parse(json) as { t?: unknown } | null)?.t;
+    return typeof t === "number" && Number.isFinite(t) ? t : null;
+  } catch {
+    return null;
+  }
+}

src/lib/sync/reset.ts

@@ -0,0 +1,19 @@
+/**
+ * Expire every delta cursor an account's paired clients hold.
+ *
+ * Called when the account's record is replaced wholesale: a backup restore
+ * (inside its transaction and again right after the commit) and the
+ * person's delete-all-data. `/api/sync/changes` answers `cursorExpired` to
+ * any cursor issued before the stamp, and the client re-initialises. See
+ * `User.syncResetAt` in the schema for why an incremental catch-up from such
+ * a cursor would miss rows.
+ */
+import type { Prisma, PrismaClient } from "@/generated/prisma/client";
+
+export async function stampSyncReset(
+  db: Pick<PrismaClient | Prisma.TransactionClient, "user">,
+  userId: string,
+  at: Date = new Date(),
+): Promise<void> {
+  await db.user.update({ where: { id: userId }, data: { syncResetAt: at } });
+}