cursedbelt-server 1.1.0 → 2.0.0

package/dist/server/sync/types.d.ts

@@ -67,8 +67,6 @@ export interface RemoteApi {
         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. */
 export interface ApplyContext {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "1.1.0",
+	"version": "2.0.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/noTimerDialsAPeer.spec.ts

@@ -0,0 +1,469 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 🔴 **Nothing in this package may dial a peer on a timer.**
+ *
+ * The owner's ruling, 2026-09-15: *"station shouldn't need it either. This mac can
+ * use a station api to send updates to prod if needed, such as for openclaw. There
+ * should be no polling in cb unless you can make some good case for it that beats
+ * the api option."* He asked for the case against; there isn't one, and this file is
+ * the ruling expressed as a check rather than as a paragraph.
+ *
+ * ## Why a paragraph was not enough
+ *
+ * `REQUEST_POLL_MS = 20_000` did not survive in this repo as a habit. It survived as
+ * **exported public API** (`sync/index.ts:75`), four hours before the ruling, which
+ * meant one more consumer would have turned deleting it into a breaking change
+ * instead of an edit. It cost `vault` **68 % of that app's entire traffic — one
+ * request every 22 seconds, for an app with one user.** Document the WHY; automate
+ * the WHETHER.
+ *
+ * ## The three things called "polling", and which one this forbids
+ *
+ * | | example | verdict |
+ * |---|---|---|
+ * | 🔴 a timer that dials a peer | the old `sync/timer.ts` `probeRequest` → `GET /requested` every 20s | **forbidden — this check** |
+ * | prod → Mac delivery | `sync/signal.ts`: the Mac holds a stream open, the peer pushes down it | fine, and it is what makes the first one unnecessary |
+ * | 🟢 local housekeeping timers | `metrics/metricsBuffer.ts` flush · `auth/sessionStore.ts` prune · `retention/sweeper.ts` | **fine — they issue no network request at all** |
+ *
+ * 🔴 The third row is why this is not "no `setInterval`". `metricsBuffer`'s flush
+ * timer is literally the *"turn many requests into 1"* the owner asked for in the
+ * same conversation, and a rule that deleted it would contradict him while claiming
+ * to enforce him. The forbidden act is **dialing a peer**, not scheduling work. The
+ * same carve-out covers `signal.ts`'s heartbeat (a comment frame on an already-open
+ * socket) and its reconnect backoff, which runs *only while disconnected*.
+ *
+ * ## What it measures, and what it cannot
+ *
+ * For every non-spec source file: strip comments and template literals, find each
+ * timer-scheduling site, resolve its callback (inline, or a same-file identifier),
+ * and red if that callback body issues a `fetch`.
+ *
+ * 🔴 **This is a FLOOR, not a ceiling, and the limit is worth naming because it is
+ * exactly where the original bug lived.** The scan cannot see through an injected
+ * dependency: `sync/timer.ts`'s callback calls `deps.sync(peer)`, which dials, and
+ * that is legitimate (it is the push). A reintroduced `deps.checkRequest(peer)`
+ * would be structurally identical and this check would miss it. Nothing static can
+ * separate those two — so the strict measurement is **behavioural** and lives in
+ * `sync/timer.spec.ts` ("a healthy peer with no local news is dialed ONCE at boot,
+ * then never", 24 simulated hours) and `sync/signal.spec.ts` ("a connected client
+ * issues exactly ONE outbound request, forever"). Those two bound the sync engine
+ * whatever shape a future edit takes; this one catches the obvious reintroduction
+ * anywhere else in the package, where no such harness exists.
+ *
+ * ## Measured against the tree before its strictness was chosen
+ *
+ * A coarser rule — "a file that has a timer AND has a `fetch`" — was tried first and
+ * flagged **seven files, all false positives**: `metricsBuffer`/`sessionStore` match
+ * `.push(` on an array, and `master-lock/lockPage.ts` holds browser code inside a
+ * template literal whose `fetch(paths.status)` runs in the reader's tab, not on a
+ * server timer. Hence the template-literal and comment stripping below, and hence
+ * callback-scoped rather than file-scoped matching. With the dialer removed, the
+ * real count across `src/` is zero — so this starts green on a clean tree rather
+ * than shipping with a baseline of excuses.
+ *
+ * ## Verified failing before it was trusted
+ *
+ * Every assertion below has a fixture proving it reds on the thing it forbids and
+ * passes on the thing it must not touch — see `FIXTURES`. A check that has only ever
+ * been seen green is not a check.
+ */
+
+const REPO = fileURLToPath(new URL('.', import.meta.url));
+
+/** Schedulers, including this package's injected seams (`setTimer`, `setIntervalFn`). */
+const TIMER_CALL =
+  /\b(setInterval|setTimeout|setTimer|setIntervalFn|setTimeoutFn|setImmediate)\s*\(/g;
+
+/** What "dials a peer" looks like once the callback body is isolated. */
+const OUTBOUND_CALL = /\b(fetch|doFetch|fetchImpl)\s*\(/;
+
+/**
+ * Blank out comments, string literals and template literals, preserving LENGTH so
+ * every offset below still refers to the original source.
+ *
+ * 🔴 Both halves are load-bearing in THIS repo. Comments are code to a scanner and
+ * the files here are unusually comment-dense — the paragraph above literally
+ * contains `probeRequest → GET /requested`, and `sync/signal.ts` documents the very
+ * `setTimeout`-that-calls-`fetch` shape it refuses to use. Template literals hold
+ * browser payloads (`master-lock/lockPage.ts`) whose `fetch` runs in a tab.
+ *
+ * Indexing is plain UTF-16 offsets — never `[...source]`, which splits CODE POINTS
+ * and desynchronizes every later index the moment one emoji appears in a comment.
+ */
+export function stripNonCode(source: string): string {
+  const out: string[] = [];
+  let i = 0;
+  const n = source.length;
+  // Template-literal nesting: each `${` inside a template pushes back to code.
+  const stack: Array<'template' | 'expr'> = [];
+  while (i < n) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < n && source[i] !== '\n') {
+        out.push(' ');
+        i++;
+      }
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      while (i < n && !(source[i] === '*' && source[i + 1] === '/')) {
+        out.push(source[i] === '\n' ? '\n' : ' ');
+        i++;
+      }
+      out.push('  ');
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      const quote = c;
+      out.push(' ');
+      i++;
+      while (i < n && source[i] !== quote) {
+        if (source[i] === '\\') {
+          out.push(' ');
+          i++;
+        }
+        if (i < n) {
+          out.push(source[i] === '\n' ? '\n' : ' ');
+          i++;
+        }
+      }
+      out.push(' ');
+      i++;
+      continue;
+    }
+    if (c === '`') {
+      out.push(' ');
+      i++;
+      while (i < n) {
+        if (source[i] === '\\') {
+          out.push('  ');
+          i += 2;
+          continue;
+        }
+        if (source[i] === '`') break;
+        if (source[i] === '$' && source[i + 1] === '{') {
+          // An interpolation is real code again — hand it back to the main loop.
+          stack.push('template');
+          out.push('  ');
+          i += 2;
+          break;
+        }
+        out.push(source[i] === '\n' ? '\n' : ' ');
+        i++;
+      }
+      if (stack.at(-1) === 'template') continue;
+      out.push(' ');
+      i++;
+      continue;
+    }
+    if (c === '}' && stack.at(-1) === 'template') {
+      // Back into the template's literal half.
+      stack.pop();
+      out.push(' ');
+      i++;
+      while (i < n && source[i] !== '`') {
+        out.push(source[i] === '\n' ? '\n' : ' ');
+        i++;
+      }
+      out.push(' ');
+      i++;
+      continue;
+    }
+    out.push(c ?? '');
+    i++;
+  }
+  return out.join('');
+}
+
+/** Slice from `start` (at an opening bracket) to its match, or '' if unbalanced. */
+function balanced(source: string, start: number, open: string, close: string): string {
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    if (source[i] === open) depth++;
+    else if (source[i] === close) {
+      depth--;
+      if (depth === 0) return source.slice(start, i + 1);
+    }
+  }
+  return '';
+}
+
+/** `const name = …` / `function name(…)` / `name = …` — the body, or null. */
+function resolveIdentifier(code: string, name: string): string | null {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const declaration = new RegExp(
+    `(?:const|let|var)\\s+${escaped}\\s*(?::[^=]+)?=|function\\s+${escaped}\\s*\\(`,
+  );
+  const at = declaration.exec(code);
+  if (!at) return null;
+  const brace = code.indexOf('{', at.index);
+  if (brace === -1) return null;
+  const body = balanced(code, brace, '{', '}');
+  return body === '' ? null : body;
+}
+
+export interface TimerSite {
+  scheduler: string;
+  /** 1-indexed line of the scheduling call. */
+  line: number;
+  /** The callback body, or '' when it could not be resolved (a parameter, say). */
+  body: string;
+}
+
+/** Every timer-scheduling site in `source`, with its callback body resolved. */
+export function timerSites(source: string): TimerSite[] {
+  const code = stripNonCode(source);
+  const sites: TimerSite[] = [];
+  for (const match of code.matchAll(TIMER_CALL)) {
+    const scheduler = match[1] as string;
+    const open = match.index + match[0].length - 1;
+    const args = balanced(code, open, '(', ')');
+    // `async () => {…}` is the shape the deleted `probeRequest` used, and it is the
+    // one the first draft of this scan missed — the fixture caught it.
+    const inner = args.slice(1).trimStart().replace(/^async\s+/, '');
+    let body = '';
+    if (inner.startsWith('(') || inner.startsWith('function') || /^[A-Za-z_$]/.test(inner)) {
+      const brace = inner.indexOf('{');
+      const arrow = inner.indexOf('=>');
+      if (brace !== -1 && (arrow === -1 || brace > arrow) && /^[({]|^function/.test(inner)) {
+        // An inline callback with a block body.
+        body = balanced(inner, brace, '{', '}');
+      }
+      if (body === '' && arrow !== -1 && /^\(/.test(inner)) {
+        // A concise arrow body: `() => somethingUp(to, the, comma)`.
+        body = inner.slice(arrow + 2);
+      }
+      if (body === '') {
+        // A bare identifier: `setTimer(tick, ms)`. Resolve it in this file.
+        const identifier = /^([A-Za-z_$][\w$]*)\s*[,)]/.exec(inner)?.[1];
+        if (identifier) body = resolveIdentifier(code, identifier) ?? '';
+      }
+    }
+    sites.push({
+      scheduler,
+      line: code.slice(0, match.index).split('\n').length,
+      body,
+    });
+  }
+  return sites;
+}
+
+/** The rule: a timer callback that issues an outbound request. */
+export function dialingTimerSites(source: string): TimerSite[] {
+  return timerSites(source).filter((site) => OUTBOUND_CALL.test(site.body));
+}
+
+/** Exported constants whose NAME is a polling cadence. See the describe below. */
+export function pollCadenceExports(source: string): string[] {
+  const found: string[] = [];
+  for (const match of stripNonCode(source).matchAll(
+    /export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g,
+  )) {
+    const name = match[1] as string;
+    if (/POLL_?MS$|_POLL_|POLL_INTERVAL/i.test(name)) found.push(name);
+  }
+  return found;
+}
+
+/* ------------------------------------------------------------------ fixtures */
+
+/**
+ * 🔴 Proven both ways. Without these the check could be silently inert — the failure
+ * mode `leafSubpathsImportNothing.spec.ts` calls a vacuous pass, and the one that let
+ * `REQUEST_POLL_MS` reach public API in the first place.
+ */
+const FIXTURES = {
+  reintroducedDialer: {
+    reds: true,
+    why: 'the exact shape that was deleted — a cadence constant and a timer that dials',
+    source: `
+      export const REQUEST_POLL_MS = 20_000;
+      export function startProbe(peer: Peer) {
+        setInterval(async () => {
+          const r = await fetch(\`\${peer.basePath}/requested\`);
+          if (r.ok) syncNow();
+        }, REQUEST_POLL_MS);
+      }`,
+  },
+  dialerBehindAnIdentifier: {
+    reds: true,
+    why: 'the same thing written as a named callback — `setTimer(tick, ms)` is how timer.ts spells it',
+    source: `
+      const tick = (): void => {
+        void fetch(peer.basePath + '/requested');
+      };
+      setTimeout(tick, 20_000);`,
+  },
+  conciseArrowDialer: {
+    reds: true,
+    why: 'a concise arrow body has no braces to match',
+    source: `setInterval(() => fetch(peer.basePath + '/requested'), 20_000);`,
+  },
+  housekeepingFlush: {
+    reds: false,
+    why: "metricsBuffer's flush — the 'turn many requests into 1' timer the owner ASKED for",
+    source: `
+      const flush = (): void => {
+        if (buffer.length === 0) return;
+        insertMany(db, buffer.splice(0, buffer.length));
+      };
+      setInterval(flush, FLUSH_MS).unref();`,
+  },
+  sessionPrune: {
+    reds: false,
+    why: 'a local sweep — no network at all',
+    source: `setInterval(() => { db.query('DELETE FROM sessions WHERE expires_at < ?').run(now()); }, PRUNE_MS);`,
+  },
+  streamHeartbeat: {
+    reds: false,
+    why: "signal.ts's keep-alive: a comment frame on an ALREADY-OPEN socket, not a request",
+    source: `setIntervalFn(() => { write(': keep-alive\\n\\n'); }, heartbeatMs);`,
+  },
+  reconnectSleep: {
+    reds: false,
+    why: 'the reconnect backoff — a sleep that resolves a promise, dialing nothing itself',
+    source: `const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));`,
+  },
+  fetchInAComment: {
+    reds: false,
+    why: 'this repo documents the shapes it refuses; prose must not red the gate',
+    source: `
+      // Never do this: setInterval(() => fetch(peer), 20_000) is the poll we deleted.
+      /* setTimeout(async () => { await fetch(peer.basePath); }, 1000); */
+      setInterval(() => { compactTheLog(); }, HOUR);`,
+  },
+  fetchInBrowserPayload: {
+    reds: false,
+    why: "master-lock/lockPage.ts — the fetch runs in the reader's tab, not on a server timer",
+    source: `
+      const page = \`<script>
+        setInterval(async () => { const r = await fetch(paths.status); render(await r.json()); }, 2000);
+      </script>\`;
+      setInterval(() => { sweepExpiredEnrollments(); }, SWEEP_MS);`,
+  },
+} as const;
+
+/* -------------------------------------------------------------------- the tree */
+
+function sourceFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const path = `${dir}/${entry}`;
+    if (statSync(path).isDirectory()) {
+      sourceFiles(path, found);
+      continue;
+    }
+    if (!entry.endsWith('.ts') && !entry.endsWith('.tsx')) continue;
+    // Specs may construct a dialer on purpose — the fixtures above are the proof
+    // that this check works, and they live in a spec.
+    if (/\.(spec|test)\.tsx?$/.test(entry)) continue;
+    found.push(path);
+  }
+  return found;
+}
+
+describe('the check itself reds on a dialer and not on housekeeping', () => {
+  for (const [name, fixture] of Object.entries(FIXTURES)) {
+    it(`${fixture.reds ? 'reds' : 'passes'}: ${name} — ${fixture.why}`, () => {
+      const hits = dialingTimerSites(fixture.source);
+      expect(
+        hits.length > 0,
+        fixture.reds
+          ? `${name} must be caught: it is a timer callback that dials a peer, and this check is the only thing standing between that shape and the tree`
+          : `${name} is a FALSE POSITIVE — it issues no outbound request. Narrow the rule to the act being forbidden; do not excuse the file. Matched: ${JSON.stringify(hits)}`,
+      ).toBe(fixture.reds);
+    });
+  }
+
+  it('finds the timer sites it is supposed to be looking at (non-vacuity)', () => {
+    // Without this, a stripNonCode that blanked EVERYTHING would pass every
+    // "passes" fixture above and the whole suite would be inert.
+    expect(timerSites(FIXTURES.housekeepingFlush.source)).toHaveLength(1);
+    expect(timerSites(FIXTURES.fetchInBrowserPayload.source)).toHaveLength(1);
+    expect(timerSites(FIXTURES.reintroducedDialer.source)).toHaveLength(1);
+  });
+});
+
+describe('no timer in this package dials a peer', () => {
+  const files = sourceFiles(REPO);
+
+  it('is actually reading the tree', () => {
+    expect(files.length, 'the scan found no source files — it is measuring nothing').toBeGreaterThan(
+      50,
+    );
+    const withTimers = files.filter((f) => timerSites(readText(f)).length > 0);
+    expect(
+      withTimers.length,
+      'no file in this package schedules a timer at all — the scan is not resolving callbacks',
+    ).toBeGreaterThan(5);
+  });
+
+  it('has no timer callback that issues an outbound request', () => {
+    const offenders: string[] = [];
+    for (const file of files) {
+      for (const site of dialingTimerSites(readText(file))) {
+        offenders.push(`${file.slice(REPO.length)}:${site.line} (${site.scheduler})`);
+      }
+    }
+    expect(
+      offenders,
+      'a timer callback here dials a peer. That is the poll the owner ruled out on 2026-09-15 ' +
+        '("There should be no polling in cb unless you can make some good case for it that beats ' +
+        'the api option"), and it cost vault 68% of its traffic the last time it shipped. If the ' +
+        'far side needs to tell this one something, it says so: see src/server/sync/signal.ts. ' +
+        'Do not add the file to an exception list.',
+    ).toEqual([]);
+  });
+});
+
+/**
+ * 🔴 The regression that actually happened: not a stray `setInterval`, but a cadence
+ * published as **public API**, which is what made it expensive to remove. A constant
+ * naming a POLL has no legitimate use in this package.
+ *
+ * 🔴 **`_INTERVAL_MS` is deliberately NOT matched, and that was a measurement, not a
+ * guess.** The first draft included it and immediately flagged two innocents —
+ * `retention/sweeper.ts`'s `DEFAULT_SWEEP_INTERVAL_MS` and `jobs/types.ts`'s
+ * `DEFAULT_FIRE_INTERVAL_MS`, both row (c) housekeeping that touches no network.
+ * Shipping that would have meant two `:ignore` comments on good code on day one,
+ * which is how `check-app-tenancy.ts`'s header records a checker dying: *a checker
+ * that reddens on the record of a bug gets excused line by line until it checks
+ * nothing.* An interval is not a poll; a poll is.
+ */
+describe('no exported symbol names a polling cadence', () => {
+  it('catches the constant that was actually shipped, and spares the innocents', () => {
+    // Verified both ways, from the real names in this tree.
+    expect(pollCadenceExports('export const REQUEST_POLL_MS = 20_000;')).toEqual([
+      'REQUEST_POLL_MS',
+    ]);
+    expect(pollCadenceExports('export const PEER_POLL_INTERVAL = 5;')).toHaveLength(1);
+    expect(pollCadenceExports('export const DEFAULT_SWEEP_INTERVAL_MS = 60_000;')).toEqual([]);
+    expect(pollCadenceExports('export const DEFAULT_FIRE_INTERVAL_MS = 1_000;')).toEqual([]);
+    expect(pollCadenceExports('export const PEER_CONTACT_WRITE_MS = 30_000;')).toEqual([]);
+    expect(pollCadenceExports('// export const REQUEST_POLL_MS = 20_000;')).toEqual([]);
+  });
+
+  it('exports no *_POLL_MS constant', () => {
+    const offenders: string[] = [];
+    for (const file of sourceFiles(REPO)) {
+      for (const name of pollCadenceExports(readText(file))) {
+        offenders.push(`${file.slice(REPO.length)} → ${name}`);
+      }
+    }
+    expect(
+      offenders,
+      'this is exactly how REQUEST_POLL_MS survived: a poll cadence exported from ' +
+        'src/server/sync/index.ts, four hours before the ruling against it. Public API is ' +
+        'the difference between deleting a poll and negotiating its removal with every consumer.',
+    ).toEqual([]);
+  });
+});
+
+function readText(path: string): string {
+  return readFileSync(path, 'utf8');
+}

