@vibeorm/adapter-bun 2.4.1 → 4.0.0

package/dist/index.js

@@ -2,39 +2,57 @@
 // packages/adapter-bun/src/driver.ts
 var {SQL } = globalThis.Bun;
 function createBunSql(params) {
-  return params.url === undefined ? new SQL(params.options) : new SQL(params.url, params.options);
+  return new SQL(params.url, params.options);
 }
 
 // packages/adapter-bun/src/config.ts
+var MINIMUM_BUN_VERSION = "1.4.1";
+var MAX_BIND_PARAMETERS = 65535;
 var SESSION_CONNECTION = Object.freeze({
   max: 1,
   closeGraceSeconds: 0.001
 });
 
+// packages/adapter-bun/src/bun-version.ts
+import { VibeError } from "@vibeorm/schema";
+function refuseUnsupportedBun(params) {
+  if (Bun.semver.satisfies(params.version, `>=${MINIMUM_BUN_VERSION}`))
+    return;
+  throw new VibeError({
+    code: "VIBE_CONFIG",
+    message: `@vibeorm/adapter-bun requires Bun ${MINIMUM_BUN_VERSION} or newer (running ${params.version}): older bun:sql ` + "releases hang after COPY, read timestamps without a time zone in host-local time and turn infinity dates into Invalid Date. " + "Upgrade Bun, or use @vibeorm/adapter-pg.",
+    meta: { bunVersion: params.version, minimumBunVersion: MINIMUM_BUN_VERSION }
+  });
+}
+
 // packages/adapter-bun/src/index.ts
 import { postgresDialect, renderDiagnostic } from "@vibeorm/sql";
 import {
   abortTransactionOnServerFailure,
+  createDeferredControl,
   observeRowChanges,
   readRowChanges,
   statementRowChanges,
-  markSavepointOpened,
+  createAdapterLifecycleGate,
   runPinnedSession,
+  runShutdownCleanup,
+  transactionLifecycleRefusal,
   createSavepointScope,
-  savepointRollbackFailedError,
   engineStatementBudgetMs,
-  isTransactionDeadlineError,
+  markTransactionAborted,
   runNestedSavepoint,
   runRootScope,
   scopeTurn,
+  settleFailedTransaction,
   startTransactionBudget,
-  transactionOutcomeUnknownError,
-  validateTransactionDeadline
+  transactionAbortedError,
+  validateTransactionDeadline,
+  readOnlyRequested
 } from "@vibeorm/runtime/adapter-kit";
-import { VibeError as VibeError6 } from "@vibeorm/schema";
+import { VibeError as VibeError7 } from "@vibeorm/schema";
 
 // packages/adapter-bun/src/connection-url.ts
