@vibeorm/runtime 2.0.1 → 2.1.0

package/README.md

@@ -55,6 +55,8 @@ const adapter: DatabaseAdapter = {
 
 `toSqlExecutor({ adapter })` bridges an adapter to the `SqlExecutor` shape `@vibeorm/migrate` runs on.
 
+`@vibeorm/runtime/adapter-kit` carries the transaction helpers every shipped adapter is built on, so a custom adapter does not re-implement them: savepoint naming (`createSavepointCounter`), the savepoint lifetime gate that serialises overlapping sibling `transaction()` calls on one connection (`createSavepointScope`, `runRootScope`, `runNestedSavepoint`, `scopeTurn`), and the transaction budget behind `TransactionOptions.deadline` (`validateTransactionDeadline`, `startTransactionBudget`, `engineStatementBudgetMs` and the typed refusals). The shipped adapters re-export them unchanged.
+
 ## Relation strategies
 
 ```ts

package/dist/adapter-kit/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @vibeorm/runtime/adapter-kit — the transaction-safety helpers every driver
+ * adapter shares: savepoint naming, the savepoint lifetime gate (F14) and the
+ * transaction budget (EPIC 6).
+ *
+ * ONE copy. Each adapter imports from this subpath and re-exports the helpers
+ * it always offered, so a fix to the gate or the budget reaches every engine
+ * in the same change instead of six hand-synchronised files.
+ *
+ * Nothing here renders SQL or knows a driver: the gate runs the savepoint
+ * control statements through an `execute` the adapter injects, and the budget
+ * is a clock plus typed refusals.
+ */
+export { createSavepointCounter, nextSavepointName } from "./savepoints.ts";
+export type { SavepointCounter } from "./savepoints.ts";
+export { createSavepointScope, runNestedSavepoint, runRootScope, scopeTurn } from "./savepoint-gate.ts";
+export type { SavepointScope, SavepointState } from "./savepoint-gate.ts";
+export { DEFAULT_DEADLINE_CLOCK, engineStatementBudgetMs, isTransactionDeadlineError, startTransactionBudget, transactionClosedError, transactionDeadlineError, transactionOutcomeUnknownError, validateTransactionDeadline, } from "./transaction-budget.ts";
+export type { BudgetStage, DeadlineClock, TransactionBudget, TransactionOutcome } from "./transaction-budget.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter-kit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACxG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/adapter-kit/index.js

@@ -0,0 +1,247 @@
+// @bun
+// packages/runtime/src/adapter-kit/savepoints.ts
+function createSavepointCounter() {
+  return { n: 0 };
+}
+function nextSavepointName(params) {
+  return `vibeorm_sp_${params.counter.n++}`;
+}
+// packages/runtime/src/adapter-kit/savepoint-gate.ts
+import { AsyncLocalStorage } from "async_hooks";
+var CURRENT = new AsyncLocalStorage;
+function createSavepointScope() {
+  return { depth: 0, state: { counter: createSavepointCounter(), open: null } };
+}
+function runRootScope(params) {
+  return CURRENT.run(params.scope, params.body);
+}
+function scopeTurn(params) {
+  const open = params.scope.state.open;
+  if (mayProceed({ scope: params.scope, open }))
+    return;
+  return waitForTurn({ scope: params.scope });
+}
+async function runNestedSavepoint(params) {
+  const { scope, execute, body } = params;
+  const node = await acquire({ scope });
+  try {
+    if (execute !== undefined)
+      await execute(`SAVEPOINT ${node.name}`);
+    let result;
+    try {
+      result = await CURRENT.run(node.scope, () => body(node.scope));
+    } catch (error) {
+      await drainDescendants({ node });
+      if (execute !== undefined) {
+        try {
+          await execute(`ROLLBACK TO SAVEPOINT ${node.name}`);
+        } catch {}
+      }
+      throw error;
+    }
+    await drainDescendants({ node });
+    if (execute !== undefined)
+      await execute(`RELEASE SAVEPOINT ${node.name}`);
+    return result;
+  } finally {
+    closeNode({ node });
+  }
+}
+function mayProceed(params) {
+  const { scope, open } = params;
+  if (open === null)
+    return true;
+  if (open.scope === scope)
+    return true;
+  if (open.scope.depth < scope.depth)
+    return true;
+  return CURRENT.getStore() === open.scope;
+}
+async function waitForTurn(params) {
+  for (;; ) {
+    const open = params.scope.state.open;
+    if (open === null || mayProceed({ scope: params.scope, open }))
+      return;
+    await open.settled;
+  }
+}
+async function acquire(params) {
+  const { scope } = params;
+  for (;; ) {
+    const open = scope.state.open;
+    if (mayProceed({ scope, open }))
+      return pushNode({ scope, parent: open });
+    await open.settled;
+  }
+}
+function pushNode(params) {
+  const { scope, parent } = params;
+  const state = scope.state;
+  let settle = () => {
+    return;
+  };
+  const settled = new Promise((resolve) => {
+    settle = () => resolve();
+  });
+  const node = {
+    scope: { depth: (parent === null ? 0 : parent.scope.depth) + 1, state },
+    name: nextSavepointName({ counter: state.counter }),
+    parent,
+    settled,
+    settle
+  };
+  state.open = node;
+  return node;
+}
+function closeNode(params) {
+  const { node } = params;
+  const state = node.scope.state;
+  if (state.open === node)
+    state.open = node.parent;
+  node.settle();
+}
+async function drainDescendants(params) {
+  const state = params.node.scope.state;
+  for (;; ) {
+    const open = state.open;
+    if (open === null || open === params.node || open.scope.depth <= params.node.scope.depth)
+      return;
+    await open.settled;
+  }
+}
+// packages/runtime/src/adapter-kit/transaction-budget.ts
+import { VibeError } from "@vibeorm/schema";
+var DEFAULT_DEADLINE_CLOCK = () => Date.now();
+function validateTransactionDeadline(params) {
+  const { options, support, provider } = params;
+  const deadline = options?.deadline;
+  if (deadline === undefined)
+    return;
+  if (support === "unsupported") {
+    throw new VibeError({
+      code: "VIBE_UNSUPPORTED_CAPABILITY",
+      message: `${provider} cannot enforce a transaction deadline \u2014 remove the \`deadline\` option`,
+      meta: { provider, feature: "transactionDeadline", supported: support }
+    });
+  }
+  if (!Number.isInteger(deadline.totalMs) || deadline.totalMs <= 0) {
+    throw new VibeError({
+      code: "VIBE_VALIDATION",
+      message: `transaction deadline \`totalMs\` must be a positive integer of milliseconds, received ${String(deadline.totalMs)}`,
+      meta: { provider, feature: "transactionDeadline", totalMs: deadline.totalMs }
+    });
+  }
+  const requested = deadline.enforcement ?? "between-statements";
+  if (requested === "cancel-running-statements" && support !== "cancel-running-statements") {
+    throw new VibeError({
+      code: "VIBE_UNSUPPORTED_CAPABILITY",
+      message: `${provider} cannot cancel a statement that is already running, so the requested ` + "`cancel-running-statements` deadline guarantee is refused rather than silently downgraded \u2014 " + 'ask for "between-statements" if a budget checked between statements is enough',
+      meta: { provider, feature: "transactionDeadline", requested, supported: support }
+    });
+  }
+}
+function startTransactionBudget(params) {
+  const { options, provider } = params;
+  const clock = params.clock ?? DEFAULT_DEADLINE_CLOCK;
+  const deadline = options?.deadline;
+  const totalMs = deadline === undefined ? null : deadline.totalMs;
+  const enforcement = deadline === undefined ? null : deadline.enforcement ?? "between-statements";
+  const expiresAt = totalMs === null ? null : clock() + totalMs;
+  let outcome = null;
+  const budget = {
+    enforcement,
+    totalMs,
+    statementTimeoutMs: options?.timeout ?? null,
+    remainingMs() {
+      return expiresAt === null ? null : Math.max(0, expiresAt - clock());
+    },
+    expired() {
+      return expiresAt !== null && clock() >= expiresAt;
+    },
+    assertUsable(assertParams) {
+      if (outcome !== null) {
+        throw transactionClosedError({ provider, outcome, stage: assertParams.stage });
+      }
+      if (expiresAt !== null && clock() >= expiresAt) {
+        throw transactionDeadlineError({
+          provider,
+          stage: assertParams.stage,
+          totalMs,
+          overdueMs: clock() - expiresAt
+        });
+      }
+    },
+    close(closeParams) {
+      if (outcome === null)
+        outcome = closeParams.outcome;
+    },
+    get outcome() {
+      return outcome;
+    }
+  };
+  return budget;
+}
+function engineStatementBudgetMs(params) {
+  const { budget } = params;
+  if (budget.enforcement !== "cancel-running-statements")
+    return null;
+  const remaining = budget.remainingMs();
+  if (remaining === null)
+    return null;
+  const totalBound = Math.max(1, Math.ceil(remaining));
+  return budget.statementTimeoutMs !== null && budget.statementTimeoutMs > 0 ? Math.min(totalBound, budget.statementTimeoutMs) : totalBound;
+}
+function transactionDeadlineError(params) {
+  const { provider, stage, totalMs, overdueMs } = params;
+  const what = stage === "commit" ? "the transaction was rolled back instead of committed" : "the statement was never sent and the transaction is being rolled back";
+  return new VibeError({
+    code: "VIBE_TRANSACTION",
+    message: `transaction deadline of ${totalMs} ms expired ${Math.max(0, Math.round(overdueMs))} ms ago \u2014 ${what}. ` + "Nothing is retried automatically: work the callback did outside the database may already have happened.",
+    meta: { provider, reason: "transaction-deadline", stage, totalMs, overdueMs: Math.max(0, Math.round(overdueMs)) }
+  });
+}
+function transactionClosedError(params) {
+  const { provider, outcome, stage } = params;
+  return new VibeError({
+    code: "VIBE_TRANSACTION",
+    message: `this transaction has already finished (${outcome}), so its client can no longer be used \u2014 ` + "a handle kept past the end of `$transaction` would run outside the transaction, on a connection " + "that now belongs to someone else",
+    meta: { provider, reason: "transaction-closed", outcome, stage }
+  });
+}
+function transactionOutcomeUnknownError(params) {
+  const { provider, totalMs, cause } = params;
+  return new VibeError({
+    code: "VIBE_TRANSACTION",
+    message: `transaction deadline of ${totalMs} ms expired and the rollback that should have cleaned up failed \u2014 ` + "the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data " + "before deciding.",
+    meta: {
+      provider,
+      reason: "transaction-outcome-unknown",
+      outcome: "unknown",
+      totalMs,
+      rollbackFailed: true
+    },
+    cause
+  });
+}
+function isTransactionDeadlineError(error) {
+  const reason = error?.meta?.reason;
+  return reason === "transaction-deadline";
+}
+export {
+  validateTransactionDeadline,
+  transactionOutcomeUnknownError,
+  transactionDeadlineError,
+  transactionClosedError,
+  startTransactionBudget,
+  scopeTurn,
+  runRootScope,
+  runNestedSavepoint,
+  nextSavepointName,
+  isTransactionDeadlineError,
+  engineStatementBudgetMs,
+  createSavepointScope,
+  createSavepointCounter,
+  DEFAULT_DEADLINE_CLOCK
+};
+
+//# debugId=90A5C246EB2BA1E264756E2164756E21

