cursedbelt-server 4.15.0 → 4.17.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,6 +16,7 @@
  */
 export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup.js';
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.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';

package/dist/server/d1/index.js

@@ -34,6 +34,7 @@ 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 { 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';

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

@@ -82,3 +82,4 @@ export declare function createLocalBackup(opts: LocalBackupOpts): DatabaseBackup
  * a host that genuinely has both.
  */
 export declare function backupFor(flavor: 'local' | 'd1', local: () => LocalBackupOpts, remote: () => TimeTravelOpts): DatabaseBackup;
+export { type BackupSourceChoice, type BackupSourceInput, backupTables, chooseBackupSource, type PullD1Options, pullD1ToSqlite, servedRuntime, type Wrangler, } from './pullD1.js';

package/dist/server/d1/localBackup.js

@@ -108,3 +108,7 @@ export function createLocalBackup(opts) {
 export function backupFor(flavor, local, remote) {
     return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
 }
+// After a Worker cutover the live rows are D1's, and a Mac-hosted backup must pull them down
+// rather than snapshot the frozen file — see `./pullD1.ts`. Here, not in the `./d1` barrel,
+// for the reason this file's header gives: it reaches `bun:sqlite`.
+export { backupTables, chooseBackupSource, pullD1ToSqlite, servedRuntime, } from './pullD1.js';

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

@@ -0,0 +1,90 @@
+/**
+ * After a Worker cutover, the Mac's nightly backup must snapshot the LIVE rows — D1 — and not
+ * the Mac's frozen file. The three pieces of that, which `apps/collections` wrote first
+ * (2026-09-19/22) and `apps/music` needed next, so they live here once:
+ *
+ *  · {@link chooseBackupSource} — which side holds the live rows, asked of the production
+ *    hostname's `/healthz` rather than of a config flag, and REFUSING when it cannot tell;
+ *  · {@link servedRuntime} — that probe;
+ *  · {@link pullD1ToSqlite} — the live database pulled down into a real SQLite file, table by
+ *    table ({@link backupTables}), so the app's existing whole-file snapshot path is unchanged.
+ *
+ * ## 🔴 Why the production hostname and not `cursed.app.runtime`
+ *
+ * An app declares `runtime: "worker"` when it is PORTED, which can be months before a single
+ * row moves. Keying on the marker points the nightly backup at an empty D1 the day the port
+ * lands. `/healthz` publishes `runtime` for exactly this question — ask the hostname who
+ * answered. And an unreadable answer REFUSES: guessing the Mac snapshots a frozen file after
+ * the cutover (a GREEN backup of nothing current — the worst failure a backup has), guessing
+ * D1 snapshots a stale copy while the Mac is live.
+ *
+ * ## 🔴 Why table by table, and through `wrangler`
+ *
+ * `wrangler d1 export` REFUSES a whole database holding a virtual table — *"cannot export
+ * databases with Virtual Tables (fts5)"*, measured on collections' first post-cutover night —
+ * and a per-table export is allowed. `wrangler` rather than the REST API because the export
+ * is typed SQL: the REST API's JSON cannot tell the REAL `5.0` from the INTEGER `5`
+ * (`./http.ts` has the measurement), and a restore must put back what was there.
+ */
+export type BackupSourceChoice = {
+    kind: 'file' | 'd1' | 'refuse';
+    why: string;
+};
+export interface BackupSourceInput {
+    /** `--from-file`: the operator overriding all of this on purpose. */
+    fromFileFlag: boolean;
+    /** `package.json`'s `cursed.app.runtime`. NOT sufficient on its own — see the header. */
+    runtimeMarker: string | undefined;
+    /** What the PRODUCTION hostname's `/healthz` said its `runtime` was; `null` = no usable answer. */
+    servedRuntime: string | null;
+}
+/** Which side a backup must read. Pure, so every branch is testable without a network. */
+export declare function chooseBackupSource(input: BackupSourceInput): BackupSourceChoice;
+/**
+ * What `/healthz` says `runtime` is at `url`, or `null` if no usable answer came back — which
+ * means UNKNOWN and is never conflated with "not the Worker". Three attempts, because one blip
+ * must not cost a night's backup; a short timeout, because a hung fetch leaves launchd with a
+ * job that never exits.
+ */
+export declare function servedRuntime(url: string, { attempts, sleep }?: {
+    attempts?: number | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+}): Promise<string | null>;
+/** One `wrangler` invocation, as {@link pullD1ToSqlite} needs it. Injected so a spec runs none. */
+export type Wrangler = (args: string[]) => {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * The tables a snapshot carries, from D1's own `sqlite_master` rows — every real table, and
+ * none of what cannot or must not be re-inserted: a virtual table and its shadows (`_config`,
+ * `_data`, `_docsize`, `_idx`, `_content` — an inverted index, not rows), `_cf_*`
+ * (Cloudflare's bookkeeping), and every `sqlite_*` table except `sqlite_sequence`, whose
+ * AUTOINCREMENT high-water marks belong in a restore.
+ */
+export declare function backupTables(rows: ReadonlyArray<{
+    name: string;
+    sql: string | null;
+}>): string[];
+export interface PullD1Options {
+    /** The SQLite file to create. */
+    destination: string;
+    /** The D1 database's NAME as `wrangler.jsonc` declares it at the top level. */
+    database: string;
+    /** The whole schema — normally the app's `db/schema.sql`. */
+    schemaSql: string;
+    /** A table that must be listed, or the pull is refused as the wrong database. */
+    requiredTable: string;
+    /** Run after the rows are loaded — where an app REBUILDS its search index (never copied). */
+    afterLoadSql?: string;
+    wrangler: Wrangler;
+}
+/**
+ * Pull the live D1 database into a real SQLite file.
+ *
+ * 🔴 It THROWS rather than returning an empty database. Every layer beneath treats a readable
+ * SQLite file as success, so an export that produced nothing would sail through the
+ * magic-byte check and `integrity_check` and land on the shelf with today's date on it.
+ */
+export declare function pullD1ToSqlite(options: PullD1Options): Promise<void>;

package/dist/server/d1/pullD1.js

@@ -0,0 +1,149 @@
+/**
+ * After a Worker cutover, the Mac's nightly backup must snapshot the LIVE rows — D1 — and not
+ * the Mac's frozen file. The three pieces of that, which `apps/collections` wrote first
+ * (2026-09-19/22) and `apps/music` needed next, so they live here once:
+ *
+ *  · {@link chooseBackupSource} — which side holds the live rows, asked of the production
+ *    hostname's `/healthz` rather than of a config flag, and REFUSING when it cannot tell;
+ *  · {@link servedRuntime} — that probe;
+ *  · {@link pullD1ToSqlite} — the live database pulled down into a real SQLite file, table by
+ *    table ({@link backupTables}), so the app's existing whole-file snapshot path is unchanged.
+ *
+ * ## 🔴 Why the production hostname and not `cursed.app.runtime`
+ *
+ * An app declares `runtime: "worker"` when it is PORTED, which can be months before a single
+ * row moves. Keying on the marker points the nightly backup at an empty D1 the day the port
+ * lands. `/healthz` publishes `runtime` for exactly this question — ask the hostname who
+ * answered. And an unreadable answer REFUSES: guessing the Mac snapshots a frozen file after
+ * the cutover (a GREEN backup of nothing current — the worst failure a backup has), guessing
+ * D1 snapshots a stale copy while the Mac is live.
+ *
+ * ## 🔴 Why table by table, and through `wrangler`
+ *
+ * `wrangler d1 export` REFUSES a whole database holding a virtual table — *"cannot export
+ * databases with Virtual Tables (fts5)"*, measured on collections' first post-cutover night —
+ * and a per-table export is allowed. `wrangler` rather than the REST API because the export
+ * is typed SQL: the REST API's JSON cannot tell the REAL `5.0` from the INTEGER `5`
+ * (`./http.ts` has the measurement), and a restore must put back what was there.
+ */
+import { Database } from 'bun:sqlite';
+import { existsSync, readFileSync } from 'node:fs';
+/** Which side a backup must read. Pure, so every branch is testable without a network. */
+export function chooseBackupSource(input) {
+    if (input.fromFileFlag) {
+        return { kind: 'file', why: "--from-file was given: snapshotting this Mac's sqlite on purpose" };
+    }
+    if (input.runtimeMarker !== 'worker') {
+        return { kind: 'file', why: 'this app does not declare a worker runtime, so the Mac holds the live rows' };
+    }
+    if (input.servedRuntime === null) {
+        return {
+            kind: 'refuse',
+            why: "could not read `runtime` from the production hostname's /healthz, so which side holds the live " +
+                'rows is unknown. Guessing the Mac would snapshot a database that may have been frozen at the ' +
+                'cutover; guessing D1 would snapshot a stale copy while the Mac is still serving. Neither is a ' +
+                'backup. Fix the probe, or run `bun run backup -- --from-file` if you know the Mac is live.',
+        };
+    }
+    if (input.servedRuntime === 'worker') {
+        return { kind: 'd1', why: 'the production hostname is served by the Worker, so the live rows are in D1' };
+    }
+    return {
+        kind: 'file',
+        why: `the production hostname is still served by '${input.servedRuntime}', so the Mac holds the live rows`,
+    };
+}
+/**
+ * What `/healthz` says `runtime` is at `url`, or `null` if no usable answer came back — which
+ * means UNKNOWN and is never conflated with "not the Worker". Three attempts, because one blip
+ * must not cost a night's backup; a short timeout, because a hung fetch leaves launchd with a
+ * job that never exits.
+ */
+export async function servedRuntime(url, { attempts = 3, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            const response = await fetch(`${url.replace(/\/+$/, '')}/healthz`, {
+                signal: AbortSignal.timeout(10_000),
+                headers: { 'cache-control': 'no-cache' },
+            });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            const body = (await response.json());
+            // A body with no `runtime` is not an answer.
+            if (typeof body.runtime === 'string' && body.runtime)
+                return body.runtime;
+            return null;
+        }
+        catch {
+            if (attempt === attempts)
+                return null;
+            await sleep(2000 * attempt);
+        }
+    }
+    return null;
+}
+/**
+ * The tables a snapshot carries, from D1's own `sqlite_master` rows — every real table, and
+ * none of what cannot or must not be re-inserted: a virtual table and its shadows (`_config`,
+ * `_data`, `_docsize`, `_idx`, `_content` — an inverted index, not rows), `_cf_*`
+ * (Cloudflare's bookkeeping), and every `sqlite_*` table except `sqlite_sequence`, whose
+ * AUTOINCREMENT high-water marks belong in a restore.
+ */
+export function backupTables(rows) {
+    const virtual = rows.filter((r) => /^\s*CREATE\s+VIRTUAL\s+TABLE/i.test(r.sql ?? '')).map((r) => r.name);
+    const shadow = new Set(virtual.flatMap((vt) => ['config', 'data', 'docsize', 'idx', 'content'].map((suffix) => `${vt}_${suffix}`)));
+    return rows
+        .map((r) => r.name)
+        .filter((name) => !virtual.includes(name) && !shadow.has(name))
+        .filter((name) => !name.startsWith('_cf_'))
+        .filter((name) => name === 'sqlite_sequence' || !name.startsWith('sqlite_'))
+        .sort();
+}
+/**
+ * Pull the live D1 database into a real SQLite file.
+ *
+ * 🔴 It THROWS rather than returning an empty database. Every layer beneath treats a readable
+ * SQLite file as success, so an export that produced nothing would sail through the
+ * magic-byte check and `integrity_check` and land on the shelf with today's date on it.
+ */
+export async function pullD1ToSqlite(options) {
+    const { destination, database, wrangler } = options;
+    const listed = wrangler([
+        'd1', 'execute', database, '--remote', '--env=', '--json',
+        '--command', "select name, sql from sqlite_master where type = 'table'",
+    ]);
+    if (listed.code !== 0)
+        throw new Error(`could not list D1's tables: ${listed.stderr.trim() || listed.stdout.trim()}`);
+    const json = listed.stdout.slice(listed.stdout.indexOf('['));
+    const rows = JSON.parse(json)[0]?.results ?? [];
+    const tables = backupTables(rows);
+    if (!tables.includes(options.requiredTable)) {
+        throw new Error(`D1 lists no \`${options.requiredTable}\` table (saw: ${rows.map((r) => r.name).join(', ') || 'nothing'})`);
+    }
+    let sql = '';
+    for (const table of tables) {
+        const dump = `${destination}.${table}.sql`;
+        const exported = wrangler(['d1', 'export', database, '--remote', '--env=', '--table', table, '--no-schema', '--output', dump, '-y']);
+        if (exported.code !== 0) {
+            throw new Error(`wrangler d1 export --table ${table} failed: ${exported.stderr.trim() || exported.stdout.trim()}`);
+        }
+        if (!existsSync(dump))
+            throw new Error(`wrangler d1 export --table ${table} reported success and wrote no file at ${dump}`);
+        sql += `${readFileSync(dump, 'utf8')}\n`;
+    }
+    if (!/INSERT INTO/i.test(sql)) {
+        throw new Error('the D1 export contains no rows — refusing to snapshot an empty database as if it were the library');
+    }
+    const db = new Database(destination, { create: true });
+    try {
+        // `exec`, not `run`: each is many statements and `run` would execute only the first,
+        // leaving a file with a schema and no rows that looks perfectly valid.
+        db.exec(options.schemaSql);
+        db.exec(sql);
+        if (options.afterLoadSql)
+            db.exec(options.afterLoadSql);
+    }
+    finally {
+        db.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.15.0",
+	"version": "4.17.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,6 +40,7 @@ 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 { createHttpD1, D1HttpError, type HttpD1Options } from './http.js';
 export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export {

package/src/server/d1/localBackup.ts

@@ -135,3 +135,17 @@ export function backupFor(
 ): DatabaseBackup {
 	return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
 }
+
+// After a Worker cutover the live rows are D1's, and a Mac-hosted backup must pull them down
+// rather than snapshot the frozen file — see `./pullD1.ts`. Here, not in the `./d1` barrel,
+// for the reason this file's header gives: it reaches `bun:sqlite`.
+export {
+	type BackupSourceChoice,
+	type BackupSourceInput,
+	backupTables,
+	chooseBackupSource,
+	type PullD1Options,
+	pullD1ToSqlite,
+	servedRuntime,
+	type Wrangler,
+} from './pullD1.js';

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

@@ -0,0 +1,166 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { backupTables, chooseBackupSource, pullD1ToSqlite, servedRuntime, type Wrangler } from './localBackup.js';
+
+const dirs: string[] = [];
+const scratch = (): string => {
+	const dir = mkdtempSync(join(tmpdir(), 'd1-pull-'));
+	dirs.push(dir);
+	return dir;
+};
+afterEach(() => {
+	for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true });
+});
+
+describe('🔴 chooseBackupSource — the one whose failure looks like a green backup', () => {
+	const WORKER = 'worker';
+
+	test('a ported app whose production hostname is still the Mac reads the MAC file', () => {
+		const choice = chooseBackupSource({ fromFileFlag: false, runtimeMarker: WORKER, servedRuntime: 'bun' });
+		expect(choice.kind).toBe('file');
+		expect(choice.why).toContain("still served by 'bun'");
+	});
+
+	test('once the production hostname answers as the Worker, it pulls D1', () => {
+		expect(chooseBackupSource({ fromFileFlag: false, runtimeMarker: WORKER, servedRuntime: WORKER }).kind).toBe('d1');
+	});
+
+	test('🔴 an unreadable probe REFUSES — it never guesses a side', () => {
+		const choice = chooseBackupSource({ fromFileFlag: false, runtimeMarker: WORKER, servedRuntime: null });
+		expect(choice.kind).toBe('refuse');
+		expect(choice.why).toContain('--from-file');
+	});
+
+	test('an app that never declared a worker runtime never pulls', () => {
+		for (const marker of [undefined, 'bun', '']) {
+			expect(chooseBackupSource({ fromFileFlag: false, runtimeMarker: marker, servedRuntime: null }).kind).toBe('file');
+		}
+	});
+
+	test('--from-file wins over everything, including a live Worker', () => {
+		const choice = chooseBackupSource({ fromFileFlag: true, runtimeMarker: WORKER, servedRuntime: WORKER });
+		expect(choice.kind).toBe('file');
+		expect(choice.why).toContain('on purpose');
+	});
+});
+
+describe('servedRuntime', () => {
+	const serve = (body: unknown, status = 200) =>
+		Bun.serve({ port: 0, fetch: () => Response.json(body, { status }) });
+
+	test('reads `runtime` off /healthz', async () => {
+		const server = serve({ runtime: 'worker' });
+		try {
+			expect(await servedRuntime(`http://127.0.0.1:${server.port}`)).toBe('worker');
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test('🔴 a body with no runtime, or an error, is UNKNOWN — never "not the Worker"', async () => {
+		const bare = serve({ ok: true });
+		const broken = serve({ runtime: 'worker' }, 503);
+		try {
+			const noSleep = { attempts: 2, sleep: async () => undefined };
+			expect(await servedRuntime(`http://127.0.0.1:${bare.port}`, noSleep)).toBeNull();
+			expect(await servedRuntime(`http://127.0.0.1:${broken.port}`, noSleep)).toBeNull();
+		} finally {
+			bare.stop(true);
+			broken.stop(true);
+		}
+	});
+});
+
+describe('pulling D1 down — table by table, because a whole-database export refuses fts5', () => {
+	const MASTER = [
+		{ name: '_cf_KV', sql: 'CREATE TABLE _cf_KV (key TEXT PRIMARY KEY)' },
+		{ name: 'items', sql: 'CREATE TABLE items ( id TEXT PRIMARY KEY )' },
+		{ name: 'items_fts', sql: 'CREATE VIRTUAL TABLE items_fts USING fts5(text)' },
+		{ name: 'items_fts_config', sql: "CREATE TABLE 'items_fts_config'(k PRIMARY KEY, v)" },
+		{ name: 'items_fts_data', sql: "CREATE TABLE 'items_fts_data'(id INTEGER PRIMARY KEY, block BLOB)" },
+		{ name: 'items_fts_docsize', sql: "CREATE TABLE 'items_fts_docsize'(id INTEGER PRIMARY KEY, sz BLOB)" },
+		{ name: 'items_fts_idx', sql: "CREATE TABLE 'items_fts_idx'(segid, term, pgno)" },
+		{ name: 'items_fts_map', sql: 'CREATE TABLE items_fts_map ( rowid INTEGER PRIMARY KEY AUTOINCREMENT )' },
+		{ name: 'meta', sql: 'CREATE TABLE meta ( key TEXT PRIMARY KEY )' },
+		{ name: 'sqlite_sequence', sql: 'CREATE TABLE sqlite_sequence(name,seq)' },
+		{ name: 'sqlite_stat1', sql: 'CREATE TABLE sqlite_stat1(tbl,idx,stat)' },
+	];
+	const SCHEMA = [
+		'CREATE TABLE items (id TEXT PRIMARY KEY, name TEXT NOT NULL DEFAULT "");',
+		'CREATE TABLE items_fts_map (rowid INTEGER PRIMARY KEY AUTOINCREMENT, item_id TEXT, text TEXT);',
+		'CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT);',
+		'CREATE VIRTUAL TABLE items_fts USING fts5(text);',
+	].join('\n');
+	const REBUILD = "INSERT INTO items_fts(items_fts) VALUES('delete-all'); INSERT INTO items_fts(rowid, text) SELECT rowid, text FROM items_fts_map;";
+
+	test('🔴 the virtual table and its shadows stay out, the MAP and the sequence come in', () => {
+		expect(backupTables(MASTER)).toEqual(['items', 'items_fts_map', 'meta', 'sqlite_sequence']);
+	});
+
+	const fake = (rowsFor: (table: string) => string | null): { run: Wrangler; exported: string[]; seen: string[][] } => {
+		const exported: string[] = [];
+		const seen: string[][] = [];
+		const run: Wrangler = (args) => {
+			seen.push(args);
+			if (args[1] === 'execute') return { code: 0, stdout: `noise\n${JSON.stringify([{ results: MASTER }])}`, stderr: '' };
+			const table = args[args.indexOf('--table') + 1] as string;
+			const out = args[args.indexOf('--output') + 1] as string;
+			const rows = rowsFor(table);
+			if (rows === null) return { code: 1, stdout: '', stderr: `✘ export of ${table} failed` };
+			exported.push(table);
+			writeFileSync(out, rows);
+			return { code: 0, stdout: '', stderr: '' };
+		};
+		return { run, exported, seen };
+	};
+	const pull = (dir: string, run: Wrangler) =>
+		pullD1ToSqlite({
+			destination: join(dir, 'pulled.sqlite'),
+			database: 'collections',
+			schemaSql: SCHEMA,
+			requiredTable: 'items',
+			afterLoadSql: REBUILD,
+			wrangler: run,
+		});
+
+	test('a pull is a real, searchable sqlite file built from the schema and the rows, of the named database', async () => {
+		const dir = scratch();
+		const { run, exported, seen } = fake((table) =>
+			table === 'items'
+				? "INSERT INTO items (id, name) VALUES ('itm_1', 'Travels 5388.jpg');"
+				: table === 'items_fts_map'
+					? "INSERT INTO items_fts_map (rowid, item_id, text) VALUES (1, 'itm_1', 'travels 5388');"
+					: '',
+		);
+		await pull(dir, run);
+		expect(exported).toEqual(['items', 'items_fts_map', 'meta', 'sqlite_sequence']);
+		expect(seen.every((args) => args[2] === 'collections')).toBe(true);
+		const db = new Database(join(dir, 'pulled.sqlite'), { readonly: true });
+		const hits = db.query("select count(*) as n from items_fts where items_fts match '5388'").get() as { n: number };
+		db.close();
+		expect(hits.n).toBe(1);
+	});
+
+	test('🔴 a database without the required table is refused as the wrong one', async () => {
+		const dir = scratch();
+		const { run } = fake(() => '');
+		await expect(
+			pullD1ToSqlite({ destination: join(dir, 'x.sqlite'), database: 'x', schemaSql: SCHEMA, requiredTable: 'tracks', wrangler: run }),
+		).rejects.toThrow(/lists no `tracks` table/);
+	});
+
+	test('🔴 one table failing to export THROWS — never a snapshot missing that table', async () => {
+		const dir = scratch();
+		const { run } = fake((table) => (table === 'meta' ? null : "INSERT INTO items (id) VALUES ('x');"));
+		await expect(pull(dir, run)).rejects.toThrow(/--table meta failed/);
+	});
+
+	test('🔴 an export with no rows at all THROWS — never an empty library dated today', async () => {
+		const dir = scratch();
+		const { run } = fake(() => '');
+		await expect(pull(dir, run)).rejects.toThrow(/no rows/);
+	});
+});

package/src/server/d1/pullD1.ts

@@ -0,0 +1,184 @@
+/**
+ * After a Worker cutover, the Mac's nightly backup must snapshot the LIVE rows — D1 — and not
+ * the Mac's frozen file. The three pieces of that, which `apps/collections` wrote first
+ * (2026-09-19/22) and `apps/music` needed next, so they live here once:
+ *
+ *  · {@link chooseBackupSource} — which side holds the live rows, asked of the production
+ *    hostname's `/healthz` rather than of a config flag, and REFUSING when it cannot tell;
+ *  · {@link servedRuntime} — that probe;
+ *  · {@link pullD1ToSqlite} — the live database pulled down into a real SQLite file, table by
+ *    table ({@link backupTables}), so the app's existing whole-file snapshot path is unchanged.
+ *
+ * ## 🔴 Why the production hostname and not `cursed.app.runtime`
+ *
+ * An app declares `runtime: "worker"` when it is PORTED, which can be months before a single
+ * row moves. Keying on the marker points the nightly backup at an empty D1 the day the port
+ * lands. `/healthz` publishes `runtime` for exactly this question — ask the hostname who
+ * answered. And an unreadable answer REFUSES: guessing the Mac snapshots a frozen file after
+ * the cutover (a GREEN backup of nothing current — the worst failure a backup has), guessing
+ * D1 snapshots a stale copy while the Mac is live.
+ *
+ * ## 🔴 Why table by table, and through `wrangler`
+ *
+ * `wrangler d1 export` REFUSES a whole database holding a virtual table — *"cannot export
+ * databases with Virtual Tables (fts5)"*, measured on collections' first post-cutover night —
+ * and a per-table export is allowed. `wrangler` rather than the REST API because the export
+ * is typed SQL: the REST API's JSON cannot tell the REAL `5.0` from the INTEGER `5`
+ * (`./http.ts` has the measurement), and a restore must put back what was there.
+ */
+
+import { Database } from 'bun:sqlite';
+import { existsSync, readFileSync } from 'node:fs';
+
+export type BackupSourceChoice = { kind: 'file' | 'd1' | 'refuse'; why: string };
+
+export interface BackupSourceInput {
+	/** `--from-file`: the operator overriding all of this on purpose. */
+	fromFileFlag: boolean;
+	/** `package.json`'s `cursed.app.runtime`. NOT sufficient on its own — see the header. */
+	runtimeMarker: string | undefined;
+	/** What the PRODUCTION hostname's `/healthz` said its `runtime` was; `null` = no usable answer. */
+	servedRuntime: string | null;
+}
+
+/** Which side a backup must read. Pure, so every branch is testable without a network. */
+export function chooseBackupSource(input: BackupSourceInput): BackupSourceChoice {
+	if (input.fromFileFlag) {
+		return { kind: 'file', why: "--from-file was given: snapshotting this Mac's sqlite on purpose" };
+	}
+	if (input.runtimeMarker !== 'worker') {
+		return { kind: 'file', why: 'this app does not declare a worker runtime, so the Mac holds the live rows' };
+	}
+	if (input.servedRuntime === null) {
+		return {
+			kind: 'refuse',
+			why:
+				"could not read `runtime` from the production hostname's /healthz, so which side holds the live " +
+				'rows is unknown. Guessing the Mac would snapshot a database that may have been frozen at the ' +
+				'cutover; guessing D1 would snapshot a stale copy while the Mac is still serving. Neither is a ' +
+				'backup. Fix the probe, or run `bun run backup -- --from-file` if you know the Mac is live.',
+		};
+	}
+	if (input.servedRuntime === 'worker') {
+		return { kind: 'd1', why: 'the production hostname is served by the Worker, so the live rows are in D1' };
+	}
+	return {
+		kind: 'file',
+		why: `the production hostname is still served by '${input.servedRuntime}', so the Mac holds the live rows`,
+	};
+}
+
+/**
+ * What `/healthz` says `runtime` is at `url`, or `null` if no usable answer came back — which
+ * means UNKNOWN and is never conflated with "not the Worker". Three attempts, because one blip
+ * must not cost a night's backup; a short timeout, because a hung fetch leaves launchd with a
+ * job that never exits.
+ */
+export async function servedRuntime(
+	url: string,
+	{ attempts = 3, sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms)) } = {},
+): Promise<string | null> {
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		try {
+			const response = await fetch(`${url.replace(/\/+$/, '')}/healthz`, {
+				signal: AbortSignal.timeout(10_000),
+				headers: { 'cache-control': 'no-cache' },
+			});
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			const body = (await response.json()) as { runtime?: unknown };
+			// A body with no `runtime` is not an answer.
+			if (typeof body.runtime === 'string' && body.runtime) return body.runtime;
+			return null;
+		} catch {
+			if (attempt === attempts) return null;
+			await sleep(2000 * attempt);
+		}
+	}
+	return null;
+}
+
+/** One `wrangler` invocation, as {@link pullD1ToSqlite} needs it. Injected so a spec runs none. */
+export type Wrangler = (args: string[]) => { code: number; stdout: string; stderr: string };
+
+/**
+ * The tables a snapshot carries, from D1's own `sqlite_master` rows — every real table, and
+ * none of what cannot or must not be re-inserted: a virtual table and its shadows (`_config`,
+ * `_data`, `_docsize`, `_idx`, `_content` — an inverted index, not rows), `_cf_*`
+ * (Cloudflare's bookkeeping), and every `sqlite_*` table except `sqlite_sequence`, whose
+ * AUTOINCREMENT high-water marks belong in a restore.
+ */
+export function backupTables(rows: ReadonlyArray<{ name: string; sql: string | null }>): string[] {
+	const virtual = rows.filter((r) => /^\s*CREATE\s+VIRTUAL\s+TABLE/i.test(r.sql ?? '')).map((r) => r.name);
+	const shadow = new Set(
+		virtual.flatMap((vt) => ['config', 'data', 'docsize', 'idx', 'content'].map((suffix) => `${vt}_${suffix}`)),
+	);
+	return rows
+		.map((r) => r.name)
+		.filter((name) => !virtual.includes(name) && !shadow.has(name))
+		.filter((name) => !name.startsWith('_cf_'))
+		.filter((name) => name === 'sqlite_sequence' || !name.startsWith('sqlite_'))
+		.sort();
+}
+
+export interface PullD1Options {
+	/** The SQLite file to create. */
+	destination: string;
+	/** The D1 database's NAME as `wrangler.jsonc` declares it at the top level. */
+	database: string;
+	/** The whole schema — normally the app's `db/schema.sql`. */
+	schemaSql: string;
+	/** A table that must be listed, or the pull is refused as the wrong database. */
+	requiredTable: string;
+	/** Run after the rows are loaded — where an app REBUILDS its search index (never copied). */
+	afterLoadSql?: string;
+	wrangler: Wrangler;
+}
+
+/**
+ * Pull the live D1 database into a real SQLite file.
+ *
+ * 🔴 It THROWS rather than returning an empty database. Every layer beneath treats a readable
+ * SQLite file as success, so an export that produced nothing would sail through the
+ * magic-byte check and `integrity_check` and land on the shelf with today's date on it.
+ */
+export async function pullD1ToSqlite(options: PullD1Options): Promise<void> {
+	const { destination, database, wrangler } = options;
+	const listed = wrangler([
+		'd1', 'execute', database, '--remote', '--env=', '--json',
+		'--command', "select name, sql from sqlite_master where type = 'table'",
+	]);
+	if (listed.code !== 0) throw new Error(`could not list D1's tables: ${listed.stderr.trim() || listed.stdout.trim()}`);
+	const json = listed.stdout.slice(listed.stdout.indexOf('['));
+	const rows = (JSON.parse(json) as Array<{ results: Array<{ name: string; sql: string | null }> }>)[0]?.results ?? [];
+	const tables = backupTables(rows);
+	if (!tables.includes(options.requiredTable)) {
+		throw new Error(
+			`D1 lists no \`${options.requiredTable}\` table (saw: ${rows.map((r) => r.name).join(', ') || 'nothing'})`,
+		);
+	}
+
+	let sql = '';
+	for (const table of tables) {
+		const dump = `${destination}.${table}.sql`;
+		const exported = wrangler(['d1', 'export', database, '--remote', '--env=', '--table', table, '--no-schema', '--output', dump, '-y']);
+		if (exported.code !== 0) {
+			throw new Error(`wrangler d1 export --table ${table} failed: ${exported.stderr.trim() || exported.stdout.trim()}`);
+		}
+		if (!existsSync(dump)) throw new Error(`wrangler d1 export --table ${table} reported success and wrote no file at ${dump}`);
+		sql += `${readFileSync(dump, 'utf8')}\n`;
+	}
+	if (!/INSERT INTO/i.test(sql)) {
+		throw new Error('the D1 export contains no rows — refusing to snapshot an empty database as if it were the library');
+	}
+
+	const db = new Database(destination, { create: true });
+	try {
+		// `exec`, not `run`: each is many statements and `run` would execute only the first,
+		// leaving a file with a schema and no rows that looks perfectly valid.
+		db.exec(options.schemaSql);
+		db.exec(sql);
+		if (options.afterLoadSql) db.exec(options.afterLoadSql);
+	} finally {
+		db.close();
+	}
+}