cursedbelt-server 1.1.0 → 2.1.0

package/src/server/bench/cpuBudget.ts

@@ -0,0 +1,81 @@
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+import { normalizeRoute } from '../metrics/normalizeRoute';
+import type { CpuBudgetConfig } from './budget';
+import { type CpuClock, processCpuClock } from './cpuClock';
+import { type CpuRecorder, createCpuRecorder } from './recorder';
+
+/**
+ * Per-route CPU attribution, mounted like any other cursedbelt middleware.
+ *
+ * ```ts
+ * const cpu = createCpuRecorder({ clock: processCpuClock(), config: BUDGETS })
+ * app.use('*', cpuBudget({ recorder: cpu }))
+ * ```
+ *
+ * 🔴 **It records CPU, never wall clock.** `requestLogger` beside it records duration,
+ * and duration is the quantity Cloudflare explicitly does not bill. The two numbers
+ * diverge by exactly the amount a handler spends awaiting a subrequest, which on this
+ * fleet is most of it — so a route can be slow and free, or fast and expensive, and only
+ * this middleware can tell you which.
+ *
+ * Like `requestLogger`, it records even when a downstream handler THROWS: the CPU was
+ * spent either way, and an endpoint that is expensive only on its error path is exactly
+ * the sort of thing a budget is supposed to catch. The error is re-thrown unchanged.
+ */
+export interface CpuBudgetOpts {
+  /** The recorder to write through. Provide one so the gate can read its report. */
+  recorder?: CpuRecorder;
+  /** Built into a recorder when `recorder` is omitted. */
+  config?: CpuBudgetConfig;
+  /** Defaults to {@link processCpuClock} — the local PROXY. */
+  clock?: CpuClock;
+  /**
+   * Called after each request with the sample. For shipping the number somewhere (a
+   * telemetry sink, a log line) without coupling this module to a destination.
+   */
+  onSample?: (sample: {
+    method: string;
+    route: string;
+    cpuMs: number;
+    proxy: boolean;
+    status: number;
+  }) => void;
+}
+
+export function cpuBudget(
+  opts: CpuBudgetOpts = {},
+): MiddlewareHandler<CursedbeltEnv> & { recorder: CpuRecorder } {
+  const recorder =
+    opts.recorder ??
+    createCpuRecorder({ clock: opts.clock ?? processCpuClock(), config: opts.config });
+
+  const handler: MiddlewareHandler<CursedbeltEnv> = async (c, next) => {
+    const end = recorder.clock.start();
+    let thrown: unknown;
+    let didThrow = false;
+    try {
+      await next();
+    } catch (err) {
+      thrown = err;
+      didThrow = true;
+    }
+    const cpuMs = end();
+
+    // `normalizeRoute` must run AFTER `next()` — before it, Hono has not matched a route
+    // pattern yet and every request would aggregate under its raw path.
+    const { method, route } = normalizeRoute(c);
+    recorder.record(method, route, cpuMs);
+    opts.onSample?.({
+      method,
+      route,
+      cpuMs,
+      proxy: recorder.clock.proxy,
+      status: didThrow ? 500 : c.res.status,
+    });
+
+    if (didThrow) throw thrown;
+  };
+
+  return Object.assign(handler, { recorder });
+}

package/src/server/bench/cpuClock.ts

