@pithy-sh/core 0.1.0

package/src/logger/local.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createLogger, type Logger } from "./logger";
+import type { LogLevel, LogRecord } from "./record";
+import { serializeRecord } from "./record";
+
+/**
+ * Mode 1 — local diagnostics. One unified diagnostic layer for the `pithy` CLI process and a Worker
+ * running under `pithy dev` / `wrangler dev`. Human-readable and (optionally) colorized for a person at
+ * a terminal, or a `--json` structured line stream for agents and CI. This is *diagnostic logging only*
+ * — interactive CLI UX (prompts, spinners, `PithyError` rendering) stays on the CLI's `style.ts`.
+ */
+
+/**
+ * Level-keyed color functions the local adapter paints with. Injected, not hard-coded: core stays free
+ * of ANSI, and the CLI passes its `style.ts` seam so all CLI color still flows through one place. Every
+ * entry is optional; a missing one renders plain.
+ */
+export interface LocalPalette {
+  debug?: (text: string) => string;
+  info?: (text: string) => string;
+  warn?: (text: string) => string;
+  error?: (text: string) => string;
+  /** Dimmed secondary text — the namespace, fields, and error detail. */
+  dim?: (text: string) => string;
+}
+
+/** Options for {@link createLocalLogger}. */
+export interface LocalLoggerOptions {
+  /** The threshold. Defaults to `debug` — local diagnostics are verbose by default. */
+  level?: LogLevel;
+  /** Emit each record as a `JSON.stringify` line instead of the human format — the agent/CI stream. */
+  json?: boolean;
+  /** Where a formatted line goes. Defaults to `console.error` (stderr under Node), so diagnostics never pollute a command's stdout. */
+  write?: (line: string) => void;
+  /** Optional color functions (the CLI injects its `style.ts` seam). Omitted → plain text. */
+  palette?: LocalPalette;
+  /** The clock, injectable for tests. */
+  now?: () => number;
+}
+
+/** Render one field value: strings verbatim, everything else as compact JSON — never throwing on a cycle/BigInt. */
+function renderValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** `key=value key=value` for the record's fields, in insertion order. */
+function renderFields(fields: Record<string, unknown>): string {
+  return Object.entries(fields)
+    .map(([key, value]) => `${key}=${renderValue(value)}`)
+    .join(" ");
+}
+
+/** Format one record for a terminal: `LEVEL (name) msg key=val … code detail`, colorized when a palette is set. */
+function renderHuman(record: LogRecord, palette?: LocalPalette): string {
+  const paint = palette?.[record.level] ?? ((text: string) => text);
+  const dim = palette?.dim ?? ((text: string) => text);
+  const parts = [paint(record.level.toUpperCase())];
+  if (record.name) parts.push(dim(`(${record.name})`));
+  parts.push(record.msg);
+  if (record.fields) parts.push(dim(renderFields(record.fields)));
+  if (record.error) {
+    const detail = record.error.detail ? ` ${record.error.detail}` : "";
+    parts.push(dim(`${record.error.code}${detail}`));
+  }
+  return parts.join(" ");
+}
+
+/**
+ * Build a Mode 1 local logger. Same interface as every other Pithy logger; the sink either renders a
+ * human line (default, colorized when a palette is injected) or a `--json` structured line. Writes to
+ * `stderr` by default so a command's machine-readable stdout stays clean.
+ */
+export function createLocalLogger(options: LocalLoggerOptions = {}): Logger {
+  // The one sanctioned `console` in the local adapter: this is the adapter, so console is the transport,
+  // not a shortcut past the `Logger` seam. Default to console.error — stderr under Node (the CLI), the
+  // console elsewhere — so core stays free of `process`. The CLI passes its own `write` when it wants raw
+  // `process.stderr`.
+  const write = options.write ?? ((line: string) => console.error(line));
+  return createLogger({
+    level: options.level ?? "debug",
+    now: options.now,
+    sink: (record) => write(options.json ? serializeRecord(record) : renderHuman(record, options.palette)),
+  });
+}

