cursedbelt-server 4.14.0 → 4.16.0

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

@@ -0,0 +1,66 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+import { type D1BindingLike } from './remote.js';
+import { type D1LikeDatabase } from './types.js';
+export interface HttpD1Options {
+    accountId: string;
+    databaseId: string;
+    /** An API token with D1 Edit on the account. */
+    apiToken: string;
+    /** Each request's ceiling, in ms. Default 30 s — a hung socket must not hang a job. */
+    timeoutMs?: number;
+    /** Injected for tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Defaults to `https://api.cloudflare.com/client/v4`. */
+    apiBase?: string;
+}
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export declare class D1HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export declare function httpD1Binding(options: HttpD1Options): D1BindingLike;
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export declare function createHttpD1(options: HttpD1Options): D1LikeDatabase;

package/dist/server/d1/http.js

@@ -0,0 +1,143 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+import { createRemoteD1 } from './remote.js';
+import { D1UnsupportedError } from './types.js';
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export class D1HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(`D1 over HTTP refused the request (${status}): ${message}`);
+        this.name = 'D1HttpError';
+        this.status = status;
+    }
+}
+function toWire(values) {
+    return values.map((value, index) => {
+        if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+            throw new D1UnsupportedError(`a BLOB parameter (parameter ${index + 1}) over the D1 REST API`, 'encode the bytes as text (hex or base64) — the REST API has no documented lossless BLOB spelling');
+        }
+        return value;
+    });
+}
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export function httpD1Binding(options) {
+    const doFetch = options.fetch ?? fetch;
+    const base = `${options.apiBase ?? 'https://api.cloudflare.com/client/v4'}/accounts/${options.accountId}/d1/database/${options.databaseId}`;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const post = async (path, body) => {
+        const response = await doFetch(`${base}${path}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const envelope = (await response.json().catch(() => null));
+        if (!response.ok || !envelope || envelope.success === false) {
+            const message = envelope?.errors
+                ?.map((e) => e.message)
+                .filter(Boolean)
+                .join('; ') || response.statusText || 'no body';
+            throw new D1HttpError(response.status, message);
+        }
+        return envelope.result ?? [];
+    };
+    const asResult = (wire) => ({
+        results: Array.isArray(wire?.results) ? wire?.results : [],
+        success: wire?.success !== false,
+        ...(wire?.meta ? { meta: wire.meta } : {}),
+    });
+    class HttpStatement {
+        sql;
+        params;
+        constructor(sql, params = []) {
+            this.sql = sql;
+            this.params = params;
+        }
+        bind(...values) {
+            return new HttpStatement(this.sql, toWire(values));
+        }
+        async all() {
+            return asResult((await post('/query', { sql: this.sql, params: this.params }))[0]);
+        }
+        run() {
+            return this.all();
+        }
+        async first(column) {
+            const row = ((await this.all()).results?.[0] ?? null);
+            if (row === null)
+                return null;
+            return column === undefined ? row : (row[column] ?? null);
+        }
+        async raw() {
+            const wire = (await post('/raw', { sql: this.sql, params: this.params }))[0];
+            const results = wire?.results;
+            return results?.rows ?? [];
+        }
+    }
+    return {
+        prepare: (sql) => new HttpStatement(sql),
+        async batch(statements) {
+            const batch = statements.map((s) => {
+                if (!(s instanceof HttpStatement)) {
+                    throw new TypeError('batch() accepts only statements from this same HTTP D1 handle.');
+                }
+                return { sql: s.sql, params: s.params };
+            });
+            if (batch.length === 0)
+                return [];
+            return (await post('/query', { batch })).map(asResult);
+        },
+        async exec(sql) {
+            const results = await post('/query', { sql });
+            return {
+                count: results.length,
+                duration: results.reduce((sum, r) => sum + (r.meta?.duration ?? 0), 0),
+            };
+        },
+    };
+}
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export function createHttpD1(options) {
+    return createRemoteD1(httpD1Binding(options));
+}

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

@@ -16,7 +16,8 @@
  */
 export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup.js';
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.js';
-export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { createHttpD1, D1HttpError, type HttpD1Options } from './http.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, type D1BindingLike, type D1BindingMeta, type D1BindingResult, type D1BindingStatement, } from './remote.js';
 export { classifySchedule, cronFieldCount, jobsForCron, type PortableJob, type PortableJobContext, type ScheduleVerdict, toCronTriggers, toFiveField, type TriggerShape, type WorkersPrimitive, } from './scheduling.js';

package/dist/server/d1/index.js

@@ -34,7 +34,8 @@ export { createTimeTravelBackup, } from './backup.js';
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { createPendingWrites, perInvocation } from './invocation.js';
-export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { createHttpD1, D1HttpError } from './http.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, } from './remote.js';
 export { classifySchedule, cronFieldCount, jobsForCron, toCronTriggers, toFiveField, } from './scheduling.js';

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

@@ -54,3 +54,34 @@ export declare function assertBatchSize(count: number): void;
  * ```
  */
 export declare function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[][];
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export declare function inArray(values: readonly (string | number)[]): {
+    sql: string;
+    param: string;
+};

package/dist/server/d1/limits.js

@@ -94,3 +94,40 @@ export function chunkForBind(items, paramsPerItem) {
         out.push(items.slice(i, i + size));
     return out;
 }
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export function inArray(values) {
+    for (const v of values) {
+        if (typeof v === 'string')
+            continue;
+        if (typeof v === 'number' && Number.isFinite(v))
+            continue;
+        throw new TypeError(`inArray takes strings and finite numbers, got ${typeof v}: ${String(v)}`);
+    }
+    return { sql: 'IN (SELECT value FROM json_each(?))', param: JSON.stringify(values) };
+}

package/package.json

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

package/src/server/d1/http.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+import { createHttpD1, D1HttpError } from './http.js';
+import { D1UnsupportedError } from './types.js';
+
+/**
+ * The HTTP driver against a fake of the D1 REST API's WIRE shapes — the envelopes below are
+ * copied from real responses measured 2026-09-23 on a throwaway database (see `http.ts`).
+ */
+interface Sent {
+	url: string;
+	body: Record<string, unknown>;
+	auth: string | null;
+}
+
+function fakeApi(reply: (path: string, body: Record<string, unknown>) => { status?: number; envelope: unknown }) {
+	const sent: Sent[] = [];
+	const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+		const url = String(input);
+		const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+		sent.push({ url, body, auth: new Headers(init?.headers).get('authorization') });
+		const path = url.endsWith('/raw') ? '/raw' : '/query';
+		const { status = 200, envelope } = reply(path, body);
+		return new Response(JSON.stringify(envelope), { status });
+	}) as typeof fetch;
+	const db = createHttpD1({ accountId: 'acct', databaseId: 'db1', apiToken: 'tok', fetch: fetchImpl });
+	return { db, sent };
+}
+
+const ok = (result: unknown[]) => ({ envelope: { success: true, errors: [], result } });
+const meta = { duration: 0.4, changes: 1, last_row_id: 7, rows_read: 1, rows_written: 1 };
+
+describe('createHttpD1', () => {
+	test('a statement is one POST to /query with its sql, params and the bearer', async () => {
+		const { db, sent } = fakeApi(() => ok([{ results: [{ id: 1, v: 'a' }], success: true, meta }]));
+		const rows = await db.prepare('SELECT * FROM t WHERE id = ? AND v = ?').bind(1, 'a').all();
+		expect(rows.results).toEqual([{ id: 1, v: 'a' }]);
+		expect(sent).toEqual([
+			{
+				url: 'https://api.cloudflare.com/client/v4/accounts/acct/d1/database/db1/query',
+				body: { sql: 'SELECT * FROM t WHERE id = ? AND v = ?', params: [1, 'a'] },
+				auth: 'Bearer tok',
+			},
+		]);
+	});
+
+	test('run reports changes and last_row_id; first reads a row and a column', async () => {
+		const { db } = fakeApi(() => ok([{ results: [{ n: 3 }], success: true, meta }]));
+		const res = await db.prepare('INSERT INTO t (v) VALUES (?)').bind('x').run();
+		expect(res.meta.changes).toBe(1);
+		expect(res.meta.last_row_id).toBe(7);
+		expect(await db.prepare('SELECT COUNT(*) n FROM t').first()).toEqual({ n: 3 });
+		expect(await db.prepare('SELECT COUNT(*) n FROM t').first('n')).toBe(3);
+	});
+
+	test('batch is ONE request carrying every statement, and answers one result each', async () => {
+		const { db, sent } = fakeApi(() =>
+			ok([
+				{ results: [], success: true, meta },
+				{ results: [{ id: 1 }], success: true, meta: { ...meta, changes: 0 } },
+			]),
+		);
+		const results = await db.batch([
+			db.prepare('INSERT INTO t (v) VALUES (?)').bind('a'),
+			db.prepare('SELECT id FROM t'),
+		]);
+		expect(sent).toHaveLength(1);
+		expect(sent[0]?.body).toEqual({
+			batch: [
+				{ sql: 'INSERT INTO t (v) VALUES (?)', params: ['a'] },
+				{ sql: 'SELECT id FROM t', params: [] },
+			],
+		});
+		expect(results.map((r) => r.results)).toEqual([[], [{ id: 1 }]]);
+	});
+
+	test('raw reads the /raw endpoint, so duplicate column names survive', async () => {
+		const { db, sent } = fakeApi(() =>
+			ok([{ results: { columns: ['id', 'v', 'v'], rows: [[1, 'a', 'a']] }, success: true, meta }]),
+		);
+		expect(await db.prepare('SELECT id, v, v AS v FROM t').raw()).toEqual([[1, 'a', 'a']]);
+		expect(sent[0]?.url.endsWith('/raw')).toBe(true);
+	});
+
+	test('a refused statement throws with D1 own message — never a silent empty result', async () => {
+		const { db } = fakeApi(() => ({
+			status: 400,
+			envelope: {
+				success: false,
+				result: [],
+				errors: [{ code: 7500, message: 'UNIQUE constraint failed: t.v: SQLITE_CONSTRAINT' }],
+			},
+		}));
+		const attempt = db.prepare('INSERT INTO t (v) VALUES (?)').bind('one').run();
+		await expect(attempt).rejects.toBeInstanceOf(D1HttpError);
+		await expect(db.prepare('INSERT INTO t (v) VALUES (?)').bind('one').run()).rejects.toThrow(
+			/400\): UNIQUE constraint failed/,
+		);
+	});
+
+	test('a body that is not JSON (a proxy page, an outage) still throws with the status', async () => {
+		const fetchImpl = (async () => new Response('<html>bad gateway</html>', { status: 502 })) as unknown as typeof fetch;
+		const db = createHttpD1({ accountId: 'a', databaseId: 'd', apiToken: 't', fetch: fetchImpl });
+		await expect(db.prepare('SELECT 1').all()).rejects.toThrow(/\(502\)/);
+	});
+
+	test('a BLOB parameter is refused rather than sent in a spelling D1 does not document', () => {
+		const { db } = fakeApi(() => ok([]));
+		expect(() => db.prepare('INSERT INTO t (b) VALUES (?)').bind(new Uint8Array([1, 2]))).toThrow(D1UnsupportedError);
+	});
+
+	test('the parameter cap is the binding driver own — asserted before anything is sent', () => {
+		const { db, sent } = fakeApi(() => ok([]));
+		const holes = Array.from({ length: 101 }, () => '?').join(', ');
+		expect(() => db.prepare(`SELECT ${holes}`).bind(...Array.from({ length: 101 }, (_, i) => i))).toThrow();
+		expect(sent).toHaveLength(0);
+	});
+
+	test('exec sends the whole script and counts the statements D1 ran', async () => {
+		const { db, sent } = fakeApi(() => ok([{ meta }, { meta }, { meta }]));
+		expect(await db.exec('CREATE TABLE u (x); INSERT INTO u VALUES (1); INSERT INTO u VALUES (2)')).toEqual({
+			count: 3,
+			duration: 1.2000000000000002,
+		});
+		expect(sent[0]?.body).toEqual({ sql: 'CREATE TABLE u (x); INSERT INTO u VALUES (1); INSERT INTO u VALUES (2)' });
+	});
+});