@@ -0,0 +1,119 @@
+/**
+ * Where a CPU-millisecond comes from, and how honest it is.
+ *
+ * 🔴 **Every reading carries `proxy`, and it is not decoration.** The task that asked for
+ * this module asked for the label in the same breath as the measurement: *"a local number
+ * that is called a CPU-ms measurement will be quoted as one."* A number printed without
+ * its provenance becomes a fact about Cloudflare's billing the first time somebody pastes
+ * it into a summary.
+ *
+ * Two sources, and they are not interchangeable:
+ *
+ *   · {@link processCpuClock} — `process.cpuUsage()` deltas on Bun/Node. `proxy: true`.
+ *   · {@link workerCpuClock} — a reader the Worker runtime supplies. `proxy: false`.
+ *
+ * There is deliberately no built-in Cloudflare reader here. The isolate does not hand a
+ * handler its own CPU time; `cpuTime` arrives on the trace event a **tail worker** sees.
+ * Inventing an API that does not exist would produce a clock that reads zero for ever and
+ * a gate that can never go red — so the platform passes its reader in, or there is none.
+ */
+
+/** A started measurement. Call it to end the measurement and get CPU-ms. */
+export type CpuSpan = () => number;
+
+export interface CpuClock {
+  /** Human-readable provenance, e.g. `'process.cpuUsage'`. Printed in every report. */
+  readonly source: string;
+  /**
+   * 🔴 True when this number is a PROXY for Worker CPU-ms rather than a reading of it.
+   * The report prints it and {@link CpuBudgetReport} carries it downstream.
+   */
+  readonly proxy: boolean;
+  /** True when the clock can actually measure. A false one records nothing. */
+  readonly available: boolean;
+  start(): CpuSpan;
+}
+
+/**
+ * `process.cpuUsage()` deltas — user + system, converted from µs to ms.
+ *
+ * 🔴 **The delta is PROCESS-WIDE, not per-request.** If two requests are in flight the
+ * reading for each includes the other's CPU, and any background work (a metrics flush, a
+ * GC pause attributed to the interval) lands on whichever handler happened to be open.
+ * That is why {@link runCpuBench} drives its cases SERIALLY — a serial driver is what
+ * makes this proxy sound enough to gate on. Mounted in production it is advisory: useful
+ * for ranking routes, not for a billing claim.
+ */
+export function processCpuClock(): CpuClock {
+  const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+  if (!usable) return unavailableCpuClock('process.cpuUsage (absent)');
+  return {
+    source: 'process.cpuUsage',
+    proxy: true,
+    available: true,
+    start(): CpuSpan {
+      const before = process.cpuUsage();
+      return () => {
+        const d = process.cpuUsage(before);
+        return (d.user + d.system) / 1000;
+      };
+    },
+  };
+}
+
+/**
+ * A clock over a CPU-ms reader the runtime supplies. `proxy: false` — this is the real
+ * quantity Cloudflare bills, so a report built on it may be quoted as one.
+ *
+ * @param readCpuMs Returns monotonically non-decreasing CPU-ms for the current invocation.
+ */
+export function workerCpuClock(readCpuMs: () => number, source = 'worker-runtime'): CpuClock {
+  return {
+    source,
+    proxy: false,
+    available: true,
+    start(): CpuSpan {
+      const before = readCpuMs();
+      return () => Math.max(0, readCpuMs() - before);
+    },
+  };
+}
+
+/**
+ * A clock that cannot measure. Recording through it is a no-op, and the report says so
+ * rather than reporting a confident zero.
+ */
+export function unavailableCpuClock(source = 'unavailable'): CpuClock {
+  return {
+    source,
+    proxy: true,
+    available: false,
+    start: () => () => Number.NaN,
+  };
+}
+
+/**
+ * A deterministic clock for tests: each `start()` consumes the next value in `values`,
+ * repeating the last one once exhausted. Lets the assertion be proven in both directions
+ * without burning real CPU, which is the difference between a test that is fast and
+ * reliable and one that is neither.
+ */
+export function fixedCpuClock(values: number[], source = 'fixed'): CpuClock {
+  if (values.length === 0) throw new Error('fixedCpuClock: needs at least one value');
+  let i = 0;
+  return {
+    source,
+    proxy: true,
+    available: true,
+    start(): CpuSpan {
+      const v = values[Math.min(i, values.length - 1)];
+      i += 1;
+      return () => v;
+    },
+  };
+}
+
+/** `workerCpuClock` when the platform supplied a reader, else the local proxy. */
+export function resolveCpuClock(readCpuMs?: (() => number) | null): CpuClock {
+  return readCpuMs ? workerCpuClock(readCpuMs) : processCpuClock();
+}

package/src/server/bench/index.ts

