cursedbelt 2.6.0 → 2.7.0

package/src/server/sync/engine.ts

@@ -0,0 +1,255 @@
+/**
+ * The dialer half (push-then-pull) and the batch applier. Pure over {@link RemoteApi}
+ * and {@link OpLog} so tests drive two REAL stores through the real receiver — no
+ * HTTP mocks (the notes/vault discipline).
+ *
+ * Push-before-pull is load-bearing: the push cursor must be current before the pull
+ * computes concurrency, so exactly ONE side materializes any given conflict artifact
+ * (vault's rule). Cursors advance only past durably-processed ops; a stopped batch
+ * advances exactly to the failure and the next run resumes there.
+ *
+ * Version skew (notes' hardest-won lesson): the peer's `/info` advertises `opKinds`;
+ * the push stops BEFORE the first op the peer cannot take and reports `blockedBy`
+ * instead of wedging with an error that reads like corruption. Nothing is dropped —
+ * the moment the peer is upgraded, the next push resumes from exactly that op.
+ */
+import type { OpLog } from "./opLog";
+import {
+	type ApplyContext,
+	type ApplyOne,
+	type ApplyReport,
+	type PeerInfo,
+	type RemoteApi,
+	StopBatch,
+	type SyncOp,
+	type SyncSummary,
+} from "./types";
+
+const BATCH = 500;
+
+/** Kit-owned dedupe + ledger insert around the app's per-op merge logic. Everything
+ *  for one op happens in one transaction: state change AND ledger insert, so a crash
+ *  can never apply without recording (double-apply) or record without applying
+ *  (silent drop). */
+export function createSyncApplier(log: OpLog, applyOne: ApplyOne) {
+	return (ops: SyncOp[], ctx: ApplyContext): ApplyReport => {
+		let applied = 0;
+		let seen = 0;
+		let conflicts = 0;
+		let cursor = ops.length > 0 ? (ops[0] as SyncOp).seq - 1 : 0;
+		let error: string | null = null;
+		for (const op of ops) {
+			if (log.has(op.origin, op.originSeq)) {
+				seen++;
+				cursor = op.seq;
+				continue;
+			}
+			try {
+				const outcome = log.transaction(() => {
+					const result = applyOne(op, ctx);
+					log.recordRemote(op);
+					return result;
+				});
+				if (outcome === "applied") applied++;
+				else if (outcome === "conflict") {
+					applied++;
+					conflicts++;
+				}
+				cursor = op.seq;
+			} catch (err) {
+				if (err instanceof StopBatch) {
+					error = err.message;
+					break;
+				}
+				throw err;
+			}
+		}
+		return { applied, seen, conflicts, cursor, error };
+	};
+}
+
+/** Hold back ops the far side must never see (vault values, local-only kinds).
+ *  Return null to hold; return a (possibly redacted) op to send. */
+export type ExportPolicy = (op: SyncOp) => SyncOp | null;
+
+/**
+ * A refusal the peer's `opKinds` cannot express — the SAME "stop before it, never drop
+ * it" contract, one layer deeper. Return a reason to block, or null to send.
+ *
+ * The kind check answers "can the peer take this SHAPE". It is not always the whole
+ * compatibility surface: notes negotiates `meta.set` a second time on the KEY, because
+ * `meta.set` has been a known kind since the log existed, so a NEW key rides a kind the
+ * peer recognizes and fails one layer deeper — as a skip on the receiver that looks like
+ * a delivered op, or, against a build predating that skip, as a wedged push.
+ *
+ * 🔴 This is deliberately NOT the {@link ExportPolicy}. A policy HOLDS an op back
+ * forever (the far side must never see it); a refusal PAUSES in front of it and keeps
+ * the cursor there, so the moment the peer is upgraded the next run resumes from exactly
+ * that op. Expressing "the peer is too old for this" as a hold would silently lose the
+ * mutation.
+ */
+export type PeerRefusal = (op: SyncOp, info: PeerInfo) => string | null;
+
+export interface EngineOptions {
+	log: OpLog;
+	/** The op kinds THIS build understands — advertised via /info and used to stop a
+	 *  push into an older peer before the first op it cannot take. */
+	opKinds: readonly string[];
+	policy?: ExportPolicy;
+	/** Optional second compatibility check, finer than `opKinds`. See {@link PeerRefusal}. */
+	peerRefusal?: PeerRefusal;
+	/** Byte budget per push request (default ~1 MiB). A backlog of large ops is
+	 *  sent as several requests instead of one that trips the proxy's body cap —
+	 *  the 413 WEDGES otherwise: the batch never shrinks, the cursor never moves.
+	 *  A single op larger than the budget still goes alone. */
+	maxPushBytes?: number;
+}
+
+const DEFAULT_MAX_PUSH_BYTES = 1_000_000;
+
+/** Split ops into request-sized chunks by serialized payload weight. */
+export function chunkByBytes(ops: SyncOp[], maxBytes: number): SyncOp[][] {
+	const chunks: SyncOp[][] = [];
+	let current: SyncOp[] = [];
+	let weight = 0;
+	for (const op of ops) {
+		const size = JSON.stringify(op).length + 1;
+		if (current.length > 0 && weight + size > maxBytes) {
+			chunks.push(current);
+			current = [];
+			weight = 0;
+		}
+		current.push(op);
+		weight += size;
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks;
+}
+
+export async function pushToRemote(
+	opts: EngineOptions,
+	remote: RemoteApi,
+): Promise<Pick<SyncSummary, "remoteId" | "pushed" | "held" | "conflicts" | "blockedBy">> {
+	const info = await remote.info();
+	const remoteId = info.instanceId;
+	const remoteKinds = new Set(info.opKinds);
+	// One predicate for both compatibility layers, so the "stop before it, leave the
+	// cursor there" path is shared and a caller cannot accidentally give the finer
+	// check the weaker (drop-it) semantics.
+	const refusedBecause = (op: SyncOp): string | null => {
+		if (!remoteKinds.has(op.kind)) return op.kind;
+		return opts.peerRefusal?.(op, info) ?? null;
+	};
+	const { log } = opts;
+	const peerHas = log.cursor(remoteId, "pull");
+	let cursor = log.cursor(remoteId, "push");
+	let pushed = 0;
+	let held = 0;
+	// Conflicts the RECEIVER detected while applying our push — push-before-pull means
+	// exactly one side detects any given concurrency, and when that side is the
+	// receiver the count would otherwise vanish from the dialer's summary.
+	let conflicts = 0;
+	let blockedBy: string | undefined;
+	for (;;) {
+		const page = log.listAfter(cursor, remoteId, BATCH);
+		if (page.ops.length === 0) {
+			// Nothing sendable in the window — advance past the peer's own reflected ops.
+			if (page.cursor > cursor) {
+				cursor = page.cursor;
+				log.setCursor(remoteId, "push", cursor);
+			}
+			break;
+		}
+		const blockedAt = page.ops.findIndex((op) => refusedBecause(op) !== null);
+		const sendableRaw = blockedAt === -1 ? page.ops : page.ops.slice(0, blockedAt);
+		if (blockedAt !== -1) {
+			const op = page.ops[blockedAt] as SyncOp;
+			blockedBy = refusedBecause(op) ?? op.kind;
+		}
+
+		const outbound: SyncOp[] = [];
+		for (const op of sendableRaw) {
+			const filtered = opts.policy ? opts.policy(op) : op;
+			if (filtered === null) held++;
+			else outbound.push(filtered);
+		}
+		if (outbound.length > 0) {
+			// Chunked by bytes so a large backlog cannot trip the proxy's body cap;
+			// the cursor advances per DELIVERED chunk, so an interrupted push resumes
+			// at the failure with nothing lost or re-sent.
+			for (const chunk of chunkByBytes(outbound, opts.maxPushBytes ?? DEFAULT_MAX_PUSH_BYTES)) {
+				const report = await remote.push({ ops: chunk, peerHas });
+				pushed += report.applied;
+				conflicts += report.conflicts;
+				if (report.error !== null) {
+					// The remote stopped inside the chunk (its own ordering guard). Advance
+					// to what it durably took and stop; the next run retries from there.
+					const processed = report.applied + report.seen;
+					if (processed > 0) {
+						cursor = (chunk[processed - 1] as SyncOp).seq;
+						log.setCursor(remoteId, "push", cursor);
+					}
+					return { remoteId, pushed, held, conflicts, blockedBy: report.error };
+				}
+				cursor = (chunk[chunk.length - 1] as SyncOp).seq;
+				log.setCursor(remoteId, "push", cursor);
+			}
+		}
+		if (sendableRaw.length === 0) break; // the very next op is blocked — nothing to advance past
+		cursor = (sendableRaw[sendableRaw.length - 1] as SyncOp).seq;
+		log.setCursor(remoteId, "push", cursor);
+		if (blockedBy) break;
+		if (page.cursor >= page.head && blockedAt === -1) {
+			// Window served through head with nothing blocked — take the page cursor so
+			// trailing excluded ops don't re-page forever.
+			cursor = page.cursor;
+			log.setCursor(remoteId, "push", cursor);
+			break;
+		}
+	}
+	return { remoteId, pushed, held, conflicts, blockedBy };
+}
+
+export async function pullFromRemote(
+	opts: EngineOptions,
+	remote: RemoteApi,
+	applyBatch: (ops: SyncOp[], ctx: ApplyContext) => ApplyReport,
+): Promise<Pick<SyncSummary, "remoteId" | "pulled" | "conflicts">> {
+	const info = await remote.info();
+	const remoteId = info.instanceId;
+	const { log } = opts;
+	const self = log.instanceId();
+	const peerReceivedUpTo = log.cursor(remoteId, "push");
+	let cursor = log.cursor(remoteId, "pull");
+	let pulled = 0;
+	let conflicts = 0;
+	for (;;) {
+		const page = await remote.pull(cursor, self);
+		if (page.ops.length === 0 && page.cursor <= cursor) break;
+		const report = applyBatch(page.ops, { peerId: remoteId, peerReceivedUpTo });
+		pulled += report.applied;
+		conflicts += report.conflicts;
+		if (report.error !== null) {
+			if (report.cursor > cursor) {
+				cursor = report.cursor;
+				log.setCursor(remoteId, "pull", cursor);
+			}
+			break;
+		}
+		cursor = page.ops.length === 0 ? page.cursor : Math.max(report.cursor, page.cursor);
+		log.setCursor(remoteId, "pull", cursor);
+		if (page.cursor >= page.head) break;
+	}
+	return { remoteId, pulled, conflicts };
+}
+
+/** One full reconciliation: push, then pull. */
+export async function runSync(
+	opts: EngineOptions,
+	remote: RemoteApi,
+	applyBatch: (ops: SyncOp[], ctx: ApplyContext) => ApplyReport,
+): Promise<SyncSummary> {
+	const push = await pushToRemote(opts, remote);
+	const pull = await pullFromRemote(opts, remote, applyBatch);
+	return { ...push, ...pull, conflicts: push.conflicts + pull.conflicts, remoteId: push.remoteId };
+}

package/src/server/sync/http.ts

@@ -0,0 +1,316 @@
+/**
+ * The HTTP transport: the receiver sub-app the internet-facing instance mounts, and
+ * the fetch-backed {@link RemoteApi} the dialer binds to.
+ *
+ * Mount the receiver OUTSIDE any browser-session gate (a machine peer has no session;
+ * notes' 401 trap: a token route registered after the session gate answers 401 with a
+ * valid token) but behind the token gate built here. An unconfigured receiver simply
+ * does not exist — the orch-companion idiom: no token verifier, no routes, nothing to
+ * probe.
+ */
+import { Hono } from "hono";
+import type { OpLog } from "./opLog";
+import type { ApplyContext, ApplyOne, ApplyReport, PeerInfo, RemoteApi, SyncOp } from "./types";
+import { createSyncApplier } from "./engine";
+
+const noStore = { "cache-control": "no-store" } as const;
+const SYNC_PAGE = 500;
+
+/**
+ * Byte budget for ONE pull page — the mirror of `maxPushBytes` on the push side,
+ * and it was missing.
+ *
+ * 🔴 Measured against live prod on 2026-08-01: `GET /pull?after=0` against
+ * station's 709-op log served **37 MB at 309 ops** and then OOM-killed the unit
+ * (`memoryMax=300M` on a t3.micro). `SYNC_PAGE = 500` is a COUNT cap, and these
+ * ops are not small — a 130 KB overview snapshot, a 68 KB fleet CSV — so 500 of
+ * them is tens of megabytes serialized into one response buffer.
+ *
+ * What makes it worse than a slow request is that it does not converge: the unit
+ * dies, systemd restarts it, the dialer retries the identical oversized pull, and
+ * the pair never advances. Push already learned this exact lesson (a 413 wedges
+ * because the batch never shrinks); the receiving half kept only the count cap
+ * because a fully-caught-up peer never asks for enough rows to notice.
+ *
+ * A single op larger than the budget is still served alone — refusing it would
+ * wedge the log permanently on that op, which is worse than one big response.
+ */
+const SYNC_PAGE_BYTES = 4_000_000;
+
+/**
+ * Trim a page to the byte budget, keeping it a PREFIX so `cursor` stays the seq
+ * of the last op actually returned. Anything else silently drops ops: the caller
+ * advances past rows it never received and no later pull will offer them again.
+ */
+export function capPageBytes<T extends { seq: number }>(
+	ops: T[],
+	maxBytes: number,
+): { ops: T[]; truncated: boolean } {
+	let weight = 0;
+	for (let i = 0; i < ops.length; i++) {
+		weight += JSON.stringify(ops[i]).length + 1;
+		if (weight > maxBytes && i > 0) return { ops: ops.slice(0, i), truncated: true };
+	}
+	return { ops, truncated: false };
+}
+
+/** Coerce and clamp the caller's peer id — a cursor key and a label, never trusted
+ *  further than that. */
+function peerIdOf(header: string | undefined, query: string | undefined): string {
+	const raw = query ?? header ?? "";
+	return /^[0-9A-Za-z_-]{1,64}$/.test(raw) ? raw : "peer";
+}
+
+export interface ReceiverHooks {
+	/** Every authenticated hit — the only evidence a non-dialing half has that it is
+	 *  in step (vault's `lastPeerContactAt` lesson). */
+	onPeerContact?: (peerId: string) => void;
+	/** The "Sync now was pressed HERE" stamp the dialer polls. */
+	readRequest?: () => number | null;
+}
+
+export interface ReceiverOptions {
+	log: OpLog;
+	opKinds: readonly string[];
+	/** Verify a presented bearer token for the sync scope. Return false to refuse.
+	 *  Bind this to a TokenStore (`(t) => tokens.verify(t, "sync") !== null`) or a
+	 *  constant-time static compare — the kit does not care which. */
+	verifyToken: (presented: string) => boolean;
+	/** The app's merge logic, when it is stateless across a batch (vault, station).
+	 *  Give this OR {@link beginBatch}, never both. */
+	applyOne?: ApplyOne;
+	/**
+	 * The app's merge logic when the batch needs state of its own — called once per
+	 * `POST /push`, so what it closes over belongs to that batch alone.
+	 *
+	 * 🔴 A single shared `ApplyOne` closing over a mutable accumulator is the bug this
+	 * exists to make unrepresentable: two pushes in flight would pour into one counter,
+	 * and the second response would carry the first's leftovers. notes needs it — its
+	 * applier collects the attachment blobs a purge orphaned and the items whose search
+	 * index must be rebuilt, neither of which can happen inside the op's transaction.
+	 */
+	beginBatch?: () => ApplyOne;
+	/**
+	 * Post-commit work, awaited BEFORE the response goes out — an index rebuild, a blob
+	 * delete that is a network call. Anything that must not run inside the applier's
+	 * transaction but must be done by the time the caller sees a 200, or the caller will
+	 * advance its cursor past work that never happened.
+	 */
+	afterBatch?: (report: ApplyReport) => void | Promise<void>;
+	hooks?: ReceiverHooks;
+}
+
+/** Build the receiver: GET /info, GET /pull, POST /push, GET /requested. */
+export function createSyncReceiver(options: ReceiverOptions): Hono {
+	const { log, verifyToken } = options;
+	if ((options.applyOne === undefined) === (options.beginBatch === undefined)) {
+		// Loud at construction, because both mistakes are silent at runtime: neither
+		// given means every op vanishes as "ignored"; both given means one of the two
+		// is quietly never called.
+		throw new Error("[vault sync] receiver: give exactly one of `applyOne` or `beginBatch`");
+	}
+	const beginBatch = options.beginBatch ?? (() => options.applyOne as ApplyOne);
+	const api = new Hono();
+
+	api.use("*", async (c, next) => {
+		const header = c.req.header("authorization") ?? "";
+		const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+		if (presented.length === 0 || !verifyToken(presented)) {
+			return c.json({ error: "unauthorized" }, 401, noStore);
+		}
+		await next();
+	});
+	// AFTER the gate — an unauthenticated caller must never look like peer contact.
+	api.use("*", async (c, next) => {
+		options.hooks?.onPeerContact?.(peerIdOf(c.req.header("x-sync-peer"), c.req.query("peer")));
+		await next();
+	});
+
+	api.get("/info", (c) => {
+		const body: PeerInfo = {
+			instanceId: log.instanceId(),
+			head: log.head(),
+			opKinds: [...options.opKinds],
+		};
+		return c.json(body, 200, noStore);
+	});
+
+	api.get("/requested", (c) =>
+		c.json({ requestedAt: options.hooks?.readRequest?.() ?? null }, 200, noStore),
+	);
+
+	api.get("/pull", (c) => {
+		const afterRaw = c.req.query("after");
+		const after = afterRaw !== undefined && /^\d+$/.test(afterRaw) ? Number(afterRaw) : 0;
+		const excludeRaw = c.req.query("exclude") ?? "";
+		const exclude = /^[0-9A-Za-z_-]{1,64}$/.test(excludeRaw) ? excludeRaw : "";
+		const page = log.listAfter(after, exclude, SYNC_PAGE);
+		// Count cap first (cheap, bounds the serialize below), then the byte cap.
+		const capped = capPageBytes(page.ops, SYNC_PAGE_BYTES);
+		// The cursor must name the last op ACTUALLY served, or the peer skips the
+		// remainder forever. `head` is untouched — it is how the caller knows to
+		// come back for another page.
+		const cursor = capped.truncated
+			? ((capped.ops.at(-1) as SyncOp | undefined)?.seq ?? after)
+			: page.cursor;
+		log.setCursor(peerIdOf(c.req.header("x-sync-peer"), c.req.query("peer")), "served", cursor);
+		return c.json({ ops: capped.ops, cursor, head: page.head }, 200, noStore);
+	});
+
+	api.post("/push", async (c) => {
+		let body: unknown;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "bad_request" }, 400, noStore);
+		}
+		if (body === null || typeof body !== "object")
+			return c.json({ error: "bad_request" }, 400, noStore);
+		const { ops, peerHas } = body as { ops?: unknown; peerHas?: unknown };
+		if (!Array.isArray(ops)) return c.json({ error: "bad_request" }, 400, noStore);
+		const peerId = peerIdOf(c.req.header("x-sync-peer"), c.req.query("peer"));
+		// The client's DURABLE pull cursor for us is the crash-safe concurrency bound;
+		// fall back to our served cursor if an older caller omits it (vault's rule).
+		const bound =
+			typeof peerHas === "number" && Number.isInteger(peerHas) && peerHas >= 0
+				? peerHas
+				: log.cursor(peerId, "served");
+		const ctx: ApplyContext = { peerId, peerReceivedUpTo: bound };
+		const report: ApplyReport = createSyncApplier(log, beginBatch())(ops as SyncOp[], ctx);
+		// Awaited, not fire-and-forget: the caller advances its push cursor on this
+		// response, so work still outstanding when it lands is work nobody will redo.
+		await options.afterBatch?.(report);
+		return c.json(report, report.error === null ? 200 : 409, noStore);
+	});
+
+	return api;
+}
+
+/**
+ * The fetch-backed remote the dialer binds to. `basePath` is where the peer
+ * mounted its receiver (e.g. `https://station.cursedalchemy.com/api/sync`).
+ *
+ * 🔴 **Redirects are REFUSED, never followed** (2026-08-21). `fetch` follows by
+ * default, and that turned a moved hostname into eight days of silence: the
+ * console's subdomain cutover made `station.cursedalchemy.com` a **301** to
+ * `station.cursedalchemy.com`, the dialer followed it, Cloudflare Access answered
+ * the un-credentialed redirect with its **login page — HTTP 200, text/html**,
+ * and `r.json()` threw `Failed to parse JSON`. The dialer logs that as
+ * `[sync] failed (ignored)` and retries forever, so:
+ *
+ *   · every mirrored report on prod froze at the moment of the cutover, while
+ *     each one still rendered a confident `capturedAt` age;
+ *   · nothing was red anywhere — not a gate, not a smoke, not `/healthz`;
+ *   · the error named JSON, which is three layers away from the cause.
+ *
+ * A 3xx here can only ever mean the peer address is wrong, so it is reported as
+ * exactly that, with the destination in the message. Following a redirect
+ * silently is how a sync survives its own misconfiguration.
+ *
+ * The same reasoning covers a 2xx that is not JSON: an Access login page, an
+ * nginx error page or a captive portal all arrive as `200 text/html`, and
+ * "Failed to parse JSON" is the least useful sentence available about any of
+ * them. {@link readJson} names the status, the content type and a snippet.
+ */
+export function createHttpRemote(options: {
+	basePath: string;
+	token: string;
+	selfId: string;
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+	/**
+	 * Extra headers for THIS peer's host — the Cloudflare Access service token,
+	 * where the receiver sits behind an Access application. Host-scoped BY THE
+	 * CALLER — never a blanket wrapper: a credential sent where it is not needed is a
+	 * credential leaked. The retired generation had a `satellite-kit/cloudflare-access`
+	 * helper that did the host-scoping; no caller in this app passes this today
+	 * (`syncClient.ts` handles Access by refusing to follow its 302 instead), so a
+	 * future one owns the scoping itself.
+	 */
+	extraHeaders?: Record<string, string>;
+}): RemoteApi {
+	const base = options.basePath.replace(/\/$/, "");
+	const doFetch = options.fetchImpl ?? fetch;
+	const timeout = options.timeoutMs ?? 60_000;
+	const peer = encodeURIComponent(options.selfId);
+	const request = async (path: string, init?: RequestInit): Promise<Response> => {
+		const response = await doFetch(`${base}${path}`, {
+			...init,
+			// 🔴 See the header note: a followed redirect is how this sync spent
+			// eight days reporting a JSON parse error about an Access login page.
+			redirect: "manual",
+			headers: {
+				authorization: `Bearer ${options.token}`,
+				"x-sync-peer": options.selfId,
+				...(options.extraHeaders ?? {}),
+				...(init?.headers ?? {}),
+			},
+			signal: AbortSignal.timeout(timeout),
+		});
+		if (response.status >= 300 && response.status < 400) {
+			throw new Error(
+				`${path}: ${response.status} — the peer address redirects to ` +
+					`${response.headers.get("location") ?? "an unnamed destination"}. ` +
+					`The sync URL points at a host that has moved; point it at the real one.`,
+			);
+		}
+		if (response.status === 401) {
+			throw new Error(`${path}: 401 — the sync token was refused.`);
+		}
+		return response;
+	};
+
+	/**
+	 * Read a JSON body, or say what actually arrived.
+	 *
+	 * A 200 carrying `text/html` is a login page or an error page, and it is the
+	 * shape every "the address is wrong" failure takes once a redirect has been
+	 * followed. Naming the content type and the first line turns an unactionable
+	 * `Failed to parse JSON` into the cause.
+	 */
+	const readJson = async <T>(r: Response, path: string): Promise<T> => {
+		const text = await r.text();
+		try {
+			return JSON.parse(text) as T;
+		} catch {
+			const type = r.headers.get("content-type") ?? "no content-type";
+			throw new Error(
+				`${path}: ${r.status} answered ${type}, not JSON — ` +
+					`${text.trim().slice(0, 120).replace(/\s+/g, " ") || "(empty body)"}`,
+			);
+		}
+	};
+	return {
+		async info() {
+			const r = await request("/info");
+			if (!r.ok) throw new Error(`sync/info: ${r.status}`);
+			return await readJson<PeerInfo>(r, "sync/info");
+		},
+		async pull(after, excludeOrigin) {
+			const r = await request(
+				`/pull?after=${after}&exclude=${encodeURIComponent(excludeOrigin)}&peer=${peer}`,
+			);
+			if (!r.ok) throw new Error(`sync/pull: ${r.status}`);
+			return await readJson<{ ops: SyncOp[]; cursor: number; head: number }>(r, "sync/pull");
+		},
+		async push(payload) {
+			const r = await request(`/push?peer=${peer}`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(payload),
+			});
+			if (!r.ok && r.status !== 409) throw new Error(`sync/push: ${r.status}`);
+			return await readJson<ApplyReport>(r, "sync/push");
+		},
+		async requestedAt() {
+			try {
+				const r = await request("/requested");
+				if (!r.ok) return null;
+				const body = await readJson<{ requestedAt?: unknown }>(r, "sync/requested");
+				return typeof body.requestedAt === "number" ? body.requestedAt : null;
+			} catch {
+				return null;
+			}
+		},
+	};
+}