@sproutboat/wire 0.12.2 → 0.13.1

package/src/build-d1-budget.ts

@@ -0,0 +1,38 @@
+/** Build at package/image preparation time, never on a tenant request. */
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+export const budgetExtension = resolve(
+  import.meta.dir,
+  `../native/d1-budget-${process.platform}-${process.arch}.${process.platform === "darwin" ? "dylib" : "so"}`,
+);
+if (import.meta.main) {
+  if (process.platform !== "darwin" && process.platform !== "linux")
+    throw new Error("SQL budget supports Linux and macOS");
+  mkdirSync(dirname(budgetExtension), { recursive: true });
+  const include =
+    process.env.SQLITE_INCLUDE ||
+    (process.platform === "darwin"
+      ? ["/opt/homebrew/opt/sqlite/include", "/usr/local/opt/sqlite/include"].find((p) =>
+          existsSync(`${p}/sqlite3ext.h`),
+        )
+      : undefined);
+  const child = Bun.spawnSync(
+    [
+      process.env.CC || "cc",
+      "-O2",
+      "-Wall",
+      "-Wextra",
+      "-Werror",
+      "-fPIC",
+      ...(process.platform === "darwin" ? ["-dynamiclib"] : ["-shared"]),
+      ...(include ? ["-I", include] : []),
+      resolve(import.meta.dir, "d1-budget.c"),
+      "-o",
+      budgetExtension,
+    ],
+    { stdout: "inherit", stderr: "inherit" },
+  );
+  if (child.exitCode !== 0)
+    throw new Error("SQL budget extension build failed; install a C compiler and SQLite development headers");
+  console.log(budgetExtension);
+}

package/src/d1-budget.c

@@ -0,0 +1,67 @@
+/* SQLite's public extension ABI. No Bun internals or additional database engine. */
+#include <sqlite3ext.h>
+#include <stdint.h>
+#include <string.h>
+#include <time.h>
+SQLITE_EXTENSION_INIT1
+
+typedef struct {
+  char key[65];
+  int initialized;
+  int64_t deadline;
+} Budget;
+
+static int64_t now_ns(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (int64_t)ts.tv_sec * 1000000000 + ts.tv_nsec;
+}
+static int progress(void *context) {
+  Budget *budget = context;
+  if (budget->deadline && now_ns() >= budget->deadline) {
+    /* One-shot interruption lets SQLite and the host finish rollback/cleanup. */
+    budget->deadline = 0;
+    return 1;
+  }
+  return 0;
+}
+static void arm(sqlite3_context *context, int argc, sqlite3_value **argv) {
+  Budget *budget = sqlite3_user_data(context);
+  const unsigned char *key = argc == 2 ? sqlite3_value_text(argv[0]) : 0;
+  if (!key || sqlite3_value_bytes(argv[0]) != 64) {
+    sqlite3_result_error(context, "invalid budget capability", -1);
+    return;
+  }
+  if (!budget->initialized) {
+    memcpy(budget->key, key, 64);
+    budget->initialized = 1;
+  }
+  unsigned char mismatch = 0;
+  for (int i = 0; i < 64; i++) mismatch |= (unsigned char)budget->key[i] ^ key[i];
+  if (mismatch) {
+    sqlite3_result_error(context, "invalid budget capability", -1);
+    return;
+  }
+  int ms = sqlite3_value_int(argv[1]);
+  if (ms < 0 || ms > 30000) {
+    sqlite3_result_error(context, "invalid SQL execution budget", -1);
+    return;
+  }
+  budget->deadline = ms ? now_ns() + (int64_t)ms * 1000000 : 0;
+  sqlite3_result_int(context, 1);
+}
+#ifdef _WIN32
+__declspec(dllexport)
+#endif
+int sqlite3_sproutbudget_init(sqlite3 *db, char **error, const sqlite3_api_routines *api) {
+  (void)error;
+  SQLITE_EXTENSION_INIT2(api);
+  Budget *budget = sqlite3_malloc(sizeof(Budget));
+  if (!budget) return SQLITE_NOMEM;
+  memset(budget, 0, sizeof(Budget));
+  int rc = sqlite3_create_function_v2(db, "sb_sql_budget", 2,
+    SQLITE_UTF8 | SQLITE_DIRECTONLY, budget, arm, 0, 0, sqlite3_free);
+  if (rc != SQLITE_OK) return rc;
+  sqlite3_progress_handler(db, 1000, progress, budget);
+  return SQLITE_OK;
+}

