cursedbelt-server 1.1.0 → 2.1.0

package/src/server/d1/scheduling.ts

@@ -0,0 +1,210 @@
+/**
+ * `plainjob` → the Workers answer, and the choice is measured rather than guessed.
+ *
+ * ## What `plainjob` actually is, and why a Worker cannot have it
+ *
+ * An in-process SQLite job queue that POLLS a table on a timer. A Worker has no background
+ * loop: it exists for the duration of a request or a scheduled event and then stops. There
+ * is no timer to hang a poller off, so the mechanism does not port — it is replaced.
+ *
+ * ## 🔴 The measurement that makes this cheaper than the task file assumed
+ *
+ * Re-measured 2026-09-16 over `apps/` and `libs/`: all **12** `plainjob` files are in
+ * `libs/` (ten in `cursedbelt-server`, two in `cursedbelt-cc`), and **zero** are in
+ * `apps/`. No app declares a job through this engine yet. The original table read "12
+ * files using plainjob" as twelve call sites to port; they are one mechanism in one
+ * library, which is this seam. The port is a library change, not a fleet sweep.
+ *
+ * That also means the shape below is free to be the right one rather than the compatible
+ * one — there is no app-side caller to keep happy.
+ *
+ * ## The three primitives, and the rule for choosing
+ *
+ * | primitive | cost | when it is the answer |
+ * |---|---|---|
+ * | **Cron Triggers** | free | anything periodic at ≥ 1-minute cadence. Nightly backups and ingests — most of this fleet |
+ * | **Queues** | $0.40/M operations, 1M included | work fanned out FROM a request, where the response must not wait |
+ * | **Durable Object Alarms** | DO pricing | per-entity scheduling: one timer per row, set from the row's own lifecycle |
+ *
+ * 🔴 **The hard discriminator is cadence, and it is a real cliff.** Cloudflare Cron
+ * Triggers take a **5-field** expression with a **one-minute floor**. `JobDef.cron` accepts
+ * a 6-field expression with a leading seconds column, and this repo already contains three
+ * jobs declared `'* * * * * *'` — once per second. Those cannot become Cron Triggers at
+ * all, and {@link classifySchedule} says so by name instead of silently rounding them up to
+ * a minute, which would change behaviour in production and nowhere else.
+ */
+
+import type { D1LikeDatabase } from './types';
+
+/** The Workers primitive a piece of scheduled work maps onto. */
+export type WorkersPrimitive = 'cron-trigger' | 'queue' | 'durable-object-alarm' | 'unportable';
+
+/** How a job is triggered — the input to the choice, not the choice itself. */
+export type TriggerShape =
+	| { kind: 'periodic'; cron: string }
+	| { kind: 'fanned-out-from-request'; expectedPerDay?: number }
+	| { kind: 'per-entity' };
+
+export interface ScheduleVerdict {
+	primitive: WorkersPrimitive;
+	/** Why — quoted into the port task, so the next reader sees the reasoning not the answer. */
+	reason: string;
+	/** The 5-field expression to put in `wrangler.toml`, when there is one. */
+	cron: string | null;
+	/** Monthly cost at the stated volume, in US dollars. */
+	estimatedMonthlyUsd: number;
+}
+
+/** Cloudflare Queues: $0.40 per million operations, first million free each month. */
+const QUEUE_USD_PER_MILLION = 0.4;
+const QUEUE_FREE_OPERATIONS = 1_000_000;
+
+/**
+ * A cron expression with six fields carries a leading SECONDS column. Cloudflare has no
+ * such column and no cadence below one minute.
+ */
+export function cronFieldCount(cron: string): number {
+	return cron.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/**
+ * Drop the seconds column from a 6-field expression, reporting whether doing so changes
+ * when the job fires. `'0 3 * * * *'` is 3 a.m. daily either way; `'* * * * * *'` is not.
+ */
+export function toFiveField(cron: string): { cron: string; lossless: boolean } {
+	const parts = cron.trim().split(/\s+/).filter(Boolean);
+	if (parts.length <= 5) return { cron: parts.join(' '), lossless: true };
+	const [seconds, ...rest] = parts;
+	// Only a fixed single second (`0`, `30`, …) survives the drop: it means "once, at that
+	// second of the matching minute", which a minute-granularity trigger reproduces. A
+	// wildcard or a step means sub-minute cadence, which it cannot.
+	const lossless = /^\d+$/.test(seconds ?? '');
+	return { cron: rest.join(' '), lossless };
+}
+
+/**
+ * Choose the Workers primitive for a piece of scheduled work.
+ *
+ * Returns `'unportable'` rather than a best guess when the cadence is below Cloudflare's
+ * floor — a job that silently became 60× less frequent in production would be found by a
+ * user, not by a check.
+ */
+export function classifySchedule(shape: TriggerShape): ScheduleVerdict {
+	switch (shape.kind) {
+		case 'periodic': {
+			const fields = cronFieldCount(shape.cron);
+			const { cron, lossless } = toFiveField(shape.cron);
+			if (fields > 5 && !lossless) {
+				return {
+					primitive: 'unportable',
+					reason:
+						`'${shape.cron}' fires below Cloudflare's one-minute floor. A Cron Trigger cannot express it. ` +
+						'Either relax the cadence to ≥ 1 minute, or keep this job on a host with a real timer ' +
+						'(it is a poller, and a poller is usually a Queue consumer in disguise).',
+					cron: null,
+					estimatedMonthlyUsd: 0,
+				};
+			}
+			return {
+				primitive: 'cron-trigger',
+				reason:
+					'Periodic at ≥ 1-minute cadence — a Cron Trigger, which is free and needs no table, no poll ' +
+					'and no process. This is most of the fleet: nightly backups, ingests and metric flushes.',
+				cron,
+				estimatedMonthlyUsd: 0,
+			};
+		}
+
+		case 'fanned-out-from-request': {
+			const perMonth = (shape.expectedPerDay ?? 0) * 30;
+			// Each message is counted on write and on read, so a delivered message is two
+			// operations. Pricing it as one is the mistake that makes Queues look half price.
+			const operations = perMonth * 2;
+			const billable = Math.max(0, operations - QUEUE_FREE_OPERATIONS);
+			return {
+				primitive: 'queue',
+				reason:
+					'Work fanned out from a request, where the response must not wait for it. A Queue decouples the ' +
+					'two and retries on failure. 1M operations are included each month; a delivered message costs two ' +
+					'(one write, one read).',
+				cron: null,
+				estimatedMonthlyUsd: Number(((billable / 1_000_000) * QUEUE_USD_PER_MILLION).toFixed(4)),
+			};
+		}
+
+		case 'per-entity':
+			return {
+				primitive: 'durable-object-alarm',
+				reason:
+					'One timer per entity, set from that entity’s own lifecycle — a reminder on a row, a lease that ' +
+					'expires. A Cron Trigger would have to scan every row every minute to find the few that are due; ' +
+					'an alarm is woken only for the one that is.',
+				cron: null,
+				// A DO is only billed for the requests and duration it actually uses; an idle
+				// alarm costs nothing until it fires. The real number depends on entity count,
+				// so a fabricated figure here would be worse than none.
+				estimatedMonthlyUsd: 0,
+			};
+	}
+}
+
+/** A scheduled job, declared once and readable by both the local runner and `wrangler`. */
+export interface PortableJob {
+	name: string;
+	shape: TriggerShape;
+	/** The work. Takes the async seam, so the same handler runs on either side. */
+	run(ctx: PortableJobContext): Promise<void>;
+}
+
+export interface PortableJobContext {
+	db: D1LikeDatabase;
+	signal: AbortSignal;
+	log: { info(m: string): void; warn(m: string): void; error(m: string): void };
+}
+
+/**
+ * Render the `[triggers]` block of a `wrangler.toml` from a job list — and refuse to render
+ * one that silently drops a job.
+ *
+ * 🔴 It throws on an unportable job rather than skipping it. A generated config that
+ * quietly omits a job is a job that stops running in production while every local test
+ * still passes, which is the failure mode this whole seam exists to prevent.
+ */
+export function toCronTriggers(jobs: readonly PortableJob[]): { crons: string[]; queues: string[] } {
+	const crons: string[] = [];
+	const queues: string[] = [];
+	const unportable: string[] = [];
+
+	for (const job of jobs) {
+		const verdict = classifySchedule(job.shape);
+		if (verdict.primitive === 'unportable') {
+			unportable.push(`  ${job.name}: ${verdict.reason}`);
+		} else if (verdict.primitive === 'cron-trigger' && verdict.cron) {
+			if (!crons.includes(verdict.cron)) crons.push(verdict.cron);
+		} else if (verdict.primitive === 'queue') {
+			queues.push(job.name);
+		}
+	}
+
+	if (unportable.length > 0) {
+		throw new Error(
+			`${unportable.length} job(s) cannot be expressed as a Cloudflare trigger:\n${unportable.join('\n')}\n` +
+				'Fix the cadence or keep the job on a host — do not ship a config that omits it.',
+		);
+	}
+	return { crons, queues };
+}
+
+/**
+ * 🔴 Cloudflare dispatches a Cron Trigger by EXPRESSION, not by job name — the
+ * `scheduled` handler is told which cron fired and nothing else. Two jobs sharing
+ * `0 3 * * *` arrive as one event, so the Worker has to fan back out to every job matching
+ * that expression. Forgetting this runs the first job and silently never runs the second.
+ */
+export function jobsForCron(jobs: readonly PortableJob[], firedCron: string): PortableJob[] {
+	return jobs.filter((job) => {
+		if (job.shape.kind !== 'periodic') return false;
+		const verdict = classifySchedule(job.shape);
+		return verdict.primitive === 'cron-trigger' && verdict.cron === firedCron.trim();
+	});
+}

package/src/server/d1/types.ts

@@ -0,0 +1,163 @@
+/**
+ * The async database seam every app crosses to reach SQLite — locally on `bun:sqlite`,
+ * remotely on Cloudflare D1.
+ *
+ * ## 🔴 It is async on BOTH sides, and that is the entire point
+ *
+ * `bun:sqlite` is synchronous: `db.query(sql).all()` returns rows. D1 is
+ * `await db.prepare(sql).all()`. No adapter, no proxy and no `Proxy` trap makes a
+ * synchronous call site await — so the port is a real edit at every call site, and the
+ * only question this seam answers is whether that edit has to happen TWICE.
+ *
+ * A seam that is sync locally and async remotely passes every test on this machine and
+ * fails in production. So {@link D1LikeDatabase} is the same async shape on both sides,
+ * the local driver is the one that changes, and a ported call site runs unmodified
+ * against either.
+ *
+ * ## 🔴 The local driver is as STRICT as the remote one, never as lenient as Bun
+ *
+ * The same argument applies one level down, and it is where the real bugs live. Measured
+ * against `bun:sqlite` on 2026-09-16, four things differ between the two drivers, and two
+ * of them are silent-here / throw-there:
+ *
+ *   | value                | `bun:sqlite`                  | D1 (`workerd`)          |
+ *   |----------------------|-------------------------------|-------------------------|
+ *   | `undefined` bind     | 🔴 silently binds NULL        | throws                  |
+ *   | `boolean` bind       | 🔴 silently coerces to 0/1    | throws                  |
+ *   | BLOB column read     | `Uint8Array`                  | `number[]`              |
+ *   | `.run()` result      | `{changes, lastInsertRowid}`  | `{success, meta, …}`    |
+ *
+ * Lenient-locally is the same defect as sync-locally wearing a different costume: it is
+ * green on this Mac and red in the Worker. `normalizeBind` in `./values` therefore makes
+ * the LOCAL driver refuse what D1 refuses, and normalizes what both accept to one shape.
+ * The one deliberate exception is `boolean`, which is coerced to 0/1 on both sides rather
+ * than refused on both: SQLite has no boolean type, so 0/1 is not a guess about intent,
+ * and refusing it would break every natural `where('disabled', '=', false)` in the fleet.
+ * `undefined` is refused, because "missing argument" and "intentional NULL" are genuinely
+ * different and only the caller knows which was meant.
+ *
+ * ## Transactions are refused on both sides, and `batch()` is the answer
+ *
+ * D1 has no interactive transaction — there is no `BEGIN`/`COMMIT` over HTTP, only
+ * {@link D1LikeDatabase.batch}, which is atomic and runs as one round trip. A local
+ * driver that happily honoured `BEGIN` would be the sync-vs-async trap a third time, so
+ * {@link D1UnsupportedError} is thrown by both. Wrap the statements in `batch()` instead;
+ * it is atomic on D1 and wrapped in a real `bun:sqlite` transaction locally, so the
+ * guarantee is the same.
+ *
+ * The shape below deliberately mirrors Cloudflare's own `D1Database` rather than
+ * inventing a vocabulary: the remote driver is then close to a pass-through, and the
+ * thing an app author reads in Cloudflare's docs is the thing they have.
+ */
+
+/** A row as it comes back from either driver — column name to normalized value. */
+export type D1LikeRow = Record<string, D1LikeValue>;
+
+/**
+ * Every value either driver can RETURN, after normalization. Note there is no `boolean`
+ * and no `bigint`: SQLite stores neither, and a driver that invented one on read would
+ * disagree with the other driver on the way back in.
+ */
+export type D1LikeValue = string | number | null | Uint8Array;
+
+/**
+ * Every value either driver accepts as a BOUND parameter. `boolean` is accepted and
+ * coerced to 0/1; `bigint` is accepted within the safe-integer range and refused outside
+ * it (where it could not survive the round trip anyway). `undefined` is absent on
+ * purpose — see the header.
+ */
+export type D1LikeBindable = string | number | boolean | bigint | null | Uint8Array | ArrayBuffer;
+
+/**
+ * What a statement reports about its own execution. Mirrors D1's `meta`, with the fields
+ * the local driver can honestly fill. A field the local driver cannot know is `null`
+ * rather than a plausible-looking zero — a fabricated `rows_read` of 0 would read as a
+ * measurement in `192`'s CPU accounting rather than as an absence.
+ */
+export interface D1LikeMeta {
+	/** Rows changed by the statement. `0` for a read. */
+	changes: number;
+	/** Rowid of the last insert, or `null` when the statement inserted nothing. */
+	last_row_id: number | null;
+	/** Wall-clock milliseconds the driver spent on the statement. */
+	duration: number;
+	/** D1 only — rows the query engine read. `null` locally, where nothing counts them. */
+	rows_read: number | null;
+	/** D1 only — rows the query engine wrote. `null` locally. */
+	rows_written: number | null;
+}
+
+/** The result of `.all()` / `.run()` on either driver. */
+export interface D1LikeResult<T = D1LikeRow> {
+	results: T[];
+	success: true;
+	meta: D1LikeMeta;
+}
+
+/**
+ * A prepared statement. `bind()` returns a NEW statement rather than mutating this one,
+ * which is D1's own contract and what makes a statement safe to keep and re-bind.
+ */
+export interface D1LikeStatement {
+	bind(...values: D1LikeBindable[]): D1LikeStatement;
+	/** The first row, or `null` when the query matched nothing. */
+	first<T = D1LikeRow>(): Promise<T | null>;
+	/** One column of the first row, or `null` when the query matched nothing. */
+	first<V = D1LikeValue>(column: string): Promise<V | null>;
+	all<T = D1LikeRow>(): Promise<D1LikeResult<T>>;
+	run(): Promise<D1LikeResult<never>>;
+	/** Rows as positional arrays rather than objects — the cheap shape for bulk reads. */
+	raw<V = D1LikeValue>(): Promise<V[][]>;
+}
+
+/**
+ * The database handle an app holds. One of these is constructed per request on a Worker
+ * and once per process locally; nothing below this line knows which it got.
+ */
+export interface D1LikeDatabase {
+	prepare(sql: string): D1LikeStatement;
+	/**
+	 * Run several statements atomically as ONE round trip. This is the transaction
+	 * primitive — see the header for why there is no `begin()`.
+	 */
+	batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]>;
+	/**
+	 * Run one or more statements for their side effects, with no bound parameters —
+	 * schema migrations, `PRAGMA`s, DDL. Not for anything carrying user input.
+	 */
+	exec(sql: string): Promise<{ count: number; duration: number }>;
+	/** Which side of the seam this handle is. Lets a caller branch where it genuinely must. */
+	readonly flavor: 'local' | 'd1';
+}
+
+/** Thrown when a bound parameter is of a type D1 will not accept. */
+export class D1BindError extends TypeError {
+	readonly index: number;
+	constructor(index: number, message: string) {
+		super(`parameter ${index + 1}: ${message}`);
+		this.name = 'D1BindError';
+		this.index = index;
+	}
+}
+
+/** Thrown for an operation D1 cannot perform, so the local driver refuses it too. */
+export class D1UnsupportedError extends Error {
+	constructor(what: string, instead: string) {
+		super(`${what} is not supported on D1 — ${instead}`);
+		this.name = 'D1UnsupportedError';
+	}
+}
+
+/** Thrown when a statement would exceed one of D1's hard limits. See `./limits`. */
+export class D1LimitError extends RangeError {
+	readonly limit: string;
+	readonly actual: number;
+	readonly max: number;
+	constructor(limit: string, actual: number, max: number, remedy: string) {
+		super(`D1 limit '${limit}' exceeded: ${actual} > ${max}. ${remedy}`);
+		this.name = 'D1LimitError';
+		this.limit = limit;
+		this.actual = actual;
+		this.max = max;
+	}
+}

