cursedbelt-server 2.0.0 → 3.0.0

package/src/server/d1/fakeD1.ts

@@ -0,0 +1,193 @@
+/**
+ * A `bun:sqlite`-backed stand-in for a real D1 binding, for tests that must run without a
+ * Worker.
+ *
+ * ## 🔴 It is a DIVERGENCE SIMULATOR, not a mirror of our driver
+ *
+ * The whole value of this file rests on one discipline: it reproduces the ways D1 differs
+ * from `bun:sqlite`, deliberately and on purpose. A fake written to agree with
+ * `createRemoteD1` would make `sameShape.spec.ts` assert that our code agrees with itself,
+ * which is a test that can never fail and therefore is not one.
+ *
+ * So it does the awkward things D1 really does, each measured against `bun:sqlite` on
+ * 2026-09-16 and each one a real defect this fleet would otherwise ship:
+ *
+ *   1. **BLOBs come back as `number[]`**, not `Uint8Array` — D1 crosses the wire as JSON.
+ *   2. **`undefined` and `boolean` binds are REFUSED**, where `bun:sqlite` silently binds
+ *      NULL and silently coerces to 0/1.
+ *   3. **`bigint` binds are refused** — `bun:sqlite` coerces them to numbers, losing
+ *      precision above 2^53 without a word.
+ *   4. **Results are wrapped** in `{ results, success, meta }` rather than returned bare.
+ *   5. **`BEGIN`/`COMMIT` is refused** — D1 has no interactive transaction.
+ *
+ * SQL semantics are real: it runs against an actual in-memory SQLite. Only the edges are
+ * emulated, which are exactly the edges under test.
+ *
+ * 🔴 **It is not a substitute for running against real D1 once.** It cannot reproduce
+ * network failure, a `rows_read` budget or the 30-second query cap. It is the thing that
+ * makes a port testable on a laptop, and `190`'s Worker preview is the thing that proves
+ * it.
+ */
+
+import type { Database } from 'bun:sqlite';
+import type { D1BindingLike, D1BindingResult, D1BindingStatement } from './remote';
+
+/** The bind types a real D1 binding accepts. Everything else throws. */
+function assertD1Bindable(value: unknown, index: number): void {
+	if (value === null) return;
+	const t = typeof value;
+	if (t === 'string' || t === 'number') {
+		if (t === 'number' && !Number.isFinite(value as number)) {
+			throw new TypeError(`D1_TYPE_ERROR: value ${String(value)} at position ${index + 1} is not a finite number`);
+		}
+		return;
+	}
+	if (value instanceof ArrayBuffer || value instanceof Uint8Array) return;
+	throw new TypeError(
+		`D1_TYPE_ERROR: Type '${t === 'undefined' ? 'undefined' : ((value as object)?.constructor?.name ?? t)}' ` +
+			`not supported for value at position ${index + 1}`,
+	);
+}
+
+/** D1 returns BLOB columns as plain arrays of byte values, because the wire is JSON. */
+function toWireValue(value: unknown): unknown {
+	if (value instanceof Uint8Array) return Array.from(value);
+	if (typeof value === 'bigint') return Number(value);
+	return value ?? null;
+}
+
+const toWireRow = (row: Record<string, unknown>): Record<string, unknown> => {
+	const out: Record<string, unknown> = {};
+	for (const k of Object.keys(row)) out[k] = toWireValue(row[k]);
+	return out;
+};
+
+const REFUSED_SQL = /^\s*(begin|commit|rollback|savepoint|release|vacuum|attach|detach|pragma\s+journal_mode)\b/i;
+
+function assertRunnableOnD1(sql: string): void {
+	if (REFUSED_SQL.test(sql)) {
+		throw new Error(
+			`D1_ERROR: not authorized — D1 does not permit '${sql.trim().split(/\s+/)[0]}'. ` +
+				'Use batch() for atomicity; D1 has no interactive transaction and no WAL to configure.',
+		);
+	}
+}
+
+class FakeD1Statement implements D1BindingStatement {
+	constructor(
+		private readonly db: Database,
+		/** Public so `batch()` can re-run the statement inside its transaction. */
+		readonly sql: string,
+		readonly params: unknown[] = [],
+	) {}
+
+	bind(...values: unknown[]): D1BindingStatement {
+		values.forEach((v, i) => assertD1Bindable(v, i));
+		// A real binding stores what it was given; the ArrayBuffer→Uint8Array conversion
+		// here is `bun:sqlite`'s requirement, not D1's, and happens below the emulated edge.
+		const stored = values.map((v) => (v instanceof ArrayBuffer ? new Uint8Array(v) : v));
+		return new FakeD1Statement(this.db, this.sql, stored);
+	}
+
+	private meta(started: number, changes = 0, lastRowId = 0) {
+		return {
+			duration: performance.now() - started,
+			changes,
+			last_row_id: lastRowId,
+			// D1 reports these; the numbers here are not meaningful, but their PRESENCE is
+			// what the driver's `meta` mapping has to cope with.
+			rows_read: 0,
+			rows_written: changes,
+			served_by: 'fake-d1',
+		};
+	}
+
+	async first(column?: string): Promise<unknown> {
+		assertRunnableOnD1(this.sql);
+		const row = this.db.query(this.sql).get(...(this.params as never[])) as Record<string, unknown> | null;
+		if (!row) return null;
+		const wire = toWireRow(row);
+		if (column === undefined) return wire;
+		if (!(column in wire)) throw new Error(`D1_ERROR: no such column: ${column}`);
+		return wire[column];
+	}
+
+	async all(): Promise<D1BindingResult> {
+		assertRunnableOnD1(this.sql);
+		const started = performance.now();
+		const rows = this.db.query(this.sql).all(...(this.params as never[])) as Record<string, unknown>[];
+		return { results: rows.map(toWireRow), success: true, meta: this.meta(started) };
+	}
+
+	async run(): Promise<D1BindingResult> {
+		assertRunnableOnD1(this.sql);
+		const started = performance.now();
+		const res = this.db.query(this.sql).run(...(this.params as never[]));
+		return {
+			results: [],
+			success: true,
+			meta: this.meta(started, res.changes, Number(res.lastInsertRowid)),
+		};
+	}
+
+	async raw(): Promise<unknown[][]> {
+		assertRunnableOnD1(this.sql);
+		const rows = this.db.query(this.sql).values(...(this.params as never[])) as unknown[][];
+		return rows.map((r) => r.map(toWireValue));
+	}
+}
+
+/**
+ * Wrap a real `bun:sqlite` database in D1's API and D1's restrictions.
+ *
+ * ```ts
+ * const sqlite = new Database(':memory:');
+ * const db = createRemoteD1(createFakeD1Binding(sqlite));   // behaves like the real thing
+ * ```
+ */
+export function createFakeD1Binding(db: Database): D1BindingLike {
+	return {
+		prepare(sql: string): D1BindingStatement {
+			return new FakeD1Statement(db, sql);
+		},
+
+		async batch(statements: D1BindingStatement[]): Promise<D1BindingResult[]> {
+			// D1's batch is atomic — it is the only atomicity D1 offers. A real `bun:sqlite`
+			// transaction is the faithful local equivalent.
+			const results: D1BindingResult[] = [];
+			const run = db.transaction((stmts: D1BindingStatement[]) => {
+				for (const s of stmts) {
+					const started = performance.now();
+					const inner = s as FakeD1Statement;
+					assertRunnableOnD1(inner.sql);
+					const rows = db.query(inner.sql).all(...(inner.params as never[])) as Record<string, unknown>[];
+					results.push({
+						results: rows.map(toWireRow),
+						success: true,
+						meta: {
+							duration: performance.now() - started,
+							changes: 0,
+							last_row_id: 0,
+							rows_read: rows.length,
+							rows_written: 0,
+							served_by: 'fake-d1',
+						},
+					});
+				}
+			});
+			run(statements);
+			return results;
+		},
+
+		async exec(sql: string): Promise<{ count: number; duration: number }> {
+			const started = performance.now();
+			const statements = sql
+				.split(';')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+			for (const s of statements) assertRunnableOnD1(s);
+			for (const s of statements) db.exec(s);
+			return { count: statements.length, duration: performance.now() - started };
+		},
+	};
+}

