cursedbelt-server 1.1.0 → 2.0.0

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

@@ -11,6 +11,7 @@
 import { Hono } from "hono";
 import type { OpLog } from "./opLog";
 import type { ApplyOne, ApplyReport, RemoteApi } from "./types";
+import { type SyncSignalHub } from "./signal";
 /**
  * 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
@@ -26,8 +27,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 {
     log: OpLog;
@@ -58,8 +57,26 @@ 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 declare function createSyncReceiver(options: ReceiverOptions): Hono;
 /**
  * The fetch-backed remote the dialer binds to. `basePath` is where the peer

package/dist/server/sync/http.js

@@ -10,6 +10,7 @@
  */
 import { Hono } from "hono";
 import { createSyncApplier } from "./engine";
+import { signalResponse } from "./signal";
 const noStore = { "cache-control": "no-store" };
 const SYNC_PAGE = 500;
 /**
@@ -52,7 +53,16 @@ function peerIdOf(header, query) {
     const raw = query ?? header ?? "";
     return /^[0-9A-Za-z_-]{1,64}$/.test(raw) ? raw : "peer";
 }
-/** 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) {
     const { log, verifyToken } = options;
     if ((options.applyOne === undefined) === (options.beginBatch === undefined)) {
@@ -84,7 +94,15 @@ export function createSyncReceiver(options) {
         };
         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");
         const after = afterRaw !== undefined && /^\d+$/.test(afterRaw) ? Number(afterRaw) : 0;
@@ -227,17 +245,5 @@ export function createHttpRemote(options) {
                 throw new Error(`sync/push: ${r.status}`);
             return await readJson(r, "sync/push");
         },
-        async requestedAt() {
-            try {
-                const r = await request("/requested");
-                if (!r.ok)
-                    return null;
-                const body = await readJson(r, "sync/requested");
-                return typeof body.requestedAt === "number" ? body.requestedAt : null;
-            }
-            catch {
-                return null;
-            }
-        },
     };
 }

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

@@ -34,8 +34,16 @@ 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 { DEFAULT_LOOP, isUnreachable, 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, createSyncStatusReporter, type SyncStatus, 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, createCommandQueue, createCommandReceiver, createCommandRemote, startCommandWorker, type CommandQueue, type CommandRemote, type CommandRoutesOptions, type CommandStatus, type CommandWorkerDeps, type CommandWorkerHandle, type SyncCommand, } from "./commands";

package/dist/server/sync/index.js

@@ -35,7 +35,15 @@ export { createTokenStore } from "./tokens";
 export { createSyncApplier, pushToRemote, pullFromRemote, runSync, } from "./engine";
 export { capPageBytes, createHttpRemote, createSyncReceiver, } from "./http";
 export { DEFAULT_LOOP, isUnreachable, planNextSync, } from "./planner";
+export { SIGNAL_SSE_HEADERS, connectSyncSignal, createSyncSignalHub, encodeNewsFrame, parseNewsFrame, signalResponse, signalStream, } from "./signal";
 export { OFFLINE_STATUS, PEER_CONTACT_WRITE_MS, createSyncStatusReporter, } from "./status";
-export { REQUEST_POLL_MS, startSyncTimer } 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 } from "./timer";
 export { createSyncAlarm } from "./alarm";
 export { DEFAULT_HOLD_MS, createCommandQueue, createCommandReceiver, createCommandRemote, startCommandWorker, } from "./commands";

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

@@ -1,11 +1,30 @@
 /**
- * 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.
+ * The pure loop planner: back off after a failure, else honor a debounced dirty
+ * flag, else **do not wake at all**. Pure so the timer is a thin wrapper and this
+ * is fake-clock testable.
+ *
+ * ── 🔴 There is no steady interval, and that is the whole point ──────────────────
+ *
+ * This used to end with `else: the steady interval` — `intervalMs: 5 * 60_000`, a
+ * dial at a configured peer every five minutes whether or not either side had
+ * anything to say. The owner ruled that 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."* No such case was found, so the field is gone rather than defaulted to
+ * zero — a config key that reintroduces a poll is a config key somebody sets.
+ *
+ * What is left are the two wake-ups that have a REASON, and neither is a poll:
+ *
+ *   · **debounce** — there are local ops to push. The side that has news says so;
+ *     the wait only coalesces a burst.
+ *   · **backoff** — the last attempt failed. This runs *only while disconnected*,
+ *     never against a healthy peer, which is exactly the carve-out the ruling
+ *     names for a reconnect timer.
+ *
+ * A clean, healthy loop returns `waitMs: null` — "nothing to do, do not book a
+ * timer" — and the process goes quiet until something happens. News from the far
+ * side arrives over `./signal`, not by asking.
  */
 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. */
