cursedbelt-server 1.1.0 → 2.1.0

package/dist/server/d1/backup.js

@@ -0,0 +1,128 @@
+/**
+ * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
+ *
+ * ## 🔴 BOTH, not one
+ *
+ * D1 has no WAL a caller can checkpoint, and 30 days of free point-in-time restore is
+ * strictly better than the file copy it replaces. It is tempting to read that as "the
+ * checkpoint goes away". It does not: `PRAGMA wal_checkpoint(TRUNCATE)` is in the backup
+ * path of every app in this fleet and it is load-bearing while any of them is still
+ * Mac-hosted. Measured previously, `family.sqlite` was **2.2 MB of principal against a
+ * 2.1 MB WAL** — an un-checkpointed copy is half a database, and `VACUUM INTO` merging
+ * the WAL is the only reason the existing `../sqlite/backup.ts` is safe.
+ *
+ * So the local implementation keeps checkpointing, the remote one records a restore
+ * coordinate, and both answer the same interface. An app's backup job stops caring which
+ * side it is on — which is the property that lets the job move before the database does.
+ *
+ * ## The remote side does not "take" a backup, and that is not a gap
+ *
+ * Time Travel is automatic and continuous: D1 retains 30 days and restores to any
+ * timestamp or bookmark within it. There is nothing to trigger, so
+ * {@link createTimeTravelBackup} records the coordinate rather than inventing an API call
+ * that does not exist. The coordinate IS the backup — `wrangler d1 time-travel restore`
+ * takes a timestamp.
+ *
+ * 🔴 **`wrangler d1 export` is the off-Cloudflare leg, and a Worker cannot run it.** A
+ * Worker has no shell. That leg belongs to a Cron Trigger on this Mac or in CI, which is
+ * why {@link BackupPoint.exportCommand} hands back the command rather than running it —
+ * the same split as the binary server, where the bytes and the thing that copies them are
+ * deliberately not the same process.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { snapshotSqlite } from '../sqlite/backup';
+/**
+ * Force the WAL back into the principal database and truncate the log file.
+ *
+ * `TRUNCATE` — not `PASSIVE` — because `PASSIVE` gives up silently when a reader holds the
+ * WAL, leaving a WAL that never drains while every log line says the backup succeeded.
+ *
+ * 🔴 **`busy` is the only field worth reading, and that is a measured correction.** Under
+ * `TRUNCATE` SQLite reports the counters from AFTER the truncation, so a completely
+ * successful checkpoint returns `(busy 0, log 0, checkpointed 0)` — measured 2026-09-16,
+ * draining a 70,072-byte WAL to zero reported `checkpointed: 0`. Anything asserting
+ * `checkpointed > 0` as proof of work is asserting a value that is structurally always
+ * zero here. The honest post-condition is the WAL file's SIZE, which is what
+ * `backup.spec.ts` checks; the honest error signal is `busy`.
+ */
+export function checkpointWal(db) {
+    // One row: (busy, log, checkpointed). See the note above on what they mean here.
+    const row = db.query('PRAGMA wal_checkpoint(TRUNCATE)').get();
+    return {
+        busy: (row?.busy ?? 0) === 1,
+        logPages: row?.log ?? 0,
+        checkpointed: row?.checkpointed ?? 0,
+    };
+}
+/**
+ * The Mac-hosted implementation: checkpoint, then `VACUUM INTO` a fresh file.
+ *
+ * `VACUUM INTO` is already transactionally consistent under WAL, so the checkpoint is not
+ * what makes the copy correct — it is what keeps the WAL from growing without bound on a
+ * database that is written far more often than it is read, which is how a 2.2 MB database
+ * came to carry a 2.1 MB WAL.
+ */
+export function createLocalBackup(opts) {
+    return {
+        needsPeriodicCapture: true,
+        async capture() {
+            const checkpoint = checkpointWal(opts.db);
+            if (checkpoint.busy) {
+                // Not fatal — `VACUUM INTO` still produces a consistent copy — but it is the
+                // signal that the WAL is not draining, and silence here is how it grows.
+                console.warn(`[d1/backup] wal_checkpoint(TRUNCATE) reported BUSY for ${opts.sourcePath} — ` +
+                    `${checkpoint.logPages} page(s) still in the WAL. A reader is holding it open.`);
+            }
+            if (!existsSync(opts.destDir))
+                mkdirSync(opts.destDir, { recursive: true });
+            const now = new Date();
+            const stamp = now.toISOString().replace(/[:.]/g, '-');
+            const name = opts.nameFor?.(now) ?? `backup-${stamp}.sqlite`;
+            const dest = join(opts.destDir, name);
+            const bytes = snapshotSqlite(opts.sourcePath, dest);
+            return {
+                kind: 'file',
+                ref: dest,
+                createdAt: now.toISOString(),
+                bytes,
+                restoreCommand: `cp '${dest}' '${opts.sourcePath}'   # with the app stopped`,
+                exportCommand: null,
+            };
+        },
+    };
+}
+/**
+ * The D1 implementation: record the coordinate, because retention is automatic.
+ *
+ * 🔴 It reports `needsPeriodicCapture: false`, and a scheduler must honour that rather
+ * than calling `capture()` on a timer — a nightly no-op job that logs "backup complete"
+ * is worse than no job, because it reads as evidence.
+ */
+export function createTimeTravelBackup(opts) {
+    const clock = opts.now ?? (() => new Date());
+    const exportPath = opts.exportPath ?? `./${opts.databaseName}-export.sql`;
+    return {
+        needsPeriodicCapture: false,
+        async capture() {
+            const at = clock().toISOString();
+            return {
+                kind: 'time-travel',
+                ref: at,
+                createdAt: at,
+                // Cloudflare does not report a size for a restore point, and a fabricated
+                // number would read as a measurement.
+                bytes: null,
+                restoreCommand: `wrangler d1 time-travel restore ${opts.databaseName} --timestamp=${at}`,
+                exportCommand: `wrangler d1 export ${opts.databaseName} --remote --output=${exportPath}`,
+            };
+        },
+    };
+}
+/**
+ * Pick the backup implementation from the driver flavor, so an app's job definition reads
+ * the same on both sides.
+ */
+export function backupFor(flavor, local, remote) {
+    return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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 } from './remote';
+/**
+ * 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 declare function createFakeD1Binding(db: Database): D1BindingLike;

package/dist/server/d1/fakeD1.js

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+/** The bind types a real D1 binding accepts. Everything else throws. */
+function assertD1Bindable(value, index) {
+    if (value === null)
+        return;
+    const t = typeof value;
+    if (t === 'string' || t === 'number') {
+        if (t === 'number' && !Number.isFinite(value)) {
+            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?.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) {
+    if (value instanceof Uint8Array)
+        return Array.from(value);
+    if (typeof value === 'bigint')
+        return Number(value);
+    return value ?? null;
+}
+const toWireRow = (row) => {
+    const out = {};
+    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) {
+    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 {
+    db;
+    sql;
+    params;
+    constructor(db, 
+    /** Public so `batch()` can re-run the statement inside its transaction. */
+    sql, params = []) {
+        this.db = db;
+        this.sql = sql;
+        this.params = params;
+    }
+    bind(...values) {
+        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);
+    }
+    meta(started, 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) {
+        assertRunnableOnD1(this.sql);
+        const row = this.db.query(this.sql).get(...this.params);
+        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() {
+        assertRunnableOnD1(this.sql);
+        const started = performance.now();
+        const rows = this.db.query(this.sql).all(...this.params);
+        return { results: rows.map(toWireRow), success: true, meta: this.meta(started) };
+    }
+    async run() {
+        assertRunnableOnD1(this.sql);
+        const started = performance.now();
+        const res = this.db.query(this.sql).run(...this.params);
+        return {
+            results: [],
+            success: true,
+            meta: this.meta(started, res.changes, Number(res.lastInsertRowid)),
+        };
+    }
+    async raw() {
+        assertRunnableOnD1(this.sql);
+        const rows = this.db.query(this.sql).values(...this.params);
+        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) {
+    return {
+        prepare(sql) {
+            return new FakeD1Statement(db, sql);
+        },
+        async batch(statements) {
+            // D1's batch is atomic — it is the only atomicity D1 offers. A real `bun:sqlite`
+            // transaction is the faithful local equivalent.
+            const results = [];
+            const run = db.transaction((stmts) => {
+                for (const s of stmts) {
+                    const started = performance.now();
+                    const inner = s;
+                    assertRunnableOnD1(inner.sql);
+                    const rows = db.query(inner.sql).all(...inner.params);
+                    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) {
+            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/dist/server/d1/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `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/dist/server/d1/index.js

@@ -0,0 +1,24 @@
+/**
+ * `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, checkpointWal, createLocalBackup, createTimeTravelBackup, } from './backup';
+export { createD1Kysely, D1LikeDialect } from './kysely';
+export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
+export { createLocalD1, refuseInteractiveTransaction } from './local';
+export { createRemoteD1, } from './remote';
+export { classifySchedule, cronFieldCount, jobsForCron, toCronTriggers, toFiveField, } from './scheduling';
+export { D1BindError, D1LimitError, D1UnsupportedError, } from './types';
+export { makeMeta, normalizeBind, normalizeBinds, normalizeRow, normalizeRows, normalizeValue } from './values';

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

@@ -0,0 +1,56 @@
+/**
+ * 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 DatabaseIntrospector, type Dialect, type DialectAdapter, type Driver, Kysely, type QueryCompiler } from 'kysely';
+import type { PlumbingSchema } from '../db/plumbingTypes';
+import { type D1LikeDatabase } from './types';
+/** The dialect itself — SQLite's adapter, compiler and introspector over our driver. */
+export declare class D1LikeDialect implements Dialect {
+    private readonly db;
+    constructor(db: D1LikeDatabase);
+    createAdapter(): DialectAdapter;
+    createDriver(): Driver;
+    createQueryCompiler(): QueryCompiler;
+    createIntrospector(db: Kysely<unknown>): DatabaseIntrospector;
+}
+/**
+ * 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 declare function createD1Kysely<Schema = PlumbingSchema>(db: D1LikeDatabase): Kysely<Schema>;
+export type D1PlumbingDb = Kysely<PlumbingSchema>;

package/dist/server/d1/kysely.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler, } from 'kysely';
+import { refuseInteractiveTransaction } from './local';
+import { 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, db, parameters) => {
+    const stmt = db.prepare(sql);
+    return parameters.length > 0 ? stmt.bind(...parameters) : 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) {
+    const node = query;
+    if (node.kind === 'SelectQueryNode' || node.kind === 'RawNode')
+        return true;
+    return node.returning !== undefined;
+}
+class D1LikeConnection {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async executeQuery(compiled) {
+        const stmt = bindParams(compiled.sql, this.db, compiled.parameters);
+        if (isRowReturning(compiled.query)) {
+            const res = await stmt.all();
+            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() {
+        throw new D1UnsupportedError('streaming a result set', 'D1 returns a whole result set — page with LIMIT/OFFSET, or a keyset cursor');
+    }
+}
+class D1LikeDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() { }
+    async acquireConnection() {
+        // 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() {
+        refuseInteractiveTransaction();
+    }
+    async commitTransaction() {
+        refuseInteractiveTransaction();
+    }
+    async rollbackTransaction() {
+        refuseInteractiveTransaction();
+    }
+    async releaseConnection() { }
+    async destroy() { }
+}
+/** The dialect itself — SQLite's adapter, compiler and introspector over our driver. */
+export class D1LikeDialect {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    createAdapter() {
+        return new SqliteAdapter();
+    }
+    createDriver() {
+        return new D1LikeDriver(this.db);
+    }
+    createQueryCompiler() {
+        return new SqliteQueryCompiler();
+    }
+    createIntrospector(db) {
+        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(db) {
+    return new Kysely({ dialect: new D1LikeDialect(db) });
+}

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

@@ -0,0 +1,56 @@
+/**
+ * D1's hard limits, and the helpers that keep a query inside them.
+ *
+ * 🔴 **These shape the schema, not just the bill.** Three of them change how code must be
+ * written, and all three are invisible on `bun:sqlite` — which has no such caps, so every
+ * one of them is a green-here / red-there defect waiting for the first real dataset:
+ *
+ *   · **1,000 queries per Worker invocation.** An N+1 loop over `family`'s 489 people
+ *     exceeds it. Join, or `batch()`; do not loop.
+ *   · **100 bound parameters per query.** Any seed, import or bulk insert hits this. Use
+ *     {@link chunkForBind}, which does the arithmetic rather than leaving it to a guess.
+ *   · **2 MB per string / BLOB / row.** Nothing may store a media byte in D1.
+ *
+ * The limits are asserted by the LOCAL driver as well as the remote one, which is the
+ * whole point: a bulk insert that would fail in production fails on the laptop, at the
+ * call site, with the chunk size it should have used in the message.
+ *
+ * Values are the Workers **Paid** tier, which is what the owner already pays for.
+ */
+import { type D1LikeBindable } from './types';
+export declare const LIMITS: {
+    /** Bound parameters in a single statement. */
+    readonly boundParams: 100;
+    /** Queries a single Worker invocation may issue, including every `batch()` member. */
+    readonly queriesPerInvocation: 1000;
+    /** Bytes of SQL text in one statement. A generated `IN (…)` list hits this first. */
+    readonly sqlLength: 100000;
+    /** Bytes in any single string or BLOB value, and in any single row. */
+    readonly valueBytes: 2000000;
+    /** Columns in one table. The fleet's `data JSON` pattern stays far under it. */
+    readonly columnsPerTable: 100;
+    /** Wall-clock milliseconds one query may take. */
+    readonly queryDurationMs: 30000;
+};
+/**
+ * Refuse a statement that D1 would refuse — checked on BOTH drivers, at `bind()` time, so
+ * the failure lands on the call site that built the query rather than in production.
+ */
+export declare function assertWithinLimits(sql: string, params: readonly D1LikeBindable[]): void;
+/** Refuse a `batch()` bigger than one Worker invocation may issue. */
+export declare function assertBatchSize(count: number): void;
+/**
+ * Split a list into chunks that fit under the 100-parameter cap, given how many bound
+ * parameters each item contributes.
+ *
+ * A bulk insert of `n` rows with `c` columns binds `n * c` parameters, so the batch size
+ * is `floor(100 / c)` — the arithmetic nobody does correctly by eye at 3 a.m., which is
+ * why it is a function and not a sentence in a doc.
+ *
+ * ```ts
+ * for (const rows of chunkForBind(people, 4)) {           // 4 columns → 25 rows a chunk
+ *   await db.prepare(insertSql(rows.length)).bind(...rows.flatMap(toParams)).run();
+ * }
+ * ```
+ */
+export declare function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[][];