cursedbelt-server 1.0.2 → 2.0.0

package/dist/server/index.d.ts

@@ -10,6 +10,7 @@ export { type CreateJobRunnerOptions, createFireQueue, createJobRunner, createPo
 export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ffmpegTimeToSeconds, isFfmpegAvailable, isFfprobeAvailable, type ProbeResult, parseFfmpegProgress, parseFfprobe, probeMedia, renderImage, trimVideo, type VideoCodecPlan, videoCodecPlan, } from './media-bun';
 export { createMetricsBuffer, type MetricRow, type MetricsBuffer, type MetricsBufferOptions, } from './metrics/metricsBuffer';
 export { normalizeRoute } from './metrics/normalizeRoute';
+export { type AnalyticsEngineDataset, createTelemetrySink, TELEMETRY_POINT_VERSION, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, toDataPoint, } from './metrics/telemetrySink';
 export { correlationId } from './middleware/correlationId';
 export { type CorsOpts, corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';
 export { errorEnvelope } from './middleware/errorEnvelope';

package/dist/server/index.js

@@ -27,6 +27,7 @@ export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ff
 // ── Metrics ───────────────────────────────────────────────────────────────────
 export { createMetricsBuffer, } from './metrics/metricsBuffer';
 export { normalizeRoute } from './metrics/normalizeRoute';
+export { createTelemetrySink, TELEMETRY_POINT_VERSION, toDataPoint, } from './metrics/telemetrySink';
 // ── Middleware ────────────────────────────────────────────────────────────────
 export { correlationId } from './middleware/correlationId';
 export { corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';

package/dist/server/metrics/telemetrySink.d.ts

@@ -0,0 +1,119 @@
+import type { Database } from 'bun:sqlite';
+import { type MetricRow } from './metricsBuffer';
+/**
+ * ONE seam for "this app served a request", with two backends and no third.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `request_metrics` is a row per request. On D1 that is the one line in
+ * Cloudflare's pricing with a dollar-scale overage — **$1.00 per million rows
+ * written** — and a row per request is precisely the shape that buys it. Workers
+ * Analytics Engine is purpose-built for the same job: `writeDataPoint()` per
+ * event, SQL to query, unlimited cardinality, **10M data points and 1M read
+ * queries included per month**, and **zero** database writes.
+ *
+ * 🔴 **Adopt it for the ALLOWANCE, not because it is unbilled today.**
+ * Cloudflare's own wording is that you "will not be billed for your use of
+ * Workers Analytics Engine" today and that the published prices are "shared in
+ * advance… once Cloudflare starts billing for usage in the coming months". The
+ * free-today part is temporary; the allowance is not. At this fleet's measured
+ * ~1M requests/month the bill is $0 either way, so building against the
+ * allowance makes the billing switch a non-event.
+ *
+ * ── Why not `prom-client` / a `/metrics` scrape ──────────────────────────────
+ * A scrape genuinely does turn many writes into one, and on a long-lived Bun
+ * process it would work. A Worker is **a stateless V8 isolate with no
+ * long-lived process**: isolates are created and destroyed between requests and
+ * run concurrently in many datacentres, so a `/metrics` scrape reaches ONE
+ * arbitrary isolate holding a random fraction of the counters. The in-process
+ * registry has nowhere to live. (A Durable Object does have a durable identity
+ * *and* memory, and is the real `prom-client` analogue — but it is a whole
+ * stateful object to operate for counters Analytics Engine already aggregates.
+ * Prometheus itself also needs an always-on host to scrape FROM, and that host
+ * is the Mac this fleet is trying to switch off.)
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * · `analytics` bound  → one `writeDataPoint` per event, **zero** SQLite/D1 rows.
+ * · no `analytics`     → the existing {@link MetricsBuffer}, byte-for-byte
+ *                        unchanged, so the gate and a Mac-hosted app keep working.
+ * Both are proven by `telemetrySink.spec.ts`, which is the point of the seam:
+ * the choice is made ONCE here rather than per app.
+ */
+/**
+ * The Workers Analytics Engine binding, typed locally so this package needs no
+ * dependency on `@cloudflare/workers-types` (it is a Bun/Hono package, and a
+ * Worker supplies the real binding at runtime).
+ *
+ * Platform limits, which {@link toDataPoint} respects:
+ * **1** index of ≤96 bytes, ≤**20** blobs totalling ≤5120 bytes, ≤**20** doubles.
+ */
+export interface AnalyticsEngineDataset {
+    writeDataPoint(point: {
+        indexes?: (ArrayBuffer | string | null)[];
+        blobs?: (ArrayBuffer | string | null)[];
+        doubles?: number[];
+    }): void;
+}
+/** One request's telemetry. Identical to {@link MetricRow} — the seam does not re-shape it. */
+export type TelemetryEvent = MetricRow;
+/**
+ * A superset-compatible shape: a {@link MetricsBuffer} IS a `TelemetrySink`, so
+ * an app that already owns a buffer can keep passing it.
+ */
+export interface TelemetrySink {
+    /** Enqueue one request's telemetry. Never blocks the response. */
+    record(event: TelemetryEvent): void;
+    /** Force whatever is pending out now (shutdown + tests). No-op on Analytics Engine. */
+    flush(): void;
+    /** Stop any timer and drain. No-op on Analytics Engine. */
+    stop(): void;
+    /** Events pending locally. Always 0 on Analytics Engine — it has no buffer to hold. */
+    readonly size: number;
+}
+export interface TelemetrySinkOptions {
+    /**
+     * The Analytics Engine binding, when the platform supplies one. Present ⇒ it
+     * WINS, and `db` is never written. `null`/`undefined` ⇒ the SQLite path.
+     */
+    analytics?: AnalyticsEngineDataset | null;
+    /** The `request_metrics` database. Required unless `analytics` is bound. */
+    db?: Database | null;
+    /** Flush cadence for the SQLite path, in ms. Default: 1500. Ignored by Analytics Engine. */
+    flushIntervalMs?: number;
+    /** Eager-flush threshold for the SQLite path. Default: 5000. Ignored by Analytics Engine. */
+    maxSize?: number;
+}
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export declare const TELEMETRY_POINT_VERSION = 1;
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export declare function toDataPoint(event: TelemetryEvent): {
+    indexes: string[];
+    blobs: string[];
+    doubles: number[];
+};
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export declare function createTelemetrySink(opts: TelemetrySinkOptions): TelemetrySink;

package/dist/server/metrics/telemetrySink.js

@@ -0,0 +1,76 @@
+import { createMetricsBuffer } from './metricsBuffer';
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export const TELEMETRY_POINT_VERSION = 1;
+const INDEX_MAX_BYTES = 96;
+/**
+ * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point —
+ * `String.slice` counts UTF-16 units, so a route with one multi-byte character
+ * can be ≤96 chars and still exceed the 96-BYTE index limit.
+ */
+function truncateUtf8(value, maxBytes) {
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.length <= maxBytes)
+        return value;
+    return new TextDecoder('utf-8', { fatal: false }).decode(encoded.subarray(0, maxBytes)).replace(
+    // A cut through a multi-byte sequence decodes to U+FFFD; drop that trailing artefact.
+    /�+$/, '');
+}
+const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : -1;
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export function toDataPoint(event) {
+    const route = event.route ?? '';
+    return {
+        indexes: [truncateUtf8(route, INDEX_MAX_BYTES)],
+        blobs: [event.method ?? '', route, event.userId ?? ''],
+        doubles: [num(event.status), num(event.durationMs), num(event.bytesOut)],
+    };
+}
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export function createTelemetrySink(opts) {
+    const { analytics, db, flushIntervalMs, maxSize } = opts;
+    if (analytics) {
+        // Analytics Engine writes are fire-and-forget and already off the response
+        // path — there is nothing to buffer, so flush/stop are honestly no-ops.
+        return {
+            record(event) {
+                analytics.writeDataPoint(toDataPoint(event));
+            },
+            flush() { },
+            stop() { },
+            get size() {
+                return 0;
+            },
+        };
+    }
+    if (!db) {
+        throw new Error('createTelemetrySink: neither an Analytics Engine binding (`analytics`) nor a `db` was ' +
+            'provided. Telemetry would be silently dropped; bind one of the two.');
+    }
+    // The unchanged SQLite path — same module, same batching, same rows.
+    return createMetricsBuffer({ db, flushIntervalMs, maxSize });
+}

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

@@ -4,6 +4,7 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter, type RateLimitOpts } from './rateLimit';
 export { type RequestLoggerOpts, requestLogger } from './requestLogger';