package/src/server/d1/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `cursedbelt-server/d1` — the async database seam the fleet crosses to reach Cloudflare
+ * Workers, with a local `bun:sqlite` implementation so the gate, the dev loop and every
+ * still-Mac-hosted app keep working unchanged.
+ *
+ * Start at `./types`, which explains why the interface is async on BOTH sides and why the
+ * local driver is deliberately as strict as D1 rather than as lenient as Bun.
+ *
+ * ```ts
+ * import { createLocalD1, createRemoteD1, createD1Kysely } from 'cursedbelt-server/d1';
+ *
+ * const db = env.DB ? createRemoteD1(env.DB) : createLocalD1(sqlite);
+ * const row = await db.prepare('SELECT * FROM people WHERE id = ?').bind(id).first();
+ * const ky  = createD1Kysely(db);
+ * ```
+ */
+
+export {
+	backupFor,
+	type BackupPoint,
+	checkpointWal,
+	createLocalBackup,
+	createTimeTravelBackup,
+	type DatabaseBackup,
+	type LocalBackupOpts,
+	type TimeTravelOpts,
+} from './backup';
+export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
+export { createLocalD1, refuseInteractiveTransaction } from './local';
+export {
+	createRemoteD1,
+	type D1BindingLike,
+	type D1BindingMeta,
+	type D1BindingResult,
+	type D1BindingStatement,
+} from './remote';
+export {
+	classifySchedule,
+	cronFieldCount,
+	jobsForCron,
+	type PortableJob,
+	type PortableJobContext,
+	type ScheduleVerdict,
+	toCronTriggers,
+	toFiveField,
+	type TriggerShape,
+	type WorkersPrimitive,
+} from './scheduling';
+export {
+	D1BindError,
+	type D1LikeBindable,
+	type D1LikeDatabase,
+	type D1LikeMeta,
+	type D1LikeResult,
+	type D1LikeRow,
+	type D1LikeStatement,
+	type D1LikeValue,
+	D1LimitError,
+	D1UnsupportedError,
+} from './types';
+export { makeMeta, normalizeBind, normalizeBinds, normalizeRow, normalizeRows, normalizeValue } from './values';

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

