cursedbelt-server 4.16.0 → 4.17.0

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.16.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/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();
+	}
+}