cursedbelt 2.6.1 → 2.7.0

package/src/server/sync/httpRemote.spec.ts

@@ -0,0 +1,158 @@
+/**
+ * `createHttpRemote` — the dialer's transport, and the three properties that
+ * came out of an eight-day silent outage.
+ *
+ * ── What happened (2026-08-21) ───────────────────────────────────────────────
+ * The console merge on 2026-08-20 made `station.cursedalchemy.com` a **301** to
+ * `station.cursedalchemy.com`. The Mac's `STATION_SYNC_URL` still named the old
+ * host. `fetch` follows redirects by default, so every sync round went:
+ *
+ *     POST station…/api/sync/push   → 301
+ *     POST admin…/api/sync/push     → 302 (Cloudflare Access, no credential)
+ *     GET  cloudflareaccess.com/…   → 200 text/html  ← the login page
+ *     r.json()                      → "Failed to parse JSON"
+ *
+ * The timer logs that as `[sync] failed (ignored)` and retries forever. Nothing
+ * was red — not a gate, not a smoke, not `/healthz` — while every mirrored
+ * report on the prod console froze at the moment of the cutover and each one
+ * kept rendering a confident `capturedAt` age.
+ *
+ * Three separate defenses, because any one of them alone would have left this
+ * failure recoverable-but-invisible:
+ *
+ *   1. redirects are REFUSED and name their destination;
+ *   2. a non-JSON body reports what actually arrived;
+ *   3. the peer's Access credential is carried, so the console's own receiver is
+ *      reachable at all.
+ */
+import { describe, expect, test } from "bun:test";
+import { createHttpRemote } from "./http";
+
+/** A fetch that records what it was asked and answers a canned response. */
+function fakeFetch(reply: (url: string, init?: RequestInit) => Response) {
+	const seen: Array<{ url: string; init?: RequestInit }> = [];
+	const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+		seen.push({ url: String(url), ...(init ? { init } : {}) });
+		return reply(String(url), init);
+	}) as unknown as typeof fetch;
+	return { impl, seen };
+}
+
+/** The one request the fake saw. Throws rather than optional-chaining into a
+ *  cast: a missing request means the remote never called out, which is a
+ *  different failure from the one under test and must say so. */
+const onlyRequest = (seen: Array<{ url: string; init?: RequestInit }>): RequestInit => {
+	const first = seen[0];
+	if (!first?.init) throw new Error(`expected one request, saw ${seen.length}`);
+	return first.init;
+};
+
+const remoteWith = (impl: typeof fetch, extraHeaders?: Record<string, string>) =>
+	createHttpRemote({
+		basePath: "https://admin.example.com/api/sync",
+		token: "tok",
+		selfId: "mac",
+		fetchImpl: impl,
+		...(extraHeaders ? { extraHeaders } : {}),
+	});
+
+describe("a redirect is a refusal, never something to follow", () => {
+	test("a 301 names the destination and says the address has moved", async () => {
+		const { impl } = fakeFetch(
+			() =>
+				new Response("", {
+					status: 301,
+					headers: { location: "https://admin.example.com/api/sync/info" },
+				}),
+		);
+		const err = await remoteWith(impl)
+			.info()
+			.catch((e: unknown) => e as Error);
+		expect((err as Error).message).toContain("301");
+		expect((err as Error).message).toContain("https://admin.example.com/api/sync/info");
+		expect((err as Error).message).toContain("host that has moved");
+	});
+
+	test("`redirect: manual` is actually requested — the default would follow", async () => {
+		// This is the whole fix. Asserting the message alone would pass against an
+		// implementation that follows and then happens to get a 3xx back.
+		const { impl, seen } = fakeFetch(() => new Response("{}", { status: 200 }));
+		await remoteWith(impl).info();
+		expect(onlyRequest(seen).redirect).toBe("manual");
+	});
+
+	test("a 302 with no Location still refuses, rather than throwing about undefined", async () => {
+		const { impl } = fakeFetch(() => new Response("", { status: 302 }));
+		const err = await remoteWith(impl)
+			.info()
+			.catch((e: unknown) => e as Error);
+		expect((err as Error).message).toContain("an unnamed destination");
+	});
+});
+
+describe("a non-JSON body says what actually arrived", () => {
+	test("an Access login page reports its status and content type, not a parse error", async () => {
+		const { impl } = fakeFetch(
+			() =>
+				new Response("<!DOCTYPE html><html><head><title>Sign in</title>", {
+					status: 200,
+					headers: { "content-type": "text/html; charset=UTF-8" },
+				}),
+		);
+		const err = await remoteWith(impl)
+			.info()
+			.catch((e: unknown) => e as Error);
+		const message = (err as Error).message;
+		// 🔴 The old message was exactly "Failed to parse JSON", which names the
+		// last layer and none of the cause.
+		expect(message).not.toBe("Failed to parse JSON");
+		expect(message).toContain("text/html");
+		expect(message).toContain("sync/info");
+		expect(message).toContain("Sign in");
+	});
+
+	test("an empty 200 body says so rather than showing nothing", async () => {
+		const { impl } = fakeFetch(() => new Response("", { status: 200 }));
+		const err = await remoteWith(impl)
+			.info()
+			.catch((e: unknown) => e as Error);
+		expect((err as Error).message).toContain("(empty body)");
+	});
+
+	test("real JSON still parses, on every verb", async () => {
+		const { impl } = fakeFetch((url) =>
+			url.includes("/push")
+				? new Response(JSON.stringify({ applied: 1, error: null }), { status: 200 })
+				: new Response(JSON.stringify({ ops: [], cursor: 0, head: 0 }), { status: 200 }),
+		);
+		const remote = remoteWith(impl);
+		expect(await remote.pull(0, "mac")).toEqual({ ops: [], cursor: 0, head: 0 });
+		expect((await remote.push({ ops: [] } as never)).applied).toBe(1);
+	});
+});
+
+describe("the peer's own credential travels with the request", () => {
+	test("extraHeaders are sent alongside the bearer", async () => {
+		const { impl, seen } = fakeFetch(() => new Response("{}", { status: 200 }));
+		await remoteWith(impl, { "CF-Access-Client-Id": "id", "CF-Access-Client-Secret": "s" }).info();
+		const headers = onlyRequest(seen).headers as Record<string, string>;
+		expect(headers["CF-Access-Client-Id"]).toBe("id");
+		expect(headers.authorization).toBe("Bearer tok");
+		expect(headers["x-sync-peer"]).toBe("mac");
+	});
+
+	test("no extraHeaders is inert — nothing extra is sent", async () => {
+		const { impl, seen } = fakeFetch(() => new Response("{}", { status: 200 }));
+		await remoteWith(impl).info();
+		const headers = onlyRequest(seen).headers as Record<string, string>;
+		expect(Object.keys(headers).sort()).toEqual(["authorization", "x-sync-peer"]);
+	});
+
+	test("a 401 still reports the token refusal, not a redirect", async () => {
+		const { impl } = fakeFetch(() => new Response("", { status: 401 }));
+		const err = await remoteWith(impl)
+			.info()
+			.catch((e: unknown) => e as Error);
+		expect((err as Error).message).toContain("the sync token was refused");
+	});
+});

