cursedbelt-server 1.1.0 → 2.0.0

package/src/server/sync/timer.ts

@@ -1,13 +1,45 @@
 /**
- * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
- * half only; a failure NEVER takes the host daemon down (an unsynced instance still
- * serves and still accepts writes — that is the point of two independently-writable
- * instances). The timer is `unref`'d so it never holds the process open.
+ * The in-process sync loop. Runs on the dialing half only; a failure NEVER takes
+ * the host daemon down (an unsynced instance still serves and still accepts writes
+ * — that is the point of two independently-writable instances). The timer is
+ * `unref`'d so it never holds the process open.
  *
- * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
- * effect without a restart. The "Sync now" fast lane polls the receiver's request
- * stamp every ~20s while healthy, so a button press on the far side means seconds,
- * not "sometime in the next interval".
+ * ── 🔴 This loop does not poll, and it may never be made to again ────────────────
+ *
+ * Until 2026-09-15 this file was a dialer twice over: a `GET /requested` probe at a
+ * peer every 20 s while healthy (`REQUEST_POLL_MS`), and a full reconciliation every
+ * 5 minutes (`DEFAULT_LOOP.intervalMs`) whether or not either side had news. The
+ * owner ruled both out — *"There should be no polling in cb unless you can make some
+ * good case for it that beats the api option"* — and the case against was asked for
+ * and not found. Measured in `vault`: the 20 s probe alone was **68 % of that app's
+ * entire traffic, one request every 22 seconds, for an app with one user.**
+ *
+ * Both are gone. Every wake-up this loop books now carries a {@link WakeReason}, and
+ * that union is deliberately closed with no periodic member — there is no value you
+ * can pass to {@link schedule} that means "again in a while". That makes the poll
+ * unrepresentable rather than merely discouraged, which matters because
+ * `REQUEST_POLL_MS` did not survive as a habit; it survived as **exported public
+ * API**, and the next consumer to import it would have made its removal a breaking
+ * change instead of an edit.
+ *
+ * What replaced each half:
+ *
+ *   · **Mac → peer** is a PUSH. `markDirty()` after a local write books one
+ *     debounced run: the side that has news says so, which is what "sync now"
+ *     should always have been.
+ *   · **peer → Mac** is `./signal` — the dialing half holds one long-lived stream
+ *     open and the receiver writes a frame when its log grows. The Mac is still
+ *     purely a client: it dials OUT, listens on nothing, and no timer fires.
+ *
+ * 🔴 **`markDirty()` is now REQUIRED wiring, not an optimization.** With the steady
+ * interval gone it is the only thing that pushes a local write. A consumer that
+ * takes the handle and drops `markDirty` (which `apps/vault` did while the interval
+ * still covered for it) will sit clean and silent forever.
+ *
+ * The peer is re-resolved on every run, so revoking a link takes effect without a
+ * restart. Linking a NEW peer is a user action and is noticed at the next
+ * `syncNow()` / `markDirty()` rather than by a timer that was watching for it —
+ * call `syncNow()` after a link and it is immediate.
  */
 import {
 	isUnreachable,
@@ -19,21 +51,35 @@ import {
 import type { SyncStatusReporter } from "./status";
 import type { SyncSummary } from "./types";
 
-export const REQUEST_POLL_MS = 20_000;
+/**
+ * One reconciliation shortly after start: catch up on whatever happened while this
+ * process was down. A single shot at boot, not a cadence — the same catch-up a push
+ * model needs anyway.
+ */
 const KICKOFF_MS = 5_000;
 
+/**
+ * 🔴 Every reason this loop is allowed to wake up. There is deliberately no
+ * `"interval"` / `"poll"` member, and adding one is the change this whole file
+ * exists to refuse.
+ *
+ *   · `boot`   — one catch-up run at start.
+ *   · `dirty`  — local ops are waiting to be pushed (debounced).
+ *   · `forced` — `syncNow()`, or a frame off `./signal` saying the peer has news.
+ *   · `retry`  — the last attempt failed. Runs only while disconnected, never
+ *                against a healthy peer; that is a reconnect backoff, not a poll.
+ */
+export type WakeReason = "boot" | "dirty" | "forced" | "retry";
+
 export interface SyncTimerDeps {
-	/** Re-read every tick: null = not linked (quiet no-op, re-checked next tick). */
+	/** Re-read on every run: null = not linked (quiet no-op). */
 	resolvePeer: () => { basePath: string; token: string } | null;
 	/** Run one full reconciliation against the resolved peer. */
 	sync: (peer: { basePath: string; token: string }) => Promise<SyncSummary>;
 	/** The local op-log head — a head beyond the last synced one marks dirty. */
 	head: () => number;
-	/** Ask the peer whether its "Sync now" was pressed; null on any failure. */
-	checkRequest?: (peer: { basePath: string; token: string }) => Promise<number | null>;
 	status?: SyncStatusReporter;
 	loop?: SyncLoopConfig;
-	requestPollMs?: number;
 	now?: () => number;
 	setTimer?: (fn: () => void, ms: number) => unknown;
 	clearTimer?: (handle: unknown) => void;
@@ -45,9 +91,16 @@ export interface SyncTimerDeps {
 
 export interface SyncTimerHandle {
 	stop(): void;
-	/** Run the next tick immediately (the "Sync now" button on the dialing half). */
+	/**
+	 * Run now. The "Sync now" button on the dialing half, and the handler for a
+	 * `./signal` frame — both are "something has news", which is a push.
+	 */
 	syncNow(): void;
-	/** Mark local writes pending (call after any local op) — debounces a burst. */
+	/**
+	 * Mark local writes pending — call after any local op. 🔴 Required wiring: with
+	 * no steady interval this is what pushes a local write. A burst coalesces into
+	 * one run via the planner's debounce.
+	 */
 	markDirty(): void;
 }
 
@@ -68,7 +121,6 @@ export function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle {
 	const warn = deps.warn ?? ((m: string) => console.error(m));
 	const status = deps.status;
 	const peerLabel = deps.peerLabel ?? defaultPeerLabel;
-	const requestPollMs = deps.requestPollMs ?? REQUEST_POLL_MS;
 	status?.update({ enabled: true, role: "dialer" });
 
 	const state: SyncLoopState = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: null };
@@ -76,38 +128,56 @@ export function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle {
 	let stopped = false;
 	let handle: unknown = null;
 	let reportedUnreachable = false;
-	let forceRun = false;
-	let handledRequestAt = 0;
-	let probing = false;
+	/**
+	 * 🔴 Starts TRUE: the boot catch-up is a forced run, not a scheduled one.
+	 *
+	 * It used to fall out of the planner for free — `lastAttempt: 0` plus a steady
+	 * `intervalMs` made the first tick always due. With no interval left, a clean
+	 * healthy state plans nothing, so the one run this loop genuinely owes at
+	 * startup has to be asked for explicitly. It has a reason: this process may have
+	 * missed ops while it was down, and catching up is exactly what a push model
+	 * does on reconnect.
+	 */
+	let forceRun = true;
 	let inFlight = false;
+	/** Why the currently-booked wake exists, or null when the loop is quiet. */
+	let bookedFor: WakeReason | null = null;
 
-	const schedule = (ms: number): void => {
+	/**
+	 * Book the next wake-up. 🔴 The `reason` is not decoration — it is the type-level
+	 * guard: {@link WakeReason} has no periodic member, so there is no way to spell
+	 * "wake again in `intervalMs`" through this function. It is also read back by
+	 * {@link SyncTimerHandle.markDirty}, which must not push an imminent forced run
+	 * out to a debounce.
+	 */
+	const schedule = (reason: WakeReason, ms: number): void => {
 		if (stopped) return;
 		if (handle !== null) clearTimer(handle);
 		handle = setTimer(tick, ms);
 		(handle as { unref?: () => void })?.unref?.();
+		bookedFor = reason;
 	};
 
-	const sleepFor = (waitMs: number): number => {
-		const healthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-		return Math.max(1, healthy ? Math.min(waitMs, requestPollMs) : waitMs);
+	/** Nothing to push, nothing to retry: cancel any pending wake and go quiet. */
+	const idle = (): void => {
+		if (handle !== null) clearTimer(handle);
+		handle = null;
+		bookedFor = null;
 	};
 
-	const probeRequest = (peer: { basePath: string; token: string }): void => {
-		if (probing || requestPollMs === 0 || !deps.checkRequest) return;
-		probing = true;
-		void deps
-			.checkRequest(peer)
-			.then((requestedAt) => {
-				if (stopped || requestedAt === null || requestedAt <= handledRequestAt) return;
-				handledRequestAt = requestedAt;
-				log("[sync] sync requested from the peer — running now.");
-				forceRun = true;
-				schedule(1);
-			})
-			.finally(() => {
-				probing = false;
-			});
+	/** Apply the planner's verdict — the ONE place a wake-up is booked or declined. */
+	const bookNext = (): void => {
+		if (stopped) return;
+		if (forceRun) {
+			schedule("forced", 1);
+			return;
+		}
+		const plan = planNextSync(state, now(), loop);
+		if (plan.waitMs === null || plan.reason === null) {
+			idle();
+			return;
+		}
+		schedule(plan.reason, Math.max(1, plan.waitMs));
 	};
 
 	const tick = (): void => {
@@ -122,15 +192,17 @@ export function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle {
 			pending: Math.max(0, head - syncedHead),
 		});
 		if (peer === null) {
-			schedule(loop.intervalMs);
+			// Not linked. Nothing to dial and nothing to wait for — `syncNow()` or the
+			// next local write re-checks. A re-check timer here would be a poll at a
+			// peer that does not exist yet.
+			forceRun = false;
+			idle();
 			return;
 		}
 
 		const plan = planNextSync(state, now(), loop);
 		if (!plan.runNow && !forceRun) {
-			const linkedAndHealthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-			schedule(sleepFor(plan.waitMs));
-			if (linkedAndHealthy) probeRequest(peer);
+			bookNext();
 			return;
 		}
 
@@ -182,26 +254,31 @@ export function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle {
 			})
 			.finally(() => {
 				inFlight = false;
-				if (forceRun) schedule(1);
-				else schedule(sleepFor(Math.max(1_000, planNextSync(state, now(), loop).waitMs)));
+				// A local write that landed mid-run is news the planner must see.
+				if (deps.head() > syncedHead && state.dirtySince === null) state.dirtySince = now();
+				bookNext();
 			});
 	};
 
-	schedule(KICKOFF_MS);
+	schedule("boot", KICKOFF_MS);
 	return {
 		stop: () => {
 			stopped = true;
 			if (handle !== null) clearTimer(handle);
+			handle = null;
 		},
 		syncNow: () => {
 			if (stopped) return;
 			forceRun = true;
-			schedule(1);
+			schedule("forced", 1);
 		},
 		markDirty: () => {
 			if (stopped) return;
 			if (state.dirtySince === null) state.dirtySince = now();
-			schedule(1);
+			// A forced run is already due in ~1ms and will push these ops; re-booking
+			// would replace it with a 3s debounce and make "Sync now" slower.
+			if (bookedFor === "forced") return;
+			bookNext();
 		},
 	};
 }

package/src/server/sync/types.ts

@@ -67,8 +67,6 @@ export interface RemoteApi {
 		excludeOrigin: string,
 	): Promise<{ ops: SyncOp[]; cursor: number; head: number }>;
 	push(payload: { ops: SyncOp[]; peerHas: number }): Promise<ApplyReport>;
-	/** The receiver's "someone pressed Sync now here" stamp; null when unsupported. */
-	requestedAt?(): Promise<number | null>;
 }
 
 /** Context the applier gets per batch — vault's concurrency bound. */