feat(sync): protocol 2 — hydration, a counter not a clock, no silent shrinking

The reworked bundle's PORT.md makes row-level last-write-wins conditional
on three gates, each learned by losing real data. The port's sync broke
all three, and had four more ways to lose or stall work. Both ends change,
so this is one protocol version, refused by the other side if mismatched.

Gate 1, hydration. A device now pulls every page the server holds before
it may push anything; it used to push first. The 14 Sep laptop — a
week-old copy re-stamped at boot and pushed over a week of phone work —
is now a test, and the phone's week survives it. Boot writes nothing
syncable either: the lesson opens with the app's own words (the artifact's
seeded turn) and waits for Start, instead of stamping a reply and a
progress edit before a server can even be configured.

Gate 2, a counter. Every row remembers the change_seq it last agreed with
(base_seq). The server applies a write only if that still matches —
compare-and-swap under an advisory lock — and otherwise returns its copy
as a conflict. No clock is compared anywhere: a device an hour fast used
to win every conflict for an hour, and a slow one's newer edit was
silently dropped with HTTP 200. dirty and rev replace the timestamp
watermark, which lost edits whenever a clock moved backwards.

Gate 3, no silent shrinking. A conflict is settled by what each copy
holds (sync/resolve.ts): more reviews, more evidence, a finished unit, the
further roadmap position, the union of learned grammar. A deliberate
shrink is explicit: a reset or a cleared lesson raises a marker every
device obeys, including its own unsynced edits, so a reset is not undone
by a device that had not heard of it. Trimming the transcript is local
and tombstones nothing — it used to delete the other device's turns.

Also fixed on the way:
  · keys travel as JSON arrays — a space in 몇 명 used to stop every
    device's pull at that row, permanently;
  · pulls take a shared lock against pushes, so a change_seq committed
    out of order can no longer be skipped;
  · study_log and peek are per device and summed, so two devices' reviews
    of one day both count;
  · each user's data has an epoch; a server that lost it is detected,
    and the device re-hydrates and offers its data back;
  · a protocol-1 client is refused with 426 rather than half-understood.

Migration 9 adds the columns, re-keys the counters and tombstones; the
server drops protocol-1 rows once (none were deployed). Verified: 14
two-device scenarios against a real Postgres, and two browser profiles
syncing a lesson through the UI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

test/db/conformance.ts