package/src/logger/logger.ts

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ErrorPayload } from "../error/payload";
+import { PithyError } from "../error/pithyError";
+import { LOG_LEVEL_ORDER, type LogFields, type LogLevel, type LogRecord } from "./record";
+
+/**
+ * The `Logger` seam. Four levels, each taking a message plus **structured fields** (not a formatted
+ * string), and `child(name)` to derive a namespaced sub-logger. Shared across runtimes: the same
+ * interface backs the `pithy` CLI process, a Worker running locally, and a deployed Worker — only the
+ * adapter behind it differs. Resolve it from the request context (`c.var.log`) or the CLI process
+ * logger; never reach for `console`.
+ *
+ * The reserved `error` field on any call may carry a `PithyError` or `ErrorPayload` — the engine lifts
+ * it into the record's `error`, `detail` and all. A log is internal; this is the inverse of the HTTP
+ * codec, which strips `detail`. The logger must never be wired to a client-facing surface.
+ */
+export interface Logger {
+  /** Dev-time diagnostics. Dropped unless the logger's level is `debug`. */
+  debug(msg: string, fields?: LogFields): void;
+  /** Normal operational events. */
+  info(msg: string, fields?: LogFields): void;
+  /** A recoverable problem worth attention. */
+  warn(msg: string, fields?: LogFields): void;
+  /** A failure that was observed. Pass `{ error }` (a PithyError) to carry its full payload. */
+  error(msg: string, fields?: LogFields): void;
+  /**
+   * A namespaced sub-logger. `name` composes as `parent:child`; bound `fields` merge into every record
+   * the child emits. Omit `name` (pass `undefined`) to bind fields only — how request-correlation
+   * attaches `request`/`method`/`path` without renaming the logger.
+   */
+  child(name?: string, fields?: LogFields): Logger;
+}
+
+/** A sink receives a finished {@link LogRecord}. Adapters supply one; the engine builds records and calls it. */
+export type LogSink = (record: LogRecord) => void;
+
+/** Inputs to {@link createLogger}: the level threshold, the sink, and optional bound name/fields/clock. */
+export interface CreateLoggerOptions {
+  /** The threshold; records below it are dropped. */
+  level: LogLevel;
+  /** Where finished records go. */
+  sink: LogSink;
+  /** A starting namespace for this logger, if any. */
+  name?: string;
+  /** Fields bound onto every record this logger emits. */
+  fields?: LogFields;
+  /** The clock, injectable for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+/** Internal, fully-resolved logger state — `now` and `level` always set. */
+interface LoggerState {
+  level: LogLevel;
+  sink: LogSink;
+  name?: string;
+  fields?: LogFields;
+  now: () => number;
+}
+
+/**
+ * Duck-type an `ErrorPayload`: a **namespaced** `code` (`domain/reason`) plus an HTTP-range `status`.
+ * Cheap — no per-call Zod parse. The `/` and status-range checks keep an ordinary field that happens to
+ * be named `error` (e.g. `{ code: "retry", status: 3 }`) from being mistaken for a payload and lifted.
+ */
+function isErrorPayloadLike(value: unknown): value is ErrorPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const { code, status } = value as { code?: unknown; status?: unknown };
+  return (
+    typeof code === "string" &&
+    code.includes("/") &&
+    typeof status === "number" &&
+    Number.isInteger(status) &&
+    status >= 100 &&
+    status <= 599
+  );
+}
+
+/** Build a logger over `state`: level-filters, merges bound + call fields, lifts a carried error. */
+function makeLogger(state: LoggerState): Logger {
+  const emit = (level: LogLevel, msg: string, callFields?: LogFields): void => {
+    if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[state.level]) return;
+    const merged: LogFields = { ...state.fields, ...callFields };
+
+    // Lift a reserved `error` field into the record's typed `error` — a PithyError contributes its full
+    // payload (detail included); a raw ErrorPayload passes through. Everything else stays a plain field.
+    let error: ErrorPayload | undefined;
+    const carried = merged.error;
+    if (carried instanceof PithyError) {
+      error = carried.payload;
+      delete merged.error;
+    } else if (isErrorPayloadLike(carried)) {
+      error = carried;
+      delete merged.error;
+    }
+
+    const record: LogRecord = { level, msg, time: state.now() };
+    if (state.name) record.name = state.name;
+    if (Object.keys(merged).length > 0) record.fields = merged;
+    if (error) record.error = error;
+    state.sink(record);
+  };
+
+  return {
+    debug: (msg, fields) => emit("debug", msg, fields),
+    info: (msg, fields) => emit("info", msg, fields),
+    warn: (msg, fields) => emit("warn", msg, fields),
+    error: (msg, fields) => emit("error", msg, fields),
+    child: (name, fields) =>
+      makeLogger({
+        ...state,
+        name: name ? (state.name ? `${state.name}:${name}` : name) : state.name,
+        fields: { ...state.fields, ...fields },
+      }),
+  };
+}
+
+/**
+ * The shared logger engine. Both adapters build on it: they supply a {@link LogSink} and a level, and
+ * this handles level filtering, `child` namespacing, field merging, and error lifting — one place, so
+ * every adapter behaves identically.
+ */
+export function createLogger(options: CreateLoggerOptions): Logger {
+  return makeLogger({
+    level: options.level,
+    sink: options.sink,
+    name: options.name,
+    fields: options.fields,
+    now: options.now ?? (() => Date.now()),
+  });
+}
+
+/**
+ * The safe default: a logger that drops every record. Shipped so a capability that does nothing still
+ * has a `c.var.log` to call, and a KV store built without a logger still logs to *somewhere*. Both
+ * adapters replace it; nothing has to null-check `log`.
+ */
+export const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  child: () => noopLogger,
+};