@@ -0,0 +1,81 @@
+/**
+ * `cursedbelt-server/bench` — per-route CPU attribution for a Hono app, a budget the app
+ * declares, and an assertion that reddens a build when a route outgrows it.
+ *
+ * ## The shape of a use
+ *
+ * ```ts
+ * // routes.budgets.ts — the app declares what each route may cost
+ * export const BUDGETS: CpuBudgetConfig = {
+ *   routes: {
+ *     'GET /api/notes/:id': 4,
+ *     'POST /api/unlock': { exempt: true, reason: 'argon2id KDF — 332 CPU-ms, measured' },
+ *   },
+ * }
+ *
+ * // app.ts
+ * export const cpu = createCpuRecorder({ clock: processCpuClock(), config: BUDGETS })
+ * app.use('*', cpuBudget({ recorder: cpu }))
+ *
+ * // cpuBudget.spec.ts — the gate
+ * const report = await runCpuBench({ app, recorder: cpu, cases: CASES })
+ * assertCpuBudgets(report, { requireDeclared: true })
+ * ```
+ *
+ * ## 🔴 Two things to carry away
+ *
+ * **Wall clock is never billed.** Cloudflare's own pricing page says *"No charge or limit
+ * for duration"*. `requestLogger` records duration; this records CPU; they are different
+ * numbers and only the second one costs money.
+ *
+ * **A local reading is a PROXY.** `process.cpuUsage()` on this Mac is not Worker CPU-ms.
+ * Every report carries `proxy: true` and every formatted report says so, because the
+ * alternative is a number that gets quoted as a billing fact.
+ */
+
+export {
+  type AssertCpuBudgetsOpts,
+  assertCpuBudgets,
+  checkCpuBudgets,
+  type CpuViolation,
+  type CpuViolationKind,
+  formatCpuBudgetReport,
+} from './assert';
+export {
+  type CpuBudgetConfig,
+  type CpuBudgetExemption,
+  type CpuBudgetLimit,
+  DAYS_PER_MONTH,
+  DEFAULT_ROUTE_CPU_BUDGET_MS,
+  deriveCpuBudgetMs,
+  isExemption,
+  monthlyOverageUsd,
+  OWNER_PROJECTED_REQUESTS_PER_DAY,
+  type ResolvedBudget,
+  resolveBudget,
+  type RouteBudget,
+  validateCpuBudgetConfig,
+  WORKERS_PAID_INCLUDED_CPU_MS,
+  WORKERS_PAID_INCLUDED_REQUESTS,
+  WORKERS_PAID_USD_PER_MILLION_CPU_MS,
+  WORKERS_PAID_USD_PER_MILLION_REQUESTS,
+} from './budget';
+export { type CpuBudgetOpts, cpuBudget } from './cpuBudget';
+export {
+  type CpuClock,
+  type CpuSpan,
+  fixedCpuClock,
+  processCpuClock,
+  resolveCpuClock,
+  unavailableCpuClock,
+  workerCpuClock,
+} from './cpuClock';
+export {
+  type CpuBudgetReport,
+  type CpuRecorder,
+  type CpuRecorderOpts,
+  createCpuRecorder,
+  percentile,
+  type RouteCpuStats,
+} from './recorder';
+export { BENCH_ORIGIN, type BenchCase, runCpuBench, type RunCpuBenchOpts } from './runBench';

package/src/server/bench/recorder.ts