@@ -14,6 +14,7 @@ import {
   seedMeta,
   seedProgress,
   editCard,
+  editCardReset,
   editCurrentUnit,
   editMeta,
   editPeek,
@@ -201,6 +202,44 @@ export function conformanceSuite(name: string, open: () => Promise<Db>): void {
        newer than the server's real history.
        ═══════════════════════════════════════════════════════════════ */
     describe("seeded state carries no write timestamp", () => {
+      it("leaves nothing dirty after a full seed, so nothing seeded ever travels", async () => {
+        await seedProgress(db, "1.1");
+        await seedMeta(db, "prefs.newPerDay", "10");
+        await db.run(
+          "INSERT INTO lemma (id, headword, pos, gloss_en, source) VALUES (1,'밥','noun','rice','curated')",
+        );
+        await seedCard(db, 1, newCard());
+        await seedChatTurn(db, "assistant", "안녕! 시작하자.", 0);
+
+        for (const table of SYNCABLE) {
+          const row = await db.get<{ n: number }>(`SELECT count(*) AS n FROM ${table} WHERE dirty != 0`);
+          expect(row?.n, `${table} has a dirty seed row`).toBe(0);
+        }
+      });
+
+      it("marks every genuine edit dirty and bumps its revision each time", async () => {
+        await db.run(
+          "INSERT INTO lemma (id, headword, pos, gloss_en, source) VALUES (3,'책','noun','book','curated')",
+        );
+        await editCard(db, 3, newCard());
+        await editCard(db, 3, grade(newCard(), GOOD, 20_000));
+        expect(await db.get("SELECT dirty, rev FROM card WHERE lemma_id = 3")).toEqual({ dirty: 1, rev: 2 });
+      });
+
+      it("carries a deleted row's base_seq into its tombstone", async () => {
+        await db.run(
+          "INSERT INTO lemma (id, headword, pos, gloss_en, source) VALUES (4,'꽃','noun','flower','curated')",
+        );
+        await editCard(db, 4, newCard());
+        await db.run("UPDATE card SET base_seq = 77, dirty = 0 WHERE lemma_id = 4");
+        await editCardReset(db, 4);
+        expect(await db.get("SELECT pk, base_seq, dirty FROM tombstone WHERE tbl = 'card'")).toEqual({
+          pk: "[4]",
+          base_seq: 77,
+          dirty: 1,
+        });
+      });
+
       it("leaves updated_at at 0 across every syncable table after a full seed", async () => {
         await seedProgress(db, "1.1");
         await seedMeta(db, "focus", "auto");

test/db/migration-6.test.ts

@@ -57,7 +57,8 @@ describe("migration 6", () => {
     const graves = await db.all<{ pk: string; updated_at: number }>(
       "SELECT pk, updated_at FROM tombstone WHERE tbl = 'card'",
     );
-    expect(graves).toEqual([{ pk: String(lemmaId("책", "noun")), updated_at: 333 }]);
+    // As JSON, once migration 9 has written keys in protocol 2's form.
+    expect(graves).toEqual([{ pk: JSON.stringify([lemmaId("책", "noun")]), updated_at: 333 }]);
   });
 
   it("turns a custom lemma into a custom_word, stamped when its card was made", async () => {

test/db/migration-8.test.ts

@@ -60,7 +60,8 @@ describe("migration 8", () => {
   it("renames a chat tombstone the same way", async () => {
     const device = (await db.get<{ v: string }>("SELECT v FROM meta WHERE k = 'sync.device'"))!.v;
     expect(await db.all("SELECT pk, updated_at FROM tombstone WHERE tbl = 'chat'")).toEqual([
-      { pk: `legacy:${device}:0000000009`, updated_at: 400 },
+      // As JSON, once migration 9 has written keys in protocol 2's form.
+      { pk: JSON.stringify([`legacy:${device}:0000000009`]), updated_at: 400 },
     ]);
   });
 

test/db/migration-9.test.ts

@@ -0,0 +1,71 @@
+/* Migration 9 — sync protocol 2's columns, per-device counters, JSON keys.
+
+   A database as migration 8 left it, carrying protocol 1's bookkeeping and
+   a tombstone of every shape protocol 1 wrote. */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteWasmDb } from "@app/db/sqlite-wasm-core.js";
+import { migrate } from "@app/db/migrate.js";
+import type { Db } from "@app/db/types.js";
+
+let db: Db;
+let device: string;
+beforeEach(async () => {
+  db = await SqliteWasmDb.open({ memory: true });
+  await migrate(db, 8);
+  device = (await db.get<{ v: string }>("SELECT v FROM meta WHERE k = 'sync.device'"))!.v;
+  await db.exec(`
+    INSERT INTO study_log (day, reviews, correct, drills, updated_at) VALUES (20000, 5, 4, 1, 700);
+    INSERT INTO peek (form, count, updated_at) VALUES ('몇 명', 3, 800);
+    INSERT INTO card (lemma_id, state, reps, updated_at) VALUES (55855054575946, 1, 2, 900);
+    INSERT INTO meta (k, v, updated_at) VALUES ('sync.cursor', '41', 0), ('sync.pushedAt', '900', 0);
+    INSERT INTO tombstone (tbl, pk, updated_at) VALUES
+      ('card', '1434356355562999', 10),
+      ('study_log', '19999', 11),
+      ('peek', '몇 명', 12),
+      ('meta', 'prefs.goal', 13),
+      ('custom_word', '["던전","noun"]', 14);
+  `);
+  await migrate(db);
+});
+afterEach(async () => {
+  await db.close();
+});
+
+describe("migration 9", () => {
+  it("gives every syncable row base_seq, dirty and rev, all zero", async () => {
+    expect(await db.get("SELECT base_seq, dirty, rev, updated_at FROM card")).toEqual({
+      base_seq: 0,
+      dirty: 0,
+      rev: 0,
+      updated_at: 900,
+    });
+  });
+
+  it("hands this install's counters to this install", async () => {
+    expect(await db.get("SELECT day, device, reviews, correct, drills, updated_at FROM study_log")).toEqual({
+      day: 20000,
+      device,
+      reviews: 5,
+      correct: 4,
+      drills: 1,
+      updated_at: 700,
+    });
+    expect(await db.get("SELECT form, device, count FROM peek")).toEqual({ form: "몇 명", device, count: 3 });
+  });
+
+  it("writes every tombstone key as a JSON array, a space included", async () => {
+    const graves = await db.all<{ tbl: string; pk: string }>("SELECT tbl, pk FROM tombstone ORDER BY updated_at");
+    expect(graves).toEqual([
+      { tbl: "card", pk: "[1434356355562999]" },
+      { tbl: "study_log", pk: JSON.stringify([19999, device]) },
+      { tbl: "peek", pk: JSON.stringify(["몇 명", device]) },
+      { tbl: "meta", pk: '["prefs.goal"]' },
+      { tbl: "custom_word", pk: '["던전","noun"]' },
+    ]);
+  });
+
+  it("drops protocol 1's position, so the next sync hydrates from scratch", async () => {
+    expect(await db.all("SELECT k FROM meta WHERE k IN ('sync.cursor', 'sync.pushedAt')")).toEqual([]);
+  });
+});