package/src/logger/record.ts

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ErrorPayload } from "../error/payload";
+
+/**
+ * The logger object model. A log call is a **record**, not a formatted line — `{ level, msg, ...fields }`
+ * — so both adapters (local diagnostics, CF-native) serialize the same structured shape rather than
+ * re-parsing text. The schema IS the documentation: every field carries a `.describe()`, like any other
+ * Pithy boundary. Log copy follows the brand voice — the `msg` is one pithy line; data lives in `fields`.
+ */
+
+/** The four severities, low to high. `debug` is dev diagnostics; `error` is a failure that was observed. */
+export const LogLevel = z
+  .enum(["debug", "info", "warn", "error"])
+  .describe("Log severity, low to high: `debug` < `info` < `warn` < `error`. The threshold a logger filters on.");
+export type LogLevel = z.output<typeof LogLevel>;
+
+/**
+ * Numeric rank per level, for threshold filtering — a logger drops any record ranked below its level.
+ * Not a schema (it is a lookup table), so the meta-test that polices `.describe()` skips it.
+ */
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+/**
+ * Structured fields carried on a record — the data half of a log. Arbitrary JSON-ish values keyed by
+ * name (`{ userId, elapsed, request }`); an adapter renders or serializes them. The reserved key
+ * `error` may carry a `PithyError` or `ErrorPayload`; the engine lifts it into {@link LogRecord.error}.
+ */
+export const LogFields = z
+  .record(z.string(), z.unknown())
+  .describe("Structured, arbitrary fields carried on a log record — the queryable data half of a log call.");
+export type LogFields = z.output<typeof LogFields>;
+
+/**
+ * One finished log record — what an adapter's sink receives. This is the on-the-wire structured shape
+ * CF Workers Logs indexes per line and the local adapter renders. `error` carries the **full**
+ * `ErrorPayload` including `detail`: a log is an internal surface (the same side of the boundary as
+ * audit `detail`), the inverse of the HTTP codec which strips it. A logger is never wired to a client.
+ */
+export const LogRecord = z
+  .object({
+    level: LogLevel.describe("The severity of this record."),
+    msg: z.string().describe("The one-line, brand-voice message. No data — data lives in `fields`."),
+    time: z.number().int().describe("When the record was made, as a millisecond epoch."),
+    name: z.string().nullish().describe("The emitting logger's namespace (from `child(name)`), if any."),
+    fields: LogFields.nullish().describe("Structured fields carried on this record, if any were supplied."),
+    error: ErrorPayload.nullish().describe(
+      "The full error payload — `detail` included — when the call carried a PithyError. Internal only.",
+    ),
+  })
+  .describe("One structured log record: an adapter's sink serializes or renders exactly this shape.");
+export type LogRecord = z.output<typeof LogRecord>;
+
+/**
+ * A JSON replacer that keeps serialization total: `BigInt` becomes a string, and a repeated object
+ * reference (a cycle) becomes `"[Circular]"`. A logger must never throw — an unserializable field in a
+ * log call must not crash the caller — so both adapters serialize through {@link serializeRecord}.
+ */
+function safeReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return (_key, value) => {
+    if (typeof value === "bigint") return value.toString();
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return "[Circular]";
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+/**
+ * Serialize a record to one JSON line, tolerating cycles and `BigInt` so a log call is crash-proof. If
+ * even the safe pass fails, fall back to the always-serializable core fields — never throw.
+ */
+export function serializeRecord(record: LogRecord): string {
+  try {
+    return JSON.stringify(record, safeReplacer());
+  } catch {
+    return JSON.stringify({ level: record.level, msg: record.msg, time: record.time });
+  }
+}

package/src/logger/worker.ts

@@ -0,0 +1,117 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createLogger, type Logger } from "./logger";
+import type { LogFields, LogLevel, LogRecord } from "./record";
+import { serializeRecord } from "./record";
+
+/**
+ * Mode 2 — CF-native structured logs, for a deployed Worker. Each log emits as **one per-line
+ * structured record** Cloudflare Workers Logs indexes and can query — not one buried per-request blob.
+ * With `observability.enabled` on in the generated `wrangler.jsonc`, these are queryable in the
+ * dashboard with zero adopter setup. The `transport` hook fans the same records to a tail-consumer
+ * Worker or Logpush without touching any call site.
+ */
+
+/** Options for {@link createWorkerLogger}. */
+export interface WorkerLoggerOptions {
+  /** The threshold. Defaults to `info` — a deployed Worker is quieter than local dev. */
+  level?: LogLevel;
+  /**
+   * The tail/Logpush plug point: called with every finished record after it is emitted, so records can
+   * fan to a tail-consumer or Logpush unchanged. Enabling it changes no log call site.
+   */
+  transport?: (record: LogRecord) => void;
+  /**
+   * How a record reaches Workers Logs. Defaults to a single crash-proof JSON line via `console.log`,
+   * which Workers Logs indexes as structured JSON. Injectable for tests.
+   */
+  emit?: (record: LogRecord) => void;
+  /** Fields bound onto every record (e.g. `env`, `version`). */
+  fields?: LogFields;
+  /** A starting namespace. */
+  name?: string;
+  /** The clock, injectable for tests. */
+  now?: () => number;
+}
+
+/**
+ * Build a Mode 2 CF-native logger. The sink emits one structured line to Workers Logs, then hands the
+ * same record to `transport` when one is configured. The record shape is unchanged whether or not a
+ * transport is attached — tail/Logpush readiness is by construction.
+ */
+export function createWorkerLogger(options: WorkerLoggerOptions = {}): Logger {
+  // The one sanctioned `console` in a Worker: this is the adapter, so console is the transport, not a
+  // shortcut past it. `console.log` *is* the Workers Logs ingest API — a structured line written here is
+  // what the dashboard indexes. Every other module logs through the `Logger` seam and lands here.
+  const emit = options.emit ?? ((record: LogRecord) => console.log(serializeRecord(record)));
+  const { transport } = options;
+  return createLogger({
+    level: options.level ?? "info",
+    name: options.name,
+    fields: options.fields,
+    now: options.now,
+    sink: (record) => {
+      emit(record);
+      transport?.(record);
+    },
+  });
+}
+
+/** The per-request correlation fields bound onto every Worker-side record. Resolved from the request. */
+export interface RequestContext {
+  /** A stable id for this request (the CF ray id, or a generated uuid). */
+  request: string;
+  /** The HTTP method. */
+  method: string;
+  /** The request path. */
+  path: string;
+  /** The environment name (`dev` | `staging` | `production`), from config. */
+  env: string;
+  /** The deployed Worker version id, when the version-metadata binding is present. */
+  version?: string;
+}
+
+/**
+ * Derive a per-request logger by binding {@link RequestContext} onto `base` — so every record the
+ * handler emits auto-carries `request`/`method`/`path`/`env`/`version` with no caller effort. Uses the
+ * nameless `child` form, leaving the logger's namespace free for a capability to claim.
+ */
+export function bindRequestContext(base: Logger, context: RequestContext): Logger {
+  const fields: LogFields = {
+    request: context.request,
+    method: context.method,
+    path: context.path,
+    env: context.env,
+  };
+  if (context.version !== undefined) fields.version = context.version;
+  return base.child(undefined, fields);
+}
+
+/** The per-run correlation fields bound onto every record a Workflow emits. Resolved from the run's event and env. */
+export interface WorkflowContext {
+  /** The deployed Workflow name, from `event.workflowName`. */
+  workflow: string;
+  /** This run's instance id, from `event.instanceId` — what the dashboard and `wrangler workflows` key on. */
+  instance: string;
+  /** The environment name (`dev` | `staging` | `prod`), from the host's `ENVIRONMENT` var. */
+  env: string;
+  /** The deployed Worker version id, when the version-metadata binding is present. */
+  version?: string;
+}
+
+/**
+ * Derive a per-run logger by binding {@link WorkflowContext} onto `base` — the Workflow peer of
+ * {@link bindRequestContext}, so a durable run correlates the way a request already does. A run has no
+ * method or path; it has an instance, and that is the id anyone reading Workflows Logs searches by. Uses
+ * the nameless `child` form, leaving the logger's namespace free for a capability to claim.
+ */
+export function bindWorkflowContext(base: Logger, context: WorkflowContext): Logger {
+  const fields: LogFields = {
+    workflow: context.workflow,
+    instance: context.instance,
+    env: context.env,
+  };
+  if (context.version !== undefined) fields.version = context.version;
+  return base.child(undefined, fields);
+}

