cursedbelt-server 1.1.0 → 2.1.0

package/dist/server/bench/cpuClock.js

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+/**
+ * `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() {
+    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() {
+            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, source = 'worker-runtime') {
+    return {
+        source,
+        proxy: false,
+        available: true,
+        start() {
+            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') {
+    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, source = 'fixed') {
+    if (values.length === 0)
+        throw new Error('fixedCpuClock: needs at least one value');
+    let i = 0;
+    return {
+        source,
+        proxy: true,
+        available: true,
+        start() {
+            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) {
+    return readCpuMs ? workerCpuClock(readCpuMs) : processCpuClock();
+}

package/dist/server/bench/index.d.ts

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

@@ -0,0 +1,40 @@
+/**
+ * `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 { assertCpuBudgets, checkCpuBudgets, formatCpuBudgetReport, } from './assert';
+export { DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, monthlyOverageUsd, OWNER_PROJECTED_REQUESTS_PER_DAY, resolveBudget, 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 { cpuBudget } from './cpuBudget';
+export { fixedCpuClock, processCpuClock, resolveCpuClock, unavailableCpuClock, workerCpuClock, } from './cpuClock';
+export { createCpuRecorder, percentile, } from './recorder';
+export { BENCH_ORIGIN, runCpuBench } from './runBench';

package/dist/server/bench/recorder.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 } 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 declare function percentile(sortedAsc: readonly number[], p: number): number;
+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;
+}
+export declare function createCpuRecorder(opts: CpuRecorderOpts): CpuRecorder;

package/dist/server/bench/recorder.js

@@ -0,0 +1,95 @@
+/**
+ * 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 { resolveBudget, validateCpuBudgetConfig, } from './budget';
+/**
+ * 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, p) {
+    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 function createCpuRecorder(opts) {
+    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();
+    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() {
+            const routes = [];
+            for (const [key, b] of buckets) {
+                const sorted = [...b.samples].sort((x, y) => x - y);
+                const resolved = 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/dist/server/bench/runBench.d.ts

@@ -0,0 +1,61 @@
+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 declare 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;
+}
+export declare function runCpuBench(opts: RunCpuBenchOpts): Promise<CpuBudgetReport>;

package/dist/server/bench/runBench.js

@@ -0,0 +1,61 @@
+/**
+ * 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';
+function statusAllowed(c, status) {
+    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) {
+    return `${(c.method ?? 'GET').toUpperCase()} ${c.path}`;
+}
+async function fire(opts, c) {
+    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) {
+    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/dist/server/d1/backup.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
+ *
+ * ## 🔴 BOTH, not one
+ *
+ * D1 has no WAL a caller can checkpoint, and 30 days of free point-in-time restore is
+ * strictly better than the file copy it replaces. It is tempting to read that as "the
+ * checkpoint goes away". It does not: `PRAGMA wal_checkpoint(TRUNCATE)` is in the backup
+ * path of every app in this fleet and it is load-bearing while any of them is still
+ * Mac-hosted. Measured previously, `family.sqlite` was **2.2 MB of principal against a
+ * 2.1 MB WAL** — an un-checkpointed copy is half a database, and `VACUUM INTO` merging
+ * the WAL is the only reason the existing `../sqlite/backup.ts` is safe.
+ *
+ * So the local implementation keeps checkpointing, the remote one records a restore
+ * coordinate, and both answer the same interface. An app's backup job stops caring which
+ * side it is on — which is the property that lets the job move before the database does.
+ *
+ * ## The remote side does not "take" a backup, and that is not a gap
+ *
+ * Time Travel is automatic and continuous: D1 retains 30 days and restores to any
+ * timestamp or bookmark within it. There is nothing to trigger, so
+ * {@link createTimeTravelBackup} records the coordinate rather than inventing an API call
+ * that does not exist. The coordinate IS the backup — `wrangler d1 time-travel restore`
+ * takes a timestamp.
+ *
+ * 🔴 **`wrangler d1 export` is the off-Cloudflare leg, and a Worker cannot run it.** A
+ * Worker has no shell. That leg belongs to a Cron Trigger on this Mac or in CI, which is
+ * why {@link BackupPoint.exportCommand} hands back the command rather than running it —
+ * the same split as the binary server, where the bytes and the thing that copies them are
+ * deliberately not the same process.
+ */
+import 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';
+    /** A filesystem path for `file`; an ISO-8601 timestamp for `time-travel`. */
+    ref: string;
+    createdAt: string;
+    /** Bytes on disk, or `null` where the platform does not tell us. */
+    bytes: number | null;
+    /** The exact command that restores this point. Printed in the job log, not executed. */
+    restoreCommand: string;
+    /** For `time-travel`, the command that pulls a copy OFF Cloudflare. `null` locally. */
+    exportCommand: string | null;
+}
+export interface DatabaseBackup {
+    /** Capture a restore point now, and describe it. */
+    capture(): Promise<BackupPoint>;
+    /** 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;
+    /** Where an export should be written, for the off-Cloudflare leg. */
+    exportPath?: string;
+    /** Injected for the test; defaults to the real clock. */
+    now?: () => Date;
+}
+/**
+ * The D1 implementation: record the coordinate, because retention is automatic.
+ *
+ * 🔴 It reports `needsPeriodicCapture: false`, and a scheduler must honour that rather
+ * than calling `capture()` on a timer — a nightly no-op job that logs "backup complete"
+ * is worse than no job, because it reads as evidence.
+ */
+export 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;