@@ -0,0 +1,163 @@
+/**
+ * Per-route CPU samples, and the percentiles read off them.
+ *
+ * 🔴 **p99, not a mean.** A mean over a route that is fast 99 times and 400 ms once
+ * reports ~4 ms and looks healthy. The number that decides whether a route is safe to
+ * make common is its tail, so the mean is reported beside p99 and never instead of it.
+ */
+
+import {
+  type CpuBudgetConfig,
+  type ResolvedBudget,
+  resolveBudget,
+  validateCpuBudgetConfig,
+} from './budget';
+import type { CpuClock } from './cpuClock';
+
+/**
+ * Nearest-rank percentile over an ASCENDING-sorted array: the smallest value at or below
+ * which at least `p`% of samples fall. No interpolation — an interpolated p99 reports a
+ * CPU cost no request ever actually paid, which is the wrong direction to be wrong in
+ * when the number is a ceiling.
+ */
+export function percentile(sortedAsc: readonly number[], p: number): number {
+  if (sortedAsc.length === 0) return Number.NaN;
+  if (p <= 0) return sortedAsc[0];
+  if (p >= 100) return sortedAsc[sortedAsc.length - 1];
+  const rank = Math.ceil((p / 100) * sortedAsc.length);
+  return sortedAsc[Math.min(sortedAsc.length, Math.max(1, rank)) - 1];
+}
+
+export interface RouteCpuStats {
+  method: string;
+  route: string;
+  /** `'GET /api/notes/:id'` — how the route is named in a violation message. */
+  key: string;
+  samples: number;
+  /** Samples actually retained (≤ `samples` once the reservoir is full). */
+  retained: number;
+  mean: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  max: number;
+  /** Total CPU-ms observed across every sample — what the route costs in aggregate. */
+  totalCpuMs: number;
+  /** The ceiling in CPU-ms, or `null` when exempt. */
+  budgetMs: number | null;
+  exemptReason?: string;
+  noticeAboveMs?: number;
+  /** False when no explicit entry matched and the default was applied. */
+  declared: boolean;
+}
+
+export interface CpuBudgetReport {
+  /** Provenance of every number below — e.g. `'process.cpuUsage'`. */
+  source: string;
+  /** 🔴 True ⇒ these are a PROXY for Worker CPU-ms, not a reading of them. */
+  proxy: boolean;
+  /** False ⇒ nothing could be measured; every stat is NaN and nothing may be concluded. */
+  available: boolean;
+  routes: RouteCpuStats[];
+}
+
+export interface CpuRecorderOpts {
+  clock: CpuClock;
+  config?: CpuBudgetConfig;
+  /**
+   * Samples retained per route. Beyond this, reservoir sampling keeps the retained set
+   * representative of the WHOLE run rather than of its first N requests — truncating
+   * would quietly turn a long-lived mount into a measurement of its own warm-up.
+   */
+  maxSamplesPerRoute?: number;
+  /**
+   * Deterministic source of randomness for the reservoir, for tests. Defaults to
+   * `Math.random`.
+   */
+  random?: () => number;
+}
+
+export interface CpuRecorder {
+  readonly clock: CpuClock;
+  readonly config: CpuBudgetConfig;
+  record(method: string, route: string, cpuMs: number): void;
+  report(): CpuBudgetReport;
+  reset(): void;
+}
+
+interface Bucket {
+  method: string;
+  route: string;
+  seen: number;
+  samples: number[];
+  total: number;
+}
+
+export function createCpuRecorder(opts: CpuRecorderOpts): CpuRecorder {
+  const config = opts.config ?? {};
+  validateCpuBudgetConfig(config);
+  const cap = opts.maxSamplesPerRoute ?? 10_000;
+  if (!(cap > 0)) throw new Error('createCpuRecorder: maxSamplesPerRoute must be > 0');
+  const random = opts.random ?? Math.random;
+  let buckets = new Map<string, Bucket>();
+
+  return {
+    clock: opts.clock,
+    config,
+    record(method, route, cpuMs) {
+      // A NaN reading means the clock could not measure. Recording it would poison every
+      // percentile on the route, so an unmeasurable request is not a sample.
+      if (!Number.isFinite(cpuMs)) return;
+      const key = `${method} ${route}`;
+      let b = buckets.get(key);
+      if (!b) {
+        b = { method, route, seen: 0, samples: [], total: 0 };
+        buckets.set(key, b);
+      }
+      b.seen += 1;
+      b.total += cpuMs;
+      if (b.samples.length < cap) {
+        b.samples.push(cpuMs);
+      } else {
+        // Algorithm R: keep each observed sample with equal probability.
+        const j = Math.floor(random() * b.seen);
+        if (j < cap) b.samples[j] = cpuMs;
+      }
+    },
+    report(): CpuBudgetReport {
+      const routes: RouteCpuStats[] = [];
+      for (const [key, b] of buckets) {
+        const sorted = [...b.samples].sort((x, y) => x - y);
+        const resolved: ResolvedBudget = resolveBudget(config, b.method, b.route);
+        routes.push({
+          method: b.method,
+          route: b.route,
+          key,
+          samples: b.seen,
+          retained: sorted.length,
+          mean: b.seen > 0 ? b.total / b.seen : Number.NaN,
+          p50: percentile(sorted, 50),
+          p95: percentile(sorted, 95),
+          p99: percentile(sorted, 99),
+          max: percentile(sorted, 100),
+          totalCpuMs: b.total,
+          budgetMs: resolved.cpuMs,
+          exemptReason: resolved.exemptReason,
+          noticeAboveMs: resolved.noticeAboveMs,
+          declared: resolved.declared,
+        });
+      }
+      // Worst offender first — a report is read from the top.
+      routes.sort((a, z) => (z.p99 || 0) - (a.p99 || 0));
+      return {
+        source: opts.clock.source,
+        proxy: opts.clock.proxy,
+        available: opts.clock.available,
+        routes,
+      };
+    },
+    reset() {
+      buckets = new Map();
+    },
+  };
+}