package/dist/adapter-kit/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter-kit/savepoints.ts", "../src/adapter-kit/savepoint-gate.ts", "../src/adapter-kit/transaction-budget.ts"],
+  "sourcesContent": [
+    "/**\n * Savepoint naming for nested transactions.\n *\n * v1 lesson (LEARNINGS.md): the counter is shared **by reference** across every\n * adapter created for one top-level transaction, so sibling and deeply nested\n * savepoints can never collide on a name.\n */\n\n/** Mutable counter shared by reference across one top-level transaction. */\nexport type SavepointCounter = { n: number };\n\n/** Fresh counter — one per top-level transaction. */\nexport function createSavepointCounter(): SavepointCounter {\n  return { n: 0 };\n}\n\n/**\n * Allocate the next savepoint name (`vibeorm_sp_0`, `vibeorm_sp_1`, …) and\n * advance the shared counter. The name is an identifier by construction, so it\n * is safe to interpolate into `SAVEPOINT` / `RELEASE` / `ROLLBACK TO` SQL.\n */\nexport function nextSavepointName(params: { counter: SavepointCounter }): string {\n  return `vibeorm_sp_${params.counter.n++}`;\n}\n",
+    "/**\n * Savepoint lifetimes inside one top-level transaction (F14).\n *\n * A savepoint stack lives on ONE connection: `ROLLBACK TO SAVEPOINT s` undoes\n * everything done after `s`, including work a LATER savepoint already released.\n * Two `transaction()` callbacks opened from the same handle and overlapping in\n * time therefore share that one stack, and the earlier one's rollback silently\n * erases the later one's already committed work. Unique savepoint names do not\n * help — the names never collided, the lifetimes did.\n *\n * The rule enforced here, on every handle of a transaction:\n *\n * > A handle runs when nothing deeper than itself is open. Otherwise it waits\n * > for the innermost open savepoint to settle — unless the call is being made\n * > from INSIDE that savepoint's own callback, which is genuine nesting and\n * > proceeds immediately.\n *\n * The \"from inside\" test is an {@link AsyncLocalStorage} lookup, so the common\n * nesting shapes never wait on themselves: a child opened from its parent's\n * callback, and the parent handle used from within an open child's callback,\n * both proceed. Only genuinely concurrent siblings serialize.\n *\n * Not covered: a callback that awaits a sibling it did not start. That\n * arrangement asks for two savepoints to be open at once, which is exactly what\n * loses work; it now blocks instead. Deliberate — see the notes for this fix.\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport { type SavepointCounter, createSavepointCounter, nextSavepointName } from \"./savepoints.ts\";\n\n// ─── Types ────────────────────────────────────────────────────────\n\n/**\n * One handle's position in the savepoint stack of a top-level transaction.\n * `state` is shared by reference across every handle of that transaction.\n */\nexport type SavepointScope = {\n  /** Physical savepoint depth; 0 is the top-level transaction itself. */\n  readonly depth: number;\n  /** Shared state: name allocation plus the innermost open savepoint. */\n  readonly state: SavepointState;\n};\n\n/** Mutable state shared by every scope of one top-level transaction. */\nexport type SavepointState = {\n  /** Savepoint name counter (shared, so names never collide). */\n  readonly counter: SavepointCounter;\n  /** The innermost savepoint currently open, or `null` when none is. */\n  open: OpenSavepoint | null;\n};\n\n/** An open savepoint: its handle, its name, and when it finished. */\ntype OpenSavepoint = {\n  readonly scope: SavepointScope;\n  readonly name: string;\n  readonly parent: OpenSavepoint | null;\n  readonly settled: Promise<void>;\n  readonly settle: () => void;\n};\n\n/**\n * The savepoint whose callback the current async context is running inside.\n * This is the discriminator between genuine nesting (proceed) and an\n * overlapping sibling (wait).\n */\nconst CURRENT = new AsyncLocalStorage<SavepointScope>();\n\n// ─── Public API ───────────────────────────────────────────────────\n\n/** Fresh scope for one top-level transaction: depth 0, nothing open. */\nexport function createSavepointScope(): SavepointScope {\n  return { depth: 0, state: { counter: createSavepointCounter(), open: null } };\n}\n\n/**\n * Run a top-level transaction callback inside its scope's async context, so\n * nested calls made from it can be told apart from calls made inside an open\n * child.\n */\nexport function runRootScope<T>(params: { scope: SavepointScope; body: () => Promise<T> }): Promise<T> {\n  return CURRENT.run(params.scope, params.body);\n}\n\n/**\n * The wait a statement on `scope` owes before it may run, or `undefined` when\n * it may run now. Returning `undefined` keeps the uncontended path — nothing\n * deeper open — free of an extra promise and microtask.\n */\nexport function scopeTurn(params: { scope: SavepointScope }): Promise<void> | undefined {\n  const open = params.scope.state.open;\n  if (mayProceed({ scope: params.scope, open })) return undefined;\n  return waitForTurn({ scope: params.scope });\n}\n\n/**\n * Open a nested savepoint under `scope`, run `body` inside it and release it —\n * rolling back to it if `body` throws, exactly as before this gate existed.\n *\n * `execute` runs the savepoint control SQL (already wrapped in the adapter's\n * own driver-error mapping). Omit it when the driver manages the savepoint\n * itself (bun:sql's `savepoint()`), in which case only the lifetime is gated.\n */\nexport async function runNestedSavepoint<T>(params: {\n  readonly scope: SavepointScope;\n  readonly execute?: (statement: string) => Promise<unknown> | unknown;\n  readonly body: (scope: SavepointScope) => Promise<T>;\n}): Promise<T> {\n  const { scope, execute, body } = params;\n  const node = await acquire({ scope });\n  try {\n    if (execute !== undefined) await execute(`SAVEPOINT ${node.name}`);\n    let result: T;\n    try {\n      result = await CURRENT.run(node.scope, () => body(node.scope));\n    } catch (error) {\n      // A descendant the callback started but never awaited must finish before\n      // this savepoint may be rolled back — releasing out of order corrupts\n      // the stack.\n      await drainDescendants({ node });\n      if (execute !== undefined) {\n        // Best effort: never mask the original failure with a rollback failure.\n        try {\n          await execute(`ROLLBACK TO SAVEPOINT ${node.name}`);\n        } catch {\n          /* rollback is best-effort */\n        }\n      }\n      throw error;\n    }\n    await drainDescendants({ node });\n    if (execute !== undefined) await execute(`RELEASE SAVEPOINT ${node.name}`);\n    return result;\n  } finally {\n    closeNode({ node });\n  }\n}\n\n// ─── Internals ────────────────────────────────────────────────────\n\n/** Whether `scope` may act while `open` is the innermost open savepoint. */\nfunction mayProceed(params: { scope: SavepointScope; open: OpenSavepoint | null }): boolean {\n  const { scope, open } = params;\n  if (open === null) return true;\n  // This handle IS the innermost open savepoint.\n  if (open.scope === scope) return true;\n  // This handle's own savepoint has already closed (a retained child handle):\n  // it can only act at the connection's current depth, and waiting for a\n  // shallower savepoint it does not own would never resolve.\n  if (open.scope.depth < scope.depth) return true;\n  // Genuine nesting: the call is being made from inside the open callback.\n  return CURRENT.getStore() === open.scope;\n}\n\nasync function waitForTurn(params: { scope: SavepointScope }): Promise<void> {\n  for (;;) {\n    const open = params.scope.state.open;\n    if (open === null || mayProceed({ scope: params.scope, open })) return;\n    await open.settled;\n  }\n}\n\n/**\n * Wait for this handle's turn and take it in the SAME synchronous step — the\n * check and the push must not be separated by an await, or two waiters woken\n * together would both open a savepoint.\n */\nasync function acquire(params: { scope: SavepointScope }): Promise<OpenSavepoint> {\n  const { scope } = params;\n  for (;;) {\n    const open = scope.state.open;\n    if (mayProceed({ scope, open })) return pushNode({ scope, parent: open });\n    // `mayProceed` returns true for a null `open`, so this is never null here.\n    await (open as OpenSavepoint).settled;\n  }\n}\n\nfunction pushNode(params: { scope: SavepointScope; parent: OpenSavepoint | null }): OpenSavepoint {\n  const { scope, parent } = params;\n  const state = scope.state;\n  let settle: () => void = () => undefined;\n  const settled = new Promise<void>((resolve) => {\n    settle = () => resolve();\n  });\n  // Physical depth follows the connection's stack, not the handle that opened\n  // it: a savepoint opened from an outer handle inside a child's callback still\n  // nests inside that child.\n  const node: OpenSavepoint = {\n    scope: { depth: (parent === null ? 0 : parent.scope.depth) + 1, state },\n    name: nextSavepointName({ counter: state.counter }),\n    parent,\n    settled,\n    settle,\n  };\n  state.open = node;\n  return node;\n}\n\nfunction closeNode(params: { node: OpenSavepoint }): void {\n  const { node } = params;\n  const state = node.scope.state;\n  if (state.open === node) state.open = node.parent;\n  node.settle();\n}\n\n/** Wait out savepoints a callback opened below this node and never awaited. */\nasync function drainDescendants(params: { node: OpenSavepoint }): Promise<void> {\n  const state = params.node.scope.state;\n  for (;;) {\n    const open = state.open;\n    if (open === null || open === params.node || open.scope.depth <= params.node.scope.depth) return;\n    await open.settled;\n  }\n}\n",
+    "/**\n * Transaction budgets — the total-deadline clock and the handle-closure gate.\n *\n * ONE copy, shared by every adapter package through the\n * `@vibeorm/runtime/adapter-kit` subpath (like `savepoint-gate.ts`), so a\n * change here reaches all engines at once — a per-adapter copy would drift\n * into a silent per-engine behaviour difference.\n *\n * WHAT A DEADLINE IS, AND IS NOT\n *\n * `TransactionOptions.timeout` is unchanged: a PER-STATEMENT engine-side bound.\n * `TransactionOptions.deadline` is new and different — a TOTAL wall-clock bound\n * on one top-level transaction. Its clock starts immediately before `BEGIN` is\n * sent, so connection acquisition (which has its own budget on the pooled\n * adapters) is deliberately NOT counted.\n *\n * Enforcement is never `Promise.race` over a statement that keeps running:\n *\n * - `\"between-statements\"` (the default, and all six adapters can deliver it):\n *   before every statement, every nested `transaction()` and the `COMMIT`, an\n *   expired budget refuses. The statement is never sent and the transaction is\n *   rolled back. A statement ALREADY IN FLIGHT is not interrupted.\n * - `\"cancel-running-statements\"` (postgres servers only): additionally hands\n *   the engine the remaining budget as `statement_timeout`, so the SERVER\n *   cancels an over-long statement. An adapter that cannot do this refuses the\n *   request outright rather than quietly delivering the weaker level.\n *\n * JavaScript cannot forcibly stop a running callback. A callback that keeps\n * going past the deadline finds its later database calls refused; work it does\n * outside the database (an HTTP call, an SMS) is not stopped and cannot be.\n * There is no automatic retry: a deadline failure is terminal for that\n * transaction, because external side effects may already have happened.\n */\n\nimport { VibeError } from \"@vibeorm/schema\";\nimport type {\n  TransactionDeadlineEnforcement,\n  TransactionDeadlineSupport,\n  TransactionOptions,\n} from \"../adapter.ts\";\n\n// ─── Types ────────────────────────────────────────────────────────\n\n/** Where a budget check happened, reported as `meta.stage`. */\nexport type BudgetStage = \"statement\" | \"nested\" | \"commit\";\n\n/**\n * What is known about a finished transaction. `\"unknown\"` is a first-class\n * outcome, not a failure to decide: when a rollback itself fails the commit\n * state genuinely cannot be asserted, and claiming \"rolled back\" would be a lie.\n */\nexport type TransactionOutcome = \"committed\" | \"rolled-back\" | \"unknown\";\n\n/** Wall clock, injectable so tests are deterministic instead of sleep-timed. */\nexport type DeadlineClock = () => number;\n\n/** The ambient clock, used whenever no seam is injected. */\nexport const DEFAULT_DEADLINE_CLOCK: DeadlineClock = (): number => Date.now();\n\n/**\n * One top-level transaction's budget. Nested savepoint handles share this\n * object BY REFERENCE — they never get an independent clock, connection or\n * session setting.\n */\nexport type TransactionBudget = {\n  /** The enforcement level in force, or `null` when no deadline was requested. */\n  readonly enforcement: TransactionDeadlineEnforcement | null;\n  /** The requested total budget in milliseconds, or `null` when none was. */\n  readonly totalMs: number | null;\n  /** Existing per-statement limit, independent of the total deadline. Zero disables it. */\n  readonly statementTimeoutMs: number | null;\n  /** Milliseconds left (never negative), or `null` when no deadline is set. */\n  remainingMs(): number | null;\n  /** True only when a deadline is set and has passed. */\n  expired(): boolean;\n  /** Refuse a closed handle or an expired budget. Called BEFORE anything is sent. */\n  assertUsable(params: { stage: BudgetStage }): void;\n  /** Record the terminal outcome; the first call wins and later ones are ignored. */\n  close(params: { outcome: TransactionOutcome }): void;\n  /** The recorded outcome, or `null` while the transaction is still open. */\n  readonly outcome: TransactionOutcome | null;\n};\n\n// ─── Validation (before BEGIN, before any write) ──────────────────\n\n/**\n * Check `options.deadline` against what this adapter can honestly deliver.\n * Called BEFORE `BEGIN` — a budget this engine cannot honour must never leave\n * a transaction open behind it.\n *\n * @throws VibeError `VIBE_VALIDATION` when `totalMs` is not a positive integer.\n * @throws VibeError `VIBE_UNSUPPORTED_CAPABILITY` when the requested\n * `enforcement` is stronger than `support` — refused, never silently degraded.\n */\nexport function validateTransactionDeadline(params: {\n  options?: TransactionOptions;\n  support: TransactionDeadlineSupport;\n  provider: string;\n}): void {\n  const { options, support, provider } = params;\n  const deadline = options?.deadline;\n  if (deadline === undefined) return;\n\n  if (support === \"unsupported\") {\n    throw new VibeError({\n      code: \"VIBE_UNSUPPORTED_CAPABILITY\",\n      message: `${provider} cannot enforce a transaction deadline — remove the \\`deadline\\` option`,\n      meta: { provider, feature: \"transactionDeadline\", supported: support },\n    });\n  }\n\n  if (!Number.isInteger(deadline.totalMs) || deadline.totalMs <= 0) {\n    throw new VibeError({\n      code: \"VIBE_VALIDATION\",\n      message: `transaction deadline \\`totalMs\\` must be a positive integer of milliseconds, received ${String(deadline.totalMs)}`,\n      meta: { provider, feature: \"transactionDeadline\", totalMs: deadline.totalMs },\n    });\n  }\n\n  const requested: TransactionDeadlineEnforcement = deadline.enforcement ?? \"between-statements\";\n  if (requested === \"cancel-running-statements\" && support !== \"cancel-running-statements\") {\n    throw new VibeError({\n      code: \"VIBE_UNSUPPORTED_CAPABILITY\",\n      message:\n        `${provider} cannot cancel a statement that is already running, so the requested ` +\n        \"`cancel-running-statements` deadline guarantee is refused rather than silently downgraded — \" +\n        'ask for \"between-statements\" if a budget checked between statements is enough',\n      meta: { provider, feature: \"transactionDeadline\", requested, supported: support },\n    });\n  }\n}\n\n// ─── The budget ───────────────────────────────────────────────────\n\n/**\n * Start the clock for one top-level transaction. Call it immediately before\n * `BEGIN`; {@link validateTransactionDeadline} must already have run.\n */\nexport function startTransactionBudget(params: {\n  options?: TransactionOptions;\n  provider: string;\n  clock?: DeadlineClock;\n}): TransactionBudget {\n  const { options, provider } = params;\n  const clock = params.clock ?? DEFAULT_DEADLINE_CLOCK;\n  const deadline = options?.deadline;\n  const totalMs = deadline === undefined ? null : deadline.totalMs;\n  const enforcement: TransactionDeadlineEnforcement | null =\n    deadline === undefined ? null : (deadline.enforcement ?? \"between-statements\");\n  const expiresAt = totalMs === null ? null : clock() + totalMs;\n  let outcome: TransactionOutcome | null = null;\n\n  const budget: TransactionBudget = {\n    enforcement,\n    totalMs,\n    statementTimeoutMs: options?.timeout ?? null,\n    remainingMs(): number | null {\n      return expiresAt === null ? null : Math.max(0, expiresAt - clock());\n    },\n    expired(): boolean {\n      return expiresAt !== null && clock() >= expiresAt;\n    },\n    assertUsable(assertParams: { stage: BudgetStage }): void {\n      if (outcome !== null) {\n        throw transactionClosedError({ provider, outcome, stage: assertParams.stage });\n      }\n      if (expiresAt !== null && clock() >= expiresAt) {\n        throw transactionDeadlineError({\n          provider,\n          stage: assertParams.stage,\n          totalMs: totalMs as number,\n          overdueMs: clock() - expiresAt,\n        });\n      }\n    },\n    close(closeParams: { outcome: TransactionOutcome }): void {\n      if (outcome === null) outcome = closeParams.outcome;\n    },\n    get outcome(): TransactionOutcome | null {\n      return outcome;\n    },\n  };\n  return budget;\n}\n\n/**\n * The engine-side bound for the NEXT statement, or `null` when the caller did\n * not buy `\"cancel-running-statements\"`. Floored at 1 ms: on postgres `0` means\n * \"no limit\", so a spent budget must never be handed over as a zero.\n */\nexport function engineStatementBudgetMs(params: { budget: TransactionBudget }): number | null {\n  const { budget } = params;\n  if (budget.enforcement !== \"cancel-running-statements\") return null;\n  const remaining = budget.remainingMs();\n  if (remaining === null) return null;\n  const totalBound = Math.max(1, Math.ceil(remaining));\n  return budget.statementTimeoutMs !== null && budget.statementTimeoutMs > 0\n    ? Math.min(totalBound, budget.statementTimeoutMs) : totalBound;\n}\n\n// ─── Errors ───────────────────────────────────────────────────────\n\n/**\n * The refusal an expired budget raises. `VIBE_TRANSACTION` with a stable\n * `meta.reason` — no SQL text, no parameter values, no credentials.\n */\nexport function transactionDeadlineError(params: {\n  provider: string;\n  stage: BudgetStage;\n  totalMs: number;\n  overdueMs: number;\n}): VibeError {\n  const { provider, stage, totalMs, overdueMs } = params;\n  const what =\n    stage === \"commit\"\n      ? \"the transaction was rolled back instead of committed\"\n      : \"the statement was never sent and the transaction is being rolled back\";\n  return new VibeError({\n    code: \"VIBE_TRANSACTION\",\n    message:\n      `transaction deadline of ${totalMs} ms expired ${Math.max(0, Math.round(overdueMs))} ms ago — ${what}. ` +\n      \"Nothing is retried automatically: work the callback did outside the database may already have happened.\",\n    meta: { provider, reason: \"transaction-deadline\", stage, totalMs, overdueMs: Math.max(0, Math.round(overdueMs)) },\n  });\n}\n\n/**\n * The refusal an ESCAPED transaction handle raises — a transactional adapter\n * kept past the end of its transaction. Without this it would run on a\n * connection that is back in the pool, outside any transaction.\n */\nexport function transactionClosedError(params: {\n  provider: string;\n  outcome: TransactionOutcome;\n  stage: BudgetStage;\n}): VibeError {\n  const { provider, outcome, stage } = params;\n  return new VibeError({\n    code: \"VIBE_TRANSACTION\",\n    message:\n      `this transaction has already finished (${outcome}), so its client can no longer be used — ` +\n      \"a handle kept past the end of `$transaction` would run outside the transaction, on a connection \" +\n      \"that now belongs to someone else\",\n    meta: { provider, reason: \"transaction-closed\", outcome, stage },\n  });\n}\n\n/**\n * The stable typed outcome for \"the deadline expired and the rollback that was\n * supposed to clean up failed too\". Promising a rollback here would be false;\n * promising a retry would be worse.\n *\n * `cause` is the CAUSAL error (the deadline refusal), so the reason the\n * transaction was being abandoned survives. The rollback failure itself is\n * reported only as `meta.rollbackFailed`: a raw driver failure can carry\n * statement text, and this error is meant to be logged.\n */\nexport function transactionOutcomeUnknownError(params: {\n  provider: string;\n  totalMs: number;\n  cause: unknown;\n}): VibeError {\n  const { provider, totalMs, cause } = params;\n  return new VibeError({\n    code: \"VIBE_TRANSACTION\",\n    message:\n      `transaction deadline of ${totalMs} ms expired and the rollback that should have cleaned up failed — ` +\n      \"the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data \" +\n      \"before deciding.\",\n    meta: {\n      provider,\n      reason: \"transaction-outcome-unknown\",\n      outcome: \"unknown\",\n      totalMs,\n      rollbackFailed: true,\n    },\n    cause,\n  });\n}\n\n/** Whether `error` is this module's deadline refusal (used to pick the cleanup path). */\nexport function isTransactionDeadlineError(error: unknown): boolean {\n  const reason = (error as { meta?: { reason?: unknown } } | null)?.meta?.reason;\n  return reason === \"transaction-deadline\";\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "90A5C246EB2BA1E264756E2164756E21",
+  "names": []
+}