@@ -0,0 +1,145 @@
+/**
+ * The cheap half, proved on BOTH drivers with the same assertions — the point being that
+ * `createD1Kysely` is one dialect over the driver seam, so a plumbing query cannot tell
+ * which side it is on.
+ */
+
+import { Database } from 'bun:sqlite';
+import { describe, expect, test } from 'bun:test';
+import type { Kysely } from 'kysely';
+import { createFakeD1Binding } from './fakeD1';
+import { createD1Kysely } from './kysely';
+import { createLocalD1 } from './local';
+import { createRemoteD1 } from './remote';
+import { D1UnsupportedError, type D1LikeDatabase } from './types';
+
+const DDL = `CREATE TABLE app_config (
+  key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL, updated_by TEXT
+)`;
+
+interface Schema {
+	app_config: { key: string; value: string; updated_at: string; updated_by: string | null };
+}
+
+/** The same schema behind each driver, so every test below runs twice. */
+const drivers = (): Array<[string, () => D1LikeDatabase]> => [
+	[
+		'local',
+		() => {
+			const db = new Database(':memory:');
+			db.run(DDL);
+			return createLocalD1(db);
+		},
+	],
+	[
+		'd1',
+		() => {
+			const db = new Database(':memory:');
+			db.run(DDL);
+			return createRemoteD1(createFakeD1Binding(db));
+		},
+	],
+];
+
+for (const [flavor, make] of drivers()) {
+	describe(`createD1Kysely on the ${flavor} driver`, () => {
+		const fresh = (): Kysely<Schema> => createD1Kysely<Schema>(make());
+
+		test('selectAll on an empty table returns []', async () => {
+			expect(await fresh().selectFrom('app_config').selectAll().execute()).toEqual([]);
+		});
+
+		test('insert + select round-trips a row', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'media_backend', value: 'disk', updated_at: 't', updated_by: null })
+				.execute();
+
+			const row = await ky
+				.selectFrom('app_config')
+				.select(['key', 'value'])
+				.where('key', '=', 'media_backend')
+				.executeTakeFirst();
+
+			expect(row).toEqual({ key: 'media_backend', value: 'disk' });
+		});
+
+		test('an insert reports the rows it affected', async () => {
+			const ky = fresh();
+			const res = await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.executeTakeFirst();
+			expect(Number(res.numInsertedOrUpdatedRows)).toBe(1);
+		});
+
+		test('update and delete report their affected row counts', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.execute();
+
+			const updated = await ky
+				.updateTable('app_config')
+				.set({ value: '2' })
+				.where('key', '=', 'a')
+				.executeTakeFirst();
+			expect(Number(updated.numUpdatedRows)).toBe(1);
+
+			const deleted = await ky.deleteFrom('app_config').where('key', '=', 'a').executeTakeFirst();
+			expect(Number(deleted.numDeletedRows)).toBe(1);
+		});
+
+		test('RETURNING gives back rows rather than a count', async () => {
+			const ky = fresh();
+			const returned = await ky
+				.insertInto('app_config')
+				.values({ key: 'k', value: 'v', updated_at: 't', updated_by: null })
+				.returning(['key', 'value'])
+				.executeTakeFirst();
+			expect(returned).toEqual({ key: 'k', value: 'v' });
+		});
+
+		test('a NULL column comes back as null on both', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.execute();
+			const row = await ky.selectFrom('app_config').selectAll().executeTakeFirstOrThrow();
+			expect(row.updated_by).toBeNull();
+		});
+
+		test('🔴 an interactive transaction is REFUSED — D1 has none, so neither does local', async () => {
+			// The trap this closes: a local dialect that honoured BEGIN would be green here
+			// and red in the Worker. `db.batch()` is the atomicity primitive instead.
+			const ky = fresh();
+			await expect(
+				ky.transaction().execute(async (trx) => {
+					await trx
+						.insertInto('app_config')
+						.values({ key: 'x', value: '1', updated_at: 't', updated_by: null })
+						.execute();
+				}),
+			).rejects.toThrow(D1UnsupportedError);
+		});
+
+		test('a refused transaction leaves NOTHING behind', async () => {
+			const db = make();
+			const ky = createD1Kysely<Schema>(db);
+			await ky
+				.transaction()
+				.execute(async (trx) => {
+					await trx
+						.insertInto('app_config')
+						.values({ key: 'x', value: '1', updated_at: 't', updated_by: null })
+						.execute();
+				})
+				.catch(() => {});
+			const rows = await ky.selectFrom('app_config').selectAll().execute();
+			expect(rows).toEqual([]);
+		});
+	});
+}