package/src/server/bench/runBench.ts

@@ -0,0 +1,110 @@
+import type { CpuRecorder } from './recorder';
+import type { CpuBudgetReport } from './recorder';
+
+/**
+ * Drive a Hono app's routes and measure what each costs in CPU.
+ *
+ * 🔴 **Serial on purpose, and this is the load-bearing decision.** `process.cpuUsage()`
+ * deltas are PROCESS-wide (see `cpuClock.ts`), so two requests in flight each absorb the
+ * other's CPU and every number is inflated by an amount nobody can subtract afterwards.
+ * Running one request at a time is what makes the local proxy sound enough to gate on.
+ * There is deliberately no `concurrency` option — it would produce numbers that look
+ * finer-grained and are strictly less true.
+ *
+ * Wall-clock cost of the bench itself is irrelevant; it is a gate, not a load test.
+ */
+
+/** RFC 2606 reserved TLD — a bench request must never be able to leave the process. */
+export const BENCH_ORIGIN = 'http://cpu-bench.invalid';
+
+export interface BenchCase {
+  /** Default `'GET'`. */
+  method?: string;
+  /** Path with a leading slash, e.g. `'/api/notes/abc'`. */
+  path: string;
+  /** Extra request init — headers, body. `method` above wins over `init.method`. */
+  init?: RequestInit;
+  /** Overrides the run-wide `iterations` for this case. */
+  iterations?: number;
+  /**
+   * Statuses this case is expected to return. Default: anything `< 400`.
+   *
+   * 🔴 This guard is the point. A route that 404s or 500s costs almost no CPU, so a
+   * bench that does not check the response reports a beautiful number for a handler
+   * that never ran — a green budget over a broken route.
+   */
+  expectStatus?: number | number[] | ((status: number) => boolean);
+}
+
+export interface RunCpuBenchOpts {
+  /** Anything with Hono's `fetch` shape. */
+  app: { fetch: (req: Request, env?: unknown, ctx?: unknown) => Response | Promise<Response> };
+  /** The recorder the app's `cpuBudget()` middleware writes through. */
+  recorder: CpuRecorder;
+  cases: BenchCase[];
+  /** Measured iterations per case. Default 30 — above `assertCpuBudgets`' 20-sample floor. */
+  iterations?: number;
+  /**
+   * Unmeasured iterations per case, run first and then DISCARDED.
+   *
+   * 🔴 Without this the bench measures JIT warm-up. A first call through a cold handler
+   * can cost an order of magnitude more than its steady state, and with 30 samples one
+   * cold call lands squarely in the p99 — so the route that fails is whichever one the
+   * bench happened to touch first. Default 5.
+   */
+  warmup?: number;
+  /** Origin for the synthesized requests. Default {@link BENCH_ORIGIN}. */
+  origin?: string;
+  /** Passed through to `app.fetch` as the Worker `env`. */
+  env?: unknown;
+  /** Passed through to `app.fetch` as the Worker execution context. */
+  ctx?: unknown;
+}
+
+function statusAllowed(c: BenchCase, status: number): boolean {
+  const expect = c.expectStatus;
+  if (expect === undefined) return status < 400;
+  if (typeof expect === 'function') return expect(status);
+  if (Array.isArray(expect)) return expect.includes(status);
+  return expect === status;
+}
+
+function describe(c: BenchCase): string {
+  return `${(c.method ?? 'GET').toUpperCase()} ${c.path}`;
+}
+
+async function fire(opts: RunCpuBenchOpts, c: BenchCase): Promise<void> {
+  const method = (c.method ?? c.init?.method ?? 'GET').toUpperCase();
+  const req = new Request(`${opts.origin ?? BENCH_ORIGIN}${c.path}`, { ...c.init, method });
+  const res = await opts.app.fetch(req, opts.env, opts.ctx);
+  if (!statusAllowed(c, res.status)) {
+    const body = await res.text().catch(() => '');
+    throw new Error(
+      `cpu-bench: ${describe(c)} returned ${res.status}, which this case does not expect. ` +
+        'A route that errors costs no CPU, so measuring it would report a budget it never ' +
+        `met. Fix the case or set expectStatus.${body ? ` Body: ${body.slice(0, 200)}` : ''}`,
+    );
+  }
+  // Drain the body so a streamed response's work is actually done before the span ends.
+  if (res.body && !res.bodyUsed) await res.arrayBuffer().catch(() => undefined);
+}
+
+export async function runCpuBench(opts: RunCpuBenchOpts): Promise<CpuBudgetReport> {
+  if (opts.cases.length === 0) throw new Error('runCpuBench: no cases given');
+  const iterations = opts.iterations ?? 30;
+  const warmup = opts.warmup ?? 5;
+  if (!(iterations > 0)) throw new Error('runCpuBench: iterations must be > 0');
+
+  for (const c of opts.cases) {
+    for (let i = 0; i < warmup; i += 1) await fire(opts, c);
+  }
+  // 🔴 Everything above was warm-up. Discard it — measuring it is the bug this guards.
+  opts.recorder.reset();
+
+  for (const c of opts.cases) {
+    const n = c.iterations ?? iterations;
+    for (let i = 0; i < n; i += 1) await fire(opts, c);
+  }
+
+  return opts.recorder.report();
+}

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