package/src/d1-pool.test.ts

@@ -0,0 +1,209 @@
+import { expect, test } from "bun:test";
+import { createBroker, type Frame } from "./broker";
+import { D1Pool } from "./d1-pool";
+
+const slowSql =
+  "WITH RECURSIVE t(x) AS (VALUES(0) UNION ALL SELECT x+1 FROM t WHERE x<8000000) SELECT sum(x) AS total FROM t";
+test("shared SQL leaves sibling KV and control timers responsive, preserves D1 transactions and session isolation", async () => {
+  const pool = new D1Pool(128, 16, 10_000, 10_000);
+  const a = createBroker({ d1Pool: pool, bindings: { d1: ["DB"] } });
+  const b = createBroker({ d1Pool: pool, bindings: { d1: ["DB"], kv: ["DATA"] } });
+  try {
+    expect(
+      (await a.dispatch({ op: "d1.exec", db: "DB", sql: "CREATE TABLE t(v INTEGER); INSERT INTO t VALUES(7)" })).ok,
+    ).toBe(true);
+    expect(
+      await b.dispatch({ op: "d1.query", db: "DB", sql: "SELECT * FROM t" }).then(
+        () => "unexpected success",
+        (e) => String(e),
+      ),
+    ).toContain("no such table");
+    await b.dispatch({ op: "kv.put", ns: "DATA", key: "test", value: "B" });
+    const heavy = a.dispatch({ op: "d1.query", db: "DB", sql: slowSql });
+    const start = performance.now();
+    await Bun.sleep(25);
+    expect((await b.dispatch({ op: "kv.get", ns: "DATA", key: "test" })).value).toBe("B");
+    expect(performance.now() - start).toBeLessThan(150);
+    expect((await heavy).ok).toBe(true);
+    expect(
+      await a
+        .dispatch({
+          op: "d1.batch",
+          db: "DB",
+          statements: [{ sql: "INSERT INTO t VALUES(8)" }, { sql: "INSERT INTO absent VALUES(9)" }],
+        })
+        .then(
+          () => "unexpected success",
+          (e) => String(e),
+        ),
+    ).toContain("no such table");
+    expect((await a.dispatch({ op: "d1.query", db: "DB", sql: "SELECT * FROM t" })).results).toEqual([{ v: 7 }]);
+    a.close();
+    expect((await b.dispatch({ op: "d1.exec", db: "DB", sql: "CREATE TABLE t(v); INSERT INTO t VALUES(11)" })).ok).toBe(
+      true,
+    );
+    expect((await b.dispatch({ op: "d1.query", db: "DB", sql: "SELECT * FROM t" })).results).toEqual([{ v: 11 }]);
+  } finally {
+    b.close();
+    pool.close();
+  }
+}, 15_000);
+
+test("SQL admission is bounded and queued deadlines never execute expired mutations", async () => {
+  const pool = new D1Pool(2, 2, 30, 10_000);
+  const session = pool.session();
+  const request = (sql: string) =>
+    session.execute({ key: "one", path: ":memory:", name: "DB", msg: { op: "d1.query", sql } });
+  try {
+    const active = request(slowSql);
+    const expired = request("CREATE TABLE must_not_exist(v)");
+    const rejected = expect(request("SELECT 1")).rejects.toThrow("capacity exceeded");
+    await expect(expired).rejects.toThrow("queue deadline exceeded");
+    await rejected;
+    await active;
+    const result = await request("SELECT count(*) AS n FROM sqlite_master WHERE name='must_not_exist'");
+    expect(result.results).toEqual([{ n: 0 }]);
+  } finally {
+    session.close();
+    pool.close();
+  }
+}, 15_000);
+
+test("SQL lanes rotate all waiting sessions instead of alternating only two noisy sessions", async () => {
+  const pool = new D1Pool(128, 16, 10_000, 10_000);
+  const sessions = [pool.session(), pool.session(), pool.session()];
+  const order: string[] = [];
+  const submit = (owner: number, sql: string, label: string) =>
+    sessions[owner]!.execute({
+      key: "same-lane",
+      path: ":memory:",
+      name: "DB",
+      msg: { op: "d1.query", sql },
+    }).then(() => {
+      order.push(label);
+    });
+  try {
+    const work = [submit(0, slowSql, "active")];
+    for (let owner = 0; owner < 3; owner++) {
+      work.push(submit(owner, "SELECT 1", `${owner}:1`), submit(owner, "SELECT 2", `${owner}:2`));
+    }
+    await Promise.all(work);
+    expect(order).toEqual(["active", "0:1", "1:1", "2:1", "0:2", "1:2", "2:2"]);
+  } finally {
+    for (const session of sessions) session.close();
+    pool.close();
+  }
+}, 15_000);
+
+test("unexpected SQL thread loss fails closed and notifies broker supervision", async () => {
+  const pool = new D1Pool(128, 16, 10_000, 10_000);
+  const session = pool.session();
+  const request = () =>
+    session.execute({ key: "failure", path: ":memory:", name: "DB", msg: { op: "d1.query", sql: "SELECT 1" } });
+  let signal!: () => void;
+  const failed = new Promise<void>((resolve) => {
+    signal = resolve;
+  });
+  pool.onFailure = signal;
+  try {
+    await request();
+    // SAFETY: fault injection into this test's own private worker, never a shared process.
+    // oxlint-disable-next-line anti-slop/no-chained-type-assertions, anti-slop/no-known-value-widening -- Deliberate private-state fault injection avoids adding a production test API.
+    const lanes = (pool as unknown as { lanes: Array<{ worker?: Worker }> }).lanes;
+    lanes.find((lane) => lane.worker)!.worker!.terminate();
+    await failed;
+    expect(
+      await request().then(
+        () => "unexpected success",
+        (e) => String(e),
+      ),
+    ).toContain("session closed");
+  } finally {
+    session.close();
+    pool.close();
+  }
+}, 5000);
+
+test("running SQL is interrupted, batch writes roll back, and the same lane recovers without replay", async () => {
+  const pool = new D1Pool(128, 16, 10_000, 50);
+  const session = pool.session();
+  const peer = pool.session();
+  const run = (msg: Frame) => session.execute({ key: "deadline", path: ":memory:", name: "DB", msg });
+  try {
+    await run({ op: "d1.exec", sql: "CREATE TABLE writes(v INTEGER)" });
+    const started = performance.now();
+    const interrupted = run({
+      op: "d1.batch",
+      statements: [{ sql: "INSERT INTO writes VALUES(1)" }, { sql: slowSql }, { sql: "INSERT INTO writes VALUES(2)" }],
+    }).then(
+      () => "unexpected success",
+      (error) => String(error),
+    );
+    const queuedPeer = peer.execute({
+      key: "deadline",
+      path: ":memory:",
+      name: "DB",
+      msg: { op: "d1.query", sql: "SELECT 42 AS n" },
+    });
+    expect(await interrupted).toContain("execution deadline exceeded");
+    expect((await queuedPeer).results).toEqual([{ n: 42 }]);
+    expect(performance.now() - started).toBeLessThan(500);
+    expect((await run({ op: "d1.query", sql: "SELECT * FROM writes" })).results).toEqual([]);
+    await run({ op: "d1.query", sql: "INSERT INTO writes VALUES(3)" });
+    expect((await run({ op: "d1.query", sql: "SELECT * FROM writes" })).results).toEqual([{ v: 3 }]);
+    expect(
+      await run({ op: "d1.query", sql: "SELECT sb_sql_budget(?, 30000)", params: ["0".repeat(64)] }).then(
+        () => "unexpected success",
+        (error) => String(error),
+      ),
+    ).toContain("invalid budget capability");
+    expect(
+      await run({ op: "d1.query", sql: "SELECT load_extension('untrusted')" }).then(
+        () => "unexpected success",
+        (error) => String(error),
+      ),
+    ).toContain("not authorized");
+    expect(
+      await run({ op: "d1.query", sql: slowSql }).then(
+        () => "unexpected success",
+        (error) => String(error),
+      ),
+    ).toContain("execution deadline exceeded");
+  } finally {
+    session.close();
+    peer.close();
+    pool.close();
+  }
+}, 5000);
+
+test("watchdog revokes a broker stuck in SQLite lock wait and does not commit or replay its write", async () => {
+  const { Database } = await import("bun:sqlite");
+  const { mkdtempSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const dir = mkdtempSync(join(tmpdir(), "sb-budget-lock-"));
+  const path = join(dir, "locked.sqlite");
+  const db = new Database(path);
+  db.exec("PRAGMA journal_mode=WAL; CREATE TABLE writes(v); BEGIN IMMEDIATE");
+  const script = `import {D1Pool} from ${JSON.stringify(join(import.meta.dir, "d1-pool.ts"))};
+    const pool=new D1Pool(128,16,10000,50);
+    pool.onFailure=()=>process.exit(1);
+    await pool.session().execute({key:${JSON.stringify(path)},path:${JSON.stringify(path)},name:"DB",msg:{op:"d1.exec",sql:"PRAGMA busy_timeout=600000; INSERT INTO writes VALUES(1)"}}).catch(()=>{});`;
+  const child = Bun.spawn([process.execPath, "-e", script], { stdout: "ignore", stderr: "pipe" });
+  const started = performance.now();
+  const timeout = setTimeout(() => child.kill(9), 4000);
+  try {
+    expect(await child.exited).toBe(1);
+    expect(performance.now() - started).toBeLessThan(2500);
+    db.exec("ROLLBACK");
+    expect(db.query("SELECT * FROM writes").all()).toEqual([]);
+    db.exec("INSERT INTO writes VALUES(2)");
+    expect(db.query("SELECT * FROM writes").all()).toEqual([{ v: 2 }]);
+  } finally {
+    clearTimeout(timeout);
+    child.kill(9);
+    await child.exited;
+    db.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}, 5000);

package/src/d1-pool.ts

@@ -0,0 +1,156 @@
+import "./d1-sqlite";
+import { randomBytes } from "node:crypto";
+import type { D1Request } from "./d1";
+import type { Frame } from "./broker";
+
+type Job = {
+  request: D1Request;
+  resolve: (value: Frame) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+type Lane = { worker?: Worker; active?: Job; queue: Job[]; owners: string[] };
+/** Bounded SQL threads per broker process, created only when D1 is used.
+ * Database affinity preserves in-memory data and connection-local SQL state.
+ * Queues rotate sessions; SQLite interrupts long statements through its progress hook.
+ */
+export class D1Pool {
+  /** Fatal SQL-thread loss revokes the hosting broker, never replaying uncertain SQL. */
+  onFailure?: (error: Error) => void;
+  private lanes: Lane[] = [
+    { queue: [], owners: [] },
+    { queue: [], owners: [] },
+  ];
+  private closed = false;
+  private sequence = 0;
+  private capability = "";
+  constructor(
+    private readonly queueLimit = 128,
+    private readonly ownerLimit = 16,
+    private readonly queueTimeoutMs = 10_000,
+    private readonly executionMs = Number(process.env.SPROUTBOAT_D1_EXECUTION_MS ?? 1000),
+  ) {
+    if (!Number.isSafeInteger(executionMs) || executionMs < 10 || executionMs > 30_000)
+      throw new Error("invalid D1 execution budget (10..30000 ms)");
+  }
+  session() {
+    const owner = String(++this.sequence);
+    let closed = false;
+    return {
+      execute: (request: Omit<D1Request, "owner">): Promise<Frame> => {
+        if (closed || this.closed) return Promise.reject(new Error("D1 session closed"));
+        // Stable affinity also covers resources shared by multiple sessions.
+        let hash = 2166136261;
+        for (let i = 0; i < request.key.length; i++) hash = Math.imul(hash ^ request.key.charCodeAt(i), 16777619);
+        const lane = this.lanes[(hash >>> 0) % this.lanes.length]!;
+        if (request.path === ":memory:") request = { ...request, key: `${owner}:${request.key}` };
+        const jobs = this.lanes.flatMap((l) => (l.active ? [...l.queue, l.active] : l.queue));
+        if (jobs.length >= this.queueLimit || jobs.filter((j) => j.request.owner === owner).length >= this.ownerLimit)
+          return Promise.reject(new Error("D1 capacity exceeded"));
+        return new Promise((resolve, reject) => {
+          const job: Job = {
+            request: { ...request, owner },
+            resolve,
+            reject,
+            timer: setTimeout(() => {
+              const index = lane.queue.indexOf(job);
+              if (index !== -1) {
+                lane.queue.splice(index, 1);
+                if (!lane.queue.some((j) => j.request.owner === owner))
+                  lane.owners = lane.owners.filter((id) => id !== owner);
+                reject(new Error("D1 queue deadline exceeded"));
+              }
+            }, this.queueTimeoutMs),
+          };
+          if (!lane.owners.includes(owner)) lane.owners.push(owner);
+          lane.queue.push(job);
+          this.pump(lane);
+        });
+      },
+      close: () => {
+        if (closed) return;
+        closed = true;
+        for (const lane of this.lanes) {
+          for (const job of lane.queue.filter((j) => j.request.owner === owner)) {
+            clearTimeout(job.timer);
+            job.reject(new Error("D1 session closed"));
+          }
+          lane.queue = lane.queue.filter((j) => j.request.owner !== owner);
+          lane.owners = lane.owners.filter((id) => id !== owner);
+          // The active statement may already have committed. Never retry it.
+          lane.worker?.postMessage({ op: "release", owner });
+        }
+      },
+    };
+  }
+  private pump(lane: Lane) {
+    if (lane.active || !lane.queue.length || this.closed) return;
+    if (!lane.worker) {
+      const worker = new Worker(new URL("./d1-worker.ts", import.meta.url).href, { smol: true });
+      lane.worker = worker;
+      worker.onmessage = (event: MessageEvent<{ ok: boolean; value: Frame; error: string }>) => {
+        const job = lane.active;
+        if (!job) return;
+        clearTimeout(job.timer);
+        lane.active = undefined;
+        if (event.data.ok) job.resolve(event.data.value);
+        else job.reject(new Error(event.data.error));
+        this.pump(lane);
+      };
+      const failed = () => {
+        if (lane.worker !== worker) return;
+        lane.worker = undefined;
+        const jobs = lane.active ? [lane.active, ...lane.queue] : lane.queue;
+        lane.active = undefined;
+        lane.queue = [];
+        lane.owners = [];
+        for (const job of jobs) {
+          clearTimeout(job.timer);
+          job.reject(new Error("D1 worker lost; SQL outcome unknown"));
+        }
+        // Fail closed: lost in-memory databases must never silently become empty.
+        worker.terminate();
+        this.close();
+        this.onFailure?.(new Error("D1 worker lost; SQL outcome unknown"));
+      };
+      worker.addEventListener("error", failed);
+      worker.addEventListener("close", failed);
+    }
+    const owner = lane.owners.shift()!;
+    const index = lane.queue.findIndex((j) => j.request.owner === owner);
+    const job = lane.queue.splice(index, 1)[0]!;
+    if (lane.queue.some((j) => j.request.owner === owner)) lane.owners.push(owner);
+    clearTimeout(job.timer);
+    lane.active = job;
+    // Native progress interrupts VM work. This watchdog also bounds operations
+    // that do not poll progress (locks, native allocation, or stalled I/O).
+    // Revoke the broker instead of claiming an uncertain mutation rolled back.
+    job.timer = setTimeout(() => {
+      if (lane.active !== job) return;
+      this.close();
+      this.onFailure?.(new Error("D1 execution watchdog expired; SQL outcome unknown"));
+    }, this.executionMs + 1000);
+    this.capability ||= randomBytes(32).toString("hex");
+    lane.worker.postMessage({
+      op: "run",
+      executionMs: this.executionMs,
+      capability: this.capability,
+      request: job.request,
+    });
+  }
+  close() {
+    this.closed = true;
+    for (const lane of this.lanes) {
+      for (const job of lane.active ? [lane.active, ...lane.queue] : lane.queue) {
+        clearTimeout(job.timer);
+        job.reject(new Error("D1 pool closed; active SQL outcome unknown"));
+      }
+      lane.active = undefined;
+      lane.queue = [];
+      lane.owners = [];
+      const worker = lane.worker;
+      lane.worker = undefined;
+      worker?.terminate();
+    }
+  }
+}

package/src/d1-sqlite.ts

@@ -0,0 +1,14 @@
+/** Bun shares its SQLite library across threads: select it before any DB opens. */
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+export function configureBudgetSQLite() {
+  if (process.platform !== "darwin") return;
+  const library =
+    process.env.SPROUTBOAT_D1_SQLITE_LIBRARY ||
+    ["/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib", "/usr/local/opt/sqlite/lib/libsqlite3.dylib"].find(existsSync);
+  if (!library)
+    throw new Error("Shared SQL budgets need extension-capable SQLite on macOS; set SPROUTBOAT_D1_SQLITE_LIBRARY");
+  Database.setCustomSQLite(library);
+}
+// Also used as the package test preload, before dedicated-broker tests open DBs.
+configureBudgetSQLite();

package/src/d1-worker.ts

@@ -0,0 +1,22 @@
+/** Private messages only: paths and identities are supplied by the broker. */
+import { createD1Store, type D1Request } from "./d1";
+declare var self: Worker;
+let store: ReturnType<typeof createD1Store> | undefined;
+self.onmessage = (
+  event: MessageEvent<
+    { op: "run"; executionMs: number; capability: string; request: D1Request } | { op: "release"; owner: string }
+  >,
+) => {
+  const message = event.data;
+  if (message.op === "release") {
+    store?.release(message.owner);
+    return;
+  }
+  try {
+    store ??= createD1Store(message.executionMs, message.capability);
+    postMessage({ ok: true, value: store.execute(message.request) });
+  } catch (error) {
+    postMessage({ ok: false, error: error instanceof Error ? error.message : String(error) });
+  }
+};
+process.on("exit", () => store?.close());

package/src/d1.ts

@@ -0,0 +1,164 @@
+/** D1's synchronous storage contract, shared by dedicated and SQL-worker modes. */
+import { budgetExtension } from "./build-d1-budget";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { isBoolean, isString, jsonObject, type JsonObject, type JsonValue } from "./json";
+import type { Frame } from "./broker";
+
+const isNumber = (value: JsonValue): value is number => Number.isFinite(value);
+type SqlParam = string | number | null;
+const str = (v: JsonValue | undefined) => (isString(v) ? v : String(v ?? ""));
+const params = (v: JsonValue | undefined): SqlParam[] =>
+  Array.isArray(v)
+    ? v.map((p) => (p === null || isNumber(p) || isString(p) ? p : isBoolean(p) ? Number(p) : String(p)))
+    : [];
+export type D1Request = { owner: string; key: string; path: string; name: string; msg: Frame };
+
+export function createD1Store(executionMs = 0, capability = "") {
+  if (executionMs && !/^[a-f0-9]{64}$/.test(capability)) throw new Error("invalid host budget capability");
+  const connections = new Map<string, { db: Database; owners: Set<string> }>();
+  const run = (db: Database, sql: string, values: SqlParam[]) => {
+    const started = performance.now();
+    const results = db.query<JsonObject, SqlParam[]>(sql).all(...values);
+    const meta = db
+      .query<{ changes: number; last_row_id: number }, []>(
+        "SELECT changes() AS changes, last_insert_rowid() AS last_row_id",
+      )
+      .get();
+    return {
+      results,
+      meta: {
+        duration: performance.now() - started,
+        changes: meta?.changes ?? 0,
+        last_row_id: meta?.last_row_id ?? 0,
+        rows_read: results.length,
+      },
+    };
+  };
+  return {
+    execute({ owner, key, path, name, msg }: D1Request): Frame {
+      let entry = connections.get(key);
+      if (!entry) {
+        if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+        const db = new Database(path, { create: true });
+        db.exec("PRAGMA journal_mode = WAL");
+        db.exec("PRAGMA synchronous = NORMAL");
+        if (executionMs) {
+          try {
+            db.loadExtension(
+              process.env.SPROUTBOAT_D1_BUDGET_EXTENSION || budgetExtension,
+              "sqlite3_sproutbudget_init",
+            );
+            db.query("SELECT sb_sql_budget(?, ?)").get(capability, 0);
+          } catch (error) {
+            db.close();
+            throw new Error(`SQL budget extension unavailable; run wire build:sql-budget: ${String(error)}`);
+          }
+        }
+        entry = { db, owners: new Set() };
+        connections.set(key, entry);
+      }
+      entry.owners.add(owner);
+      const db = entry.db;
+      const deadline = performance.now() + executionMs;
+      const guard = executionMs ? db.query("SELECT sb_sql_budget(?, ?)") : null;
+      guard?.get(capability, executionMs);
+      const disarm = () => {
+        try {
+          guard?.get(capability, 0);
+        } catch (error) {
+          // The expired one-shot callback can interrupt the cleanup SELECT itself.
+          if (error instanceof Error && "code" in error && error.code === "SQLITE_INTERRUPT") guard?.get(capability, 0);
+          else throw error;
+        }
+      };
+      try {
+        switch (msg.op) {
+          case "d1.query":
+            return { ok: true, ...run(db, str(msg.sql), params(msg.params)) };
+          case "d1.exec":
+            db.exec(str(msg.sql));
+            return { ok: true };
+          case "d1.batch": {
+            const statements = Array.isArray(msg.statements) ? msg.statements.map((s) => jsonObject(s) ?? {}) : [];
+            return {
+              ok: true,
+              results: db.transaction(() =>
+                statements.map((s) => {
+                  if (executionMs && performance.now() >= deadline)
+                    throw new Error("D1 execution deadline exceeded; batch rolled back");
+                  return run(db, str(s.sql), params(s.params));
+                }),
+              )(),
+            };
+          }
+          case "d1.backup": {
+            if (path === ":memory:") throw new Error("d1 backup needs a file-backed database");
+            const requested = str(msg.name);
+            const file = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(requested)
+              ? requested
+              : `${name}-${new Date().toISOString().replace(/[:.]/g, "-")}.sqlite`;
+            const dir = join(dirname(dirname(resolve(path))), "backups");
+            mkdirSync(dir, { recursive: true });
+            const dest = join(dir, file);
+            if (existsSync(dest)) rmSync(dest);
+            try {
+              db.run("VACUUM INTO ?", [dest]);
+            } catch (error) {
+              rmSync(dest, { force: true });
+              throw error;
+            }
+            const copy = new Database(dest, { readonly: true });
+            try {
+              if (executionMs) {
+                const remaining = Math.floor(deadline - performance.now());
+                if (remaining <= 0) throw new Error("D1 execution deadline exceeded during backup");
+                copy.loadExtension(
+                  process.env.SPROUTBOAT_D1_BUDGET_EXTENSION || budgetExtension,
+                  "sqlite3_sproutbudget_init",
+                );
+                copy.query("SELECT sb_sql_budget(?, ?)").get(capability, remaining);
+              }
+              if (
+                copy.query<{ integrity_check: string }, []>("PRAGMA integrity_check").get()?.integrity_check !== "ok"
+              ) {
+                rmSync(dest, { force: true });
+                throw new Error("integrity check failed on the backup");
+              }
+            } catch (error) {
+              rmSync(dest, { force: true });
+              throw error;
+            } finally {
+              copy.close();
+            }
+            return { ok: true, path: dest, bytes: statSync(dest).size };
+          }
+          default:
+            throw new Error("unknown D1 operation");
+        }
+      } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "SQLITE_INTERRUPT")
+          throw new Error(
+            `D1 execution deadline exceeded; SQL was not retried${msg.op === "d1.exec" ? "; earlier exec statements may have committed" : ""}`,
+          );
+        throw error;
+      } finally {
+        disarm();
+      }
+    },
+    release(owner: string) {
+      for (const [key, entry] of connections) {
+        entry.owners.delete(owner);
+        if (!entry.owners.size) {
+          entry.db.close();
+          connections.delete(key);
+        }
+      }
+    },
+    close() {
+      for (const entry of connections.values()) entry.db.close();
+      connections.clear();
+    },
+  };
+}