@@ -22,10 +41,21 @@ export interface SyncLoopState {
     /** When the oldest un-synced local write happened, or null if clean. */
     dirtySince: number | null;
 }
-export declare function planNextSync(state: SyncLoopState, now: number, cfg?: SyncLoopConfig): {
+/**
+ * What the loop should do next.
+ *
+ * 🔴 `waitMs: null` means **do not schedule anything** — not "wait zero" and not
+ * "wait forever". It is the idle state, and a caller that turns it into a number
+ * has put the poll back.
+ */
+export interface SyncPlan {
     runNow: boolean;
-    waitMs: number;
-};
+    /** Milliseconds until the next wake-up, or `null` when there is no reason to wake. */
+    waitMs: number | null;
+    /** Why the loop will wake — `null` alongside `waitMs: null`. */
+    reason: "retry" | "dirty" | null;
+}
+export declare function planNextSync(state: SyncLoopState, now: number, cfg?: SyncLoopConfig): SyncPlan;
 /** 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 declare function isUnreachable(err: unknown): boolean;

package/dist/server/sync/planner.js

@@ -1,10 +1,30 @@
 /**
- * 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.
+ * The pure loop planner: back off after a failure, else honor a debounced dirty
+ * flag, else **do not wake at all**. Pure so the timer is a thin wrapper and this
+ * is fake-clock testable.
+ *
+ * ── 🔴 There is no steady interval, and that is the whole point ──────────────────
+ *
+ * This used to end with `else: the steady interval` — `intervalMs: 5 * 60_000`, a
+ * dial at a configured peer every five minutes whether or not either side had
+ * anything to say. The owner ruled that 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."* No such case was found, so the field is gone rather than defaulted to
+ * zero — a config key that reintroduces a poll is a config key somebody sets.
+ *
+ * What is left are the two wake-ups that have a REASON, and neither is a poll:
+ *
+ *   · **debounce** — there are local ops to push. The side that has news says so;
+ *     the wait only coalesces a burst.
+ *   · **backoff** — the last attempt failed. This runs *only while disconnected*,
+ *     never against a healthy peer, which is exactly the carve-out the ruling
+ *     names for a reconnect timer.
+ *
+ * A clean, healthy loop returns `waitMs: null` — "nothing to do, do not book a
+ * timer" — and the process goes quiet until something happens. News from the far
+ * side arrives over `./signal`, not by asking.
  */
 export const DEFAULT_LOOP = {
-    intervalMs: 5 * 60_000,
     debounceMs: 3_000,
     backoffBaseMs: 30_000,
     backoffMaxMs: 30 * 60_000,
@@ -13,14 +33,18 @@ export function planNextSync(state, now, cfg = DEFAULT_LOOP) {
     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 };
+        return now >= due
+            ? { runNow: true, waitMs: 0, reason: "retry" }
+            : { runNow: false, waitMs: due - now, reason: "retry" };
     }
     if (state.dirtySince !== null) {
         const due = state.dirtySince + cfg.debounceMs;
-        return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+        return now >= due
+            ? { runNow: true, waitMs: 0, reason: "dirty" }
+            : { runNow: false, waitMs: due - now, reason: "dirty" };
     }
-    const due = state.lastAttempt + cfg.intervalMs;
-    return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+    // Clean and healthy: nothing to push, nothing to retry. Stay silent.
+    return { runNow: false, waitMs: null, reason: null };
 }
 /** A peer that is asleep (the nightly EC2 window) or an internet-less Mac is NORMAL,
  *  not an error. It still feeds the backoff. */

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