package/src/server/d1/kysely.ts

@@ -0,0 +1,169 @@
+/**
+ * The cheap half: a Kysely dialect that speaks {@link D1LikeDatabase}, so every session,
+ * config, log, metric and job table crosses the seam at once and the schema types do not
+ * change at all.
+ *
+ * ## 🔴 ONE dialect over the driver, not two dialects side by side
+ *
+ * The obvious port is "swap `BunSqliteDialect` for a D1 dialect behind a factory". It is
+ * the wrong shape, and cheaply so: two dialects are two implementations of value handling,
+ * and the identical-shapes test would then be asserting that two third-party packages
+ * happen to agree about BLOBs, booleans and `undefined` — the four places SQLite drivers
+ * are already known to disagree. Here there is one dialect. It talks to the driver seam,
+ * the driver seam normalizes through `./values`, and "local and remote return the same
+ * shape" is true by construction rather than by luck.
+ *
+ * It also means the D1 half needs no `kysely-d1` dependency, and the local half keeps
+ * working with the `bun:sqlite` handle the rest of a half-ported app still holds.
+ *
+ * ## What a caller gives up
+ *
+ * `ky.transaction()` throws {@link D1UnsupportedError} on BOTH drivers — D1 has no
+ * interactive transaction, and a local dialect that honoured `BEGIN` would be green here
+ * and red in the Worker. Use `db.batch()` for atomicity. Streaming is refused for the same
+ * reason: D1 returns a whole result set.
+ *
+ * The existing `../db/kysely.ts` is untouched and still correct for an app that has not
+ * moved; this is the one to reach for when it does.
+ */
+
+import {
+	type CompiledQuery,
+	type DatabaseConnection,
+	type DatabaseIntrospector,
+	type Dialect,
+	type DialectAdapter,
+	type Driver,
+	Kysely,
+	type QueryCompiler,
+	type QueryResult,
+	SqliteAdapter,
+	SqliteIntrospector,
+	SqliteQueryCompiler,
+} from 'kysely';
+import type { PlumbingSchema } from '../db/plumbingTypes';
+import { refuseInteractiveTransaction } from './local';
+import { type D1LikeBindable, type D1LikeDatabase, D1UnsupportedError } from './types';
+
+/**
+ * Kysely compiles to a parameter list that may contain values our seam refuses
+ * (`undefined` from an optional column, a `Date` from a careless caller). Passing them
+ * through `bind()` is what turns those into a named error at the call site instead of a
+ * NULL locally and a 500 in production.
+ */
+const bindParams = (sql: string, db: D1LikeDatabase, parameters: readonly unknown[]) => {
+	const stmt = db.prepare(sql);
+	return parameters.length > 0 ? stmt.bind(...(parameters as D1LikeBindable[])) : stmt;
+};
+
+/**
+ * Decide whether a compiled query should be read (`.all()`) or executed (`.run()`).
+ *
+ * Kysely needs `numAffectedRows`/`insertId` from a write and rows from a read, and only
+ * `.run()` reports the former. A write carrying `RETURNING` is a read for this purpose —
+ * its rows are the whole point of the statement.
+ */
+function isRowReturning(query: CompiledQuery['query']): boolean {
+	const node = query as { kind?: string; returning?: unknown };
+	if (node.kind === 'SelectQueryNode' || node.kind === 'RawNode') return true;
+	return node.returning !== undefined;
+}
+
+class D1LikeConnection implements DatabaseConnection {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	async executeQuery<R>(compiled: CompiledQuery): Promise<QueryResult<R>> {
+		const stmt = bindParams(compiled.sql, this.db, compiled.parameters);
+
+		if (isRowReturning(compiled.query)) {
+			const res = await stmt.all<R>();
+			return { rows: res.results };
+		}
+
+		const res = await stmt.run();
+		return {
+			rows: [],
+			numAffectedRows: BigInt(res.meta.changes),
+			insertId: res.meta.last_row_id === null ? undefined : BigInt(res.meta.last_row_id),
+		};
+	}
+
+	// biome-ignore lint/correctness/useYield: it always throws; a generator body with no
+	// yield is the honest shape for an operation the seam does not have.
+	async *streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
+		throw new D1UnsupportedError(
+			'streaming a result set',
+			'D1 returns a whole result set — page with LIMIT/OFFSET, or a keyset cursor',
+		);
+	}
+}
+
+class D1LikeDriver implements Driver {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	async init(): Promise<void> {}
+
+	async acquireConnection(): Promise<DatabaseConnection> {
+		// A D1 binding is not a connection: there is no pool, nothing to check out and
+		// nothing to close. The local driver shares the app's single handle for the same
+		// reason. So one connection object serves every query.
+		return new D1LikeConnection(this.db);
+	}
+
+	async beginTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async commitTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async rollbackTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async releaseConnection(): Promise<void> {}
+
+	async destroy(): Promise<void> {}
+}
+
+/** The dialect itself — SQLite's adapter, compiler and introspector over our driver. */
+export class D1LikeDialect implements Dialect {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	createAdapter(): DialectAdapter {
+		return new SqliteAdapter();
+	}
+
+	createDriver(): Driver {
+		return new D1LikeDriver(this.db);
+	}
+
+	createQueryCompiler(): QueryCompiler {
+		return new SqliteQueryCompiler();
+	}
+
+	createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+		return new SqliteIntrospector(db);
+	}
+}
+
+/**
+ * A Kysely query builder over either driver.
+ *
+ * Defaults to {@link PlumbingSchema} — sessions, config, logs, metrics and jobs — which is
+ * the boundary `../db/kysely.ts` drew and this keeps: business / `data JSON` tables stay
+ * on the raw statement API, so the Kysely schema never grows a row per feature table.
+ * Apps with their own plumbing pass their own schema.
+ *
+ * ```ts
+ * const db = createLocalD1(sqlite);            // or createRemoteD1(env.DB)
+ * const ky = createD1Kysely(db);
+ * await ky.selectFrom('auth_sessions').selectAll().execute();   // identical on both
+ * ```
+ */
+export function createD1Kysely<Schema = PlumbingSchema>(db: D1LikeDatabase): Kysely<Schema> {
+	return new Kysely<Schema>({ dialect: new D1LikeDialect(db) });
+}
+
+export type D1PlumbingDb = Kysely<PlumbingSchema>;

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