+export { type AnalyticsEngineDataset, createTelemetrySink, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, } from '../metrics/telemetrySink';
 export { type CspDirectives, type SecurityHeadersOpts, securityHeaders, } from './securityHeaders';
 export { toValidationIssues, VALIDATION_ERROR_CODE, type ValidationIssue, validationEnvelope, } from '../errors';
 export { type ZValidatorTarget, zValidator } from './zValidator';

package/dist/server/middleware/index.js

@@ -5,6 +5,9 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter } from './rateLimit';
 export { requestLogger } from './requestLogger';
+// The telemetry seam `requestLogger` writes through — re-exported here so a caller
+// that reaches `./middleware` for the logger can bind Analytics Engine in the same import.
+export { createTelemetrySink, } from '../metrics/telemetrySink';
 export { securityHeaders, } from './securityHeaders';
 export { toValidationIssues, VALIDATION_ERROR_CODE, validationEnvelope, } from '../errors';
 export { zValidator } from './zValidator';

package/dist/server/middleware/requestLogger.d.ts

@@ -1,29 +1,48 @@
 import type { Database } from 'bun:sqlite';
 import type { MiddlewareHandler } from 'hono';
 import type { CursedbeltEnv } from '../context';
-import { type MetricsBuffer } from '../metrics/metricsBuffer';
+import type { MetricsBuffer } from '../metrics/metricsBuffer';
+import { type AnalyticsEngineDataset, type TelemetrySink } from '../metrics/telemetrySink';
 /**
- * Structured request/response logging. After each request it records one slim
- * `request_metrics` row (via the batched {@link MetricsBuffer}, off the hot path)
- * and, for errors (status ≥ 400) or slow requests, one `event_logs` row tagged with
- * the correlation id. Attributes rows to `c.get('userId')` when the app's auth
+ * Structured request/response logging. After each request it records one
+ * telemetry event through the {@link TelemetrySink} (off the hot path) and, for
+ * errors (status ≥ 400) or slow requests, one `event_logs` row tagged with the
+ * correlation id. Attributes rows to `c.get('userId')` when the app's auth
  * middleware has set it.
  *
+ * 🔴 **Where the telemetry LANDS is the sink's decision, not this file's.** With
+ * an Analytics Engine binding it is one `writeDataPoint` and **zero** database
+ * rows; without one it is the same batched `request_metrics` insert it has always
+ * been. See `../metrics/telemetrySink.ts` for why that is the only choice offered.
+ *
  * It records metrics even when a downstream handler THROWS: the error is caught,
- * the would-be status derived, the row written, then the error re-thrown so the
+ * the would-be status derived, the event recorded, then the error re-thrown so the
  * error-envelope `onError` still produces the response.
  */
 export interface RequestLoggerOpts {
     /**
-     * The metrics buffer to write through. Provide one (and own its lifecycle via
-     * `buffer.stop()`) to share it / flush deterministically; omit to create one from
-     * `db`. Its flush timer is `unref()`'d, so an internally-created buffer is fine for
-     * long-running servers.
+     * The Analytics Engine binding, when the platform supplies one. Present ⇒ the
+     * telemetry goes there and NOTHING is written to `request_metrics`.
+     */
+    analytics?: AnalyticsEngineDataset | null;
+    /**
+     * The sink to write through. Provide one (and own its lifecycle via
+     * `sink.stop()`) to share it / flush deterministically; omit to build one from
+     * `db` + `analytics`. A {@link MetricsBuffer} is a valid sink.
      */
+    sink?: TelemetrySink;
+    /** @deprecated Use {@link RequestLoggerOpts.sink} — a `MetricsBuffer` is one. Kept for callers that predate the sink. */
     buffer?: MetricsBuffer;
     /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
     slowMs?: number;
     /** Also write `event_logs` rows for status ≥ 400. Default: true. */
     logErrors?: boolean;
 }