package/dist/adapter-kit/savepoint-gate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Savepoint lifetimes inside one top-level transaction (F14).
+ *
+ * A savepoint stack lives on ONE connection: `ROLLBACK TO SAVEPOINT s` undoes
+ * everything done after `s`, including work a LATER savepoint already released.
+ * Two `transaction()` callbacks opened from the same handle and overlapping in
+ * time therefore share that one stack, and the earlier one's rollback silently
+ * erases the later one's already committed work. Unique savepoint names do not
+ * help — the names never collided, the lifetimes did.
+ *
+ * The rule enforced here, on every handle of a transaction:
+ *
+ * > A handle runs when nothing deeper than itself is open. Otherwise it waits
+ * > for the innermost open savepoint to settle — unless the call is being made
+ * > from INSIDE that savepoint's own callback, which is genuine nesting and
+ * > proceeds immediately.
+ *
+ * The "from inside" test is an {@link AsyncLocalStorage} lookup, so the common
+ * nesting shapes never wait on themselves: a child opened from its parent's
+ * callback, and the parent handle used from within an open child's callback,
+ * both proceed. Only genuinely concurrent siblings serialize.
+ *
+ * Not covered: a callback that awaits a sibling it did not start. That
+ * arrangement asks for two savepoints to be open at once, which is exactly what
+ * loses work; it now blocks instead. Deliberate — see the notes for this fix.
+ */
+import { type SavepointCounter } from "./savepoints.ts";
+/**
+ * One handle's position in the savepoint stack of a top-level transaction.
+ * `state` is shared by reference across every handle of that transaction.
+ */
+export type SavepointScope = {
+    /** Physical savepoint depth; 0 is the top-level transaction itself. */
+    readonly depth: number;
+    /** Shared state: name allocation plus the innermost open savepoint. */
+    readonly state: SavepointState;
+};
+/** Mutable state shared by every scope of one top-level transaction. */
+export type SavepointState = {
+    /** Savepoint name counter (shared, so names never collide). */
+    readonly counter: SavepointCounter;
+    /** The innermost savepoint currently open, or `null` when none is. */
+    open: OpenSavepoint | null;
+};
+/** An open savepoint: its handle, its name, and when it finished. */
+type OpenSavepoint = {
+    readonly scope: SavepointScope;
+    readonly name: string;
+    readonly parent: OpenSavepoint | null;
+    readonly settled: Promise<void>;
+    readonly settle: () => void;
+};
+/** Fresh scope for one top-level transaction: depth 0, nothing open. */
+export declare function createSavepointScope(): SavepointScope;
+/**
+ * Run a top-level transaction callback inside its scope's async context, so
+ * nested calls made from it can be told apart from calls made inside an open
+ * child.
+ */
+export declare function runRootScope<T>(params: {
+    scope: SavepointScope;
+    body: () => Promise<T>;
+}): Promise<T>;
+/**
+ * The wait a statement on `scope` owes before it may run, or `undefined` when
+ * it may run now. Returning `undefined` keeps the uncontended path — nothing
+ * deeper open — free of an extra promise and microtask.
+ */
+export declare function scopeTurn(params: {
+    scope: SavepointScope;
+}): Promise<void> | undefined;
+/**
+ * Open a nested savepoint under `scope`, run `body` inside it and release it —
+ * rolling back to it if `body` throws, exactly as before this gate existed.
+ *
+ * `execute` runs the savepoint control SQL (already wrapped in the adapter's
+ * own driver-error mapping). Omit it when the driver manages the savepoint
+ * itself (bun:sql's `savepoint()`), in which case only the lifetime is gated.
+ */
+export declare function runNestedSavepoint<T>(params: {
+    readonly scope: SavepointScope;
+    readonly execute?: (statement: string) => Promise<unknown> | unknown;
+    readonly body: (scope: SavepointScope) => Promise<T>;
+}): Promise<T>;
+export {};
+//# sourceMappingURL=savepoint-gate.d.ts.map