package/src/server/d1/values.ts

@@ -0,0 +1,138 @@
+/**
+ * The one place that decides what a bound parameter and a returned column MEAN, shared by
+ * both drivers.
+ *
+ * 🔴 **Both drivers call these, and that is why the identical-shapes test can pass.** If
+ * the local driver normalized its own way and the remote driver normalized its own way,
+ * the test in `sameShape.spec.ts` would be asserting that two independent implementations
+ * happen to agree today — which is a coincidence with a maintenance schedule. Here there
+ * is one implementation of the meaning and two implementations of the transport.
+ *
+ * Every rule below was measured against `bun:sqlite` on 2026-09-16 (`Bun 1.3`), not
+ * recalled: the probe wrote each type into a `CREATE TABLE t (v)` column and read it back.
+ */
+
+import { D1BindError, type D1LikeBindable, type D1LikeMeta, type D1LikeValue } from './types';
+
+/**
+ * The largest integer a JS number holds exactly. A `bigint` beyond this cannot survive the
+ * round trip through either driver — measured, `bun:sqlite` returns `9007199254740992` for
+ * a stored `9007199254740993` — so it is refused rather than silently rounded.
+ */
+const SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Normalize one bound parameter to something BOTH drivers accept, or throw.
+ *
+ * The local driver is deliberately made as strict as D1 here. `bun:sqlite` accepts
+ * `undefined` (binding NULL) and `boolean` (coercing to 0/1) where D1 throws; a local
+ * driver that inherited that leniency would go green on this Mac and red in the Worker,
+ * which is the same defect as a sync seam.
+ */
+export function normalizeBind(value: unknown, index: number): D1LikeBindable {
+	if (value === null) return null;
+
+	switch (typeof value) {
+		case 'string':
+		case 'number':
+			// 🔴 NaN and ±Infinity have no SQLite representation. `bun:sqlite` stores NaN as
+			// NULL; D1 rejects it. Refusing both is the only answer that reads the same.
+			if (typeof value === 'number' && !Number.isFinite(value)) {
+				throw new D1BindError(index, `${value} has no SQLite representation — store null, or a string`);
+			}
+			return value;
+
+		// SQLite has no boolean type: 0/1 is the storage, not a guess about intent. Coerced
+		// on BOTH sides so the two agree, rather than refused on both, which would break
+		// every natural `where('disabled', '=', false)` in the fleet.
+		case 'boolean':
+			return value ? 1 : 0;
+
+		case 'bigint':
+			if (value > SAFE || value < -SAFE) {
+				throw new D1BindError(
+					index,
+					`bigint ${value} is outside the safe-integer range and cannot round-trip — store it as TEXT`,
+				);
+			}
+			return Number(value);
+
+		case 'undefined':
+			// 🔴 The measured trap. `bun:sqlite` binds NULL and says nothing; D1 throws.
+			// "Missing argument" and "intentional NULL" are different, and only the caller
+			// knows which was meant — so the caller says so.
+			throw new D1BindError(index, 'undefined — pass null explicitly if you mean SQL NULL');
+
+		case 'object':
+			if (value instanceof Uint8Array) return value;
+			if (value instanceof ArrayBuffer) return new Uint8Array(value);
+			if (value instanceof Date) {
+				// Common enough to deserve its own sentence rather than "not supported".
+				throw new D1BindError(index, 'Date — store an ISO string (`d.toISOString()`) or an epoch number');
+			}
+			throw new D1BindError(index, `${value.constructor?.name ?? 'object'} — bind a string, number, null or Uint8Array`);
+
+		default:
+			throw new D1BindError(index, `${typeof value} is not bindable`);
+	}
+}
+
+/** Normalize a whole parameter list, reporting the offending position on failure. */
+export const normalizeBinds = (values: readonly unknown[]): D1LikeBindable[] =>
+	values.map((v, i) => normalizeBind(v, i));
+
+/**
+ * Normalize one column value coming BACK from a driver.
+ *
+ * The measured disagreement is BLOBs: `bun:sqlite` returns a `Uint8Array`, D1 returns a
+ * plain `number[]` (it crosses the wire as JSON). `Uint8Array` wins on both — it is the
+ * type every consumer of a blob actually wants, and `Array.isArray` is a reliable way to
+ * spot D1's shape because no other column type returns an array.
+ */
+export function normalizeValue(value: unknown): D1LikeValue {
+	if (value === null || value === undefined) return null;
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	if (Array.isArray(value)) return Uint8Array.from(value as number[]);
+	if (typeof value === 'bigint') return Number(value);
+	if (typeof value === 'boolean') return value ? 1 : 0;
+	if (typeof value === 'string' || typeof value === 'number') return value;
+	// Nothing else can come out of either driver; if it does, that is a driver change we
+	// want to hear about loudly rather than pass through as an opaque object.
+	throw new TypeError(`unexpected column value of type ${typeof value} from the database driver`);
+}
+
+/** Normalize a row object, preserving column order. */
+export function normalizeRow<T>(row: Record<string, unknown>): T {
+	const out: Record<string, D1LikeValue> = {};
+	for (const key of Object.keys(row)) out[key] = normalizeValue(row[key]);
+	return out as T;
+}
+
+/** Normalize a whole result set. */
+export const normalizeRows = <T>(rows: readonly Record<string, unknown>[]): T[] =>
+	rows.map((r) => normalizeRow<T>(r));
+
+/**
+ * Build a {@link D1LikeMeta}. `rows_read`/`rows_written` default to `null` — the local
+ * driver genuinely cannot count them, and a plausible-looking `0` would be read as a
+ * measurement by `192`'s CPU accounting rather than as an absence.
+ */
+export function makeMeta(partial: {
+	changes?: number;
+	last_row_id?: number | bigint | null;
+	duration: number;
+	rows_read?: number | null;
+	rows_written?: number | null;
+}): D1LikeMeta {
+	const raw = partial.last_row_id ?? null;
+	return {
+		changes: partial.changes ?? 0,
+		// A rowid of 0 means "nothing was inserted" in both drivers; report it as absent
+		// so a caller can `?? ` it rather than having to know that 0 is a sentinel.
+		last_row_id: raw === null || Number(raw) === 0 ? null : Number(raw),
+		duration: partial.duration,
+		rows_read: partial.rows_read ?? null,
+		rows_written: partial.rows_written ?? null,
+	};
+}

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,