package/src/server/sync/index.ts

@@ -0,0 +1,90 @@
+/**
+ * `cursedbelt/sync` — the op-log replication engine, shared rather than forked.
+ *
+ * ## Why it is here and not in the app
+ *
+ * The retired tree had FOUR consumers of this engine: `apps/vault` (8 files),
+ * `apps/station` (6), `apps/notes` (4) and `packages/feedback-kit` (5). `vault`
+ * graduated first and carried all 3,245 lines in whole, as
+ * `apps/vault/src/kit/sync/`, because a Phase A that also publishes a library is a
+ * Phase A that does not land. This is the other half of that trade, and it had a
+ * DEADLINE rather than a backlog slot: the moment `apps/station` graduates with the
+ * copy still in `vault`, the generation owns two divergent forks of a replication
+ * engine — the exact shape the owner ruled against on 2026-09-13, *"if we don't
+ * adapt to this at the right time then it will be hard to remember to keep updating
+ * multiple copies as the apps move and grow."*
+ *
+ * ## 🔴 A LEAF export, and it must stay one
+ *
+ * `cursedbelt/sync` resolves straight to this directory. It is deliberately NOT
+ * reachable through the `cursedbelt/server` barrel, which drags `kysely` and
+ * `otplib` behind it — an app that wants an op-log should not install two
+ * databases to get one. The only runtime dependency beneath this subpath is
+ * `hono` (for the receiver routes in `http.ts` and `commands.ts`); everything else
+ * is `bun:sqlite`, `node:crypto` and `node:fs`.
+ *
+ * It lives under `src/server/` because that is where this package's two typecheck
+ * projects put Bun's ambient types: the root `tsconfig.json` runs `types: []` to
+ * keep the browser/React surface pristine and EXCLUDES `src/server`, so
+ * `bun:sqlite` and `node:crypto` only resolve on this side of the split. The
+ * directory decides the types; the `exports` key decides the spelling.
+ */
+export {
+	StopBatch,
+	type ApplyContext,
+	type ApplyOne,
+	type ApplyReport,
+	type PeerInfo,
+	type RemoteApi,
+	type SyncOp,
+	type SyncSummary,
+} from "./types";
+export { createOpLog, type OpLog } from "./opLog";
+export { createTokenStore, type DeviceToken, type TokenStore } from "./tokens";
+export {
+	createSyncApplier,
+	pushToRemote,
+	pullFromRemote,
+	runSync,
+	type EngineOptions,
+	type ExportPolicy,
+	type PeerRefusal,
+} from "./engine";
+export {
+	capPageBytes,
+	createHttpRemote,
+	createSyncReceiver,
+	type ReceiverHooks,
+	type ReceiverOptions,
+} from "./http";
+export {
+	DEFAULT_LOOP,
+	isUnreachable,
+	planNextSync,
+	type SyncLoopConfig,
+	type SyncLoopState,
+} from "./planner";
+export {
+	OFFLINE_STATUS,
+	PEER_CONTACT_WRITE_MS,
+	createSyncStatusReporter,
+	type SyncStatus,
+	type SyncStatusReporter,
+	type SyncStatusStore,
+} from "./status";
+export { REQUEST_POLL_MS, startSyncTimer, type SyncTimerDeps, type SyncTimerHandle } from "./timer";
+export { createSyncAlarm, type AlarmOutcome, type SyncAlarm, type SyncAlarmOptions } from "./alarm";
+export {
+	DEFAULT_HOLD_MS,
+	createCommandQueue,
+	createCommandReceiver,
+	createCommandRemote,
+	startCommandWorker,
+	type CommandQueue,
+	type CommandRemote,
+	type CommandRoutesOptions,
+	type CommandStatus,
+	type CommandWorkerDeps,
+	type CommandWorkerHandle,
+	type SyncCommand,
+} from "./commands";

