feat(sync): let a client start the delta feed at the present

GET /api/sync/changes?start=now answers an empty page whose cursor sits at
serverNow in every domain, in the same opaque format the feed hands out.
A client that only needs what changes from now on, such as the Apple
Health write-back, pages forward from it instead of draining the whole
history first. start and cursor together are refused with 422.

Refs #1339

src/app/api/sync/changes/__tests__/start-now.test.ts

@@ -0,0 +1,100 @@
+/**
+ * `GET /api/sync/changes?start=now` (#1339) — a cursor at the present.
+ *
+ * The answer is an empty page whose cursor sits at `serverNow` in every
+ * domain, in the feed's own opaque format, and nothing is read: the point is
+ * to skip the history walk, so a read here would be the bug. The database is
+ * deliberately not mocked and not reachable: any read would fail the request,
+ * so the 200 below is itself the proof that none happened.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { NextRequest } from "next/server";
+
+vi.mock("@/lib/auth/session", () => ({ getSession: vi.fn() }));
+vi.mock("@/lib/rate-limit", () => ({ checkRateLimit: vi.fn() }));
+vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() }));
+vi.mock("@/lib/modules/gate", () => ({ isModuleEnabled: vi.fn() }));
+vi.mock("next/headers", () => ({
+  headers: vi.fn(async () => ({ get: () => null })),
+  cookies: vi.fn(async () => ({
+    get: () => undefined,
+    set: () => {},
+    delete: () => {},
+  })),
+}));
+
+import { GET } from "../route";
+import { getSession } from "@/lib/auth/session";
+import { checkRateLimit } from "@/lib/rate-limit";
+import {
+  decodeCursor,
+  decodeCursorIssuedAt,
+  SYNC_DOMAINS,
+} from "@/lib/sync/cursor";
+
+const SESSION_OK = {
+  session: { id: "sess-1", expiresAt: new Date(Date.now() + 3_600_000) },
+  user: { id: "user-1", username: "tester", role: "USER" as const },
+};
+
+function req(query: string): NextRequest {
+  return new NextRequest(`http://localhost/api/sync/changes${query}`);
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.mocked(getSession).mockResolvedValue(
+    SESSION_OK as Awaited<ReturnType<typeof getSession>>,
+  );
+  vi.mocked(checkRateLimit).mockResolvedValue({
+    allowed: true,
+    remaining: 119,
+    resetAt: Date.now() + 60_000,
+  } as Awaited<ReturnType<typeof checkRateLimit>>);
+});
+
+describe("GET /api/sync/changes?start=now", () => {
+  it("answers an empty page with a cursor at serverNow in every domain", async () => {
+    const before = Date.now();
+    const res = await GET(req("?start=now"));
+    const after = Date.now();
+    expect(res.status).toBe(200);
+    const { data } = (await res.json()) as {
+      data: {
+        serverNow: string;
+        cursor: string;
+        hasMore: boolean;
+        cursorExpired: boolean;
+        changes: Record<string, { upserts: unknown[]; tombstones: unknown[] }>;
+      };
+    };
+    expect(data.hasMore).toBe(false);
+    expect(data.cursorExpired).toBe(false);
+    expect(Object.keys(data.changes).sort()).toEqual([...SYNC_DOMAINS].sort());
+    for (const block of Object.values(data.changes)) {
+      expect(block).toEqual({ upserts: [], tombstones: [] });
+    }
+    const nowMs = Date.parse(data.serverNow);
+    expect(nowMs).toBeGreaterThanOrEqual(before);
+    expect(nowMs).toBeLessThanOrEqual(after);
+    const cursor = decodeCursor(data.cursor);
+    expect(cursor).not.toBeNull();
+    for (const domain of SYNC_DOMAINS) {
+      expect(cursor![domain], domain).toEqual({ updatedAtMs: nowMs, id: "0" });
+    }
+    expect(decodeCursorIssuedAt(data.cursor)).toBe(nowMs);
+  });
+
+  it("refuses start together with a cursor, and any start value but now", async () => {
+    const both = await GET(req("?start=now&cursor=abc"));
+    expect(both.status).toBe(422);
+    const other = await GET(req("?start=oldest"));
+    expect(other.status).toBe(422);
+  });
+
+  it("still requires a session", async () => {
+    vi.mocked(getSession).mockResolvedValue(null);
+    const res = await GET(req("?start=now"));
+    expect(res.status).toBe(401);
+  });
+});

src/app/api/sync/changes/route.ts

@@ -43,6 +43,11 @@
  *     cycle tracking off gets both blocks empty (never a 403 — see the
  *     gate note in the handler) and their cursor watermarks untouched.
  *
+ * `start=now` (#1339) answers an empty page whose cursor sits at
+ * `serverNow` in every domain, in the same opaque format, so a client that
+ * only wants what changes from now on (the Apple Health write-back) pages
+ * forward from there instead of draining the whole history first.
+ *
  * `apiHandler` + `requireAuth` (cookie OR Bearer; iOS uses Bearer).
  * Read-only — no idempotency, no write side-effect (unlike the legacy
  * `/api/sync/state` checkpoint bump). The cursor is owned by the client.
@@ -59,15 +64,23 @@ import {
   sanitiseZodIssues,
 } from "@/lib/api-response";
 import { checkRateLimit } from "@/lib/rate-limit";
-import { pullSyncChanges } from "@/lib/sync/changes/pull";
+import { pullSyncChanges, syncChangesFromNow } from "@/lib/sync/changes/pull";
 
 const DEFAULT_LIMIT = 200;
 const MAX_LIMIT = 500;
 
-const querySchema = z.object({
-  cursor: z.string().min(1).max(2048).optional(),
-  limit: z.coerce.number().int().min(1).max(MAX_LIMIT).optional(),
-});
+// `start=now` (#1339) asks for a cursor at the present instead of a page;
+// it contradicts an echoed cursor, so the two together are refused.
+const querySchema = z
+  .object({
+    cursor: z.string().min(1).max(2048).optional(),
+    limit: z.coerce.number().int().min(1).max(MAX_LIMIT).optional(),
+    start: z.literal("now").optional(),
+  })
+  .refine((q) => !(q.start && q.cursor), {
+    message: "start and cursor are mutually exclusive",
+    path: ["start"],
+  });
 
 export const GET = apiHandler(async (request: NextRequest) => {
   const { user } = await requireAuth();
@@ -83,6 +96,7 @@ export const GET = apiHandler(async (request: NextRequest) => {
   const parsed = querySchema.safeParse({
     cursor: url.searchParams.get("cursor") ?? undefined,
     limit: url.searchParams.get("limit") ?? undefined,
+    start: url.searchParams.get("start") ?? undefined,
   });
   if (!parsed.success) {
     return apiValidationError(
@@ -92,6 +106,10 @@ export const GET = apiHandler(async (request: NextRequest) => {
     );
   }
 
+  if (parsed.data.start === "now") {
+    return apiSuccess(syncChangesFromNow(new Date()));
+  }
+
   return apiSuccess(
     await pullSyncChanges({
       userId: user.id,

src/lib/openapi/routes/sync.ts

@@ -252,6 +252,12 @@ const syncChangesQuery = z
       .describe(
         "Opaque multi-domain keyset cursor from the previous page. Treat as fully opaque — echo, never parse. Omit for the initial sync.",
       ),
+    start: z
+      .literal("now")
+      .optional()
+      .describe(
+        "`now` answers an empty page (every domain empty, `hasMore: false`) whose `cursor` sits at `serverNow` in every domain, in the same opaque format as any other page. Paging forward from it yields only what changes from then on, including `measurementMirror`, without walking the history first. Mutually exclusive with `cursor` (422). A server without it ignores the parameter and starts from the oldest row.",
+      ),
     limit: z.coerce
       .number()
       .int()

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

@@ -7,6 +7,8 @@ import {
   encodeCursor,
   decodeCursor,
   decodeCursorIssuedAt,
+  encodeCursorAtNow,
+  SYNC_DOMAINS,
   type SyncCursor,
 } from "../cursor";
 
@@ -134,3 +136,19 @@ describe("cursor issue time (sync reset)", () => {
     expect(decodeCursorIssuedAt("not a token")).toBeNull();
   });
 });
+
+describe("encodeCursorAtNow", () => {
+  it("places every domain at the instant, before any id in that millisecond", () => {
+    const nowMs = 1_790_000_000_123;
+    const token = encodeCursorAtNow(nowMs);
+    const cursor = decodeCursor(token);
+    for (const domain of SYNC_DOMAINS) {
+      expect(cursor?.[domain], domain).toEqual({ updatedAtMs: nowMs, id: "0" });
+    }
+    expect(decodeCursorIssuedAt(token)).toBe(nowMs);
+    // Every cuid sorts after the tie-breaker, so a row in the same
+    // millisecond is delivered, not skipped.
+    expect("0" < "c").toBe(true);
+    expect("0" < "a").toBe(true);
+  });
+});

src/lib/sync/changes/pull.ts

@@ -13,6 +13,7 @@ import {
   decodeCursor,
   decodeCursorIssuedAt,
   encodeCursor,
+  encodeCursorAtNow,
   SYNC_DOMAINS,
   type SyncCursor,
   type SyncDomain,
@@ -108,6 +109,26 @@ function emptyChanges(): SyncChangesBody["changes"] {
   };
 }
 
+/**
+ * `start=now` (#1339): an empty page with a cursor at `serverNow` in every
+ * domain, for a client that wants changes from now on (the Apple Health
+ * write-back) without paging through the history first. `hasMore` is false:
+ * the client is caught up as of `serverNow` by definition.
+ */
+export function syncChangesFromNow(serverNow: Date): SyncChangesBody {
+  annotate({
+    action: { name: "sync.changes.start_now" },
+    meta: { returned: 0 },
+  });
+  return {
+    serverNow: serverNow.toISOString(),
+    cursor: encodeCursorAtNow(serverNow.getTime()),
+    hasMore: false,
+    cursorExpired: false,
+    changes: emptyChanges(),
+  };
+}
+
 export async function pullSyncChanges(input: {
   userId: string;
   /** The opaque cursor the client echoed, if any. */

src/lib/sync/cursor.ts

@@ -102,6 +102,22 @@ export function encodeCursor(cursor: SyncCursor, issuedAtMs?: number): string {
   return Buffer.from(json, "utf-8").toString("base64url");
 }
 
+/**
+ * A token positioned at `nowMs` in every domain (#1339), the same opaque
+ * format a drained page hands out: paging forward from it yields only what
+ * changes from now on, with no walk through the history first. The id `"0"`
+ * sorts before every cuid, so a row stamped in the very millisecond is
+ * delivered rather than skipped; the client's upserts are idempotent, so an
+ * overlap costs nothing and a gap would.
+ */
+export function encodeCursorAtNow(nowMs: number): string {
+  const cursor: SyncCursor = {};
+  for (const domain of SYNC_DOMAINS) {
+    cursor[domain] = { updatedAtMs: nowMs, id: "0" };
+  }
+  return encodeCursor(cursor, nowMs);
+}
+
 function parseWatermark(raw: unknown): DomainWatermark | null {
   if (typeof raw !== "object" || raw === null) return null;
   const u = (raw as { u?: unknown }).u;