package/src/server/d1/http.ts

@@ -0,0 +1,182 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+
+import { createRemoteD1, type D1BindingLike, type D1BindingResult, type D1BindingStatement } from './remote.js';
+import { D1UnsupportedError, type D1LikeDatabase } from './types.js';
+
+export interface HttpD1Options {
+	accountId: string;
+	databaseId: string;
+	/** An API token with D1 Edit on the account. */
+	apiToken: string;
+	/** Each request's ceiling, in ms. Default 30 s — a hung socket must not hang a job. */
+	timeoutMs?: number;
+	/** Injected for tests. Defaults to the global `fetch`. */
+	fetch?: typeof fetch;
+	/** Defaults to `https://api.cloudflare.com/client/v4`. */
+	apiBase?: string;
+}
+
+interface WireResult {
+	results?: unknown;
+	success?: boolean;
+	meta?: D1BindingResult['meta'];
+}
+
+interface Envelope {
+	success?: boolean;
+	errors?: { code?: number; message?: string }[];
+	result?: WireResult[];
+}
+
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export class D1HttpError extends Error {
+	readonly status: number;
+	constructor(status: number, message: string) {
+		super(`D1 over HTTP refused the request (${status}): ${message}`);
+		this.name = 'D1HttpError';
+		this.status = status;
+	}
+}
+
+function toWire(values: readonly unknown[]): unknown[] {
+	return values.map((value, index) => {
+		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+			throw new D1UnsupportedError(
+				`a BLOB parameter (parameter ${index + 1}) over the D1 REST API`,
+				'encode the bytes as text (hex or base64) — the REST API has no documented lossless BLOB spelling',
+			);
+		}
+		return value;
+	});
+}
+
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export function httpD1Binding(options: HttpD1Options): D1BindingLike {
+	const doFetch = options.fetch ?? fetch;
+	const base = `${options.apiBase ?? 'https://api.cloudflare.com/client/v4'}/accounts/${options.accountId}/d1/database/${options.databaseId}`;
+	const timeoutMs = options.timeoutMs ?? 30_000;
+
+	const post = async (path: '/query' | '/raw', body: unknown): Promise<WireResult[]> => {
+		const response = await doFetch(`${base}${path}`, {
+			method: 'POST',
+			headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		const envelope = (await response.json().catch(() => null)) as Envelope | null;
+		if (!response.ok || !envelope || envelope.success === false) {
+			const message =
+				envelope?.errors
+					?.map((e) => e.message)
+					.filter(Boolean)
+					.join('; ') || response.statusText || 'no body';
+			throw new D1HttpError(response.status, message);
+		}
+		return envelope.result ?? [];
+	};
+
+	const asResult = (wire: WireResult | undefined): D1BindingResult => ({
+		results: Array.isArray(wire?.results) ? (wire?.results as unknown[]) : [],
+		success: wire?.success !== false,
+		...(wire?.meta ? { meta: wire.meta } : {}),
+	});
+
+	class HttpStatement implements D1BindingStatement {
+		constructor(
+			readonly sql: string,
+			readonly params: unknown[] = [],
+		) {}
+
+		bind(...values: unknown[]): D1BindingStatement {
+			return new HttpStatement(this.sql, toWire(values));
+		}
+
+		async all(): Promise<D1BindingResult> {
+			return asResult((await post('/query', { sql: this.sql, params: this.params }))[0]);
+		}
+
+		run(): Promise<D1BindingResult> {
+			return this.all();
+		}
+
+		async first(column?: string): Promise<unknown> {
+			const row = ((await this.all()).results?.[0] ?? null) as Record<string, unknown> | null;
+			if (row === null) return null;
+			return column === undefined ? row : (row[column] ?? null);
+		}
+
+		async raw(): Promise<unknown[][]> {
+			const wire = (await post('/raw', { sql: this.sql, params: this.params }))[0];
+			const results = wire?.results as { rows?: unknown[][] } | undefined;
+			return results?.rows ?? [];
+		}
+	}
+
+	return {
+		prepare: (sql) => new HttpStatement(sql),
+		async batch(statements) {
+			const batch = statements.map((s) => {
+				if (!(s instanceof HttpStatement)) {
+					throw new TypeError('batch() accepts only statements from this same HTTP D1 handle.');
+				}
+				return { sql: s.sql, params: s.params };
+			});
+			if (batch.length === 0) return [];
+			return (await post('/query', { batch })).map(asResult);
+		},
+		async exec(sql) {
+			const results = await post('/query', { sql });
+			return {
+				count: results.length,
+				duration: results.reduce((sum, r) => sum + (r.meta?.duration ?? 0), 0),
+			};
+		},
+	};
+}
+
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export function createHttpD1(options: HttpD1Options): D1LikeDatabase {
+	return createRemoteD1(httpD1Binding(options));
+}

package/src/server/d1/index.ts

@@ -40,7 +40,8 @@ export {
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.js';
-export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { createHttpD1, D1HttpError, type HttpD1Options } from './http.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export {
 	createRemoteD1,

package/src/server/d1/limits.spec.ts

@@ -1,6 +1,6 @@
 import { Database } from 'bun:sqlite';
 import { describe, expect, test } from 'bun:test';
-import { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+import { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 import { createLocalD1 } from './local.js';
 import { D1LimitError } from './types.js';
 
@@ -87,4 +87,69 @@ describe('D1 limits are enforced on the LOCAL driver too', () => {
 			expect(() => chunkForBind([1], 1.5)).toThrow(RangeError);
 		});
 	});
+
+	describe('inArray binds a list of any length as ONE parameter', () => {
+		const seeded = (n: number) => {
+			const db = new Database(':memory:');
+			db.run('CREATE TABLE items (id TEXT PRIMARY KEY, n INTEGER, deleted_at INTEGER)');
+			const insert = db.prepare('INSERT INTO items (id, n) VALUES (?, ?)');
+			for (let i = 0; i < n; i++) insert.run(`itm_${String(i).padStart(4, '0')}`, i);
+			return { raw: db, seam: createLocalD1(db) };
+		};
+		const ids = (n: number) => Array.from({ length: n }, (_, i) => `itm_${String(i).padStart(4, '0')}`);
+
+		test('the shape it replaces is refused at 150 ids — the red this exists for', () => {
+			const { seam } = seeded(150);
+			const holes = ids(150).map(() => '?').join(', ');
+			expect(() => seam.prepare(`SELECT id FROM items WHERE id IN (${holes})`).bind(...ids(150))).toThrow(
+				D1LimitError,
+			);
+		});
+
+		test('a 150-id read under ORDER BY / LIMIT / OFFSET selects exactly those rows', async () => {
+			const { seam } = seeded(400);
+			const set = inArray(ids(150));
+			const page = await seam
+				.prepare(`SELECT id FROM items WHERE id ${set.sql} ORDER BY id LIMIT ? OFFSET ?`)
+				.bind(set.param, 100, 20)
+				.all<{ id: string }>();
+			expect(page.results.map((r) => r.id)).toEqual(ids(150).slice(20, 120));
+			const count = await seam
+				.prepare(`SELECT COUNT(*) AS n FROM items WHERE id ${set.sql}`)
+				.bind(set.param)
+				.first<{ n: number }>();
+			expect(count?.n).toBe(150);
+		});
+
+		test('a 1,000-id UPDATE is one statement and touches only those rows', async () => {
+			const { raw, seam } = seeded(1_200);
+			const set = inArray(ids(1_000));
+			await seam.prepare(`UPDATE items SET deleted_at = ? WHERE id ${set.sql}`).bind(7, set.param).run();
+			expect(raw.query('SELECT COUNT(*) AS n FROM items WHERE deleted_at = 7').get()).toEqual({ n: 1_000 });
+			expect(raw.query('SELECT COUNT(*) AS n FROM items WHERE deleted_at IS NULL').get()).toEqual({ n: 200 });
+		});
+
+		test('numbers compare as numbers, and an empty list is valid SQL that matches nothing', async () => {
+			const { seam } = seeded(10);
+			const nums = inArray([2, 4, 6]);
+			const hit = await seam.prepare(`SELECT id FROM items WHERE n ${nums.sql} ORDER BY n`).bind(nums.param).all<{ id: string }>();
+			expect(hit.results.map((r) => r.id)).toEqual(['itm_0002', 'itm_0004', 'itm_0006']);
+			const none = inArray([]);
+			const empty = await seam.prepare(`SELECT id FROM items WHERE id ${none.sql}`).bind(none.param).all();
+			expect(empty.results).toEqual([]);
+		});
+
+		test('a value it cannot compare honestly is refused, not matched against nothing', () => {
+			expect(() => inArray([null as unknown as string])).toThrow(TypeError);
+			expect(() => inArray([Number.NaN])).toThrow(TypeError);
+			expect(() => inArray([{} as unknown as string])).toThrow(TypeError);
+		});
+
+		test('past 2 MB of JSON the seam refuses it at bind(), naming the byte count', () => {
+			const { seam } = seeded(1);
+			const huge = inArray(Array.from({ length: 90_000 }, (_, i) => `itm_${String(i).padStart(20, '0')}`));
+			expect(() => seam.prepare(`SELECT id FROM items WHERE id ${huge.sql}`).bind(huge.param)).toThrow(/value size/);
+		});
+	});
 });
+

package/src/server/d1/limits.ts

@@ -121,3 +121,39 @@ export function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[]
 	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size) as T[]);
 	return out;
 }
+
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export function inArray(values: readonly (string | number)[]): { sql: string; param: string } {
+	for (const v of values) {
+		if (typeof v === 'string') continue;
+		if (typeof v === 'number' && Number.isFinite(v)) continue;
+		throw new TypeError(`inArray takes strings and finite numbers, got ${typeof v}: ${String(v)}`);
+	}
+	return { sql: 'IN (SELECT value FROM json_each(?))', param: JSON.stringify(values) };
+}