cursedbelt 2.7.0 → 3.0.0

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

@@ -1,158 +0,0 @@
-/**
- * `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

@@ -1,90 +0,0 @@
-/**
- * `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

@@ -1,110 +0,0 @@
-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

@@ -1,189 +0,0 @@
-/**
- * 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

@@ -1,53 +0,0 @@
-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

@@ -1,62 +0,0 @@
-/**
- * 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,
-	);
-}