cursedbelt-server 4.6.0 → 4.7.0

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

@@ -1,19 +1,23 @@
 /**
  * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
  *
- * ## 🔴 BOTH, not one
+ * ## 🔴 BOTH, not one — but only one of them is in this file
  *
  * 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.
+ * checkpoint goes away". It does not: 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.
  *
- * 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 local half lives in `./localBackup` (`cursedbelt-server/d1/backup-local`), and
+ * that split is load-bearing.** It reaches `bun:sqlite` through `../sqlite/backup`, and
+ * `wrangler`'s esbuild resolves imports statically, so while it was re-exported from the
+ * `./d1` barrel no Worker could import the seam at all — measured 2026-09-18, the first
+ * real Worker deploy in this fleet died on `Could not resolve "bun:sqlite"`. This file
+ * therefore holds the interface and the remote implementation ONLY, and everything in it
+ * must stay importable on a Worker. `../../barrelsReachNoOptionalPeer.spec.ts` is what
+ * keeps it that way.
  *
  * ## The remote side does not "take" a backup, and that is not a gap
  *
@@ -29,7 +33,6 @@
  * the same split as the binary server, where the bytes and the thing that copies them are
  * deliberately not the same process.
  */
-import type { Database } from 'bun:sqlite';
 /** A restore coordinate — a file on this Mac, or a point in D1's retention window. */
 export interface BackupPoint {
     kind: 'file' | 'time-travel';
@@ -49,44 +52,6 @@ export interface DatabaseBackup {
     /** Whether this side needs a periodic capture at all. Time Travel does not. */
     readonly needsPeriodicCapture: boolean;
 }
-export interface LocalBackupOpts {
-    /** The live handle — checkpointed before the snapshot is taken. */
-    db: Database;
-    /** Path of the database file being backed up. */
-    sourcePath: string;
-    /** Directory the snapshot is written into. Created if missing. */
-    destDir: string;
-    /** Override the snapshot's file name. Defaults to `<name>-<ISO>.sqlite`. */
-    nameFor?: (now: Date) => string;
-}
-/**
- * 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 declare function checkpointWal(db: Database): {
-    busy: boolean;
-    logPages: number;
-    checkpointed: number;
-};
-/**
- * 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 declare function createLocalBackup(opts: LocalBackupOpts): DatabaseBackup;
 export interface TimeTravelOpts {
     /** The database name as `wrangler` knows it — what the restore command needs. */
     databaseName: string;
@@ -103,8 +68,3 @@ export interface TimeTravelOpts {
  * is worse than no job, because it reads as evidence.
  */
 export declare function createTimeTravelBackup(opts: TimeTravelOpts): DatabaseBackup;
-/**
- * Pick the backup implementation from the driver flavor, so an app's job definition reads
- * the same on both sides.
- */
-export declare function backupFor(flavor: 'local' | 'd1', local: () => LocalBackupOpts, remote: () => TimeTravelOpts): DatabaseBackup;

package/dist/server/d1/backup.js

@@ -1,19 +1,23 @@
 /**
  * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
  *
- * ## 🔴 BOTH, not one
+ * ## 🔴 BOTH, not one — but only one of them is in this file
  *
  * 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.
+ * checkpoint goes away". It does not: 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 local half lives in `./localBackup` (`cursedbelt-server/d1/backup-local`), and
+ * that split is load-bearing.** It reaches `bun:sqlite` through `../sqlite/backup`, and
+ * `wrangler`'s esbuild resolves imports statically, so while it was re-exported from the
+ * `./d1` barrel no Worker could import the seam at all — measured 2026-09-18, the first
+ * real Worker deploy in this fleet died on `Could not resolve "bun:sqlite"`. This file
+ * therefore holds the interface and the remote implementation ONLY, and everything in it
+ * must stay importable on a Worker. `../../barrelsReachNoOptionalPeer.spec.ts` is what
+ * keeps it that way.
  *
  * ## The remote side does not "take" a backup, and that is not a gap
  *
@@ -29,69 +33,6 @@
  * 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.
  *
@@ -119,10 +60,3 @@ export function createTimeTravelBackup(opts) {
         },
     };
 }
-/**
- * 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/index.d.ts

@@ -14,7 +14,7 @@
  * const ky  = createD1Kysely(db);
  * ```
  */
-export { backupFor, type BackupPoint, checkpointWal, createLocalBackup, createTimeTravelBackup, type DatabaseBackup, type LocalBackupOpts, type TimeTravelOpts, } from './backup';
+export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup';
 export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';

package/dist/server/d1/index.js

@@ -14,7 +14,18 @@
  * const ky  = createD1Kysely(db);
  * ```
  */
-export { backupFor, checkpointWal, createLocalBackup, createTimeTravelBackup, } from './backup';
+export { createTimeTravelBackup, } from './backup';
+// 🔴 `./localBackup` is deliberately NOT re-exported here — import `checkpointWal`,
+// `createLocalBackup`, `LocalBackupOpts` and `backupFor` from
+// `cursedbelt-server/d1/backup-local`. It reaches `bun:sqlite` for real (via
+// `../sqlite/backup`'s `snapshotSqlite`), and `wrangler` bundles with esbuild, which
+// resolves imports STATICALLY — so while it was re-exported here, `wrangler deploy` died
+// with `Could not resolve "bun:sqlite"` naming `dist/server/sqlite/backup.js`, and the
+// seam written FOR Workers was the one thing that could not load on one. Measured
+// 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`). Same class
+// as the note below, one step wider: a barrel must reach neither an optional peer nor a
+// runtime the target platform lacks. `barrelsReachNoOptionalPeer.spec.ts` checks both.
+//
 // 🔴 `./kysely` is deliberately NOT re-exported here — import it from
 // `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
 // `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it

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

@@ -0,0 +1,84 @@
+/**
+ * `cursedbelt-server/d1/backup-local` — the Mac-hosted half of the backup seam:
+ * `PRAGMA wal_checkpoint(TRUNCATE)`, then `VACUUM INTO` a fresh file.
+ *
+ * ## 🔴 Why this is a subpath and not part of `./d1`
+ *
+ * It reaches `bun:sqlite` for real, through `../sqlite/backup`'s {@link snapshotSqlite}.
+ * `wrangler deploy` bundles with esbuild, which resolves imports STATICALLY — so a Worker
+ * that imported `cursedbelt-server/d1` for `createRemoteD1` paid for this file too and the
+ * deploy failed outright:
+ *
+ *     ✘ [ERROR] Could not resolve "bun:sqlite"
+ *         node_modules/cursedbelt-server/dist/server/sqlite/backup.js:1:25
+ *
+ * Measured 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`). The
+ * error names the leaf rather than the barrel that dragged it in, which is why the first
+ * five minutes went into the wrong file. It is the same defect as `./d1/kysely` one class
+ * wider: there, the barrel reached an optional PEER; here, it reached a runtime the target
+ * platform does not have. `../../barrelsReachNoOptionalPeer.spec.ts` now checks both.
+ *
+ * The remote half — {@link createTimeTravelBackup}, {@link BackupPoint},
+ * {@link DatabaseBackup} — stays in `./backup` and stays in the barrel, because a Worker
+ * needs it and it reaches nothing.
+ *
+ * ## The checkpoint is load-bearing, and stays
+ *
+ * D1 has no WAL a caller can checkpoint, so it is tempting to read the port 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 `../sqlite/backup.ts` is safe.
+ */
+import type { Database } from 'bun:sqlite';
+import type { DatabaseBackup, TimeTravelOpts } from './backup';
+export interface LocalBackupOpts {
+    /** The live handle — checkpointed before the snapshot is taken. */
+    db: Database;
+    /** Path of the database file being backed up. */
+    sourcePath: string;
+    /** Directory the snapshot is written into. Created if missing. */
+    destDir: string;
+    /** Override the snapshot's file name. Defaults to `<name>-<ISO>.sqlite`. */
+    nameFor?: (now: Date) => string;
+}
+/**
+ * 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 declare function checkpointWal(db: Database): {
+    busy: boolean;
+    logPages: number;
+    checkpointed: number;
+};
+/**
+ * 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 declare function createLocalBackup(opts: LocalBackupOpts): DatabaseBackup;
+/**
+ * Pick the backup implementation from the driver flavor, so an app's job definition reads
+ * the same on both sides.
+ *
+ * 🔴 This lives here rather than in `./backup` because it CONSTRUCTS the local one, and a
+ * construction is a value import: a `backupFor` in the barrel would drag `bun:sqlite` back
+ * in for every Worker. A Worker never needs it — its flavor is always `'d1'`, so it calls
+ * {@link createTimeTravelBackup} from `cursedbelt-server/d1` directly. This is the seam for
+ * a host that genuinely has both.
+ */
+export declare function backupFor(flavor: 'local' | 'd1', local: () => LocalBackupOpts, remote: () => TimeTravelOpts): DatabaseBackup;

package/dist/server/d1/localBackup.js

@@ -0,0 +1,110 @@
+/**
+ * `cursedbelt-server/d1/backup-local` — the Mac-hosted half of the backup seam:
+ * `PRAGMA wal_checkpoint(TRUNCATE)`, then `VACUUM INTO` a fresh file.
+ *
+ * ## 🔴 Why this is a subpath and not part of `./d1`
+ *
+ * It reaches `bun:sqlite` for real, through `../sqlite/backup`'s {@link snapshotSqlite}.
+ * `wrangler deploy` bundles with esbuild, which resolves imports STATICALLY — so a Worker
+ * that imported `cursedbelt-server/d1` for `createRemoteD1` paid for this file too and the
+ * deploy failed outright:
+ *
+ *     ✘ [ERROR] Could not resolve "bun:sqlite"
+ *         node_modules/cursedbelt-server/dist/server/sqlite/backup.js:1:25
+ *
+ * Measured 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`). The
+ * error names the leaf rather than the barrel that dragged it in, which is why the first
+ * five minutes went into the wrong file. It is the same defect as `./d1/kysely` one class
+ * wider: there, the barrel reached an optional PEER; here, it reached a runtime the target
+ * platform does not have. `../../barrelsReachNoOptionalPeer.spec.ts` now checks both.
+ *
+ * The remote half — {@link createTimeTravelBackup}, {@link BackupPoint},
+ * {@link DatabaseBackup} — stays in `./backup` and stays in the barrel, because a Worker
+ * needs it and it reaches nothing.
+ *
+ * ## The checkpoint is load-bearing, and stays
+ *
+ * D1 has no WAL a caller can checkpoint, so it is tempting to read the port 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 `../sqlite/backup.ts` is safe.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { snapshotSqlite } from '../sqlite/backup';
+import { createTimeTravelBackup } from './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,
+            };
+        },
+    };
+}
+/**
+ * Pick the backup implementation from the driver flavor, so an app's job definition reads
+ * the same on both sides.
+ *
+ * 🔴 This lives here rather than in `./backup` because it CONSTRUCTS the local one, and a
+ * construction is a value import: a `backupFor` in the barrel would drag `bun:sqlite` back
+ * in for every Worker. A Worker never needs it — its flavor is always `'d1'`, so it calls
+ * {@link createTimeTravelBackup} from `cursedbelt-server/d1` directly. This is the seam for
+ * a host that genuinely has both.
+ */
+export function backupFor(flavor, local, remote) {
+    return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.6.0",
+	"version": "4.7.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -84,6 +84,12 @@
 			"source": "./src/server/d1/index.ts",
 			"import": "./dist/server/d1/index.js"
 		},
+		"./d1/backup-local": {
+			"types": "./dist/server/d1/localBackup.d.ts",
+			"bun": "./src/server/d1/localBackup.ts",
+			"source": "./src/server/d1/localBackup.ts",
+			"import": "./dist/server/d1/localBackup.js"
+		},
 		"./d1/kysely": {
 			"types": "./dist/server/d1/kysely.d.ts",
 			"bun": "./src/server/d1/kysely.ts",

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -4,8 +4,10 @@ import { fileURLToPath } from 'node:url';
 import pkg from '../package.json';
 
 /**
- * A public subpath must not STATICALLY drag an OPTIONAL peer, because a static import is
- * paid at import time by every consumer — including the ones that will never call it.
+ * A public subpath must not STATICALLY drag anything its consumers cannot have — an
+ * OPTIONAL PEER they have not installed, or a BUN BUILTIN their runtime does not provide.
+ * A static import is paid at import time (or at bundle time) by every consumer, including
+ * the ones that will never call it.
  *
  * ## 🔴 This is the same defect for the THIRD time, and the first two are why the rule is
  * a check rather than a sentence
@@ -39,13 +41,45 @@ import pkg from '../package.json';
  * The fix was to give `createD1Kysely` its own subpath (`./d1/kysely`) and take it out of
  * the barrel. This spec is what stops the fourth occurrence.
  *
+ * ## 🔴 And the FOURTH, which was the same class one step wider
+ *
+ * Measured 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`),
+ * hours after the `./d1/kysely` split above:
+ *
+ *     ✘ [ERROR] Could not resolve "bun:sqlite"
+ *         node_modules/cursedbelt-server/dist/server/sqlite/backup.js:1:25
+ *
+ * `wrangler deploy` failed outright. `./d1`'s index re-exported `./backup`, whose local
+ * half imported `snapshotSqlite` from `../sqlite/backup`, which imports `Database` from
+ * `bun:sqlite` — so the seam written FOR Workers was the one thing that could not load on
+ * one. esbuild resolves imports statically, so it did not matter that a Worker never calls
+ * it, and the error named the library's leaf rather than the barrel that dragged it in.
+ *
+ * `kysely` and `bun:sqlite` are the same defect with different missing things: a public
+ * subpath may not statically reach what its consumers do not have. An optional peer is
+ * absent because nobody installed it; a bun builtin is absent because `workerd` is not Bun
+ * and never will be. Neither can be fixed by the consumer, and both fail at import/bundle
+ * time rather than at the call that needed them. So both are checked here, off the same
+ * bundle, against the same shape of allowlist. The fix was to give the local half its own
+ * subpath (`./d1/backup-local`) and take it out of the barrel — exactly the `./d1/kysely`
+ * move, a second time.
+ *
  * ## What it measures
  *
  * Every subpath in the `exports` map is bundled with bare imports left external, and the
- * remaining static specifiers are read out of the emitted JS. A DYNAMIC `await
+ * remaining static specifiers are read out of the emitted JS — bare ones checked against
+ * {@link MAY_DRAG}, `bun:*` ones against {@link MAY_NEED_BUN}. A DYNAMIC `await
  * import('sharp')` inside the function that needs it matches neither branch of
  * {@link STATIC_SPECIFIER} and must not — that is the lazy shape this file exists to
- * permit, not forbid.
+ * permit, not forbid. A TYPE-ONLY `import type { Database } from 'bun:sqlite'` is erased
+ * by the bundler and so does not count either, which is correct and is why `./d1/testing`
+ * and `./d1` itself pass while holding that exact line.
+ *
+ * `bun:*` is the whole bun-builtin class, not just `bun:sqlite` — `bun:ffi`, `bun:jsc` and
+ * `bun:test` are equally absent on a Worker. `node:*` is deliberately NOT checked: Workers
+ * provide a growing subset of it under `nodejs_compat`, so which members are absent depends
+ * on the consumer's compatibility date, and a check whose verdict moves with somebody
+ * else's config is a check that will be deleted the first time it is wrong.
  *
  * ## Verified failing before it was trusted (2026-09-18)
  *
@@ -56,6 +90,11 @@ import pkg from '../package.json';
  *       → red identically. That is the branch that matters.
  *   · removing `'./jobs'` from {@link MAY_DRAG} → red, proving the allowlist is load-bearing
  *     rather than decorative.
+ *   · re-adding `export { createLocalBackup } from './localBackup'` to
+ *     `src/server/d1/index.ts` — the deploy failure above, reproduced
+ *       → red: "./d1 statically reaches bun builtin(s): bun:sqlite"
+ *   · removing `'./sqlite'` from {@link MAY_NEED_BUN} → red, same proof for the second
+ *     allowlist.
  */
 
 const REPO = fileURLToPath(new URL('..', import.meta.url));
@@ -82,6 +121,31 @@ const MAY_DRAG: Record<string, readonly string[]> = {
 	'./jobs': ['plainjob'],
 };
 
+/**
+ * The subpaths whose whole PURPOSE is a bun-specific runtime, mapped to the builtins they
+ * are allowed to reach. Everything NOT listed here must be importable on `workerd`, which
+ * is the property the D1 seam exists to deliver.
+ *
+ * 🔴 Measured 2026-09-18 after the `./d1/backup-local` split: these five are the ONLY
+ * subpaths in the map that reach a bun builtin at all. Like {@link MAY_DRAG} it is an
+ * allowlist, not a baseline — it can only shrink, and an entry that stops being true is a
+ * failure rather than a tidy-up.
+ */
+const MAY_NEED_BUN: Record<string, readonly string[]> = {
+	// The whole-package barrel — it re-exports everything, including the Mac-hosted halves.
+	// An app importing `cursedbelt-server` whole is a Bun server by construction; an app
+	// importing `cursedbelt-server/d1` is not, and that is the distinction this protects.
+	'.': ['bun:sqlite'],
+	// The local backup IS `VACUUM INTO` against a live `bun:sqlite` handle. Split out of
+	// `./d1` on 2026-09-18 precisely so the seam itself stops paying for it — see the header.
+	'./d1/backup-local': ['bun:sqlite'],
+	// The guard's revocation store is a `bun:sqlite` table, and `./guard` mounts it.
+	'./guard': ['bun:sqlite'],
+	'./guard/revocations': ['bun:sqlite'],
+	// `./sqlite` is the bun:sqlite tier. Naming it is the point of the subpath.
+	'./sqlite': ['bun:sqlite'],
+};
+
 const OPTIONAL_PEERS = new Set(
 	Object.entries(
 		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},
@@ -107,13 +171,14 @@ const packageOf = (specifier: string): string | undefined => {
 };
 
 /**
- * Bundle one entry and return the bare packages it still imports.
+ * Bundle one entry and return what it still statically imports, split into the two classes
+ * a consumer can be missing: bare `packages`, and `bun` builtins.
  *
  * 🔴 A bundle that did not happen must never read as a subpath that pulls nothing, so a
  * non-zero exit or an empty bundle THROWS rather than returning an empty set. That is the
  * one way a check like this dies quietly.
  */
-const staticExternalsOf = (entry: string, subpath: string): Set<string> => {
+const scan = (entry: string, subpath: string): { packages: Set<string>; bun: Set<string> } => {
 	const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-server-barrel-scan/${subpath.replace(/[^a-z0-9]+/gi, '-')}`;
 	const build = Bun.spawnSync(['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir], {
 		cwd: REPO,
@@ -127,14 +192,35 @@ const staticExternalsOf = (entry: string, subpath: string): Set<string> => {
 			`could not bundle ${subpath} (${entry}, exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
 		);
 	}
-	const found = new Set<string>();
+	const packages = new Set<string>();
+	const bun = new Set<string>();
 	for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
 		const specifier = match[1] ?? match[2];
-		if (specifier === undefined || specifier.startsWith('.') || specifier.startsWith('bun:')) continue;
+		if (specifier === undefined || specifier.startsWith('.')) continue;
+		// `bun:*` is a builtin, not a package — `workerd` has none of them, and no consumer
+		// can install one. `node:*` falls through to `packageOf` and is simply never an
+		// optional peer, so it lands in neither verdict; the header says why.
+		if (specifier.startsWith('bun:')) {
+			bun.add(specifier);
+			continue;
+		}
 		const name = packageOf(specifier);
-		if (name !== undefined) found.add(name);
+		if (name !== undefined) packages.add(name);
 	}
-	return found;
+	return { packages, bun };
+};
+
+/**
+ * One bundle per subpath, shared by both assertions. Bundling is the expensive part of this
+ * file and the answer cannot change between two `it`s in the same run.
+ */
+const scans = new Map<string, { packages: Set<string>; bun: Set<string> }>();
+const scanOnce = (entry: string, subpath: string): { packages: Set<string>; bun: Set<string> } => {
+	const cached = scans.get(subpath);
+	if (cached !== undefined) return cached;
+	const fresh = scan(entry, subpath);
+	scans.set(subpath, fresh);
+	return fresh;
 };
 
 /** Every subpath with a `source` entry — the ones whose real graph can be measured. */
@@ -142,7 +228,7 @@ const SUBPATHS = Object.entries(pkg.exports as Record<string, { source?: string
 	.filter(([, e]) => typeof e?.source === 'string' && /\.tsx?$/.test(e.source))
 	.map(([subpath, e]) => ({ subpath, entry: (e as { source: string }).source }));
 
-describe('no public subpath statically drags an optional peer', () => {
+describe('no public subpath statically reaches what its consumers may not have', () => {
 	it('measures a non-trivial number of subpaths, so a broken exports map cannot pass vacuously', () => {
 		expect(SUBPATHS.length).toBeGreaterThan(20);
 		expect(OPTIONAL_PEERS.size).toBeGreaterThan(0);
@@ -151,7 +237,7 @@ describe('no public subpath statically drags an optional peer', () => {
 	for (const { subpath, entry } of SUBPATHS) {
 		const allowed = MAY_DRAG[subpath] ?? [];
 		it(`${subpath} drags ${allowed.length === 0 ? 'no optional peer' : allowed.join(' + ') + ' and nothing more'}`, () => {
-			const dragged = [...staticExternalsOf(entry, subpath)].filter((n) => OPTIONAL_PEERS.has(n)).sort();
+			const dragged = [...scanOnce(entry, subpath).packages].filter((n) => OPTIONAL_PEERS.has(n)).sort();
 			const unexpected = dragged.filter((n) => !allowed.includes(n));
 			expect(
 				unexpected,
@@ -170,4 +256,31 @@ describe('no public subpath statically drags an optional peer', () => {
 			);
 		});
 	}
+
+	for (const { subpath, entry } of SUBPATHS) {
+		const allowed = MAY_NEED_BUN[subpath] ?? [];
+		it(`${subpath} ${allowed.length === 0 ? 'loads on a Worker — no bun builtin' : `needs ${allowed.join(' + ')} and nothing more`}`, () => {
+			const reached = [...scanOnce(entry, subpath).bun].sort();
+			const unexpected = reached.filter((n) => !allowed.includes(n));
+			expect(
+				unexpected,
+				`${subpath} statically reaches bun builtin(s): ${unexpected.join(', ')}\n` +
+					`  '${pkg.name}${subpath.slice(1)}' can no longer be imported on Cloudflare Workers — wrangler\n` +
+					`  bundles with esbuild, which resolves imports STATICALLY, so 'wrangler deploy' fails with\n` +
+					`  \`Could not resolve "${unexpected[0] ?? 'bun:sqlite'}"\` naming the leaf rather than this barrel.\n` +
+					`  Nothing needs to CALL it. Measured 2026-09-18 on apps/patterns: the ./d1 seam written for\n` +
+					`  Workers was itself unloadable on one. Give the bun-specific half its own subpath — see\n` +
+					`  ./d1/backup-local, which is exactly this fix — or make the import \`import type\`, which the\n` +
+					`  bundler erases.`,
+			).toEqual([]);
+
+			// Same one-way ratchet as above: an allowed subpath that no longer reaches what it
+			// promised is a stale exception, and this list may only shrink.
+			const stale = allowed.filter((n) => !reached.includes(n));
+			expect(
+				stale,
+				`${subpath} is allowed to reach ${stale.join(', ')} but no longer does — remove the exception`,
+			).toEqual([]);
+		});
+	}
 });

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

@@ -3,7 +3,10 @@ import { afterEach, describe, expect, test } from 'bun:test';
 import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { backupFor, checkpointWal, createLocalBackup, createTimeTravelBackup } from './backup';
+import { createTimeTravelBackup } from './backup';
+// The local half is a separate module on purpose — it reaches `bun:sqlite`, so it may not
+// sit in the `./d1` barrel a Worker imports. See `./localBackup.ts`'s header.
+import { backupFor, checkpointWal, createLocalBackup } from './localBackup';
 
 const dirs: string[] = [];
 const scratch = (): string => {

package/src/server/d1/backup.ts

@@ -1,19 +1,23 @@
 /**
  * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
  *
- * ## 🔴 BOTH, not one
+ * ## 🔴 BOTH, not one — but only one of them is in this file
  *
  * 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.
+ * checkpoint goes away". It does not: 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.
  *
- * 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 local half lives in `./localBackup` (`cursedbelt-server/d1/backup-local`), and
+ * that split is load-bearing.** It reaches `bun:sqlite` through `../sqlite/backup`, and
+ * `wrangler`'s esbuild resolves imports statically, so while it was re-exported from the
+ * `./d1` barrel no Worker could import the seam at all — measured 2026-09-18, the first
+ * real Worker deploy in this fleet died on `Could not resolve "bun:sqlite"`. This file
+ * therefore holds the interface and the remote implementation ONLY, and everything in it
+ * must stay importable on a Worker. `../../barrelsReachNoOptionalPeer.spec.ts` is what
+ * keeps it that way.
  *
  * ## The remote side does not "take" a backup, and that is not a gap
  *
@@ -30,11 +34,6 @@
  * deliberately not the same process.
  */
 
-import type { Database } from 'bun:sqlite';
-import { existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { snapshotSqlite } from '../sqlite/backup';
-
 /** A restore coordinate — a file on this Mac, or a point in D1's retention window. */
 export interface BackupPoint {
 	kind: 'file' | 'time-travel';
@@ -56,85 +55,6 @@ export interface DatabaseBackup {
 	readonly needsPeriodicCapture: boolean;
 }
 
-export interface LocalBackupOpts {
-	/** The live handle — checkpointed before the snapshot is taken. */
-	db: Database;
-	/** Path of the database file being backed up. */
-	sourcePath: string;
-	/** Directory the snapshot is written into. Created if missing. */
-	destDir: string;
-	/** Override the snapshot's file name. Defaults to `<name>-<ISO>.sqlite`. */
-	nameFor?: (now: Date) => string;
-}
-
-/**
- * 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: Database): { busy: boolean; logPages: number; checkpointed: number } {
-	// One row: (busy, log, checkpointed). See the note above on what they mean here.
-	const row = db.query('PRAGMA wal_checkpoint(TRUNCATE)').get() as
-		| { busy?: number; log?: number; checkpointed?: number }
-		| null;
-	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: LocalBackupOpts): DatabaseBackup {
-	return {
-		needsPeriodicCapture: true,
-
-		async capture(): Promise<BackupPoint> {
-			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,
-			};
-		},
-	};
-}
-
 export interface TimeTravelOpts {
 	/** The database name as `wrangler` knows it — what the restore command needs. */
 	databaseName: string;
@@ -172,15 +92,3 @@ export function createTimeTravelBackup(opts: TimeTravelOpts): DatabaseBackup {
 		},
 	};
 }
-
-/**
- * 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' | 'd1',
-	local: () => LocalBackupOpts,
-	remote: () => TimeTravelOpts,
-): DatabaseBackup {
-	return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
-}

package/src/server/d1/index.ts

@@ -16,15 +16,22 @@
  */
 
 export {
-	backupFor,
 	type BackupPoint,
-	checkpointWal,
-	createLocalBackup,
 	createTimeTravelBackup,
 	type DatabaseBackup,
-	type LocalBackupOpts,
 	type TimeTravelOpts,
 } from './backup';
+// 🔴 `./localBackup` is deliberately NOT re-exported here — import `checkpointWal`,
+// `createLocalBackup`, `LocalBackupOpts` and `backupFor` from
+// `cursedbelt-server/d1/backup-local`. It reaches `bun:sqlite` for real (via
+// `../sqlite/backup`'s `snapshotSqlite`), and `wrangler` bundles with esbuild, which
+// resolves imports STATICALLY — so while it was re-exported here, `wrangler deploy` died
+// with `Could not resolve "bun:sqlite"` naming `dist/server/sqlite/backup.js`, and the
+// seam written FOR Workers was the one thing that could not load on one. Measured
+// 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`). Same class
+// as the note below, one step wider: a barrel must reach neither an optional peer nor a
+// runtime the target platform lacks. `barrelsReachNoOptionalPeer.spec.ts` checks both.
+//
 // 🔴 `./kysely` is deliberately NOT re-exported here — import it from
 // `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
 // `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it

package/src/server/d1/localBackup.ts

@@ -0,0 +1,137 @@
+/**
+ * `cursedbelt-server/d1/backup-local` — the Mac-hosted half of the backup seam:
+ * `PRAGMA wal_checkpoint(TRUNCATE)`, then `VACUUM INTO` a fresh file.
+ *
+ * ## 🔴 Why this is a subpath and not part of `./d1`
+ *
+ * It reaches `bun:sqlite` for real, through `../sqlite/backup`'s {@link snapshotSqlite}.
+ * `wrangler deploy` bundles with esbuild, which resolves imports STATICALLY — so a Worker
+ * that imported `cursedbelt-server/d1` for `createRemoteD1` paid for this file too and the
+ * deploy failed outright:
+ *
+ *     ✘ [ERROR] Could not resolve "bun:sqlite"
+ *         node_modules/cursedbelt-server/dist/server/sqlite/backup.js:1:25
+ *
+ * Measured 2026-09-18 by the first real Worker deploy in this fleet (`apps/patterns`). The
+ * error names the leaf rather than the barrel that dragged it in, which is why the first
+ * five minutes went into the wrong file. It is the same defect as `./d1/kysely` one class
+ * wider: there, the barrel reached an optional PEER; here, it reached a runtime the target
+ * platform does not have. `../../barrelsReachNoOptionalPeer.spec.ts` now checks both.
+ *
+ * The remote half — {@link createTimeTravelBackup}, {@link BackupPoint},
+ * {@link DatabaseBackup} — stays in `./backup` and stays in the barrel, because a Worker
+ * needs it and it reaches nothing.
+ *
+ * ## The checkpoint is load-bearing, and stays
+ *
+ * D1 has no WAL a caller can checkpoint, so it is tempting to read the port 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 `../sqlite/backup.ts` is safe.
+ */
+
+import type { Database } from 'bun:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { snapshotSqlite } from '../sqlite/backup';
+import type { BackupPoint, DatabaseBackup, TimeTravelOpts } from './backup';
+import { createTimeTravelBackup } from './backup';
+
+export interface LocalBackupOpts {
+	/** The live handle — checkpointed before the snapshot is taken. */
+	db: Database;
+	/** Path of the database file being backed up. */
+	sourcePath: string;
+	/** Directory the snapshot is written into. Created if missing. */
+	destDir: string;
+	/** Override the snapshot's file name. Defaults to `<name>-<ISO>.sqlite`. */
+	nameFor?: (now: Date) => string;
+}
+
+/**
+ * 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: Database): { busy: boolean; logPages: number; checkpointed: number } {
+	// One row: (busy, log, checkpointed). See the note above on what they mean here.
+	const row = db.query('PRAGMA wal_checkpoint(TRUNCATE)').get() as
+		| { busy?: number; log?: number; checkpointed?: number }
+		| null;
+	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: LocalBackupOpts): DatabaseBackup {
+	return {
+		needsPeriodicCapture: true,
+
+		async capture(): Promise<BackupPoint> {
+			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,
+			};
+		},
+	};
+}
+
+/**
+ * Pick the backup implementation from the driver flavor, so an app's job definition reads
+ * the same on both sides.
+ *
+ * 🔴 This lives here rather than in `./backup` because it CONSTRUCTS the local one, and a
+ * construction is a value import: a `backupFor` in the barrel would drag `bun:sqlite` back
+ * in for every Worker. A Worker never needs it — its flavor is always `'d1'`, so it calls
+ * {@link createTimeTravelBackup} from `cursedbelt-server/d1` directly. This is the seam for
+ * a host that genuinely has both.
+ */
+export function backupFor(
+	flavor: 'local' | 'd1',
+	local: () => LocalBackupOpts,
+	remote: () => TimeTravelOpts,
+): DatabaseBackup {
+	return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
+}