package/dist/adapter-kit/savepoint-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"savepoint-gate.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/savepoint-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,KAAK,gBAAgB,EAA6C,MAAM,iBAAiB,CAAC;AAInG;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,sEAAsE;IACtE,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,qEAAqE;AACrE,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B,CAAC;AAWF,wEAAwE;AACxE,wBAAgB,oBAAoB,IAAI,cAAc,CAErD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAErG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAItF;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE;IAClD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb"}

package/dist/adapter-kit/savepoints.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Savepoint naming for nested transactions.
+ *
+ * v1 lesson (LEARNINGS.md): the counter is shared **by reference** across every
+ * adapter created for one top-level transaction, so sibling and deeply nested
+ * savepoints can never collide on a name.
+ */
+/** Mutable counter shared by reference across one top-level transaction. */
+export type SavepointCounter = {
+    n: number;
+};
+/** Fresh counter — one per top-level transaction. */
+export declare function createSavepointCounter(): SavepointCounter;
+/**
+ * Allocate the next savepoint name (`vibeorm_sp_0`, `vibeorm_sp_1`, …) and
+ * advance the shared counter. The name is an identifier by construction, so it
+ * is safe to interpolate into `SAVEPOINT` / `RELEASE` / `ROLLBACK TO` SQL.
+ */
+export declare function nextSavepointName(params: {
+    counter: SavepointCounter;
+}): string;
+//# sourceMappingURL=savepoints.d.ts.map