package/src/migrations/batch.ts

@@ -0,0 +1,226 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types";
+import type { CompiledQuery, DatabaseConnection, Driver, QueryResult, TransactionSettings } from "kysely";
+import { CamelCasePlugin, Kysely } from "kysely";
+import type { Migration, MigrationProvider } from "kysely/migration";
+import { D1MigrationDialect } from "./bookkeeping";
+
+/**
+ * **One round trip per migration, instead of one per statement.**
+ *
+ * `kysely-d1` executes every compiled query as its own `prepare().bind().all()`, so a capability's
+ * `0001_init` — nineteen tables and thirty-eight indexes, composed — cost fifty-seven hops to D1.
+ * Measured against a real composed application in the Workers runtime: 1,028ms and 68 round trips to
+ * migrate, 2,041ms per drop-and-rebuild. An adopter following the kit's own advice (Workers-runtime
+ * tests against real D1, not mocks) pays that once per test that needs a clean database; in
+ * `pithy-sh/dashboard` it was 78% of total wall time, and the setup floor it left put ordinary test
+ * bodies within reach of the 5,000ms timeout (`pithy-sh/pithy#368`).
+ *
+ * `d1.batch()` sends many statements in one round trip, in order, in one implicit transaction. A
+ * migration's statements are already ordered and already a unit, which is the shape `batch` exists
+ * for. So a migration body runs against a Kysely whose driver **queues** its statements and sends
+ * them as one batch when the body returns.
+ *
+ * ## Only DDL is queued, and that is the whole safety argument
+ *
+ * A queued statement's result is returned to the migration body before the statement has run, so it
+ * cannot carry rows, a row count, or an insert id. Rather than document that as a caveat, the queue
+ * only takes statements that **have no such result to carry** — `create`/`drop`/`alter` on a table,
+ * index, view, schema or type. Everything else — every select, insert, update, delete, and every raw
+ * `sql` template, whose shape is not knowable from its node — **flushes the queue and then executes
+ * on its own**, exactly as before. Ordering is therefore preserved unconditionally: a read always
+ * sees every statement written before it.
+ *
+ * The consequence worth stating: a migration that interleaves data with DDL is split into several
+ * batches, one per run of consecutive DDL. It is still correct and still faster; it is simply not one
+ * transaction. Every migration the kit ships is pure DDL and is one batch.
+ *
+ * ## Failure semantics, which did change
+ *
+ * Before: a migration failing at its k-th statement left statements 1..k-1 applied, with no ledger
+ * row — a half-applied migration, the thing a chain exists to prevent. After: the batch is the unit,
+ * so a failure anywhere in it rolls back all of it and the ledger still records nothing. The
+ * migration is all-or-nothing.
+ *
+ * What did **not** change is anything across a migration boundary. Each `up`/`down` builds its own
+ * queue and flushes before returning, so no statement of one migration can share a batch with
+ * another's, and the ledger row is written by Kysely's `Migrator` on the ordinary path afterwards.
+ * A chain that fails at its third migration still has its first two applied and recorded, and the
+ * error still names them. Batching across migrations would make a partial chain unrepresentable in
+ * the ledger, which is worse than slow.
+ */
+
+/**
+ * Compiled-query kinds with no result a migration body could read — the only ones safe to queue.
+ * SQLite ignores schemas and types, but the nodes exist and cost nothing to name.
+ */
+const QUEUEABLE_KINDS: ReadonlySet<string> = new Set([
+  "CreateTableNode",
+  "DropTableNode",
+  "CreateIndexNode",
+  "DropIndexNode",
+  "AlterTableNode",
+  "CreateViewNode",
+  "DropViewNode",
+  "CreateSchemaNode",
+  "DropSchemaNode",
+  "CreateTypeNode",
+  "DropTypeNode",
+]);
+
+/** Statements waiting for their one round trip. Ordered; flushed as a single `d1.batch()`. */
+class StatementQueue {
+  readonly #database: D1Database;
+  #pending: CompiledQuery[] = [];
+
+  constructor(database: D1Database) {
+    this.#database = database;
+  }
+
+  add(query: CompiledQuery): void {
+    this.#pending.push(query);
+  }
+
+  /**
+   * Send everything queued, in order, as one batch — and nothing at all when nothing is queued, so a
+   * flush is always safe to call. Cleared before the call, so a failed batch is not retried by a
+   * later flush.
+   */
+  async flush(): Promise<void> {
+    if (this.#pending.length === 0) return;
+    const pending = this.#pending;
+    this.#pending = [];
+    const statements: D1PreparedStatement[] = pending.map((query) =>
+      this.#database.prepare(query.sql).bind(...query.parameters),
+    );
+    await this.#database.batch(statements);
+  }
+}
+
+/** Queues what it can, and flushes before anything it cannot — see the module note. */
+class QueueingConnection implements DatabaseConnection {
+  readonly #direct: DatabaseConnection;
+  readonly #queue: StatementQueue;
+
+  constructor(direct: DatabaseConnection, queue: StatementQueue) {
+    this.#direct = direct;
+    this.#queue = queue;
+  }
+
+  async executeQuery<R>(query: CompiledQuery): Promise<QueryResult<R>> {
+    if (QUEUEABLE_KINDS.has(query.query.kind)) {
+      this.#queue.add(query);
+      return { rows: [] };
+    }
+    await this.#queue.flush();
+    return this.#direct.executeQuery<R>(query);
+  }
+
+  streamQuery<R>(query: CompiledQuery, chunkSize: number): AsyncIterableIterator<QueryResult<R>> {
+    return this.#direct.streamQuery<R>(query, chunkSize);
+  }
+}
+
+/** The stock D1 driver, with every connection wrapped in the queue. Transactions stay unsupported. */
+class QueueingDriver implements Driver {
+  readonly #inner: Driver;
+  readonly #queue: StatementQueue;
+  readonly #inners = new WeakMap<DatabaseConnection, DatabaseConnection>();
+
+  constructor(inner: Driver, queue: StatementQueue) {
+    this.#inner = inner;
+    this.#queue = queue;
+  }
+
+  async init(): Promise<void> {
+    await this.#inner.init();
+  }
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    const inner = await this.#inner.acquireConnection();
+    const wrapped = new QueueingConnection(inner, this.#queue);
+    this.#inners.set(wrapped, inner);
+    return wrapped;
+  }
+
+  async beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void> {
+    await this.#inner.beginTransaction(this.#unwrap(connection), settings);
+  }
+
+  async commitTransaction(connection: DatabaseConnection): Promise<void> {
+    await this.#inner.commitTransaction(this.#unwrap(connection));
+  }
+
+  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+    await this.#inner.rollbackTransaction(this.#unwrap(connection));
+  }
+
+  async releaseConnection(connection: DatabaseConnection): Promise<void> {
+    await this.#inner.releaseConnection(this.#unwrap(connection));
+  }
+
+  async destroy(): Promise<void> {
+    await this.#inner.destroy();
+  }
+
+  #unwrap(connection: DatabaseConnection): DatabaseConnection {
+    return this.#inners.get(connection) ?? connection;
+  }
+}
+
+/** Pithy's D1 dialect — same compiler, same `sqlite_master`-only introspector — driving the queue. */
+class QueueingD1Dialect extends D1MigrationDialect {
+  readonly #queue: StatementQueue;
+
+  constructor(database: D1Database, queue: StatementQueue) {
+    super({ database });
+    this.#queue = queue;
+  }
+
+  override createDriver(): Driver {
+    return new QueueingDriver(super.createDriver(), this.#queue);
+  }
+}
+
+/**
+ * Run one migration body against a queueing Kysely and send its statements as one batch.
+ *
+ * The `db` Kysely's `Migrator` would have passed is deliberately not used: it is the instance that
+ * also writes the ledger, and the ledger row must stay on the ordinary path so that a failed batch
+ * leaves no record of having applied. Same binding, same `CamelCasePlugin`, same dialect — a
+ * migration body cannot tell the difference except in how many hops it costs.
+ */
+async function batchBody(body: (db: Kysely<unknown>) => Promise<void>, database: D1Database): Promise<void> {
+  const queue = new StatementQueue(database);
+  const db = new Kysely<unknown>({ dialect: new QueueingD1Dialect(database, queue), plugins: [new CamelCasePlugin()] });
+  await body(db);
+  await queue.flush();
+}
+
+/** One migration, both directions batched. A migration with no `down` still has none. */
+function batchMigration(migration: Migration, database: D1Database): Migration {
+  const down = migration.down;
+  return {
+    up: async (): Promise<void> => batchBody((db) => migration.up(db), database),
+    ...(down ? { down: async (): Promise<void> => batchBody((db) => down(db), database) } : {}),
+  };
+}
+
+/**
+ * Wrap a provider so every migration it yields applies and reverses in one round trip each.
+ *
+ * Applied at the runner's seam rather than inside each capability, so a migration author writes
+ * ordinary Kysely and gets this for free — including adopters, who are the ones paying for it.
+ */
+export function batchedProvider(provider: MigrationProvider, database: D1Database): MigrationProvider {
+  return {
+    getMigrations: async (): Promise<Record<string, Migration>> => {
+      const migrations = await provider.getMigrations();
+      return Object.fromEntries(
+        Object.entries(migrations).map(([name, migration]) => [name, batchMigration(migration, database)]),
+      );
+    },
+  };
+}