package/src/server/sync/opLog.spec.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { createOpLog } from "./opLog";
+
+describe("opLog", () => {
+	test("instance id is minted once and stable across reopen", () => {
+		const db = new Database(":memory:");
+		const a = createOpLog(db);
+		const b = createOpLog(db);
+		expect(a.instanceId()).toBe(b.instanceId());
+		expect(a.instanceId()).toMatch(/^i-/);
+	});
+
+	test("recordLocal assigns monotonic seq + originSeq and round-trips payloads", () => {
+		const log = createOpLog(new Database(":memory:"));
+		const one = log.recordLocal("doc.set", { path: "a.md", body: "x" });
+		const two = log.recordLocal("doc.set", { path: "b.md" });
+		expect(two.seq).toBeGreaterThan(one.seq);
+		expect(one.originSeq).toBe(1);
+		expect(two.originSeq).toBe(2);
+		const page = log.listAfter(0, "someone-else", 10);
+		expect(page.ops.map((o) => (o.payload as { path: string }).path)).toEqual(["a.md", "b.md"]);
+		expect(page.head).toBe(two.seq);
+	});
+
+	test("listAfter excludes the peer's own ops and still advances the cursor past them", () => {
+		const log = createOpLog(new Database(":memory:"));
+		log.recordRemote({ seq: 0, origin: "peer-1", originSeq: 1, ts: 1, kind: "k", payload: null });
+		log.recordRemote({ seq: 0, origin: "peer-1", originSeq: 2, ts: 2, kind: "k", payload: null });
+		const page = log.listAfter(0, "peer-1", 10);
+		expect(page.ops).toHaveLength(0);
+		// The window was all the peer's own reflections — cursor jumps to head so the
+		// peer never re-pages a stream made of itself.
+		expect(page.cursor).toBe(log.head());
+	});
+
+	test("(origin, originSeq) is unique — a duplicate remote insert throws", () => {
+		const log = createOpLog(new Database(":memory:"));
+		const op = { seq: 0, origin: "p", originSeq: 7, ts: 1, kind: "k", payload: null };
+		log.recordRemote(op);
+		expect(log.has("p", 7)).toBe(true);
+		expect(() => log.recordRemote(op)).toThrow();
+	});
+
+	test("cursors are per-peer, per-direction, durable", () => {
+		const db = new Database(":memory:");
+		const log = createOpLog(db);
+		expect(log.cursor("p", "push")).toBe(0);
+		log.setCursor("p", "push", 41);
+		log.setCursor("p", "pull", 7);
+		expect(createOpLog(db).cursor("p", "push")).toBe(41);
+		expect(log.cursor("p", "pull")).toBe(7);
+		expect(log.cursor("q", "push")).toBe(0);
+	});
+
+	// The receiver-side leak that put 963 MB of superseded `overview` snapshots on the
+	// receiving half (then the `prod-ec2` box): compactOwn is scoped to
+	// `origin = instanceId`, so an instance that
+	// only RECEIVES a state kind never compacts it.
+	const snap = (originSeq: number, key: string) => ({
+		seq: 0,
+		origin: "mac",
+		originSeq,
+		ts: originSeq,
+		kind: "snapshot.set",
+		payload: { key, data: `v${originSeq}` },
+	});
+
+	test("compactOwn does NOT touch a peer's ops — the leak this reproduces", () => {
+		const log = createOpLog(new Database(":memory:"));
+		for (const n of [1, 2, 3]) log.recordRemote(snap(n, "overview"));
+		expect(log.compactOwn("snapshot.set", 99, '%"key":"overview"%')).toBe(0);
+		expect(log.listAfter(0, "nobody", 10).ops).toHaveLength(3);
+	});
+
+	test("compactOrigin drops a peer's superseded state ops, keeping the newest", () => {
+		const log = createOpLog(new Database(":memory:"));
+		for (const n of [1, 2, 3]) log.recordRemote(snap(n, "overview"));
+		expect(log.compactOrigin("mac", "snapshot.set", 3, '%"key":"overview"%')).toBe(2);
+		const ops = log.listAfter(0, "nobody", 10).ops;
+		expect(ops).toHaveLength(1);
+		expect(ops[0]?.originSeq).toBe(3);
+		expect((ops[0]?.payload as { data: string } | undefined)?.data).toBe("v3");
+	});
+
+	test("compactOrigin is scoped to the origin, the kind and the payload key", () => {
+		const log = createOpLog(new Database(":memory:"));
+		log.recordRemote(snap(1, "overview"));
+		log.recordRemote(snap(2, "overview"));
+		log.recordRemote(snap(3, "health")); // different key
+		log.recordRemote({ ...snap(4, "overview"), kind: "doc.set" }); // different kind
+		log.recordRemote({ ...snap(5, "overview"), origin: "other" }); // different origin
+		expect(log.compactOrigin("mac", "snapshot.set", 2, '%"key":"overview"%')).toBe(1);
+		const kept = log.listAfter(0, "nobody", 10).ops;
+		expect(kept).toHaveLength(4);
+		expect(
+			kept.some((o) => o.origin === "mac" && o.kind === "snapshot.set" && o.originSeq === 1),
+		).toBe(false);
+	});
+
+	test("a compacted-away op leaves a seq gap that paging tolerates", () => {
+		const log = createOpLog(new Database(":memory:"));
+		for (const n of [1, 2, 3]) log.recordRemote(snap(n, "overview"));
+		log.compactOrigin("mac", "snapshot.set", 3, '%"key":"overview"%');
+		// A peer still parked on the oldest cursor converges on the newest state.
+		const page = log.listAfter(0, "nobody", 10);
+		expect(page.ops).toHaveLength(1);
+		expect(page.cursor).toBe(page.head);
+	});
+});

