cursedbelt-server 1.1.0 → 2.1.0

package/dist/server/d1/scheduling.js

@@ -0,0 +1,164 @@
+/**
+ * `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.
+ */
+/** 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) {
+    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) {
+    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) {
+    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,
+            };
+    }
+}
+/**
+ * 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) {
+    const crons = [];
+    const queues = [];
+    const unportable = [];
+    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, firedCron) {
+    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/dist/server/d1/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 declare class D1BindError extends TypeError {
+    readonly index: number;
+    constructor(index: number, message: string);
+}
+/** Thrown for an operation D1 cannot perform, so the local driver refuses it too. */
+export declare class D1UnsupportedError extends Error {
+    constructor(what: string, instead: string);
+}
+/** Thrown when a statement would exceed one of D1's hard limits. See `./limits`. */
+export declare class D1LimitError extends RangeError {
+    readonly limit: string;
+    readonly actual: number;
+    readonly max: number;
+    constructor(limit: string, actual: number, max: number, remedy: string);
+}

package/dist/server/d1/types.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/** Thrown when a bound parameter is of a type D1 will not accept. */
+export class D1BindError extends TypeError {
+    index;
+    constructor(index, message) {
+        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, instead) {
+        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 {
+    limit;
+    actual;
+    max;
+    constructor(limit, actual, max, remedy) {
+        super(`D1 limit '${limit}' exceeded: ${actual} > ${max}. ${remedy}`);
+        this.name = 'D1LimitError';
+        this.limit = limit;
+        this.actual = actual;
+        this.max = max;
+    }
+}

package/dist/server/d1/values.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { type D1LikeBindable, type D1LikeMeta, type D1LikeValue } from './types';
+/**
+ * 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 declare function normalizeBind(value: unknown, index: number): D1LikeBindable;
+/** Normalize a whole parameter list, reporting the offending position on failure. */
+export declare const normalizeBinds: (values: readonly unknown[]) => D1LikeBindable[];
+/**
+ * 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 declare function normalizeValue(value: unknown): D1LikeValue;
+/** Normalize a row object, preserving column order. */
+export declare function normalizeRow<T>(row: Record<string, unknown>): T;
+/** Normalize a whole result set. */
+export declare const normalizeRows: <T>(rows: readonly Record<string, unknown>[]) => T[];
+/**
+ * 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 declare function makeMeta(partial: {
+    changes?: number;
+    last_row_id?: number | bigint | null;
+    duration: number;
+    rows_read?: number | null;
+    rows_written?: number | null;
+}): D1LikeMeta;

package/dist/server/d1/values.js

@@ -0,0 +1,124 @@
+/**
+ * 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 } 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, index) {
+    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) => 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) {
+    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);
+    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(row) {
+    const out = {};
+    for (const key of Object.keys(row))
+        out[key] = normalizeValue(row[key]);
+    return out;
+}
+/** Normalize a whole result set. */
+export const normalizeRows = (rows) => rows.map((r) => normalizeRow(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) {
+    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/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;
-            }
-        },
     };
 }