@@ -0,0 +1,121 @@
+import { Database } from 'bun:sqlite';
+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';
+
+const dirs: string[] = [];
+const scratch = (): string => {
+	const d = mkdtempSync(join(tmpdir(), 'd1-backup-'));
+	dirs.push(d);
+	return d;
+};
+afterEach(() => {
+	for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+/** A WAL-mode database on disk with enough rows to produce a real WAL file. */
+function seeded(dir: string): { path: string; db: Database } {
+	const path = join(dir, 'app.sqlite');
+	const db = new Database(path, { create: true });
+	db.exec('PRAGMA journal_mode = WAL');
+	db.run('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)');
+	const insert = db.prepare('INSERT INTO t (v) VALUES (?)');
+	for (let i = 0; i < 2_000; i++) insert.run(`row-${i}`);
+	return { path, db };
+}
+
+describe('the local half keeps checkpointing the WAL', () => {
+	test('🔴 wal_checkpoint(TRUNCATE) actually drains the WAL file', () => {
+		// The measurement this exists for: `family.sqlite` was once 2.2 MB of principal
+		// against a 2.1 MB WAL. An un-checkpointed copy is half a database.
+		const dir = scratch();
+		const { path, db } = seeded(dir);
+		const walPath = `${path}-wal`;
+
+		expect(existsSync(walPath)).toBe(true);
+		expect(statSync(walPath).size).toBeGreaterThan(0);
+
+		const result = checkpointWal(db);
+		expect(result.busy).toBe(false);
+		// 🔴 The post-condition is the FILE SIZE, not the pragma's counters. Measured
+		// 2026-09-16: under TRUNCATE, SQLite reports the counters from after the
+		// truncation, so a fully successful checkpoint returns `checkpointed: 0`. A test
+		// asserting `checkpointed > 0` would be asserting a structurally impossible value
+		// — it fails on a working checkpoint, which is how a real check gets deleted.
+		expect(result.checkpointed).toBe(0);
+		// TRUNCATE, not PASSIVE: the file is emptied, not merely merged.
+		expect(statSync(walPath).size).toBe(0);
+		db.close();
+	});
+
+	test('capture() checkpoints and writes a readable snapshot containing every row', async () => {
+		const dir = scratch();
+		const { path, db } = seeded(dir);
+		const destDir = join(dir, 'backups');
+
+		const point = await createLocalBackup({ db, sourcePath: path, destDir }).capture();
+
+		expect(point.kind).toBe('file');
+		expect(existsSync(point.ref)).toBe(true);
+		expect(point.bytes).toBeGreaterThan(0);
+		expect(point.exportCommand).toBeNull();
+
+		// The snapshot is a real database with the full row count — which is what would
+		// have failed had the WAL not been merged in.
+		const restored = new Database(point.ref, { readonly: true });
+		const count = restored.query('SELECT COUNT(*) AS n FROM t').get() as { n: number };
+		expect(count.n).toBe(2_000);
+		restored.close();
+		db.close();
+	});
+
+	test('the local half reports that it DOES need a periodic capture', () => {
+		const dir = scratch();
+		const { path, db } = seeded(dir);
+		expect(createLocalBackup({ db, sourcePath: path, destDir: dir }).needsPeriodicCapture).toBe(true);
+		db.close();
+	});
+});
+
+describe('the D1 half records a coordinate instead of copying bytes', () => {
+	const at = new Date('2026-09-16T04:30:00.000Z');
+
+	test('capture() returns a restorable timestamp and the two real commands', async () => {
+		const point = await createTimeTravelBackup({ databaseName: 'patterns', now: () => at }).capture();
+
+		expect(point.kind).toBe('time-travel');
+		expect(point.ref).toBe('2026-09-16T04:30:00.000Z');
+		expect(point.restoreCommand).toBe(
+			'wrangler d1 time-travel restore patterns --timestamp=2026-09-16T04:30:00.000Z',
+		);
+		expect(point.exportCommand).toContain('wrangler d1 export patterns --remote');
+	});
+
+	test('🔴 it reports needsPeriodicCapture: false — Time Travel is automatic', () => {
+		// A nightly no-op job logging "backup complete" is worse than no job, because it
+		// reads as evidence. A scheduler must honour this flag.
+		expect(createTimeTravelBackup({ databaseName: 'patterns' }).needsPeriodicCapture).toBe(false);
+	});
+
+	test('bytes is null rather than a fabricated zero', () => {
+		// Cloudflare reports no size for a restore point; a 0 would read as a measurement.
+		return createTimeTravelBackup({ databaseName: 'x', now: () => at })
+			.capture()
+			.then((p) => expect(p.bytes).toBeNull());
+	});
+});
+
+describe('backupFor picks the implementation from the driver flavor', () => {
+	test('local flavor checkpoints; d1 flavor does not need to', async () => {
+		const dir = scratch();
+		const { path, db } = seeded(dir);
+		const local = () => ({ db, sourcePath: path, destDir: join(dir, 'b') });
+		const remote = () => ({ databaseName: 'patterns' });
+
+		expect(backupFor('local', local, remote).needsPeriodicCapture).toBe(true);
+		expect(backupFor('d1', local, remote).needsPeriodicCapture).toBe(false);
+		db.close();
+	});
+});