package/src/server/sync/http.ts

@@ -12,6 +12,7 @@ import { Hono } from "hono";
 import type { OpLog } from "./opLog";
 import type { ApplyContext, ApplyOne, ApplyReport, PeerInfo, RemoteApi, SyncOp } from "./types";
 import { createSyncApplier } from "./engine";
+import { type SyncSignalHub, signalResponse } from "./signal";
 
 const noStore = { "cache-control": "no-store" } as const;
 const SYNC_PAGE = 500;
@@ -65,8 +66,6 @@ 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 {
@@ -98,9 +97,27 @@ export interface ReceiverOptions {
 	 */
 	afterBatch?: (report: ApplyReport) => void | Promise<void>;
 	hooks?: ReceiverHooks;
+	/**
+	 * Mount `GET /signal` — the long-lived stream that replaced the dialer's
+	 * 20-second `GET /requested` probe. Omitted ⇒ the route does not exist, the
+	 * orch-companion idiom: nothing to probe, nothing to authenticate against.
+	 *
+	 * Call {@link SyncSignalHub.announce} after a local write on THIS half and the
+	 * dialing half reconciles within the round trip. See `./signal.ts`.
+	 */
+	signal?: SyncSignalHub;
 }
 
-/** Build the receiver: GET /info, GET /pull, POST /push, GET /requested. */
+/**
+ * Build the receiver: GET /info, GET /pull, POST /push.
+ *
+ * 🔴 There was a fourth route, `GET /requested`, and it is gone (2026-09-15). It
+ * served a single integer — "was Sync now pressed here?" — and existed only to be
+ * asked, every 20 seconds, by a dialer that otherwise had nothing to say. That made
+ * it **68 % of `vault`'s entire traffic**. A receiver with news now says so over
+ * {@link import("./signal")} instead of waiting to be asked; deleting the route is
+ * what stops a stale consumer from keeping the poll alive against a new build.
+ */
 export function createSyncReceiver(options: ReceiverOptions): Hono {
 	const { log, verifyToken } = options;
 	if ((options.applyOne === undefined) === (options.beginBatch === undefined)) {
@@ -135,9 +152,17 @@ export function createSyncReceiver(options: ReceiverOptions): Hono {
 		return c.json(body, 200, noStore);
 	});
 
-	api.get("/requested", (c) =>
-		c.json({ requestedAt: options.hooks?.readRequest?.() ?? null }, 200, noStore),
-	);
+	const signal = options.signal;
+	if (signal !== undefined) {
+		api.get("/signal", (c) =>
+			signalResponse(signal, {
+				// The catch-up frame: a client reconnecting after a sleep learns the
+				// current head without a round trip of its own.
+				initial: { head: log.head(), instanceId: log.instanceId() },
+				signal: c.req.raw.signal,
+			}),
+		);
+	}
 
 	api.get("/pull", (c) => {
 		const afterRaw = c.req.query("after");
@@ -302,15 +327,5 @@ export function createHttpRemote(options: {
 			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;
-			}
-		},
 	};
 }

package/src/server/sync/index.ts

@@ -63,7 +63,22 @@ export {
 	planNextSync,
 	type SyncLoopConfig,
 	type SyncLoopState,
+	type SyncPlan,
 } from "./planner";
+export {
+	SIGNAL_SSE_HEADERS,
+	connectSyncSignal,
+	createSyncSignalHub,
+	encodeNewsFrame,
+	parseNewsFrame,
+	signalResponse,
+	signalStream,
+	type SignalClient,
+	type SignalClientOptions,
+	type SignalStreamOptions,
+	type SyncNews,
+	type SyncSignalHub,
+} from "./signal";
 export {
 	OFFLINE_STATUS,
 	PEER_CONTACT_WRITE_MS,
@@ -72,7 +87,14 @@ export {
 	type SyncStatusReporter,
 	type SyncStatusStore,
 } from "./status";
-export { REQUEST_POLL_MS, startSyncTimer, type SyncTimerDeps, type SyncTimerHandle } from "./timer";
+/**
+ * 🔴 `REQUEST_POLL_MS` was exported from here until 2026-09-15 and is GONE — that
+ * removal is why this package went to 2.0.0. It was a 20-second dial at a configured
+ * peer, and being *public API* is what made it dangerous: one more consumer and
+ * deleting it would have been a breaking change rather than an edit. `./timer`'s
+ * header has the ruling and the measurement; `./signal` is what replaced it.
+ */
+export { startSyncTimer, type SyncTimerDeps, type SyncTimerHandle, type WakeReason } from "./timer";
 export { createSyncAlarm, type AlarmOutcome, type SyncAlarm, type SyncAlarmOptions } from "./alarm";
 export {
 	DEFAULT_HOLD_MS,

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

@@ -1,31 +1,37 @@
 import { describe, expect, test } from "bun:test";
-import { isUnreachable, planNextSync, type SyncLoopConfig } from "./planner";
+import { DEFAULT_LOOP, 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);
+	/**
+	 * 🔴 The load-bearing one. This test used to be called "steady interval when
+	 * clean" and asserted the opposite: that a clean, healthy loop books another
+	 * dial. That interval was 5 minutes at a configured peer with nothing to say,
+	 * and the owner ruled it out on 2026-09-15. `waitMs: null` is the ruling
+	 * expressed as a return value — "there is no reason to wake up".
+	 */
+	test("a clean, healthy state books NOTHING — there is no steady interval", () => {
+		for (const lastAttempt of [0, 100_000, 1_000_000]) {
+			for (const now of [100_000, 500_000, 86_400_000]) {
+				expect(
+					planNextSync({ lastAttempt, consecutiveFailures: 0, dirtySince: null }, now, cfg),
+				).toEqual({ runNow: false, waitMs: null, reason: null });
+			}
+		}
 	});
 
-	test("a dirty flag debounces then wins over the interval", () => {
+	test("a dirty flag debounces, then runs — the push side", () => {
 		const state = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: 10_000 };
-		expect(planNextSync(state, 11_000, cfg)).toEqual({ runNow: false, waitMs: 2_000 });
+		expect(planNextSync(state, 11_000, cfg)).toEqual({
+			runNow: false,
+			waitMs: 2_000,
+			reason: "dirty",
+		});
 		expect(planNextSync(state, 13_000, cfg).runNow).toBe(true);
 	});
 
@@ -39,6 +45,17 @@ describe("planNextSync", () => {
 		// 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);
+		// The backoff is the ONE timer allowed to dial, and only while disconnected.
+		expect(at(1, 0).reason).toBe("retry");
+	});
+
+	test("the config has no interval field left to set", () => {
+		// A cadence key is a cadence somebody configures. Its absence is the check.
+		expect(Object.keys(DEFAULT_LOOP).sort()).toEqual([
+			"backoffBaseMs",
+			"backoffMaxMs",
+			"debounceMs",
+		]);
 	});
 });