@@ -0,0 +1,161 @@
+/**
+ * **The peer says it has news. Nobody asks.**
+ *
+ * This is the half of the replication story that deleting the dialer (`./timer`,
+ * `./http`'s old `GET /requested`) would otherwise have left open, and it is the
+ * reason that deletion costs nothing.
+ *
+ * ## The three ways, and why this is the one
+ *
+ * Push-from-the-Mac answers Mac → peer completely: the side that has news calls
+ * `markDirty()` and pushes. It does not answer **peer → Mac**, and something must:
+ *
+ * | | |
+ * |---|---|
+ * | the Mac polls an outbox | ❌ polling. Ruled out 2026-09-15 |
+ * | the peer dials the Mac | ❌ needs the Mac reachable — a tunnel, an open port, a laptop that cannot sleep. That is the thing we are trying to delete |
+ * | 🟢 **the Mac holds a stream open and the peer pushes down it** | ✅ the Mac is still purely a client: it dials **out**, listens on nothing, and no timer fires |
+ *
+ * So: one long-lived outbound connection, opened by the dialing half, carrying a
+ * `news` frame whenever the receiver's op log grows. The Mac's reaction is
+ * `syncNow()` — the push it would have made anyway, at the moment there is a reason
+ * for it instead of 4,320 times a day on the chance.
+ *
+ * ## 🔴 Two honest caveats, neither of which is a poll
+ *
+ *   · **A sleeping Mac drops the connection.** On wake it reconnects and catches up
+ *     from `since` — the same catch-up a push model needs anyway, so it costs
+ *     nothing extra. `since` is the receiver's head as the client last saw it.
+ *   · **The reconnect backoff is a timer.** It runs *only while disconnected*, never
+ *     against a healthy peer, and it is written below as an `await sleep()` in a
+ *     loop rather than a `setTimeout` that calls `fetch` — the shape matters,
+ *     because the second one is indistinguishable from the poll this file exists to
+ *     replace. A connected client issues **exactly one** outbound request for as
+ *     long as it stays connected, and `signal.spec.ts` measures that over 24
+ *     simulated hours.
+ *
+ * ## Why this is not `cursedbelt-cc`'s `serverPush.ts`
+ *
+ * `libs/cursedbelt-cc/src/server/stream/serverPush.ts` is the real tenant-scoped
+ * push tier — heartbeats, backpressure, SSE — and on shape it is exactly this.
+ * It is not imported here for a reason that survives the preference:
+ * `cursedbelt-server/sync` is a **leaf** whose only runtime dependency is `hono`
+ * (see `./index.ts`), and `cursedbelt-cc` is a separate published package with zero
+ * consumers today, parked whole. Importing it would make every app that wants an
+ * op log install the cc platform to get one — the precise trade `./index.ts` was
+ * split to refuse, and the one `leafSubpathsImportNothing.spec.ts` now gates.
+ *
+ * The hub below is therefore the same model at a tenth the surface: this channel
+ * carries one frame kind, to one peer, with no tenant dimension. If `cursedbelt-cc`
+ * ever gains consumers and the two packages can depend on each other, {@link
+ * SyncSignalHub} is a strict subset of `ServerPushHub` and swaps in without
+ * touching a producer.
+ *
+ * ## The Workers path, named and not required yet
+ *
+ * On Cloudflare the durable form of "the Mac holds a connection all day" is a
+ * **Durable Object with WebSocket Hibernation**: the socket stays open while the
+ * object is evicted from memory, so an idle connection is not billed for duration.
+ * That is what keeps this free at rest, and it is the shape task `195` (the Mac is
+ * a client, never an origin) lands on. Nothing here needs it today — SSE over the
+ * existing receiver works on Bun and on Workers alike — but the frame format below
+ * is deliberately transport-free so the move is a transport swap, not a protocol
+ * change.
+ */
+/** SSE frame headers. `x-accel-buffering` keeps nginx from holding the stream in a
+ *  proxy buffer, which turns a live channel into a silent one — the same trap that
+ *  makes a cached `200` sit over a dead origin elsewhere in this fleet. */
+export declare const SIGNAL_SSE_HEADERS: Readonly<Record<string, string>>;
+/** What the receiver tells the dialing half. One kind, deliberately. */
+export interface SyncNews {
+    /** The receiver's op-log head at the moment it announced. The client's `since`. */
+    head: number;
+    /** The announcing instance, so a client linked to several can tell them apart. */
+    instanceId: string;
+}
+export interface SyncSignalHub {
+    /** Tell every listener the log grew. Never throws, never blocks on a socket. */
+    announce(news: SyncNews): void;
+    /** Attach a listener. The returned handle is safe to call more than once. */
+    subscribe(listener: (news: SyncNews) => void): () => void;
+    /** Live subscriber count — the reconnect tests assert against this. */
+    readonly subscriberCount: number;
+    /** Drop every subscriber (server shutdown). */
+    close(): void;
+}
+export declare function createSyncSignalHub(): SyncSignalHub;
+export interface SignalStreamOptions {
+    /** Overridden only in tests, so the heartbeat can be driven by hand. */
+    setIntervalFn?: (fn: () => void, ms: number) => unknown;
+    clearIntervalFn?: (handle: unknown) => void;
+    heartbeatMs?: number;
+    /** Cancels the stream (the request's abort signal). */
+    signal?: AbortSignal;
+    /**
+     * Sent as the first frame so a client that reconnects after a sleep learns the
+     * current head without a round trip. This is the `since` catch-up.
+     */
+    initial?: SyncNews;
+}
+/**
+ * Bridge a hub subscription onto a `ReadableStream` of SSE bytes.
+ *
+ * The stream ends when the client disconnects (`signal`) or the hub closes; both
+ * paths run the same teardown, so a dropped connection cannot leave a subscription
+ * — or an interval — behind.
+ */
+export declare function signalStream(hub: SyncSignalHub, options?: SignalStreamOptions): ReadableStream<Uint8Array>;
+/** Serialize one announcement as an SSE frame. */
+export declare const encodeNewsFrame: (news: SyncNews) => string;
+/** A ready-to-return SSE `Response` — what the receiver's `GET /signal` answers. */
+export declare const signalResponse: (hub: SyncSignalHub, options?: SignalStreamOptions) => Response;
+export interface SignalClientOptions {
+    /** Where the peer mounted its receiver, e.g. `https://peer.example/api/sync`. */
+    basePath: string;
+    /** The same bearer the rest of the sync surface uses. */
+    token: string;
+    /** This instance's id, echoed as `x-sync-peer` so the far side can label us. */
+    selfId: string;
+    /**
+     * The peer has news. Wire this to {@link import("./timer").SyncTimerHandle.syncNow}
+     * — the whole point is that a reconciliation now happens for a REASON.
+     */
+    onNews: (news: SyncNews) => void;
+    fetchImpl?: typeof fetch;
+    /** First reconnect step. Doubles to {@link backoffMaxMs}. Default 1s. */
+    backoffBaseMs?: number;
+    /** Reconnect ceiling — an offline laptop settles here. Default 5 min. */
+    backoffMaxMs?: number;
+    /** Swapped in tests. Resolves after `ms`; never issues a request. */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Jitter in [0,1). Real randomness by default — see the note on the stampede. */
+    jitterFn?: () => number;
+    log?: (msg: string) => void;
+}
+export interface SignalClient {
+    /** Close the stream and stop reconnecting. Idempotent. */
+    stop(): void;
+    /** Whether a stream is open right now — the tests assert against this. */
+    readonly connected: boolean;
+    /** Outbound requests issued since start. 🔴 The number the ruling is about. */
+    readonly requestCount: number;
+}
+/**
+ * Hold one stream open against the peer, calling {@link SignalClientOptions.onNews}
+ * on every `news` frame, and reconnect with jittered backoff **while disconnected**.
+ *
+ * 🔴 Read the loop shape as load-bearing. The reconnect is `await sleep(ms)` inside
+ * an async loop, NOT a `setTimeout` whose callback calls `fetch`. The second shape
+ * is byte-for-byte what a poll looks like, and a reviewer — or a checker — cannot
+ * tell the two apart once it is written that way. Here, a connected client is
+ * parked on `reader.read()` and issues nothing; `requestCount` stops moving the
+ * moment a connection succeeds, and that is what `signal.spec.ts` asserts over 24
+ * simulated hours.
+ *
+ * The jitter is not decoration either: a fixed backoff across N clients recovering
+ * from the same outage is a synchronized stampede at the instant the peer comes
+ * back up — the worst possible moment to send it a thundering herd.
+ */
+export declare function connectSyncSignal(options: SignalClientOptions): SignalClient;
+/** `event: news\ndata: {...}` → {@link SyncNews}, or null for a heartbeat/unknown. */
+export declare function parseNewsFrame(frame: string): SyncNews | null;