package/dist/adapter-kit/savepoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"savepoints.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/savepoints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,qDAAqD;AACrD,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAAG,MAAM,CAE/E"}

package/dist/adapter-kit/transaction-budget.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Transaction budgets — the total-deadline clock and the handle-closure gate.
+ *
+ * ONE copy, shared by every adapter package through the
+ * `@vibeorm/runtime/adapter-kit` subpath (like `savepoint-gate.ts`), so a
+ * change here reaches all engines at once — a per-adapter copy would drift
+ * into a silent per-engine behaviour difference.
+ *
+ * WHAT A DEADLINE IS, AND IS NOT
+ *
+ * `TransactionOptions.timeout` is unchanged: a PER-STATEMENT engine-side bound.
+ * `TransactionOptions.deadline` is new and different — a TOTAL wall-clock bound
+ * on one top-level transaction. Its clock starts immediately before `BEGIN` is
+ * sent, so connection acquisition (which has its own budget on the pooled
+ * adapters) is deliberately NOT counted.
+ *
+ * Enforcement is never `Promise.race` over a statement that keeps running:
+ *
+ * - `"between-statements"` (the default, and all six adapters can deliver it):
+ *   before every statement, every nested `transaction()` and the `COMMIT`, an
+ *   expired budget refuses. The statement is never sent and the transaction is
+ *   rolled back. A statement ALREADY IN FLIGHT is not interrupted.
+ * - `"cancel-running-statements"` (postgres servers only): additionally hands
+ *   the engine the remaining budget as `statement_timeout`, so the SERVER
+ *   cancels an over-long statement. An adapter that cannot do this refuses the
+ *   request outright rather than quietly delivering the weaker level.
+ *
+ * JavaScript cannot forcibly stop a running callback. A callback that keeps
+ * going past the deadline finds its later database calls refused; work it does
+ * outside the database (an HTTP call, an SMS) is not stopped and cannot be.
+ * There is no automatic retry: a deadline failure is terminal for that
+ * transaction, because external side effects may already have happened.
+ */
+import { VibeError } from "@vibeorm/schema";
+import type { TransactionDeadlineEnforcement, TransactionDeadlineSupport, TransactionOptions } from "../adapter.ts";
+/** Where a budget check happened, reported as `meta.stage`. */
+export type BudgetStage = "statement" | "nested" | "commit";
+/**
+ * What is known about a finished transaction. `"unknown"` is a first-class
+ * outcome, not a failure to decide: when a rollback itself fails the commit
+ * state genuinely cannot be asserted, and claiming "rolled back" would be a lie.
+ */
+export type TransactionOutcome = "committed" | "rolled-back" | "unknown";
+/** Wall clock, injectable so tests are deterministic instead of sleep-timed. */
+export type DeadlineClock = () => number;
+/** The ambient clock, used whenever no seam is injected. */
+export declare const DEFAULT_DEADLINE_CLOCK: DeadlineClock;
+/**
+ * One top-level transaction's budget. Nested savepoint handles share this
+ * object BY REFERENCE — they never get an independent clock, connection or
+ * session setting.
+ */
+export type TransactionBudget = {
+    /** The enforcement level in force, or `null` when no deadline was requested. */
+    readonly enforcement: TransactionDeadlineEnforcement | null;
+    /** The requested total budget in milliseconds, or `null` when none was. */
+    readonly totalMs: number | null;
+    /** Existing per-statement limit, independent of the total deadline. Zero disables it. */
+    readonly statementTimeoutMs: number | null;
+    /** Milliseconds left (never negative), or `null` when no deadline is set. */
+    remainingMs(): number | null;
+    /** True only when a deadline is set and has passed. */
+    expired(): boolean;
+    /** Refuse a closed handle or an expired budget. Called BEFORE anything is sent. */
+    assertUsable(params: {
+        stage: BudgetStage;
+    }): void;
+    /** Record the terminal outcome; the first call wins and later ones are ignored. */
+    close(params: {
+        outcome: TransactionOutcome;
+    }): void;
+    /** The recorded outcome, or `null` while the transaction is still open. */
+    readonly outcome: TransactionOutcome | null;
+};
+/**
+ * Check `options.deadline` against what this adapter can honestly deliver.
+ * Called BEFORE `BEGIN` — a budget this engine cannot honour must never leave
+ * a transaction open behind it.
+ *
+ * @throws VibeError `VIBE_VALIDATION` when `totalMs` is not a positive integer.
+ * @throws VibeError `VIBE_UNSUPPORTED_CAPABILITY` when the requested
+ * `enforcement` is stronger than `support` — refused, never silently degraded.
+ */
+export declare function validateTransactionDeadline(params: {
+    options?: TransactionOptions;
+    support: TransactionDeadlineSupport;
+    provider: string;
+}): void;
+/**
+ * Start the clock for one top-level transaction. Call it immediately before
+ * `BEGIN`; {@link validateTransactionDeadline} must already have run.
+ */
+export declare function startTransactionBudget(params: {
+    options?: TransactionOptions;
+    provider: string;
+    clock?: DeadlineClock;
+}): TransactionBudget;
+/**
+ * The engine-side bound for the NEXT statement, or `null` when the caller did
+ * not buy `"cancel-running-statements"`. Floored at 1 ms: on postgres `0` means
+ * "no limit", so a spent budget must never be handed over as a zero.
+ */
+export declare function engineStatementBudgetMs(params: {
+    budget: TransactionBudget;
+}): number | null;
+/**
+ * The refusal an expired budget raises. `VIBE_TRANSACTION` with a stable
+ * `meta.reason` — no SQL text, no parameter values, no credentials.
+ */
+export declare function transactionDeadlineError(params: {
+    provider: string;
+    stage: BudgetStage;
+    totalMs: number;
+    overdueMs: number;
+}): VibeError;
+/**
+ * The refusal an ESCAPED transaction handle raises — a transactional adapter
+ * kept past the end of its transaction. Without this it would run on a
+ * connection that is back in the pool, outside any transaction.
+ */
+export declare function transactionClosedError(params: {
+    provider: string;
+    outcome: TransactionOutcome;
+    stage: BudgetStage;
+}): VibeError;
+/**
+ * The stable typed outcome for "the deadline expired and the rollback that was
+ * supposed to clean up failed too". Promising a rollback here would be false;
+ * promising a retry would be worse.
+ *
+ * `cause` is the CAUSAL error (the deadline refusal), so the reason the
+ * transaction was being abandoned survives. The rollback failure itself is
+ * reported only as `meta.rollbackFailed`: a raw driver failure can carry
+ * statement text, and this error is meant to be logged.
+ */
+export declare function transactionOutcomeUnknownError(params: {
+    provider: string;
+    totalMs: number;
+    cause: unknown;
+}): VibeError;
+/** Whether `error` is this module's deadline refusal (used to pick the cleanup path). */
+export declare function isTransactionDeadlineError(error: unknown): boolean;
+//# sourceMappingURL=transaction-budget.d.ts.map

package/dist/adapter-kit/transaction-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-budget.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/transaction-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EACV,8BAA8B,EAC9B,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAIvB,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAEzE,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC;AAEzC,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,EAAE,aAAwC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC5D,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,6EAA6E;IAC7E,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAC7B,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC;IACnB,mFAAmF;IACnF,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,mFAAmF;IACnF,KAAK,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,kBAAkB,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC7C,CAAC;AAIF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,0BAA0B,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAgCP;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GAAG,iBAAiB,CAyCpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAQ5F;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,SAAS,CAaZ;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;CACpB,GAAG,SAAS,CAUZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,SAAS,CAiBZ;AAED,yFAAyF;AACzF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGlE"}