-import { VibeError } from "@vibeorm/schema";
+import { VibeError as VibeError2 } from "@vibeorm/schema";
 function buildStartupOptions(params) {
   const { planCacheMode, statementTimeout } = params;
   const parts = [];
@@ -42,7 +60,7 @@ function buildStartupOptions(params) {
     parts.push(`-c plan_cache_mode=${planCacheMode}`);
   if (statementTimeout !== undefined) {
     if (!Number.isInteger(statementTimeout) || statementTimeout < 0) {
-      throw new VibeError({
+      throw new VibeError2({
         code: "VIBE_VALIDATION",
         message: `statementTimeout must be a non-negative integer of milliseconds, received ${String(statementTimeout)}`,
         meta: { statementTimeout }
@@ -52,9 +70,28 @@ function buildStartupOptions(params) {
   }
   return parts.length === 0 ? undefined : parts.join(" ");
 }
+function takeConnectTimeout(params) {
+  if (!URL.canParse(params.url))
+    return { url: params.url };
+  const url = new URL(params.url);
+  const raw = url.searchParams.get("connect_timeout");
+  if (raw === null)
+    return { url: params.url };
+  const seconds = Number(raw.trim());
+  if (raw.trim() === "" || !Number.isInteger(seconds)) {
+    throw new VibeError2({
+      code: "VIBE_VALIDATION",
+      message: `connect_timeout in the connection URL must be an integer number of seconds, received "${raw}"`,
+      meta: { connectTimeout: raw }
+    });
+  }
+  url.searchParams.delete("connect_timeout");
+  url.search = url.searchParams.toString().replace(/\+/g, "%20");
+  return seconds > 0 ? { url: url.toString(), seconds } : { url: url.toString() };
+}
 function applyStartupOptions(params) {
   if (!URL.canParse(params.url)) {
-    throw new VibeError({ code: "VIBE_VALIDATION", message: "invalid PostgreSQL connection URL" });
+    throw new VibeError2({ code: "VIBE_VALIDATION", message: "invalid PostgreSQL connection URL" });
   }
   const url = new URL(params.url);
   const merged = [...url.searchParams.getAll("options"), params.startupOptions].filter(Boolean).join(" ");
@@ -64,7 +101,7 @@ function applyStartupOptions(params) {
 }
 
 // packages/adapter-bun/src/errors.ts
-import { VibeError as VibeError2 } from "@vibeorm/schema";
+import { VibeError as VibeError3 } from "@vibeorm/schema";
 var BUN_SQLSTATE_ERROR_CODES = Object.freeze({
   "23P01": "VIBE_EXCLUSION_VIOLATION",
   "23505": "VIBE_UNIQUE_VIOLATION",
@@ -81,16 +118,18 @@ var BUN_SQLSTATE_ERROR_CODES = Object.freeze({
   "40001": "VIBE_TRANSACTION",
   "40P01": "VIBE_TRANSACTION",
   "57014": "VIBE_TRANSACTION",
-  "55P03": "VIBE_LOCK_NOT_AVAILABLE"
+  "55P03": "VIBE_LOCK_NOT_AVAILABLE",
+  "25006": "VIBE_TRANSACTION"
 });
 var BUN_SQLSTATE_REASONS = Object.freeze({
   "23P01": "exclusion-violation",
   "57014": "timeout",
   "55P03": "lock-not-available",
   "40P01": "deadlock",
-  "40001": "serialization-failure"
+  "40001": "serialization-failure",
+  "25006": "read-only-transaction"
 });
-var SQLSTATE_PATTERN = /^[0-9A-Z]{5}$/;
+var SQLSTATE_PATTERN = /^(?=[A-Z]*\d)[0-9A-Z]{5}$/;
 function readStringField(params) {
   const value = params.source[params.key];
   return typeof value === "string" && value.length > 0 ? value : undefined;
@@ -109,7 +148,7 @@ function bunErrorSqlstate(params) {
 }
 function mapBunDriverError(params) {
   const { error } = params;
-  if (error instanceof VibeError2)
+  if (error instanceof VibeError3)
     return error;
   const source = error !== null && typeof error === "object" ? error : {};
   const sqlstate = bunErrorSqlstate({ error });
@@ -133,7 +172,7 @@ function mapBunDriverError(params) {
   if (driverCode !== undefined && driverCode !== sqlstate)
     meta.driverCode = driverCode;
   const message = readStringField({ source, key: "message" }) ?? (typeof error === "string" ? error : "unknown bun:sql driver error");
-  return new VibeError2({ code, message, meta, cause: error });
+  return new VibeError3({ code, message, meta, cause: error });
 }
 async function runMapped(fn) {
   try {
@@ -144,7 +183,8 @@ async function runMapped(fn) {
 }
 
 // packages/adapter-bun/src/params.ts
-import { VibeError as VibeError3 } from "@vibeorm/schema";
+import { Buffer } from "buffer";
+import { VibeError as VibeError4 } from "@vibeorm/schema";
 function quoteElement(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
 }
@@ -157,8 +197,11 @@ function toPgArrayLiteral(values) {
     }
     if (value instanceof Date)
       return quoteElement(value.toISOString());
+    if (value instanceof Uint8Array) {
+      return quoteElement(`\\x${Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString("hex")}`);
+    }
     if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
-      throw new VibeError3({
+      throw new VibeError4({
         code: "VIBE_VALIDATION",
         message: "binary values are not supported inside a postgres array literal",
         meta: { driver: "bun:sql" }
@@ -181,21 +224,31 @@ function serializeDate(params) {
     return value;
   return value.toISOString();
 }
+function serializeScalar(value) {
+  if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean")
+    return String(value);
+  if (value instanceof Date)
+    return serializeDate({ value });
+  return value;
+}
+function isJsonDocument(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Date) && !ArrayBuffer.isView(value) && !(value instanceof ArrayBuffer);
+}
 function serializeParams(params) {
-  return params.values.map((value) => value instanceof Date ? serializeDate({ value }) : value);
+  const stringifyDocuments = params.namedStatements !== true;
+  return params.values.map((value) => stringifyDocuments && isJsonDocument(value) ? JSON.stringify(value) : serializeScalar(value));
 }
 function serializeParamsRaw(params) {
+  const stringifyDocuments = params.namedStatements !== true;
   return params.values.map((value) => {
     if (Array.isArray(value))
       return toPgArrayLiteral(value);
-    if (value instanceof Date)
-      return serializeDate({ value });
-    return value;
+    return stringifyDocuments && isJsonDocument(value) ? JSON.stringify(value) : serializeScalar(value);
   });
 }
 
 // packages/adapter-bun/src/template-cache.ts
-import { VibeError as VibeError4 } from "@vibeorm/schema";
+import { VibeError as VibeError5 } from "@vibeorm/schema";
 function isIdentChar(char) {
   if (char === undefined)
     return false;
@@ -292,7 +345,7 @@ function scanPlaceholders(params) {
   }
   chunks.push(text.slice(chunkStart));
   const template = Object.assign(chunks, { raw: chunks });
-  return { template, indices };
+  return { template, indices, identityOrder: indices.every((placeholder, index) => placeholder === index + 1) };
 }
 function templateChunks(params) {
   return [...scanPlaceholders(params).template];
@@ -301,7 +354,7 @@ function bindTemplateValues(params) {
   const { text, indices, values } = params;
   return indices.map((placeholder) => {
     if (placeholder < 1 || placeholder > values.length) {
-      throw new VibeError4({
+      throw new VibeError5({
         code: "VIBE_VALIDATION",
         message: `bun:sql prepared statement references $${placeholder} but only ${values.length} parameter(s) were given`,
         meta: { text, placeholder, provided: values.length }
@@ -338,7 +391,7 @@ function createTemplateCache(params) {
 }
 
 // packages/adapter-bun/src/transaction-sql.ts
-import { VibeError as VibeError5 } from "@vibeorm/schema";
+import { VibeError as VibeError6 } from "@vibeorm/schema";
 import { refuseNestedTransactionOptions } from "@vibeorm/runtime/adapter-kit";
 var ISOLATION_LEVEL_SQL = Object.freeze({
   ReadCommitted: "READ COMMITTED",
@@ -346,13 +399,23 @@ var ISOLATION_LEVEL_SQL = Object.freeze({
   Serializable: "SERIALIZABLE"
 });
 function beginStatement(params) {
-  const { isolationLevel } = params;
-  return isolationLevel === undefined ? "BEGIN" : `BEGIN ISOLATION LEVEL ${ISOLATION_LEVEL_SQL[isolationLevel]}`;
+  const { isolationLevel, readOnly } = params;
+  const modes = [];
+  if (isolationLevel !== undefined)
+    modes.push(`ISOLATION LEVEL ${ISOLATION_LEVEL_SQL[isolationLevel]}`);
+  if (readOnly === true)
+    modes.push("READ ONLY");
+  return modes.length === 0 ? "BEGIN" : `BEGIN ${modes.join(", ")}`;
+}
+function openTransactionStatement(params) {
+  const begin = beginStatement(params);
+  return params.timeout === undefined ? begin : `${begin}; ${statementTimeoutStatement({ timeout: params.timeout })}`;
 }
+var STATEMENT_BOUND_TEXT = "SELECT set_config('statement_timeout', $1, true)";
 function statementTimeoutStatement(params) {
   const { timeout } = params;
   if (!Number.isInteger(timeout) || timeout < 0) {
-    throw new VibeError5({
+    throw new VibeError6({
       code: "VIBE_VALIDATION",
       message: `transaction timeout must be a non-negative integer of milliseconds, received ${String(timeout)}`,
       meta: { timeout }
@@ -375,78 +438,176 @@ import { createSavepointCounter, nextSavepointName } from "@vibeorm/runtime/adap
 import {
   DEFAULT_DEADLINE_CLOCK,
   engineStatementBudgetMs as engineStatementBudgetMs2,
-  isTransactionDeadlineError as isTransactionDeadlineError2,
+  isTransactionDeadlineError,
   startTransactionBudget as startTransactionBudget2,
   transactionClosedError,
   transactionDeadlineError,
-  transactionOutcomeUnknownError as transactionOutcomeUnknownError2,
+  transactionOutcomeUnknownError,
   validateTransactionDeadline as validateTransactionDeadline2
 } from "@vibeorm/runtime/adapter-kit";
-
-class CallbackError extends Error {
-  inner;
-  constructor(inner) {
-    super("vibeorm: transaction callback failed");
-    this.name = "CallbackError";
-    this.inner = inner;
-  }
-}
+var ignore = () => {
+  return;
+};
 var DIALECT = "postgres";
 var PROVIDER = "postgresql";
 var BUDGETS = Object.freeze({
   acquireTimeout: false,
   statementTimeout: "all-statements",
-  transactionDeadline: "cancel-running-statements"
+  transactionDeadline: "cancel-running-statements",
+  accessModes: Object.freeze(["readOnly"])
 });
 var WIRE_TEXT = Object.freeze({ dateTime: "native", json: "text", numbers: "native" });
 var WIRE_PARSED = Object.freeze({ dateTime: "native", json: "parsed", numbers: "native" });
+var ROUND_TRIPS = "network";
+function requireUrl(params) {
+  const url = params.options?.url;
+  if (typeof url === "string" && url.trim() !== "")
+    return url;
+  throw new VibeError7({
+    code: "VIBE_CONFIG",
+    message: "bunAdapter needs an explicit address: pass `url` (a PostgreSQL URL). " + "The adapter does not read DATABASE_URL, POSTGRES_URL or the PG* environment variables.",
+    meta: { adapter: "bun", reason: "missing-address" }
+  });
+}
 function bunAdapter(options) {
+  refuseUnsupportedBun({ version: Bun.version });
   const usePrepared = options?.preparedStatements ?? false;
+  const address = takeConnectTimeout({ url: requireUrl({ options }) });
   const templates = createTemplateCache({ max: options?.stmtCacheMax ?? 1000 });
   let activeWire = WIRE_TEXT;
   let wireSettled = false;
   let wireProbe = null;
   let instance = null;
-  const deadlineTurns = new WeakMap;
-  function budgetTurn(params) {
-    const { source, budget, body, guard } = params;
-    const run = async () => {
-      if (params.cleanup === true)
-        return body();
-      budget?.assertUsable({ stage: params.stage ?? "statement" });
-      guard?.();
-      const ms = budget === undefined ? null : engineStatementBudgetMs({ budget });
-      if (ms !== null) {
-        await runMapped(() => source.unsafe(statementTimeoutStatement({ timeout: ms })));
-        budget?.assertUsable({ stage: params.stage ?? "statement" });
-        guard?.();
+  const controlTemplates = createTemplateCache({ max: 64 });
+  function controlQuery(params) {
+    return params.connection(controlTemplates.getTemplate({ text: params.text }).template, ...params.values ?? []);
+  }
+  function createReservedControl(params) {
+    const { reserved, budget, scope } = params;
+    const deferred = createDeferredControl({ opening: params.opening === null ? [] : [params.opening] });
+    let openingFailure;
+    let openingStep = null;
+    let openingPending = null;
+    let waitTail = null;
+    let deadlineTail = Promise.resolve();
+    let lastFailure;
+    const step = (query) => new Promise((resolve) => resolve(query())).then(undefined, (error) => {
+      const mapped = mapBunDriverError({ error });
+      if (mapped.meta.sqlstate === "25P02") {
+        throw transactionAbortedError({ cause: lastFailure ?? scope.state.aborted?.cause });
       }
-      return body();
+      if (typeof mapped.meta.sqlstate === "string")
+        lastFailure = mapped;
+      throw mapped;
+    });
+    const trackOpening = (sent) => {
+      openingStep = sent;
+      const settled = sent.then(ignore, (error) => {
+        openingFailure = mapBunDriverError({ error });
+      }).then(() => {
+        if (openingPending === settled) {
+          openingPending = null;
+          openingStep = null;
+        }
+      });
+      openingPending = settled;
+      return settled;
+    };
+    const ridesOpening = (send) => send.extended && send.effect === "read";
+    const sendNow = (send) => {
+      const cleanup = send.cleanup === true;
+      if (!cleanup) {
+        if (openingFailure !== undefined)
+          throw transactionAbortedError({ cause: openingFailure });
+        budget.assertUsable({ stage: send.stage ?? "statement" });
+        send.guard?.();
+      }
+      const carriesOpening = !cleanup && !deferred.opened();
+      const control = cleanup ? [] : [...deferred.take()];
+      if (carriesOpening && !ridesOpening(send)) {
+        const [opening, ...rest] = control;
+        const confirmed = trackOpening(step(() => controlQuery({ connection: reserved, text: opening })));
+        const riding = rest.map((text) => {
+          const sent = step(() => controlQuery({ connection: reserved, text }));
+          sent.catch(ignore);
+          return sent;
+        });
+        const next = { ...send, riding };
+        if (budget.totalMs !== null)
+          return confirmed.then(() => sendNow(next));
+        return enqueue(next);
+      }
+      const ms = cleanup ? null : engineStatementBudgetMs({ budget });
+      const steps = [...send.riding ?? []];
+      if (!cleanup && !carriesOpening && openingStep !== null)
+        steps.push(openingStep);
+      control.forEach((text, index) => {
+        const sent = step(() => controlQuery({ connection: reserved, text }));
+        if (index === 0 && carriesOpening)
+          trackOpening(sent);
+        steps.push(sent);
+      });
+      if (ms !== null)
+        steps.push(step(() => controlQuery({ connection: reserved, text: STATEMENT_BOUND_TEXT, values: [String(ms)] })));
+      const statement = step(() => send.send(reserved));
+      steps.push(statement);
+      return Promise.allSettled(steps).then((settled) => {
+        const failed = settled.find((outcome) => outcome.status === "rejected");
+        if (failed !== undefined)
+          throw failed.reason;
+        return statement;
+      });
+    };
+    const enqueue = (send) => {
+      const prior = waitTail ?? openingPending ?? Promise.resolve();
+      let markStarted = ignore;
+      const started = new Promise((resolve) => {
+        markStarted = resolve;
+      });
+      waitTail = started;
+      return prior.then(() => {
+        try {
+          return sendNow(send);
+        } finally {
+          if (waitTail === started)
+            waitTail = null;
+          markStarted();
+        }
+      });
+    };
+    const dispatch = (send) => {
+      if (budget.totalMs !== null) {
+        const pending = deadlineTail.then(() => sendNow(send));
+        deadlineTail = pending.then(ignore, ignore);
+        return pending;
+      }
+      if (openingPending !== null && (waitTail !== null || !ridesOpening(send)))
+        return enqueue(send);
+      return new Promise((resolve) => resolve(sendNow(send)));
+    };
+    return {
+      deferred,
+      dispatch,
+      executor: ({ effect, guard }) => Object.assign((strings, ...values) => dispatch({ effect, guard, extended: true, send: (connection) => connection(strings, ...values) }), { unsafe: (text, values) => dispatch({ effect, guard, extended: values !== undefined && values.length > 0, send: (connection) => connection.unsafe(text, values) }) })
     };
-    if (budget === undefined || budget.totalMs === null)
-      return run();
-    const result = (deadlineTurns.get(budget) ?? Promise.resolve()).then(run);
-    deadlineTurns.set(budget, result.then(() => {
-      return;
-    }, () => {
-      return;
-    }));
-    return result;
   }
   let rawSession = null;
   function createSqlInstance(params) {
-    const sqlOptions = { max: params.max };
+    const sqlOptions = { max: params.max, prepare: usePrepared };
     if (options?.connectionTimeout !== undefined) {
       sqlOptions.connectionTimeout = Math.max(1, Math.ceil(options.connectionTimeout / 1000));
+    } else if (address.seconds !== undefined) {
+      sqlOptions.connectionTimeout = address.seconds;
     }
     const startupOptions = buildStartupOptions({
       planCacheMode: options?.planCacheMode ?? "force_custom_plan",
       statementTimeout: options?.statementTimeout
     });
-    const baseUrl = options?.url ?? process.env.DATABASE_URL;
-    const url = baseUrl === undefined || startupOptions === undefined ? baseUrl : applyStartupOptions({ url: baseUrl, startupOptions });
-    if (url === undefined && startupOptions !== undefined) {
-      sqlOptions.connection = { options: startupOptions };
+    const url = startupOptions === undefined ? address.url : applyStartupOptions({ url: address.url, startupOptions });
+    if (URL.canParse(url)) {
+      const path = new URL(url).pathname;
+      if (path.length > 1)
+        sqlOptions.database = decodeURIComponent(path.slice(1));
     }
     return createBunSql({ url, options: sqlOptions });
   }
@@ -463,7 +624,7 @@ function bunAdapter(options) {
     else if (typeof probed === "string" && /^\{\s*"__vibeorm"\s*:\s*1\s*\}$/.test(probed))
       activeWire = WIRE_TEXT;
     else {
-      throw new VibeError6({
+      throw new VibeError7({
         code: "VIBE_ADAPTER",
         message: "Bun returned an unrecognized JSON wire probe result; no ORM statement was sent",
         meta: { reason: "json-wire-probe" }
@@ -479,40 +640,44 @@ function bunAdapter(options) {
     if (results.length === 0)
       observeRowChanges({ scope: params.scope, count: statementRowChanges({ effect: params.effect }) });
     for (const rows of results)
-      observeRowChanges({ scope: params.scope, count: statementRowChanges({ effect: params.effect, count: rows.count ?? rows.affectedRows }) });
+      observeRowChanges({ scope: params.scope, count: statementRowChanges({ effect: params.effect, count: rows.count ?? rows.affectedRows, rows: rows.length, resultRows: rows }) });
   }
   async function runExecute(params) {
     if (!wireSettled) {
-      wireProbe ??= probeJsonWire(params.source).finally(() => {
-        wireProbe = null;
-      });
-      await wireProbe;
+      if (params.scope === undefined) {
+        wireProbe ??= probeJsonWire(params.source).finally(() => {
+          wireProbe = null;
+        });
+        await wireProbe;
+      } else {
+        await probeJsonWire(params.source);
+      }
     }
-    const values = serializeParams({ values: params.values });
+    const values = serializeParams({ values: params.values, namedStatements: usePrepared });
     if (usePrepared) {
       const prepared = templates.getTemplate({ text: params.text });
-      const bound = bindTemplateValues({ text: params.text, indices: prepared.indices, values });
-      const result = await runMapped(() => params.source(prepared.template, ...bound));
+      const bound = prepared.identityOrder && prepared.indices.length === values.length ? values : bindTemplateValues({ text: params.text, indices: prepared.indices, values });
+      const result = bound.length > MAX_BIND_PARAMETERS ? await runMapped(() => params.source.unsafe(params.text, values)) : await runMapped(() => params.source(prepared.template, ...bound));
       observeResult({ scope: params.scope, effect: params.effect, result });
-      return finalRows({ result });
+      return plainRows({ rows: finalRows({ result }) });
     }
     const result = await runMapped(() => params.source.unsafe(params.text, values));
     observeResult({ scope: params.scope, effect: params.effect, result });
-    return finalRows({ result });
+    return plainRows({ rows: finalRows({ result }) });
   }
   async function runExecuteUnsafe(params) {
-    const values = params.values === undefined ? undefined : serializeParamsRaw({ values: params.values });
+    const values = params.values === undefined ? undefined : serializeParamsRaw({ values: params.values, namedStatements: usePrepared });
     const result = await runMapped(() => params.source.unsafe(params.text, values));
     observeResult({ scope: params.scope, effect: params.effect, result });
     const rows = finalRows({ result });
-    return { rows, affectedRows: readAffectedRows({ rows }) };
+    return { rows: plainRows({ rows }), affectedRows: readAffectedRows({ rows }) };
   }
   function createAdapter(params) {
-    const { source, parentMode, scope, budget, lifetime } = params;
+    const { source, parentMode, scope, budget, lifetime, control } = params;
     function assertHandle() {
       budget?.assertUsable({ stage: "statement" });
       if (lifetime?.active === false) {
-        throw new VibeError6({
+        throw new VibeError7({
           code: "VIBE_TRANSACTION",
           message: "this savepoint callback has finished; its transaction handle has expired",
           meta: { reason: "expired" }
@@ -521,56 +686,32 @@ function bunAdapter(options) {
       if (scope.state.poisoned !== null)
         throw scope.state.poisoned;
     }
-    const guardedSource = Object.assign((strings, ...values) => budgetTurn({ source, budget, guard: assertHandle, body: () => source(strings, ...values) }), { unsafe: (text, values) => budgetTurn({ source, budget, guard: assertHandle, body: () => source.unsafe(text, values) }) });
-    async function transactionViaSavepoint(fn, nestedOptions) {
+    async function transactionViaSavepoint(reservedControl, fn, nestedOptions) {
       refuseNestedTransactionOptions({ options: nestedOptions, provider: PROVIDER });
       assertHandle();
       budget?.assertUsable({ stage: "nested" });
-      const transactional = source;
-      const runChild = async (child, childSource) => {
-        assertHandle();
-        const childLifetime = { active: true };
-        try {
-          return await fn(createAdapter({ source: childSource, parentMode: "tx", scope: child, budget, lifetime: childLifetime }));
-        } finally {
-          childLifetime.active = false;
-        }
-      };
-      const driverSavepoint = transactional.savepoint?.bind(transactional);
-      if (driverSavepoint !== undefined) {
-        return runNestedSavepoint({
-          scope,
-          body: async (child) => {
-            let callbackFailure;
-            try {
-              return await driverSavepoint(async (savepointSql) => {
-                markSavepointOpened({ scope: child });
-                try {
-                  return await runChild(child, savepointSql);
-                } catch (error) {
-                  callbackFailure = new CallbackError(error);
-                  throw callbackFailure;
-                }
-              });
-            } catch (error) {
-              if (callbackFailure !== undefined && error === callbackFailure)
-                throw callbackFailure.inner;
-              const poisoned = callbackFailure !== undefined ? savepointRollbackFailedError({ cause: callbackFailure.inner, rollbackFailure: mapBunDriverError({ error }) }) : unknownOutcome({ cause: mapBunDriverError({ error }), reason: "savepoint-outcome-unknown" });
-              scope.state.poisoned = poisoned;
-              throw poisoned;
-            }
-          }
+      const savepointControl = (statement, cleanup) => {
+        if (reservedControl.deferred.routeSavepoint({ text: statement }) !== "send")
+          return;
+        return reservedControl.dispatch({
+          extended: true,
+          ...cleanup ? { cleanup: true } : {},
+          send: (connection) => controlQuery({ connection, text: statement })
         });
-      }
+      };
       return runNestedSavepoint({
         scope,
-        execute: (statement) => budgetTurn({
-          source,
-          budget,
-          cleanup: statement.startsWith("ROLLBACK TO SAVEPOINT "),
-          body: () => runMapped(() => transactional.unsafe(statement))
-        }),
-        body: (child) => runChild(child, transactional)
+        execute: (statement) => savepointControl(statement, false),
+        cleanup: (statement) => savepointControl(statement, true),
+        body: async (child) => {
+          assertHandle();
+          const childLifetime = { active: true };
+          try {
+            return await fn(createAdapter({ source, parentMode: "tx", scope: child, budget, lifetime: childLifetime, control: reservedControl }));
+          } finally {
+            childLifetime.active = false;
+          }
+        }
       });
     }
     async function transactionViaPool(fn, transactionOptions) {
@@ -580,76 +721,76 @@ function bunAdapter(options) {
         support: BUDGETS.transactionDeadline,
         provider: PROVIDER
       });
-      if (transactionOptions?.isolationLevel === undefined && transactionOptions?.timeout === undefined && transactionOptions?.deadline === undefined) {
-        const budget = startTransactionBudget({ provider: PROVIDER });
-        const txScope = createSavepointScope();
-        let callbackFailure;
-        try {
-          const result = await pool.begin(async (txSql) => {
-            const txAdapter = createAdapter({
-              source: txSql,
-              parentMode: "tx",
-              scope: txScope,
-              budget
-            });
-            try {
-              return await runRootScope({ scope: txScope, body: () => fn(txAdapter) });
-            } catch (error) {
-              callbackFailure = new CallbackError(error);
-              throw callbackFailure;
-            }
-          });
-          budget.close({ outcome: "committed" });
-          return result;
-        } catch (error) {
-          const knownRollback = callbackFailure !== undefined && error === callbackFailure && txScope.state.poisoned === null;
-          budget.close({ outcome: knownRollback ? "rolled-back" : "unknown" });
-          if (callbackFailure !== undefined && error === callbackFailure)
-            throw callbackFailure.inner;
-          throw unknownOutcome({ cause: callbackFailure?.inner ?? mapBunDriverError({ error }) });
-        }
-      }
-      const timeoutText = transactionOptions.timeout === undefined ? undefined : statementTimeoutStatement({ timeout: transactionOptions.timeout });
+      const readOnly = readOnlyRequested({ options: transactionOptions, provider: PROVIDER });
+      const openingOptions = { isolationLevel: transactionOptions?.isolationLevel, readOnly };
+      const eagerOpen = transactionOptions?.timeout === undefined ? null : openTransactionStatement({ ...openingOptions, timeout: transactionOptions.timeout });
       const reserved = await runMapped(() => pool.reserve());
       const budget = startTransactionBudget({ options: transactionOptions, provider: PROVIDER });
       const txScope = createSavepointScope();
-      let commitSent = false;
+      const control = createReservedControl({
+        reserved,
+        budget,
+        scope: txScope,
+        opening: eagerOpen === null ? beginStatement(openingOptions) : null
+      });
+      const commit = { progress: "not-sent" };
       let discard = false;
       try {
-        await runMapped(() => reserved.unsafe(beginStatement({ isolationLevel: transactionOptions.isolationLevel })));
-        if (timeoutText !== undefined)
-          await runMapped(() => reserved.unsafe(timeoutText));
+        if (eagerOpen !== null)
+          await runMapped(() => reserved.unsafe(eagerOpen));
         const txAdapter = createAdapter({
           source: reserved,
           parentMode: "tx",
           scope: txScope,
-          budget
+          budget,
+          control
         });
         const result = await runRootScope({ scope: txScope, body: () => fn(txAdapter) });
-        await budgetTurn({ source: reserved, budget, stage: "commit", body: () => {
-          commitSent = true;
-          return runMapped(() => reserved.unsafe("COMMIT"));
-        } });
+        budget.assertUsable({ stage: "commit" });
+        if (!control.deferred.opened()) {
+          budget.close({ outcome: "committed" });
+          return result;
+        }
+        const reply = await control.dispatch({
+          extended: true,
+          effect: "write",
+          stage: "commit",
+          send: (connection) => {
+            commit.progress = "sent";
+            return controlQuery({ connection, text: "COMMIT" });
+          }
+        });
+        if (finalRows({ result: reply }).command === "ROLLBACK") {
+          commit.progress = "answered";
+          throw transactionAbortedError({ cause: txScope.state.aborted?.cause });
+        }
         budget.close({ outcome: "committed" });
         return result;
       } catch (error) {
+        if (txScope.state.poisoned !== null)
+          discard = true;
+        if (commit.progress === "sent")
+          commit.progress = isConnectionLoss({ error }) ? "unanswered" : "answered";
+        let rollback = "not-needed";
         try {
-          await reserved.unsafe("ROLLBACK");
-          budget.close({ outcome: commitSent || txScope.state.poisoned !== null ? "unknown" : "rolled-back" });
+          if (control.deferred.opened()) {
+            await control.dispatch({ extended: false, cleanup: true, send: (connection) => connection.unsafe("ROLLBACK") });
+            rollback = "acknowledged";
+          }
         } catch {
           discard = true;
-          budget.close({ outcome: "unknown" });
-          if (budget.totalMs !== null && isTransactionDeadlineError(error)) {
-            throw transactionOutcomeUnknownError({
-              provider: PROVIDER,
-              totalMs: budget.totalMs,
-              cause: error
-            });
-          }
+          rollback = "failed";
         }
-        if (budget.outcome === "unknown" && txScope.state.poisoned === null)
-          throw unknownOutcome({ cause: error });
-        throw error;
+        const own = commit.progress === "unanswered" && txScope.state.poisoned === null ? unknownOutcome({ cause: error }) : error;
+        throw settleFailedTransaction({
+          error: own,
+          provider: PROVIDER,
+          budget,
+          scope: txScope,
+          commit: commit.progress,
+          rollback,
+          connection: discard ? "discarded" : "returned"
+        });
       } finally {
         if (discard)
           await runMapped(() => reserved.close());
@@ -661,6 +802,7 @@ function bunAdapter(options) {
       dialect: DIALECT,
       provider: PROVIDER,
       budgets: BUDGETS,
+      roundTrips: ROUND_TRIPS,
       ...parentMode === "pool" ? {} : { rowChanges: () => {
         assertHandle();
         return readRowChanges({ scope });
@@ -674,8 +816,9 @@ function bunAdapter(options) {
         if (turn !== undefined)
           await turn;
         assertHandle();
-        const result = runExecute({ source: guardedSource, ...parentMode === "pool" ? {} : { scope }, ...execParams });
-        return parentMode === "pool" ? result : result.catch((error) => abortTransactionOnServerFailure({ scope, error }));
+        const executor = control === undefined ? source : control.executor({ effect: execParams.effect, guard: assertHandle });
+        const result = runExecute({ source: executor, ...parentMode === "pool" ? {} : { scope }, ...execParams });
+        return parentMode === "pool" ? result : result.catch((error) => abortTransactionOnStatementFailure({ scope, error }));
       },
       async executeUnsafe(execParams) {
         assertHandle();
@@ -683,21 +826,35 @@ function bunAdapter(options) {
         if (turn !== undefined)
           await turn;
         assertHandle();
-        const result = runExecuteUnsafe({ source: guardedSource, ...parentMode === "pool" ? {} : { scope }, ...execParams });
-        return parentMode === "pool" ? result : result.catch((error) => abortTransactionOnServerFailure({ scope, error }));
+        const executor = control === undefined ? source : control.executor({ effect: execParams.effect, guard: assertHandle });
+        const result = runExecuteUnsafe({ source: executor, ...parentMode === "pool" ? {} : { scope }, ...execParams });
+        return parentMode === "pool" ? result : result.catch((error) => abortTransactionOnStatementFailure({ scope, error }));
       },
       async transaction(fn, transactionOptions) {
-        return parentMode === "pool" ? transactionViaPool(fn, transactionOptions) : transactionViaSavepoint(fn, transactionOptions);
+        return control === undefined ? transactionViaPool(fn, transactionOptions) : transactionViaSavepoint(control, fn, transactionOptions);
       },
       async connect() {
-        if (parentMode !== "pool")
-          return;
+        if (parentMode !== "pool") {
+          assertHandle();
+          throw transactionLifecycleRefusal({ method: "connect" });
+        }
         const reserved = await runMapped(() => source.reserve());
-        reserved.release();
+        try {
+          if (!wireSettled && wireProbe === null) {
+            wireProbe = probeJsonWire(reserved).finally(() => {
+              wireProbe = null;
+            });
+            await wireProbe;
+          }
+        } finally {
+          reserved.release();
+        }
       },
       async disconnect() {
-        if (parentMode !== "pool")
-          return;
+        if (parentMode !== "pool") {
+          assertHandle();
+          throw transactionLifecycleRefusal({ method: "disconnect" });
+        }
         await runMapped(() => source.close());
         instance = null;
       },
@@ -713,29 +870,53 @@ function bunAdapter(options) {
       scope: createSavepointScope()
     });
   }
-  return {
-    dialect: DIALECT,
-    provider: PROVIDER,
-    budgets: BUDGETS,
-    get wire() {
-      return activeWire;
-    },
+  function closeOwnedResources() {
+    return runShutdownCleanup({
+      steps: [
+        async () => {
+          if (rawSession === null)
+            return;
+          const session = rawSession;
+          rawSession = null;
+          await runMapped(() => session.unsafe("ROLLBACK")).then(() => {
+            session.release();
+          }, (error) => {
+            session.release();
+            throw error;
+          });
+        },
+        async () => {
+          if (instance === null)
+            return;
+          const closing = instance;
+          instance = null;
+          await runMapped(() => closing.close());
+        }
+      ]
+    });
+  }
+  const lifecycle = createAdapterLifecycleGate({ driver: "bun", cleanup: closeOwnedResources });
+  const root = {
     async withSession({ run }) {
       const sessionPool = createSqlInstance({ max: SESSION_CONNECTION.max });
       const close = () => runMapped(() => sessionPool.close({ timeout: SESSION_CONNECTION.closeGraceSeconds }));
       const reserved = await runMapped(() => sessionPool.reserve()).catch(async (cause) => {
-        await close();
+        await close().catch((cleanupCause) => {
+          if (cause instanceof VibeError7)
+            throw new VibeError7({ code: cause.code, message: cause.message, meta: { ...cause.meta, cleanupCause }, cause });
+          throw cause;
+        });
         throw cause;
       });
       return runPinnedSession({
         run,
         execute: async (query) => (await runExecuteUnsafe({ source: reserved, ...query })).rows,
-        isLost: (error) => error instanceof VibeError6 && (typeof error.meta.sqlstate !== "string" || error.meta.sqlstate.startsWith("08") || ["57P01", "57P02", "57P03"].includes(error.meta.sqlstate)),
+        isLost: (error) => error instanceof VibeError7 && isConnectionLoss({ error }),
         release: close
       });
     },
     async execute(params) {
-      return poolAdapter().execute(params);
+      return runExecute({ source: getSql(), ...params });
     },
     async executeUnsafe(params) {
       const control = classifyRawTransactionControl({ text: params.text });
@@ -762,28 +943,41 @@ function bunAdapter(options) {
           throw error;
         }
       }
-      return poolAdapter().executeUnsafe(params);
+      return runExecuteUnsafe({ source: getSql(), ...params });
     },
     async transaction(fn, transactionOptions) {
       return poolAdapter().transaction(fn, transactionOptions);
     },
     async connect() {
       return poolAdapter().connect();
+    }
+  };
+  return {
+    dialect: DIALECT,
+    provider: PROVIDER,
+    budgets: BUDGETS,
+    roundTrips: ROUND_TRIPS,
+    transactionOutcome: "reported",
+    get wire() {
+      return activeWire;
     },
-    async disconnect() {
-      if (rawSession !== null) {
-        const session = rawSession;
-        rawSession = null;
-        try {
-          await session.unsafe("ROLLBACK");
-        } catch {}
-        session.release();
-      }
-      if (instance === null)
-        return;
-      const closing = instance;
-      instance = null;
-      await runMapped(() => closing.close());
+    withSession({ run }) {
+      return lifecycle.admit({ run: () => root.withSession({ run: (executor) => lifecycle.inCallback({ run: () => run(executor) }) }) });
+    },
+    execute(params) {
+      return lifecycle.admit({ run: () => root.execute(params) });
+    },
+    executeUnsafe(params) {
+      return lifecycle.admit({ run: () => root.executeUnsafe(params) });
+    },
+    transaction(fn, transactionOptions) {
+      return lifecycle.admit({ run: () => root.transaction((txAdapter) => lifecycle.inCallback({ run: () => fn(txAdapter) }), transactionOptions) });
+    },
+    connect() {
+      return lifecycle.admit({ run: () => root.connect() });
+    },
+    disconnect() {
+      return lifecycle.disconnect();
     },
     formatArrayParam(values) {
       return toPgArrayLiteral(values);
@@ -798,14 +992,31 @@ function readAffectedRows(params) {
     return rows.affectedRows;
   return rows.length;
 }
+function plainRows(params) {
+  return Array.from(params.rows);
+}
 function finalRows(params) {
   const { result } = params;
   if (result === null)
     return [];
   return Array.isArray(result[0]) ? result.at(-1) ?? [] : result;
 }
+function isConnectionLoss(params) {
+  const { error } = params;
+  if (!(error instanceof VibeError7))
+    return true;
+  const sqlstate = error.meta.sqlstate;
+  return typeof sqlstate !== "string" || sqlstate.startsWith("08") || ["57P01", "57P02", "57P03"].includes(sqlstate);
+}
+function abortTransactionOnStatementFailure(params) {
+  const { scope, error } = params;
+  if (error instanceof VibeError7 && error.meta.driverCode === "ERR_POSTGRES_TOO_MANY_PARAMETERS") {
+    markTransactionAborted({ scope, cause: error });
+  }
+  return abortTransactionOnServerFailure({ scope, error });
+}
 function unknownOutcome(params) {
-  return new VibeError6({
+  return new VibeError7({
     code: "VIBE_TRANSACTION",
     message: "Bun could not confirm transaction recovery or completion; the outcome is unknown. Nothing is retried automatically.",
     meta: { reason: params.reason ?? "transaction-outcome-unknown", outcome: "unknown" },
@@ -826,7 +1037,7 @@ export {
   createSavepointCounter,
   createTemplateCache,
   engineStatementBudgetMs2 as engineStatementBudgetMs,
-  isTransactionDeadlineError2 as isTransactionDeadlineError,
+  isTransactionDeadlineError,
   mapBunDriverError,
   nextSavepointName,
   refuseNestedTransactionOptions,
@@ -838,8 +1049,8 @@ export {
   toPgArrayLiteral,
   transactionClosedError,
   transactionDeadlineError,
-  transactionOutcomeUnknownError2 as transactionOutcomeUnknownError,
+  transactionOutcomeUnknownError,
   validateTransactionDeadline2 as validateTransactionDeadline
 };
 
-//# debugId=424C29CF8963522C64756E2164756E21
+//# debugId=ABB8B79ECB9DC73B64756E2164756E21