package/src/server/sync/opLog.ts

@@ -0,0 +1,189 @@
+/**
+ * The durable op log + cursor bookkeeping, over the app's own `bun:sqlite` handle.
+ * Fixed table names (`sync_ops`, `sync_cursors`, `sync_meta`) — a consumer of this
+ * engine is expected to give sync its own tables rather than remap; the notes/vault
+ * retrofit maps their legacy tables behind this interface, not the other way round.
+ *
+ * Identity: `(origin, origin_seq)` UNIQUE — exactly-once application with no peer
+ * coordination (the notes ledger shape). `seq` is this instance's own monotonic
+ * stream every peer pages over.
+ */
+import type { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import type { SyncOp } from "./types";
+
+export interface OpLog {
+	/** This instance's stable id (minted once, persisted in sync_meta). */
+	instanceId(): string;
+	/** Record a locally-born op; returns it with seq/originSeq assigned. */
+	recordLocal(kind: string, payload: unknown, ts?: number): SyncOp;
+	/** Record a remote op into the ledger (dedupe identity kept). Caller applies state
+	 *  FIRST in the same transaction scope; see `createSyncApplier`. */
+	recordRemote(op: SyncOp): void;
+	/** Is this (origin, originSeq) already in the ledger? */
+	has(origin: string, originSeq: number): boolean;
+	/** Page of ops with seq > after, excluding one origin (the peer's own — it already
+	 *  has them), oldest first. `cursor` = last row's seq served (or `after`). */
+	listAfter(
+		after: number,
+		excludeOrigin: string,
+		limit: number,
+	): { ops: SyncOp[]; cursor: number; head: number };
+	/** Highest local seq (0 when empty). */
+	head(): number;
+	/** Durable per-peer cursors. `direction`: what WE track about the peer. */
+	cursor(peerId: string, direction: "push" | "pull" | "served"): number;
+	setCursor(peerId: string, direction: "push" | "pull" | "served", seq: number): void;
+	/** Compaction for STATE-shaped kinds (a snapshot is not history): delete this
+	 *  origin's OWN earlier ops of `kind` matching `payloadWhere` below `keepSeq`.
+	 *  Safe under the exactly-once ledger — peers dedupe by (origin, originSeq),
+	 *  pull pages tolerate seq gaps, and a deleted op is simply never sent. */
+	compactOwn(kind: string, keepSeq: number, payloadLike: string): number;
+	/** The same compaction, for a state kind that arrived from a PEER.
+	 *
+	 *  `compactOwn` is scoped to `origin = instanceId`, so a pure RECEIVER of a
+	 *  state kind matches zero rows and its log grows without bound — prod
+	 *  station reached 5,537 revisions of one `overview` snapshot (963 MB, ~160
+	 *  MB/day) because every one of them originated on the Mac. The safety
+	 *  argument on `compactOwn` never depended on who minted the op, only on the
+	 *  kind being STATE rather than history, so it carries over verbatim.
+	 *
+	 *  Keyed on `origin_seq`, not local `seq`: a receiver compacts while
+	 *  applying, which happens BEFORE the incoming row is inserted, so there is
+	 *  no local seq yet to compare against. `(origin, origin_seq)` is the
+	 *  ledger's own identity and is monotonic per origin, so it orders the
+	 *  origin's stream exactly as well. */
+	compactOrigin(origin: string, kind: string, keepOriginSeq: number, payloadLike: string): number;
+	/** Arbitrary sync-scoped metadata (instance id lives here too). */
+	getMeta(key: string): string | null;
+	setMeta(key: string, value: string): void;
+	/** Run `fn` inside one sqlite transaction (apply + ledger-insert atomicity). */
+	transaction<T>(fn: () => T): T;
+}
+
+const INSTANCE_KEY = "sync.instance_id";
+
+export function createOpLog(db: Database): OpLog {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS sync_ops (
+			seq INTEGER PRIMARY KEY AUTOINCREMENT,
+			origin TEXT NOT NULL,
+			origin_seq INTEGER NOT NULL,
+			ts INTEGER NOT NULL,
+			kind TEXT NOT NULL,
+			payload TEXT NOT NULL,
+			UNIQUE(origin, origin_seq)
+		);
+		CREATE INDEX IF NOT EXISTS idx_sync_ops_origin ON sync_ops(origin, seq);
+		CREATE TABLE IF NOT EXISTS sync_cursors (
+			peer_id TEXT NOT NULL,
+			direction TEXT NOT NULL,
+			seq INTEGER NOT NULL DEFAULT 0,
+			PRIMARY KEY(peer_id, direction)
+		);
+		CREATE TABLE IF NOT EXISTS sync_meta (
+			key TEXT PRIMARY KEY,
+			value TEXT NOT NULL
+		);
+	`);
+
+	const getMetaStmt = db.prepare("SELECT value FROM sync_meta WHERE key = ?");
+	const setMetaStmt = db.prepare(
+		"INSERT INTO sync_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+	);
+	const getMeta = (key: string): string | null =>
+		(getMetaStmt.get(key) as { value: string } | null)?.value ?? null;
+	const setMeta = (key: string, value: string): void => {
+		setMetaStmt.run(key, value);
+	};
+
+	let cachedId = getMeta(INSTANCE_KEY);
+	if (cachedId === null) {
+		// Short + url/label safe; uniqueness across a two-or-three instance fleet is
+		// what matters, not global collision resistance.
+		cachedId = `i-${randomUUID().slice(0, 12)}`;
+		setMeta(INSTANCE_KEY, cachedId);
+	}
+	const instanceId = cachedId;
+
+	const insertOp = db.prepare(
+		"INSERT INTO sync_ops (origin, origin_seq, ts, kind, payload) VALUES (?, ?, ?, ?, ?)",
+	);
+	const hasStmt = db.prepare("SELECT 1 FROM sync_ops WHERE origin = ? AND origin_seq = ? LIMIT 1");
+	const headStmt = db.prepare("SELECT COALESCE(MAX(seq), 0) AS head FROM sync_ops");
+	const maxOriginSeqStmt = db.prepare(
+		"SELECT COALESCE(MAX(origin_seq), 0) AS m FROM sync_ops WHERE origin = ?",
+	);
+	const listStmt = db.prepare(
+		"SELECT seq, origin, origin_seq, ts, kind, payload FROM sync_ops WHERE seq > ? AND origin != ? ORDER BY seq ASC LIMIT ?",
+	);
+	const compactStmt = db.prepare(
+		"DELETE FROM sync_ops WHERE origin = ? AND kind = ? AND seq < ? AND payload LIKE ?",
+	);
+	const compactOriginStmt = db.prepare(
+		"DELETE FROM sync_ops WHERE origin = ? AND kind = ? AND origin_seq < ? AND payload LIKE ?",
+	);
+	const cursorStmt = db.prepare("SELECT seq FROM sync_cursors WHERE peer_id = ? AND direction = ?");
+	const setCursorStmt = db.prepare(
+		"INSERT INTO sync_cursors (peer_id, direction, seq) VALUES (?, ?, ?) ON CONFLICT(peer_id, direction) DO UPDATE SET seq = excluded.seq",
+	);
+
+	interface OpRow {
+		seq: number;
+		origin: string;
+		origin_seq: number;
+		ts: number;
+		kind: string;
+		payload: string;
+	}
+	const rowToOp = (row: OpRow): SyncOp => ({
+		seq: row.seq,
+		origin: row.origin,
+		originSeq: row.origin_seq,
+		ts: row.ts,
+		kind: row.kind,
+		payload: JSON.parse(row.payload) as unknown,
+	});
+
+	return {
+		instanceId: () => instanceId,
+		recordLocal(kind, payload, ts) {
+			const at = ts ?? Date.now();
+			const originSeq = (maxOriginSeqStmt.get(instanceId) as { m: number }).m + 1;
+			insertOp.run(instanceId, originSeq, at, kind, JSON.stringify(payload ?? null));
+			const seq = (headStmt.get() as { head: number }).head;
+			return { seq, origin: instanceId, originSeq, ts: at, kind, payload };
+		},
+		recordRemote(op) {
+			insertOp.run(op.origin, op.originSeq, op.ts, op.kind, JSON.stringify(op.payload ?? null));
+		},
+		has: (origin, originSeq) => hasStmt.get(origin, originSeq) !== null,
+		listAfter(after, excludeOrigin, limit) {
+			const rows = listStmt.all(after, excludeOrigin, limit) as OpRow[];
+			const ops = rows.map(rowToOp);
+			const head = (headStmt.get() as { head: number }).head;
+			// An all-excluded page must still advance the peer past what it skipped, or a
+			// log dominated by the peer's own reflected ops would page forever. Serve the
+			// true high-water mark of the WINDOW scanned: when the page is short, we
+			// reached head; otherwise the last row's seq.
+			const cursor =
+				rows.length === 0 ? Math.max(after, head) : (rows[rows.length - 1] as OpRow).seq;
+			return { ops, cursor, head };
+		},
+		head: () => (headStmt.get() as { head: number }).head,
+		compactOwn(kind, keepSeq, payloadLike) {
+			return compactStmt.run(instanceId, kind, keepSeq, payloadLike).changes;
+		},
+		compactOrigin(origin, kind, keepOriginSeq, payloadLike) {
+			return compactOriginStmt.run(origin, kind, keepOriginSeq, payloadLike).changes;
+		},
+		cursor: (peerId, direction) =>
+			(cursorStmt.get(peerId, direction) as { seq: number } | null)?.seq ?? 0,
+		setCursor(peerId, direction, seq) {
+			setCursorStmt.run(peerId, direction, seq);
+		},
+		getMeta,
+		setMeta,
+		transaction: <T>(fn: () => T): T => db.transaction(fn)(),
+	};
+}

package/src/server/sync/planner.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { isUnreachable, planNextSync, type SyncLoopConfig } from "./planner";
+
+const cfg: SyncLoopConfig = {
+	intervalMs: 300_000,
+	debounceMs: 3_000,
+	backoffBaseMs: 30_000,
+	backoffMaxMs: 1_800_000,
+};
+
+describe("planNextSync", () => {
+	test("steady interval when clean", () => {
+		expect(
+			planNextSync({ lastAttempt: 0, consecutiveFailures: 0, dirtySince: null }, 300_000, cfg)
+				.runNow,
+		).toBe(true);
+		const wait = planNextSync(
+			{ lastAttempt: 100_000, consecutiveFailures: 0, dirtySince: null },
+			200_000,
+			cfg,
+		);
+		expect(wait.runNow).toBe(false);
+		expect(wait.waitMs).toBe(200_000);
+	});
+
+	test("a dirty flag debounces then wins over the interval", () => {
+		const state = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: 10_000 };
+		expect(planNextSync(state, 11_000, cfg)).toEqual({ runNow: false, waitMs: 2_000 });
+		expect(planNextSync(state, 13_000, cfg).runNow).toBe(true);
+	});
+
+	test("failures back off exponentially and cap at backoffMaxMs", () => {
+		const at = (failures: number, now: number) =>
+			planNextSync({ lastAttempt: 0, consecutiveFailures: failures, dirtySince: null }, now, cfg);
+		expect(at(1, 29_999).runNow).toBe(false);
+		expect(at(1, 30_000).runNow).toBe(true);
+		expect(at(2, 59_999).runNow).toBe(false);
+		expect(at(2, 60_000).runNow).toBe(true);
+		// 2^10 * 30s would be ~8.5h — capped at the ceiling.
+		expect(at(11, 1_800_000).runNow).toBe(true);
+		expect(at(11, 1_799_999).waitMs).toBe(1);
+	});
+});
+
+describe("isUnreachable", () => {
+	test("network-shaped failures are unreachable; logic failures are not", () => {
+		expect(isUnreachable(new Error("fetch failed"))).toBe(true);
+		expect(isUnreachable(new Error("connect ECONNREFUSED 1.2.3.4:443"))).toBe(true);
+		expect(isUnreachable(new Error("The operation was aborted"))).toBe(true);
+		expect(isUnreachable(new Error("sync/push: 500"))).toBe(false);
+		expect(isUnreachable(new Error("401 — the sync token was refused."))).toBe(false);
+	});
+});

package/src/server/sync/planner.ts

@@ -0,0 +1,62 @@
+/**
+ * The pure loop planner — vault's `planNextSync`, unchanged in spirit: back off after
+ * a failure, else honor a debounced dirty flag, else the steady interval. Pure so
+ * the timer is a thin wrapper and this is fake-clock testable.
+ */
+
+export interface SyncLoopConfig {
+	/** Steady poll cadence when reachable and idle. */
+	intervalMs: number;
+	/** How long after a local write to wait before syncing, so a burst coalesces. */
+	debounceMs: number;
+	/** First backoff step after a failure. */
+	backoffBaseMs: number;
+	/** Backoff ceiling — an unreachable peer (the nightly window) settles here. */
+	backoffMaxMs: number;
+}
+
+export const DEFAULT_LOOP: SyncLoopConfig = {
+	intervalMs: 5 * 60_000,
+	debounceMs: 3_000,
+	backoffBaseMs: 30_000,
+	backoffMaxMs: 30 * 60_000,
+};
+
+export interface SyncLoopState {
+	/** When the last sync attempt STARTED (0 if never). */
+	lastAttempt: number;
+	/** Consecutive failed attempts — drives exponential backoff. */
+	consecutiveFailures: number;
+	/** When the oldest un-synced local write happened, or null if clean. */
+	dirtySince: number | null;
+}
+
+export function planNextSync(
+	state: SyncLoopState,
+	now: number,
+	cfg: SyncLoopConfig = DEFAULT_LOOP,
+): { runNow: boolean; waitMs: number } {
+	if (state.consecutiveFailures > 0) {
+		const step = Math.min(
+			cfg.backoffMaxMs,
+			cfg.backoffBaseMs * 2 ** (state.consecutiveFailures - 1),
+		);
+		const due = state.lastAttempt + step;
+		return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+	}
+	if (state.dirtySince !== null) {
+		const due = state.dirtySince + cfg.debounceMs;
+		return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+	}
+	const due = state.lastAttempt + cfg.intervalMs;
+	return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+}
+
+/** A peer that is asleep (the nightly EC2 window) or an internet-less Mac is NORMAL,
+ *  not an error. It still feeds the backoff. */
+export function isUnreachable(err: unknown): boolean {
+	const msg = err instanceof Error ? err.message : String(err);
+	return /ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|fetch failed|timed out|The operation was aborted|network/i.test(
+		msg,
+	);
+}