-export declare function requestLogger(db: Database, opts?: RequestLoggerOpts): MiddlewareHandler<CursedbeltEnv>;
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
+export declare function requestLogger(db: Database | null, opts?: RequestLoggerOpts): MiddlewareHandler<CursedbeltEnv>;

package/dist/server/middleware/requestLogger.js

@@ -1,7 +1,7 @@
 import { HTTPException } from 'hono/http-exception';
 import { isApiError } from '../errors';
-import { createMetricsBuffer } from '../metrics/metricsBuffer';
 import { normalizeRoute } from '../metrics/normalizeRoute';
+import { createTelemetrySink, } from '../metrics/telemetrySink';
 function statusOfThrown(err) {
     if (isApiError(err))
         return err.status;
@@ -9,13 +9,22 @@ function statusOfThrown(err) {
         return err.status;
     return 500;
 }
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
 export function requestLogger(db, opts = {}) {
-    const buffer = opts.buffer ?? createMetricsBuffer({ db });
+    const sink = opts.sink ?? opts.buffer ?? createTelemetrySink({ db, analytics: opts.analytics ?? null });
     const slowMs = opts.slowMs ?? 2000;
     const logErrors = opts.logErrors ?? true;
-    const insertEvent = db.prepare(`INSERT INTO event_logs
+    const insertEvent = db
+        ? db.prepare(`INSERT INTO event_logs
        (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        : null;
     return async (c, next) => {
         const start = performance.now();
         let thrown;
@@ -33,10 +42,10 @@ export function requestLogger(db, opts = {}) {
         const lenHeader = didThrow ? null : c.res.headers.get('content-length');
         const bytesOut = lenHeader ? Number(lenHeader) : null;
         const userId = c.get('userId') ?? null;
-        buffer.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+        sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
         const isError = status >= 400;
         const isSlow = durationMs >= slowMs;
-        if ((logErrors && isError) || isSlow) {
+        if (insertEvent && ((logErrors && isError) || isSlow)) {
             const type = status >= 500 ? 'error' : isError ? 'warn' : 'info';
             insertEvent.run(crypto.randomUUID(), c.get('correlationId') ?? null, isError ? 'http_error' : 'http_slow', type, `${method} ${route} → ${status}`, JSON.stringify({ method, route, status, durationMs: Math.round(durationMs), bytesOut }), Math.round(durationMs), userId, new Date().toISOString());
         }

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. */