@@ -0,0 +1,90 @@
+import { Database } from 'bun:sqlite';
+import { describe, expect, test } from 'bun:test';
+import { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
+import { createLocalD1 } from './local';
+import { D1LimitError } from './types';
+
+describe('D1 limits are enforced on the LOCAL driver too', () => {
+	// 🔴 The point of every test here: `bun:sqlite` has none of these caps, so without
+	// this enforcement a bulk insert is green on the laptop and fails on the first real
+	// import in production.
+
+	test('101 bound parameters is refused, naming the chunking helper', () => {
+		const db = createLocalD1(new Database(':memory:'));
+		const placeholders = Array(101).fill('?').join(',');
+		expect(() => db.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(101).fill(1))).toThrow(
+			D1LimitError,
+		);
+		try {
+			db.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(101).fill(1));
+		} catch (e) {
+			expect((e as Error).message).toContain('chunkForBind');
+		}
+	});
+
+	test('exactly 100 bound parameters is allowed — the cap is not off by one', () => {
+		const db = new Database(':memory:');
+		db.run('CREATE TABLE t (id INTEGER)');
+		const seam = createLocalD1(db);
+		const placeholders = Array(100).fill('?').join(',');
+		expect(() =>
+			seam.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(100).fill(1)),
+		).not.toThrow();
+	});
+
+	test('a value over 2 MB is refused, and says where media belongs instead', () => {
+		const db = createLocalD1(new Database(':memory:'));
+		const huge = 'x'.repeat(LIMITS.valueBytes + 1);
+		try {
+			db.prepare('INSERT INTO t (v) VALUES (?)').bind(huge);
+			throw new Error('expected a refusal');
+		} catch (e) {
+			expect(e).toBeInstanceOf(D1LimitError);
+			expect((e as Error).message).toContain('R2');
+		}
+	});
+
+	test('SQL longer than 100 KB is refused before the parameter cap bites', () => {
+		// The measured ordering: a generated `IN (...)` list hits the statement-length cap
+		// first, because inlined values carry no parameters at all.
+		const sql = `SELECT * FROM t WHERE x IN (${Array(30_000).fill("'abc'").join(',')})`;
+		expect(() => assertWithinLimits(sql, [])).toThrow(D1LimitError);
+		expect(() => assertWithinLimits(sql, [])).toThrow(/SQL statement length/);
+	});
+
+	test('a batch over 1,000 statements is refused', () => {
+		expect(() => assertBatchSize(1_001)).toThrow(D1LimitError);
+		expect(() => assertBatchSize(1_000)).not.toThrow();
+	});
+
+	describe('chunkForBind does the arithmetic nobody does correctly by eye', () => {
+		test('4 columns → 25 rows a chunk', () => {
+			const chunks = chunkForBind(Array.from({ length: 60 }, (_, i) => i), 4);
+			expect(chunks.map((c) => c.length)).toEqual([25, 25, 10]);
+			// The property that matters: no chunk exceeds the cap once expanded.
+			for (const c of chunks) expect(c.length * 4).toBeLessThanOrEqual(LIMITS.boundParams);
+		});
+
+		test('a chunk is never empty and every item appears exactly once', () => {
+			const items = Array.from({ length: 489 }, (_, i) => i); // family's 489 people
+			const chunks = chunkForBind(items, 7);
+			expect(chunks.flat()).toEqual(items);
+			for (const c of chunks) expect(c.length).toBeGreaterThan(0);
+		});
+
+		test('an empty list yields no chunks rather than one empty one', () => {
+			expect(chunkForBind([], 3)).toEqual([]);
+		});
+
+		test('an item wider than the cap is refused, not silently chunked to zero', () => {
+			// `floor(100 / 101)` is 0, and a chunk size of 0 loops for ever. This is the
+			// guard that turns an infinite loop into a sentence.
+			expect(() => chunkForBind([1, 2], 101)).toThrow(D1LimitError);
+		});
+
+		test('a nonsense chunk width is refused', () => {
+			expect(() => chunkForBind([1], 0)).toThrow(RangeError);
+			expect(() => chunkForBind([1], 1.5)).toThrow(RangeError);
+		});
+	});
+});